v0.35.0: a play history for the yearly Wrapped

The play journals keep running totals per track, which is enough for "most
played ever" and nothing a Wrapped asks: top songs of this year, minutes
listened, which month, what time of day, what got skipped. Those all come
from one timestamped line per listen, so LinTunes now keeps that, while
Preferences -> General -> "Keep a play history for my yearly Wrapped" is on.

history/<machine>/<YYYY-MM>.jsonl, one writer per folder like the journals:
local start time with its offset, ms actually heard (Player adds position
steps under 1.5 s, so seeks and pauses don't count), how it ended, where it
played and from what, and a name/artist/album snapshot that outlives a
delete. Under 5 s is noise and never written.

andTunes 0.3.0 writes the same lines on the Rabbit when sync says the
desktop wants them, and sync copies each month home when the device's copy
is longer. "Share this year's play history with friends" puts a trimmed
copy (no ids, playlists or devices) in each friend's cassette folder, daily
in November and December and monthly otherwise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-02 16:47:40 -07:00
co-authored by Claude Opus 5.5
parent b3d6c01774
commit ad1d152948
26 changed files with 1148 additions and 15 deletions
+60
View File
@@ -8,6 +8,7 @@ from PyQt6.QtMultimedia import (
from lintunes.eventlog import log_control
from lintunes.models import Track
from lintunes.storage import listen_history
# Hitting "previous" more than this far into a song restarts it instead
@@ -36,6 +37,23 @@ RESUME_NUDGE_THRESHOLD_S = 30
# on pause — if we ever move to a GStreamer sink, all of this goes away.
PARK_AFTER_IDLE_S = 30
# Listen accounting (the Wrapped history): a position step longer than this is
# a seek, not listening. Comfortably above the cast sink's 500 ms poll.
MAX_HEARD_STEP_MS = 1500
class _Listen:
"""How much of the current track has actually been heard."""
__slots__ = ("key", "track", "started", "heard", "last_pos")
def __init__(self, key, track, start_ms: int):
self.key = key
self.track = track
self.started = None # local time of the first audible step
self.heard = 0
self.last_pos = start_ms
def make_shuffle_order(count: int, start_index: int) -> list[int]:
"""A random permutation of range(count) that begins at start_index."""
@@ -401,6 +419,10 @@ class Player(QObject):
track_finished = pyqtSignal(object) # Track played to the very end
track_unplayable = pyqtSignal(object, str) # skipped: sink can't decode it
sink_changed = pyqtSignal(object) # the new PlaybackSink
# One listen ended: (queue key, Track, local start datetime, ms heard,
# "finish" | "skip" | "stop" | "quit"). Feeds the Wrapped history; the
# listener decides whether it's kept and adds the context.
listen_ended = pyqtSignal(object, object, object, int, str)
# Signals relayed from whichever sink is active.
_SINK_SIGNALS = ("position_changed", "duration_changed", "state_changed",
@@ -425,6 +447,7 @@ class Player(QObject):
# journal.
self.track_resolver = None # Callable[[str], Track | None]
self._current_key = None
self._listen: _Listen | None = None
self._volume = 1.0 # logical 0..1; what the volume slider shows
self._local = LocalSink(self)
@@ -455,6 +478,11 @@ class Player(QObject):
def active_sink(self) -> PlaybackSink:
return self._sink
@property
def is_local(self) -> bool:
"""Playing through this computer's own output (not a Chromecast)."""
return self._sink is self._local
def provides_pcm(self) -> bool:
return self._sink.provides_pcm
@@ -497,6 +525,7 @@ class Player(QObject):
if self._shutdown_done:
return
self._shutdown_done = True
self._close_listen(listen_history.QUIT)
self._sink.shutdown()
if self._sink is not self._local:
# The local sink is kept alive across a swap so switching back is
@@ -614,6 +643,10 @@ class Player(QObject):
if self.is_playing():
self._sink.pause()
elif self._current_track is not None:
if self._listen is None:
# Replaying the last track after the queue ran out.
self._listen = _Listen(self._current_key, self._current_track,
self._sink.position_ms())
self._sink.play()
elif self._queue:
self._index = max(self._index, 0)
@@ -629,6 +662,7 @@ class Player(QObject):
self._sink.pause()
def stop(self):
self._close_listen(listen_history.STOP)
self._sink.stop()
self._current_track = None
self._current_key = None
@@ -708,6 +742,9 @@ class Player(QObject):
self._index = next_index
continue
self._close_listen(listen_history.SKIP)
start_ms = track.start_time if track.start_time > 0 else 0
self._listen = _Listen(key, track, start_ms)
self._current_track = track
self._current_key = key
# Arm the custom stop time for this track. It's honored only when
@@ -755,6 +792,7 @@ class Player(QObject):
def _on_position(self, position):
"""Stop a track at its custom stop time and move on, mirroring a
natural finish (play count + scrobble)."""
self._account_heard(position)
if self._stop_at_ms and position >= self._stop_at_ms:
self._stop_at_ms = 0 # one-shot: don't re-fire while advancing
track = self._current_track
@@ -773,8 +811,30 @@ class Player(QObject):
self._counted_finish_id = key
if not isinstance(key, str):
self._manager.record_play(track.track_id)
if track is self._current_track:
self._close_listen(listen_history.FINISH)
self.track_finished.emit(track)
# ---- listen accounting ----
def _account_heard(self, position: int):
listen = self._listen
if listen is None:
return
step = position - listen.last_pos
listen.last_pos = position
if 0 < step <= MAX_HEARD_STEP_MS:
if listen.started is None:
listen.started = listen_history.local_now()
listen.heard += step
def _close_listen(self, how: str):
listen, self._listen = self._listen, None
if listen is None or not listen.heard:
return
self.listen_ended.emit(listen.key, listen.track, listen.started,
listen.heard, how)
def _resolve(self, key):
if isinstance(key, str):
return self.track_resolver(key) if self.track_resolver else None