refrain 0.4.6__tar.gz → 0.5.2__tar.gz

{refrain-0.4.6 → refrain-0.5.2}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -13,7 +13,7 @@ body:
     attributes:
       label: Refrain version
       description: Run `refrain --version` or check the bottom-right of the settings window.
-      placeholder: "0.4.6"
+      placeholder: "0.5.2"
     validations:
       required: true
 

{refrain-0.4.6 → refrain-0.5.2}/.github/workflows/security.yml

@@ -78,7 +78,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run TruffleHog
-        uses: trufflesecurity/trufflehog@bcfcf73aaf4759d4dadc2783177c245a02792318  # v3.97.0
+        uses: trufflesecurity/trufflehog@363923b901c911a9164f50b6c423f47c15372b1c  # v3.97.4
         with:
           # --only-verified: a secret only counts as flagged when TruffleHog
           # successfully validates it against the live service. Drops the

{refrain-0.4.6 → refrain-0.5.2}/.gitignore

@@ -31,11 +31,6 @@ env/
 *.swo
 .DS_Store
 
-# AI assistants
-.claude*/
-.cursor/
-.aider*
-
 # Local config / runtime
 *.log
 .refrain.local.toml

{refrain-0.4.6 → refrain-0.5.2}/CHANGELOG.md

@@ -7,6 +7,199 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-09-18
+
+A release about the gaps. Songs the iTunes catalog doesn't know — about
+one in ten here — were never scrobbled from the browser and had no end
+time on Discord; Refrain now measures their length from whole plays. A
+stream or video playing over Bluetooth no longer passes for a song,
+Discord no longer shows nothing when the tab's address has a space in
+it, and Last.fm neither scrobbles a long song twice nor loses one around
+a restart, an invalid session or an account switch.
+
+### Fixed
+
+- **The desktop entries named invalid categories.** `Audio` requires
+  `AudioVideo`, which was missing — `desktop-file-validate` reports that
+  as an error set to become fatal — and `Audio` next to `Network` put
+  Refrain in two main categories, so a menu could list it twice. The
+  menu entry, the Flatpak entry and the autostart entry now all say
+  `AudioVideo;Audio;Music;`, and an autostart entry written by an
+  earlier version gets the new categories on the next start. Nothing
+  else in it changes — not the launcher it points at, and not a switch
+  the desktop set to keep Refrain from starting with the session.
+- **The GitHub logo in the Settings footer was hard to see on a dark
+  theme.** Qt draws the logo's `currentColor` as black whatever the
+  theme; it now takes the theme's text colour, like the version beside
+  it, and follows a theme change while the window is open.
+- **A long song could be scrobbled twice after a restart.** If the first
+  poll after starting saw no song yet, the play saved on quit was thrown
+  away, the song counted again from zero and was queued a second time —
+  or, not having counted yet, was never scrobbled at all. Quitting
+  before that first poll also deleted the saved play.
+- **Pausing on an iPad could split the play in two.** The iPad reports
+  0:00 for a moment when paused; that was passed to the history and to
+  Last.fm as the player's position, which read as the song starting over
+  — a second history entry, and on songs over eight minutes a second
+  scrobble.
+- **The elapsed time could run ahead or fall behind for a whole song.**
+  A stream position that stalled and then caught up was taken for a
+  seek; a single poll that saw no song made a browser source's next
+  segment look like the song's start; and an album that arrived a few
+  seconds after the title restarted the clock at 0:00.
+- **Scrobbles were lost while the Last.fm session was invalid.** The log
+  promised they would submit after reconnecting, but songs played in the
+  meantime were never queued. They are now.
+- **Queued scrobbles could go to the wrong account.** After connecting a
+  different Last.fm account, plays still in the offline queue were sent
+  to it; they now stay with the account they were heard under.
+- **Quitting could wait on Last.fm for up to ten seconds**, and the
+  scrobble queue was written readable by other users — it is owner-only
+  now, like the history.
+- **Other apps couldn't read what Refrain was playing when the title had
+  an umlaut** — or any other letter beyond ASCII. Refrain's MPRIS track
+  ID kept it, which a D-Bus object path doesn't allow, and every read of
+  the metadata failed.
+- **Songs the iTunes catalog doesn't know were never scrobbled from the
+  browser.** Since 0.5.1 the media segments plasma reports no longer pass
+  for a song's length, and without a catalog match that left none at all —
+  no scrobble, no end time on Discord, and nothing in the history under
+  four minutes. Refrain now measures such a song itself: a play it watched
+  from the start to an end the player reached on its own is as long as the
+  song, and two plays that agree settle it. Kept under a hash of the
+  title, artist and album, so the file holds no song titles.
+- **Discord showed nothing while a song without a catalog match played
+  from Apple Music's search page.** Plasma reports the tab's address with
+  plain spaces in it, the "Listen on Apple Music" button took it as its
+  link, and Discord refused the whole activity over the malformed link.
+  The link is encoded now, and one that still isn't valid drops only the
+  button.
+- **A stream or video playing over Bluetooth passed for a song.** A Twitch
+  stream on an iPad went to Discord and, four minutes in, into the history
+  under its channel's name. Refrain now reads which app is playing and
+  takes music apps only; an app it doesn't know counts when its track has
+  a length, which a live stream doesn't.
+- **A browser tab with "Apple Music" anywhere in its title counted as the
+  Apple Music tab**, so a video about Apple Music could decide whether
+  Refrain showed the music as playing or paused.
+
+## [0.5.1] - 2026-09-15
+
+A release about what you played. A new *Recently played* window lists the
+last songs Refrain saw, and every play is now one row and one scrobble —
+on repeat, across a restart of Refrain, or through a crash. Plasma's
+browser integration turned out to report Apple Music's looping artwork
+video rather than the music; Refrain now asks the Apple Music tab itself
+whether it is playing, which also makes Play work again after a pause.
+
+Also: the crash behind Refrain simply vanishing, Plasma's Stop starting
+playback, Settings → Apply restarting a song's Last.fm count, and covers
+and lengths for far more songs. (0.5.0 was never released.)
+
+### Added
+
+- **Recently played.** A new window, opened from the tray menu or from
+  Settings → History, lists the last songs Refrain saw: cover, title,
+  artist and album, the time and day each one started, where it came
+  from — Apple Music in which browser, or which Bluetooth device — its
+  length, and whether it went to Last.fm. Every song is a link to its
+  Apple Music page — or, where Refrain never learned the page, to an
+  Apple Music search for it — and opens in the browser it played in
+  while that browser is still running; a right-click takes a single song
+  out of the list. A song shows up the moment it
+  starts playing and stays once it counts as listened: half its length
+  or four minutes, the rule Last.fm uses, so skipping through a playlist
+  leaves nothing behind. The list lives on this machine only
+  (`$XDG_STATE_HOME/refrain/history.json`, owner-only), which is why it
+  keeps running with the privacy mode set to *Off*. Settings → History
+  turns it off entirely — deleting the stored list — and sets how many
+  songs to keep, from 10 to 100; 30 by default. The song playing when
+  Refrain stops — or crashes — is saved with how much of it was heard
+  and where it was, and carries on as the same row if it is still on,
+  further along, when Refrain comes back. A song heard through and
+  played again is listed once per play.
+
+### Fixed
+
+- **After a restart mid-song, the elapsed time fell back every ten
+  seconds.** Plasma's browser integration reports the media segment the
+  page has buffered — position 0 to 10 s, over and over — and at a
+  constant segment length nothing gave it away. A source length under
+  30 s on a song the catalog knows to be longer is now never taken as the
+  song's position: the time counts on from the song's start, or stays
+  hidden when Refrain came up in the middle of it.
+- **Paused in the browser, Apple Music still counted as playing — and
+  Play didn't start it again.** KDE's browser integration takes the
+  song's title from the page but its state from whatever video plays on
+  it: Apple Music's looping artwork. That kept "playing" through a pause,
+  so the time ran on, the history and Last.fm counted the pause as
+  listened, and its Play/Pause toggle could only pause. The browser's own
+  entry for the Apple Music tab now decides playing or paused, and gets
+  Play/Pause first.
+- **Settings → Apply started the song's Last.fm count over.** Apply
+  sends the whole configuration, and the Scrobbler dropped the play in
+  progress on every one of them — for a change on any tab. Applied near
+  the end of a song, the song was never scrobbled. The play in progress
+  is now only dropped when the Last.fm account itself changes.
+- **Restarting Refrain mid-song could scrobble the song twice.** A play
+  that counted was queued on quit, and after the restart the Scrobbler
+  counted the same song again from zero — a long song got a second
+  scrobble for what was heard afterwards, and a shorter one was
+  scrobbled under the time of the restart. The play in progress is now
+  kept across a restart (`scrobble_current.json`, like the history's):
+  the same play carries on, under the time it began, and is never
+  queued twice. One that counted before a crash is still scrobbled.
+- **"Apple Music – Webplayer" could pass for a song.** With no song
+  loaded, KDE's browser integration reports the page's title as the
+  track — no artist — and calls it playing. A title like that is no
+  longer taken for a song, so it can't reach Discord or the history.
+- **A song on repeat was scrobbled only once, and lost its time.**
+  Last.fm counts every play, but the Scrobbler saw one long play for as
+  long as the title stayed the same. A song that has counted and begins
+  again is now a new play, with a scrobble of its own. The player shows
+  it: an ordinary one jumps back to zero; Apple Music in the browser,
+  through Plasma, reports the song's own length at position zero for a
+  moment; a phone over Bluetooth set to repeat-one kept counting its
+  position on across the loop (5:13 into a 3:36 song), which hid the
+  elapsed time after the first play — it now counts from the start of
+  each loop.
+
+- **The tray icon flashed to "paused" at every song change.** Apple
+  Music's web player reports a pause for a moment between two songs.
+  The icon and the Play/Pause entry now only follow a pause that lasts
+  two seconds; going back to playing still shows at once.
+- **Plasma's "Stop" started the music when it was paused.** Right-click
+  Refrain in the task manager and Plasma offers its media controls;
+  Play, Pause and Stop all toggled playback blindly, so each one did the
+  opposite of what it said whenever the music was already in the state
+  it asked for. They now only act when that gets them there.
+- **Refrain could die out of nowhere.** The daemon thread polled the
+  players over the same D-Bus connection the main thread dispatches for
+  the published MPRIS player, and dbus-glib keeps that connection's
+  bookkeeping without locks. Two threads on it at once corrupted the
+  heap, and the process aborted with `malloc(): unaligned tcache chunk
+  detected` — the "Refrain was simply gone" that the log shows as a
+  start without a stop before it. The sources now keep private
+  connections of their own, the MPRIS player is only touched from the
+  thread that dispatches it, and Plasma's play/pause/skip requests are
+  handed to the daemon thread instead of running the sources from the
+  main one. Should a crash still happen, `crash.log` next to the log
+  now holds every thread's Python stack.
+- **About one song in ten had no cover and no length.** The catalog
+  lookup asked the US store only, with the title as given — "feat."
+  credits, remaster tags and all — and took the first result without
+  checking it. German releases missing from the US store, songs
+  crediting several artists and titles with a "(feat. …)" found
+  nothing; others got a stranger's cover (a Chinese ballad on a German
+  rap track). The lookup now asks the store of the desktop's own
+  country first, strips those tags, falls back to the first of several
+  artists, and only takes a result whose artist *and* title match. A
+  lookup that fails because iTunes can't be reached is retried a minute
+  later instead of leaving the song without a cover for the whole
+  session, a song the catalog doesn't have is asked about again after
+  three days instead of never, and covers cached by the old lookup are
+  looked up once more.
+
 ## [0.4.6] - 2026-08-26
 
 A release about the clock. Apple Music's web player and Plasma's browser
@@ -1576,7 +1769,9 @@ with a proper, installable Linux app.
   pip-audit, trufflehog, release), Dependabot, issue + PR templates,
   `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`.
 
-[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.4.6...HEAD
+[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.5.2...HEAD
+[0.5.2]: https://github.com/Rockykln/refrain/compare/v0.5.1...v0.5.2
+[0.5.1]: https://github.com/Rockykln/refrain/compare/v0.4.6...v0.5.1
 [0.4.6]: https://github.com/Rockykln/refrain/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/Rockykln/refrain/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/Rockykln/refrain/compare/v0.4.3...v0.4.4

{refrain-0.4.6 → refrain-0.5.2}/CONTRIBUTING.md

@@ -124,8 +124,19 @@ descriptions instead.
 
 User-visible strings live wrapped in `tr()` calls; translations are
 kept in `src/refrain/i18n/refrain_<lang>.ts` (Qt Linguist format).
-English is the source language. German is the only translation we
-ship complete right now.
+English is the source language; every shipped language is complete.
+
+Strings that contain a number use Qt's plural forms —
+`self.tr("Last %n song(s)", "", count)` — never a sentence assembled
+around the number, because Russian and Polish change the noun's ending
+with it. Two things follow:
+
+- Only `self.tr(…)` with the count as the third argument is extracted
+  as a plural. `QCoreApplication.translate(…, n)` isn't, and neither is
+  any call whose arguments contain `//`.
+- `refrain_en.ts` holds only the English plural forms (`lupdate
+  -pluralonly`, which `make i18n-update` runs for it) — without it
+  English would read "Last 12 song(s)".
 
 To add a new language end-to-end:
 

{refrain-0.4.6 → refrain-0.5.2}/Makefile

@@ -54,11 +54,18 @@ i18n:
 
 # Refresh the .ts source-string list from the current Python sources,
 # preserving existing translations. Use after wrapping new strings in tr().
+# English is the source language, so refrain_en.ts holds only the plural
+# forms of the %n strings (-pluralonly) — without it English would read
+# "Last 12 song(s)".
 i18n-update:
 	@"$(LUPDATE)" -no-obsolete \
 		src/refrain/app.py \
 		src/refrain/ui/*.py \
-		-ts $(wildcard src/refrain/i18n/refrain_*.ts)
+		-ts $(filter-out %_en.ts,$(wildcard src/refrain/i18n/refrain_*.ts))
+	@"$(LUPDATE)" -no-obsolete -pluralonly \
+		src/refrain/app.py \
+		src/refrain/ui/*.py \
+		-ts src/refrain/i18n/refrain_en.ts
 	@$(MAKE) i18n
 
 # Remove anything that pytest, ruff, hatch, pip, or coverage might leave

{refrain-0.4.6 → refrain-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: refrain
-Version: 0.4.6
+Version: 0.5.2
 Summary: Discord Rich Presence for Apple Music on Linux
 Project-URL: Homepage, https://github.com/Rockykln/refrain
 Project-URL: Repository, https://github.com/Rockykln/refrain
@@ -58,6 +58,8 @@ streaming from your phone over Bluetooth.
 - Optionally **scrobbles to Last.fm** alongside Discord (opt-in, with a
   crash-safe offline queue).
 - Lives in your **system tray** with Play/Pause/Next/Previous controls.
+- Keeps a **recently played** list — cover, time, source — of the last
+  30 songs by default, on your machine only.
 - Provides a **settings window** (PySide6) for everything users typically want
   to tweak — privacy mode, sources, autostart, Bluetooth device picker.
 
@@ -212,6 +214,12 @@ scrobble_now_playing = true        # also send the ephemeral "now playing" indic
 # NOTE: the Last.fm shared secret and session key are credentials and
 # are deliberately NOT stored here. They live in your OS keyring
 # (KWallet / GNOME Keyring), encrypted at rest — see "Last.fm" below.
+
+[history]
+enabled = true                     # the "Recently played" list; false also deletes what it stored
+max_entries = 30                   # songs kept, 1–100 (Settings offers 10, 20, 30, 50, 75, 100)
+window_width = 0                   # the history window's size when last closed; 0 = default
+window_height = 0
 ```
 
 Per-source `client_id_*` fields let Apple Music render under one Discord
@@ -224,7 +232,10 @@ another (with a generic Bluetooth glyph). Empty falls back to the default
 Refrain publishes itself as `org.mpris.MediaPlayer2.refrain` on the session
 bus, so KDE Plasma's panel media-controls applet (and KDE Connect, GNOME
 Shell, Mako, …) drive the same Play/Pause/Next/Previous as the tray and
-render the same track Discord renders.
+render the same track Discord renders. Plasma also offers these controls
+when you right-click Refrain in the task manager, including a *Stop*
+that it adds for every player — Apple Music has no stop, so there it
+pauses, and does nothing when the music is already paused.
 
 ## Tray
 
@@ -248,6 +259,7 @@ no unicode-glyph prefixes.
 | Play / Pause      | Toggle on the active source (label follows playback state)|
 | Next              | Skip forward on the active source                         |
 | Update available — vX.Y.Z | Only visible when a newer release exists          |
+| Recently played…  | Open the history window (hidden while the history is off) |
 | Settings…         | Open the settings window                                  |
 | Live log…         | Open the live-log window                                  |
 | Restart Refrain   | Cleanly stop and re-launch (release D-Bus name + RPC, exec the same binary) |
@@ -284,26 +296,65 @@ the background.
       <img src="docs/screenshots/settings-lastfm.png" alt="Settings — Last.fm" width="420"/>
       <br/><sub>Opt-in scrobbling, API key + secret, connect / disconnect an account</sub>
     </td>
+    <td align="center">
+      <b>History</b><br/>
+      <img src="docs/screenshots/settings-history.png" alt="Settings — History" width="420"/>
+      <br/><sub>Recently played on or off, how many songs to keep</sub>
+    </td>
+  </tr>
+  <tr>
     <td align="center">
       <b>Updates</b><br/>
       <img src="docs/screenshots/settings-updates.png" alt="Settings — Updates" width="420"/>
       <br/><sub>Auto-check, last-checked, manual <i>Check for updates now</i></sub>
     </td>
-  </tr>
-  <tr>
     <td align="center">
       <b>Advanced</b><br/>
       <img src="docs/screenshots/settings-advanced.png" alt="Settings — Advanced" width="420"/>
       <br/><sub>Poll interval, notification delay, cover cache size, language, log level, restart, reset, uninstall</sub>
     </td>
+  </tr>
+  <tr>
     <td align="center">
       <b>Legal</b><br/>
       <img src="docs/screenshots/legal.png" alt="Legal notice" width="420"/>
       <br/><sub>Licence, trademark and affiliation notices — the <i>Legal</i> button in the footer</sub>
     </td>
+    <td></td>
   </tr>
 </table>
 
+## Recently played
+
+<p align="center">
+  <img src="docs/screenshots/history.png" alt="Recently played" width="520"/>
+</p>
+
+*Tray → Recently played…* lists the last songs Refrain saw — 30 by
+default, up to 100 — with cover, length, when each started, where it
+came from (which browser, which Bluetooth device) and whether it went to
+Last.fm. A song shows up the moment it plays and stays once it counts
+as listened: half its length or four minutes, the rule Last.fm uses, so
+skipping through a playlist leaves nothing behind. Restarting Refrain
+mid-song doesn't lose or duplicate it; a song heard through and played
+again is listed twice, once per play.
+
+- Click a song to open it in Apple Music — in the browser it played in,
+  while that one is still open; a search when the song's page isn't
+  known.
+- Right-click to copy artist and title or to remove the song from the
+  list; *Clear history…* empties it.
+- From ten songs on there's a search over title, artist and album —
+  blind to case and accents, found words marked — and with more than
+  one source a filter by source. <kbd>Ctrl</kbd>+<kbd>F</kbd> jumps into
+  the search, <kbd>Esc</kbd> clears it.
+- The window opens at the size you last left it.
+
+The list stays on your machine (`history.json`, readable only by you)
+and is never sent anywhere, so the privacy mode doesn't affect it.
+*Settings → History* turns it off — which deletes the file — or changes
+how many songs it keeps.
+
 ## Notifications
 
 When a track changes, Refrain fires a desktop notification with the album
@@ -355,7 +406,9 @@ A track is scrobbled once you've played at least half of it, or four
 minutes (Last.fm's rule), and only if it's longer than 30 s. Scrobbles
 are queued to disk the instant they qualify, so being offline, a
 Last.fm outage, or quitting mid-song never loses them — they submit on
-the next opportunity. Privacy mode `Off` silences scrobbling too.
+the next opportunity. Restarting Refrain mid-song carries the play on
+instead of counting it again, and a song on repeat is scrobbled once per
+play. Privacy mode `Off` silences scrobbling too.
 
 Full walkthrough + troubleshooting: [`docs/lastfm.md`](docs/lastfm.md).
 
@@ -387,7 +440,11 @@ entry + icon.)
 |---------------|---------------------------------------------|
 | Config        | `$XDG_CONFIG_HOME/refrain/config.toml`      |
 | Scrobble queue| `$XDG_STATE_HOME/refrain/scrobble_queue.jsonl` |
+| Scrobble in progress | `$XDG_STATE_HOME/refrain/scrobble_current.json` |
+| Recently played | `$XDG_STATE_HOME/refrain/history.json`    |
+| Measured song lengths | `$XDG_STATE_HOME/refrain/song_lengths.txt` |
 | Logs          | `$XDG_STATE_HOME/refrain/refrain.log` (rotates) |
+| Crash stacks  | `$XDG_STATE_HOME/refrain/crash.log` (written only if Refrain crashes) |
 | Cover cache   | `$XDG_CACHE_HOME/refrain/covers/*.txt`      |
 | Autostart     | `$XDG_CONFIG_HOME/autostart/refrain.desktop` (when enabled) |
 
@@ -420,7 +477,9 @@ directly to that provider:
   your **OS keyring** (encrypted at rest), never in `config.toml`.
 
 `Privacy → Off` is the global kill switch (no Discord status, no
-scrobbling) while keeping the tray + controls running.
+scrobbling) while keeping the tray + controls running. The *Recently
+played* list never leaves your machine, so it has its own switch in
+*Settings → History* instead.
 
 Full data-flow, retention and erasure details — written to GDPR
 transparency expectations — are in [`PRIVACY.md`](PRIVACY.md).

{refrain-0.4.6 → refrain-0.5.2}/PRIVACY.md

@@ -37,8 +37,12 @@ receiving service's own privacy policy and your account there.
 |---|---|---|
 | Now-playing metadata (title, artist, album, position) read from your media player via D-Bus / BlueZ AVRCP | Drive the tray, notifications, the published MPRIS player | In memory; reflected in the tray |
 | Listening history lines (track changes, scrobble events) | Diagnostics / live log | `$XDG_STATE_HOME/refrain/refrain.log` — rotating, ≤ 4 × 1 MB, plaintext, local only |
+| Start stamps, and Python stack traces if Refrain ever crashes | Diagnosing crashes inside Qt or D-Bus | `$XDG_STATE_HOME/refrain/crash.log` — ≤ 256 KB, then started afresh; written **owner-only (`0600`)**; local only |
 | Album-cover images + iTunes URL/duration cache | Avoid re-fetching covers | `$XDG_CACHE_HOME/refrain/` — capped (default 200), oldest pruned |
-| Pending scrobbles (artist/track/album/timestamp) | Survive offline / restart until submitted to Last.fm | `$XDG_STATE_HOME/refrain/scrobble_queue.jsonl` — capped at 1000, `0600` semantics, removed once submitted |
+| Pending scrobbles (artist/track/album/timestamp, and the Last.fm username they were heard under) | Survive offline / restart until submitted to Last.fm — and never to another account | `$XDG_STATE_HOME/refrain/scrobble_queue.jsonl` — capped at 1000, written **owner-only (`0600`)**, removed once submitted |
+| The song being scrobbled right now (artist/track/album, when it began, how much of it was heard, where the player had it) | Carry that play on across a restart of Refrain instead of counting it — or scrobbling it — twice | `$XDG_STATE_HOME/refrain/scrobble_current.json` — one song, written **owner-only (`0600`)**, removed when the song ends; only while Last.fm scrobbling is on |
+| Recently played (title, artist, album, cover URL, source + browser/device name, start time, length, whether it was scrobbled) | The *Recently played* window | `$XDG_STATE_HOME/refrain/history.json` — the last 30 songs by default (10–100), written **owner-only (`0600`)**; *Settings → History* turns it off and deletes the file |
+| How long a song ran, under a hash of its title, artist and album | Give songs the iTunes catalog doesn't know a length, so they can still be scrobbled | `$XDG_STATE_HOME/refrain/song_lengths.txt` — at most 1000 songs, written **owner-only (`0600`)**; holds **no titles**, only hashes and seconds |
 | Preferences + the *public* Discord/Last.fm application IDs | Your settings | `$XDG_CONFIG_HOME/refrain/config.toml` — written **owner-only (`0600`)**; contains **no secrets** |
 | Last.fm **shared secret** and **session token** | Authenticate scrobbling | **OS keyring** (KWallet / GNOME Keyring), encrypted at rest; or, only if no keyring exists, a `0600` owner-only `secrets.json`. **Never** in `config.toml`; never logged |
 

{refrain-0.4.6 → refrain-0.5.2}/README.md

@@ -24,6 +24,8 @@ streaming from your phone over Bluetooth.
 - Optionally **scrobbles to Last.fm** alongside Discord (opt-in, with a
   crash-safe offline queue).
 - Lives in your **system tray** with Play/Pause/Next/Previous controls.
+- Keeps a **recently played** list — cover, time, source — of the last
+  30 songs by default, on your machine only.
 - Provides a **settings window** (PySide6) for everything users typically want
   to tweak — privacy mode, sources, autostart, Bluetooth device picker.
 
@@ -178,6 +180,12 @@ scrobble_now_playing = true        # also send the ephemeral "now playing" indic
 # NOTE: the Last.fm shared secret and session key are credentials and
 # are deliberately NOT stored here. They live in your OS keyring
 # (KWallet / GNOME Keyring), encrypted at rest — see "Last.fm" below.
+
+[history]
+enabled = true                     # the "Recently played" list; false also deletes what it stored
+max_entries = 30                   # songs kept, 1–100 (Settings offers 10, 20, 30, 50, 75, 100)
+window_width = 0                   # the history window's size when last closed; 0 = default
+window_height = 0
 ```
 
 Per-source `client_id_*` fields let Apple Music render under one Discord
@@ -190,7 +198,10 @@ another (with a generic Bluetooth glyph). Empty falls back to the default
 Refrain publishes itself as `org.mpris.MediaPlayer2.refrain` on the session
 bus, so KDE Plasma's panel media-controls applet (and KDE Connect, GNOME
 Shell, Mako, …) drive the same Play/Pause/Next/Previous as the tray and
-render the same track Discord renders.
+render the same track Discord renders. Plasma also offers these controls
+when you right-click Refrain in the task manager, including a *Stop*
+that it adds for every player — Apple Music has no stop, so there it
+pauses, and does nothing when the music is already paused.
 
 ## Tray
 
@@ -214,6 +225,7 @@ no unicode-glyph prefixes.
 | Play / Pause      | Toggle on the active source (label follows playback state)|
 | Next              | Skip forward on the active source                         |
 | Update available — vX.Y.Z | Only visible when a newer release exists          |
+| Recently played…  | Open the history window (hidden while the history is off) |
 | Settings…         | Open the settings window                                  |
 | Live log…         | Open the live-log window                                  |
 | Restart Refrain   | Cleanly stop and re-launch (release D-Bus name + RPC, exec the same binary) |
@@ -250,26 +262,65 @@ the background.
       <img src="docs/screenshots/settings-lastfm.png" alt="Settings — Last.fm" width="420"/>
       <br/><sub>Opt-in scrobbling, API key + secret, connect / disconnect an account</sub>
     </td>
+    <td align="center">
+      <b>History</b><br/>
+      <img src="docs/screenshots/settings-history.png" alt="Settings — History" width="420"/>
+      <br/><sub>Recently played on or off, how many songs to keep</sub>
+    </td>
+  </tr>
+  <tr>
     <td align="center">
       <b>Updates</b><br/>
       <img src="docs/screenshots/settings-updates.png" alt="Settings — Updates" width="420"/>
       <br/><sub>Auto-check, last-checked, manual <i>Check for updates now</i></sub>
     </td>
-  </tr>
-  <tr>
     <td align="center">
       <b>Advanced</b><br/>
       <img src="docs/screenshots/settings-advanced.png" alt="Settings — Advanced" width="420"/>
       <br/><sub>Poll interval, notification delay, cover cache size, language, log level, restart, reset, uninstall</sub>
     </td>
+  </tr>
+  <tr>
     <td align="center">
       <b>Legal</b><br/>
       <img src="docs/screenshots/legal.png" alt="Legal notice" width="420"/>
       <br/><sub>Licence, trademark and affiliation notices — the <i>Legal</i> button in the footer</sub>
     </td>
+    <td></td>
   </tr>
 </table>
 
+## Recently played
+
+<p align="center">
+  <img src="docs/screenshots/history.png" alt="Recently played" width="520"/>
+</p>
+
+*Tray → Recently played…* lists the last songs Refrain saw — 30 by
+default, up to 100 — with cover, length, when each started, where it
+came from (which browser, which Bluetooth device) and whether it went to
+Last.fm. A song shows up the moment it plays and stays once it counts
+as listened: half its length or four minutes, the rule Last.fm uses, so
+skipping through a playlist leaves nothing behind. Restarting Refrain
+mid-song doesn't lose or duplicate it; a song heard through and played
+again is listed twice, once per play.
+
+- Click a song to open it in Apple Music — in the browser it played in,
+  while that one is still open; a search when the song's page isn't
+  known.
+- Right-click to copy artist and title or to remove the song from the
+  list; *Clear history…* empties it.
+- From ten songs on there's a search over title, artist and album —
+  blind to case and accents, found words marked — and with more than
+  one source a filter by source. <kbd>Ctrl</kbd>+<kbd>F</kbd> jumps into
+  the search, <kbd>Esc</kbd> clears it.
+- The window opens at the size you last left it.
+
+The list stays on your machine (`history.json`, readable only by you)
+and is never sent anywhere, so the privacy mode doesn't affect it.
+*Settings → History* turns it off — which deletes the file — or changes
+how many songs it keeps.
+
 ## Notifications
 
 When a track changes, Refrain fires a desktop notification with the album
@@ -321,7 +372,9 @@ A track is scrobbled once you've played at least half of it, or four
 minutes (Last.fm's rule), and only if it's longer than 30 s. Scrobbles
 are queued to disk the instant they qualify, so being offline, a
 Last.fm outage, or quitting mid-song never loses them — they submit on
-the next opportunity. Privacy mode `Off` silences scrobbling too.
+the next opportunity. Restarting Refrain mid-song carries the play on
+instead of counting it again, and a song on repeat is scrobbled once per
+play. Privacy mode `Off` silences scrobbling too.
 
 Full walkthrough + troubleshooting: [`docs/lastfm.md`](docs/lastfm.md).
 
@@ -353,7 +406,11 @@ entry + icon.)
 |---------------|---------------------------------------------|
 | Config        | `$XDG_CONFIG_HOME/refrain/config.toml`      |
 | Scrobble queue| `$XDG_STATE_HOME/refrain/scrobble_queue.jsonl` |
+| Scrobble in progress | `$XDG_STATE_HOME/refrain/scrobble_current.json` |
+| Recently played | `$XDG_STATE_HOME/refrain/history.json`    |
+| Measured song lengths | `$XDG_STATE_HOME/refrain/song_lengths.txt` |
 | Logs          | `$XDG_STATE_HOME/refrain/refrain.log` (rotates) |
+| Crash stacks  | `$XDG_STATE_HOME/refrain/crash.log` (written only if Refrain crashes) |
 | Cover cache   | `$XDG_CACHE_HOME/refrain/covers/*.txt`      |
 | Autostart     | `$XDG_CONFIG_HOME/autostart/refrain.desktop` (when enabled) |
 
@@ -386,7 +443,9 @@ directly to that provider:
   your **OS keyring** (encrypted at rest), never in `config.toml`.
 
 `Privacy → Off` is the global kill switch (no Discord status, no
-scrobbling) while keeping the tray + controls running.
+scrobbling) while keeping the tray + controls running. The *Recently
+played* list never leaves your machine, so it has its own switch in
+*Settings → History* instead.
 
 Full data-flow, retention and erasure details — written to GDPR
 transparency expectations — are in [`PRIVACY.md`](PRIVACY.md).

{refrain-0.4.6 → refrain-0.5.2}/ROADMAP.md

@@ -536,16 +536,45 @@ were tracked internally as "v0.2.8" but never separately tagged.
   connected"; the Connect button no longer treats an incomplete
   leftover as Disconnect. +13 tests (pure + offscreen).
 
+## Done — v0.5.1
+
+- **Recently played.** A history window (tray → *Recently played…*)
+  with cover, length, start time, source and Last.fm state per song;
+  Last.fm's rule for what counts; a click opens the song in Apple
+  Music in the browser that played it; search and a source filter;
+  remove single songs; survives restarts and crashes mid-song without
+  losing or duplicating the song. Own settings tab: on/off (off
+  deletes) and 10–100 songs.
+- **The crash behind "Refrain was simply gone".** Two threads shared
+  one dbus-glib connection; the daemon's sources now keep private
+  connections, the published MPRIS player is only touched from its
+  dispatching thread, and `crash.log` records every thread's Python
+  stack if anything still crashes.
+- **Cover and length for far more songs.** The catalog lookup asks the
+  local store first, strips "feat." and remaster tags, falls back to
+  the first artist, checks artist *and* title, retries network
+  failures and lets misses expire.
+- **Plasma's Stop no longer starts playback**, and Play/Pause only act
+  towards the state they ask for.
+- **One play, one row, one scrobble.** A song on repeat counts once per
+  play — in the browser, over Bluetooth, and on any player that jumps
+  back to the start. A restart or a crash mid-song carries the play on,
+  for the history and Last.fm alike (`scrobble_current.json`), and
+  Settings → Apply no longer starts a song's Last.fm count over.
+- **Pausing in the browser is seen as a pause.** Plasma's browser
+  integration follows Apple Music's looping artwork video, not the
+  music; the tab's own MPRIS entry now decides playing or paused and
+  takes Play/Pause. Its segment positions are no longer shown, which
+  stops the elapsed time falling back every ten seconds.
+- **Every shipped translation complete**, plural forms included
+  (English now carries its own plural catalog).
+
 ## Up next — v0.5.x
 
 - **Stable-release AUR build** that doesn't rely on the GitHub
   release tarball — switch to a `git`-source PKGBUILD pinned to the
   signed tag, so AUR users get the exact same commit the release
   workflow ships.
-- **Complete the translation catalogs** for the newly-wrapped
-  strings: regenerate the `.ts` / `.qm` files and bring every
-  shipped language back to 100% coverage via community PRs (the
-  code-side `tr()` wrapping landed in v0.3.0).
 
 ## Maybe — v0.5+