refrain 0.2.0__tar.gz → 0.2.3__tar.gz

{refrain-0.2.0 → refrain-0.2.3}/.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.1.4"
+      placeholder: "0.2.3"
     validations:
       required: true
 

{refrain-0.2.0 → refrain-0.2.3}/.github/workflows/release.yml

@@ -31,9 +31,13 @@ jobs:
       - name: Install + run tests (gate the release)
         run: |
           python -m pip install --upgrade pip
-          # System libs that dbus-python links against during build.
+          # System libs: dbus-python needs the *-dev headers at build
+          # time; PySide6.QtWidgets needs the EGL/xkbcommon/GL/fontconfig
+          # runtime libs to import (even under QT_QPA_PLATFORM=offscreen).
           sudo apt-get update
-          sudo apt-get install -y libdbus-1-dev libglib2.0-dev pkg-config
+          sudo apt-get install -y \
+            libdbus-1-dev libglib2.0-dev pkg-config \
+            libegl1 libxkbcommon0 libfontconfig1 libgl1
           # Install the package itself so the test imports get every
           # runtime dep (PySide6, pypresence, dbus-python) — without
           # this the new test_daemon_*.py files fail at collection.

{refrain-0.2.0 → refrain-0.2.3}/.github/workflows/tests.yml

@@ -26,11 +26,16 @@ jobs:
       - name: Install runtime + test dependencies
         # The newer tests import refrain modules that pull PySide6 /
         # pypresence / dbus-python at module load, so the runtime deps
-        # have to be present in CI too.
+        # have to be present in CI too. PySide6.QtWidgets requires the
+        # EGL / xkbcommon / GL / fontconfig system libs even when run
+        # under QT_QPA_PLATFORM=offscreen — without them the import
+        # itself fails before the test can opt out.
         run: |
           python -m pip install --upgrade pip
           sudo apt-get update
-          sudo apt-get install -y libdbus-1-dev libglib2.0-dev pkg-config
+          sudo apt-get install -y \
+            libdbus-1-dev libglib2.0-dev pkg-config \
+            libegl1 libxkbcommon0 libfontconfig1 libgl1
           pip install -e ".[dev]"
 
       - name: Compile-check every module

{refrain-0.2.0 → refrain-0.2.3}/.gitignore

@@ -32,13 +32,14 @@ env/
 .DS_Store
 
 # AI assistants
-.claude/
+.claude*/
 .cursor/
 .aider*
 
 # Local config / runtime
 *.log
 .refrain.local.toml
+*.local.md
 
 # Build artifacts (Flatpak / packaging)
 .flatpak-builder/

{refrain-0.2.0 → refrain-0.2.3}/CHANGELOG.md

@@ -7,6 +7,325 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-05-07
+
+A reliability + portability pass driven by hands-on testing across
+Ubuntu 25.04, CentOS Stream 10, and the existing CachyOS daily driver.
+No breaking changes — same config, same UI, same Python floor; the
+release just makes Refrain behave correctly on more distros and tightens
+a handful of long-standing rough edges.
+
+### Added
+
+- **Sandboxed Discord IPC bridge** — Snap and Flatpak Discord builds
+  publish their `discord-ipc-N` socket inside the sandbox tree instead
+  of `$XDG_RUNTIME_DIR`, so pypresence's stock discovery never finds it.
+  `_bridge_sandboxed_ipc_socket` probes the three known sandbox paths
+  (Flatpak instance dir, Flatpak config-dir layout, Snap path) and
+  symlinks the first hit into `$XDG_RUNTIME_DIR` before each connect
+  attempt. The welcome-dialog probe walks the same paths so first-run
+  diagnostics turn green on those installs.
+- **Cancel button in the update dialog** — `_apply_appimage` now
+  reads in 64 KiB chunks and polls a cancellation callback between
+  blocks. The dialog repurposes its "Later" button as "Cancel" while a
+  download is running, treats window-close as cancel, and removes the
+  partial `.AppImage.new` on abort. `UpdateResult.cancelled` lets the
+  dialog suppress the failure popup for user-initiated aborts.
+- **Orphan-download self-heal** — `cleanup_orphan_downloads` runs once
+  at startup so a `*.AppImage.new` left behind by a SIGKILL or power
+  loss mid-download doesn't sit next to the binary forever.
+- **Browser hints expanded** — Floorp, Waterfox, Mullvad Browser, Tor
+  Browser, and ungoogled-chromium are now in `DEFAULT_BROWSER_HINTS`
+  and surface as Settings checkboxes. Existing configs keep their
+  saved list (no auto-migration); the new entries appear unticked
+  until the user toggles them.
+- **iTunes-catalog duration as MPRIS override** — when MPRIS reports
+  an obviously-wrong `mpris:length` (Apple Music's preview-clip 14 s,
+  the playlist-total instead of the track length, or a stale value
+  carried over from the previous track), `pick_effective_duration_ms`
+  prefers the iTunes value if the two disagree by more than 15 % or
+  if MPRIS sits in the preview-clip band on a song iTunes considers
+  full-length. 8 new unit tests in `test_timing.py`. Discord no
+  longer briefly flips a 2:11 song's total to 0:14 / 7:21 mid-track.
+- **`docs/test-matrix.md`** — eight Tier-1 distros that together
+  cover ≈ 95 % of the realistic user base, plus Tier-2 spot-checks,
+  Tier-3 desktop / compositor combinations, and a six-step smoke
+  check ("tray + theme parity", "settings round-trip", "MPRIS to
+  Discord", "Bluetooth", "update-dialog cleanup", "restart cycle")
+  per row.
+
+### Changed
+
+- **Qt style plugin path augmentation also walks Debian / Ubuntu and
+  Fedora / RHEL / openSUSE layouts** — the v0.2.2 fix only checked
+  `/usr/lib/qt6/plugins` (Arch). pip / pipx installs on those distros
+  now also pick up the system Breeze plugin instead of falling back
+  to Fusion. Detection picks the first existing path among
+  `/usr/lib/<arch-triple>/qt6/plugins`, `/usr/lib64/qt6/plugins`,
+  `/usr/lib/qt6/plugins`.
+- **"No system tray" error** rewritten to cover GNOME, MATE, XFCE,
+  Hyprland / Sway / i3 / river, plus a "should work, try logging
+  out" hint for Plasma / Cinnamon / LXQt / Budgie. Previously the
+  fix advice was GNOME-AppIndicator-only, leaving everyone else to
+  guess.
+- **`refrain --install-desktop`** rewrites the installed
+  `Exec=` line to point at the actual launcher path of the running
+  install. Previously the bundled `Exec=refrain` only worked when
+  `refrain` was on `$PATH` (distro packages, pipx); AppImage and
+  source-checkout users got a broken menu entry. Resolution order
+  matches the autostart logic — extracted into the new
+  `autostart.resolve_exec_line(extra_args)` helper.
+- **MPRIS source duration handling decouples drift-resync from the
+  payload's preview-clip flag** — the drift-skip still keys off the
+  raw MPRIS-reported duration (because the position-field looping is
+  a property of MPRIS' preview-clip mode), but the Discord activity
+  payload's start/end fields key off the *effective* duration so a
+  brief MPRIS preview-clip glitch on a full-length song doesn't kill
+  the progress bar.
+- **PyGObject "not installed" warning fires once per startup**
+  instead of twice (eager init from `app.py` plus lazy fallback in
+  `MPRISServer.start` both used to log). The install hint also lists
+  the Fedora / RHEL / openSUSE package name (`python3-gobject`)
+  alongside the Arch and Debian ones.
+
+### Fixed
+
+- **Settings / Log / Update windows now carry the Refrain icon
+  explicitly** — on GNOME Wayland the title-based heuristic was
+  matching "Settings" against `org.gnome.Settings` and rendering the
+  gnome-control-center gear icon in the dock. The WelcomeDialog
+  already set its own icon; the other three top-level windows did
+  not.
+- **Bluetooth fast-fail when `org.bluez` is not present** — every
+  poll cycle on a VM / minimal install previously triggered a
+  `service_start_timeout=25000ms` D-Bus activation timeout, blocking
+  the worker thread for the full 25 s. `NameHasOwner` returns
+  instantly without triggering activation; the three entry points
+  (`read`, `_call_method`, `list_paired_devices`) now short-circuit
+  when the owner check returns False.
+- **Logging gaps closed in six places** — `setup_logging` runs
+  before `Config.load` so the "created default config" /
+  "config unreadable" messages reach the file log; toggling the log
+  level in Settings now applies to the running root logger via
+  `_apply_log_level` on `settings.applied`; the "no system tray"
+  early-exit gets a `log.error()`; `os.execvp`-based restarts call
+  `logging.shutdown()` first so the file handler's last buffered
+  line isn't lost; `Config.load` exception path adds `exc_info=True`;
+  `setup_logging` degrades gracefully when the XDG state dir or log
+  file can't be opened (console handler always attaches first).
+- **Catch-all exception branches in `DiscordRPC._ensure_connected`,
+  `MPRISSource._call_method_on`, and `BluetoothSource._call_method`**
+  now use `log.exception()` so the traceback lands in `refrain.log`
+  for unexpected errors. Previously they only logged `str(exc)`,
+  losing the stack exactly when it would matter most.
+- **Qt-internal log records routed through `refrain.qt`** instead
+  of the bare `qt` logger, so they parent under the project
+  namespace and show up alongside everything else when the user
+  filters by name.
+
+## [0.2.2] - 2026-05-06
+
+Two roadmap features pulled forward from v0.3 plus a substantial batch
+of reliability + UX work driven by live-testing the v0.2.1 build.
+
+### Added
+
+- **Multiple Discord profiles** — per-source `client_id_mpris` and
+  `client_id_bluetooth` fields in `Config.discord` plus matching UI in
+  Settings → General → Discord. Empty falls back to the default
+  Client ID. The daemon reconnects RPC under the source-specific ID
+  the moment the active source flips, so each source can render with
+  its own application name + uploaded artwork in the user's profile.
+- **MPRIS-server mode** — Refrain registers itself as
+  `org.mpris.MediaPlayer2.refrain` on the session bus so KDE Plasma's
+  panel media-controls applet (and KDE Connect, GNOME Shell, Mako
+  notifications, …) drive the same Play/Pause/Next/Previous as the
+  tray, and render the same track Discord renders. Implemented with
+  `dbus-python` + a daemon GLib main loop running in its own thread
+  so it doesn't compete with Qt's event loop. Falls back gracefully
+  when PyGObject isn't installed.
+- **iTunes track duration in the cover-fetcher cache** —
+  `trackTimeMillis` from the iTunes Search API rides along with
+  `cover_url` / `song_url` in the on-disk cache and exposed via
+  `CoverFetcher.get_duration_ms()`. Used as a defensive fallback when
+  MPRIS reports an obviously-wrong preview-clip length.
+- **Per-player MPRIS timeout blacklist** — if a property `Get` times
+  out we banish that bus name for 5 s so a hung player (typically
+  plasma-browser-integration on a frozen Apple Music tab) can't keep
+  eating the daemon's poll cycle one tick at a time.
+
+### Changed
+
+- **Welcome wizard** redesigned: 56×56 icon-badge + title + subtitle
+  header, intro line about tray-driven controls, dedicated diagnostics
+  card with two clearly-labelled rows (Discord / iTunes), Discord
+  Application ID block with helper text + readable italic styling
+  (the previous `palette(mid)` tone went invisible on Plasma Breeze
+  dark themes), Skip ghost-style on the left + Apply primary on the
+  right.
+- **Welcome wizard now opens Settings on confirmation** instead of
+  silently dropping into the tray, and reloads the Settings form so
+  the just-saved Discord Client ID appears in the input field.
+- **`compute_rpc_start_ts` accepts `is_preview_clip=True`** to skip
+  the drift-resync path on tracks whose MPRIS Position field loops
+  0→8s instead of advancing monotonically. Discord's elapsed counter
+  no longer resets every ~8 s on preview-mode playback.
+- **Reset-all-settings preserves every Discord Client ID** (default +
+  per-source mpris + per-source bluetooth) and the dialog text now
+  states this explicitly. Reset-dialog button labels are localised
+  (`Reset` / `Zurücksetzen` / `Cancel` / `Abbrechen`) instead of the
+  generic Yes / No.
+- **Default `notify_delay_ms` lowered from 600 ms to 0 ms** — cover
+  cache hits fire instantly, cache misses still get the existing
+  retry loop up to 2 s for the iTunes download.
+- **Default `poll_interval_ms` lowered from 1 s to 500 ms** — track
+  changes, position updates, and tray controls feel noticeably more
+  responsive without measurable CPU impact.
+- **Idle detection skips preview-clip-length tracks** (duration <
+  30 s) — Apple Music keeps reporting the same metadata while a
+  preview replays, and clearing Discord under those conditions hid
+  the activity mid-listen.
+- **Idle-detection log fires once per dangling-track instance**
+  instead of every poll tick.
+
+### Fixed
+
+- **Discord RPC connect now happens within ~1 s of the first track
+  detection** (was: up to 51 s). Root cause: dbus-python's default
+  25 s reply timeout combined with plasma-browser-integration
+  introspection hangs blocked the daemon's poll. Fix: pass
+  `introspect=False` on every `bus.get_object` and `timeout=0.5` on
+  every property `Get` and method dispatch.
+- **Discord RPC reconnects eagerly when the user changes their
+  Application ID** (welcome wizard or Settings → General). Previously
+  the new pipe wasn't established until the next *playing-state*
+  poll, so paused users sat there waiting forever.
+- **Skip / Previous reach Apple Music reliably**: dispatch tries
+  the browser-native MPRIS player (chromium / firefox) first, then
+  falls back to plasma-browser-integration. Plasma's wrapper claims
+  `CanGoNext=True` on Apple Music but its Next routes through a
+  flaky mediaSession path; the browser-native player reaches the
+  same handler via a more reliable path.
+- **Per-property `_safe_get` inside MPRIS read** — chromium MPRIS
+  rejecting one optional property (notably `DesktopEntry`, with a
+  generic `Error.Failed`) no longer drops the whole player from our
+  candidate list, which previously hid the chromium player entirely
+  from the skip-fallback chain.
+- **All apple-music candidates** beyond the metadata winner join the
+  control-fallback list, so the chromium player is reachable for
+  skip dispatches even when plasma wins the metadata pick.
+- **Notification fires immediately on cover-cache hits** (50 ms vs.
+  the previous unconditional 600-1500 ms `notify_delay_ms` wait).
+- **Discord progress bar dropped entirely on preview-clip mode**
+  (MPRIS duration < 30 s) — no `start`, no `end` in the activity
+  payload — so the elapsed timer doesn't loop nonsensically with
+  the 8-second preview.
+- **`update_config` invocation from the welcome wizard** now goes
+  through `settings.applied.emit(config)` (already QueuedConnection-
+  wired to the worker thread) instead of `QMetaObject.invokeMethod
+  (… Q_ARG(object, …))`, which PySide6 rejects with "Unable to find
+  a QMetaType for 'object'" — that exception was silently breaking
+  the post-wizard handshake on first-run.
+- **Welcome wizard X / Esc** marks `first_run_complete=True` (via
+  `reject()` override) so the wizard doesn't re-appear on the next
+  launch when the user dismisses without confirming.
+- **Welcome wizard Apply with empty ID** asks for confirmation
+  before silently saving "no Discord".
+- **Refrain's own published MPRIS bus name skipped** during the
+  source read loop — reading our own publish path back was
+  circular and added noticeable latency.
+- **`_control` exception handling** — a TypeError in
+  `getattr(src, action)()` no longer kills the entire dispatch
+  before the follow-up polls fire.
+- **Reset preserves per-source Discord IDs** (`client_id_mpris` /
+  `client_id_bluetooth`), not just the default `client_id`.
+- **dbus.proxies / dbus.connection log spam silenced** — their
+  Introspect-error tracebacks against unrelated MPRIS players
+  drowned the live log in noise that has nothing to do with
+  refrain.
+
+### Removed
+
+- **Dead `_diag_label` shim** in `WelcomeDialog` that was only there
+  for a backwards-compat path no longer in use.
+
+## [0.2.1] - 2026-05-06
+
+Polish release built around the v0.2.0 surface. The Settings window got
+a UI overhaul, two notification cover-art races are gone, and the
+external code-review punch list landed in full (atomic config writes,
+AppImage size validation, `.ts` source files no longer ship in the
+wheel, dead D-Bus watcher module deleted).
+
+### Added
+
+- **Auto-restart on Discord client_id change** — Apply now triggers an
+  in-process re-exec when the client_id field has changed, same
+  pattern as the language switch. pypresence binds to the client_id
+  at connect time, so a fresh process is the simplest way to re-init
+  cleanly.
+- **AppImage update size validation** — `_apply_appimage` now compares
+  the downloaded file against the GitHub Releases manifest's
+  `appimage_size` before replacing the live binary. A truncated
+  download is rejected and the tmp file cleaned up instead of
+  bricking the next launch.
+- **MPRIS dispatch logging** — `Next` / `Previous` / `PlayPause` log
+  which player actually received the call (INFO level). Diagnoses
+  "Next pauses instead of skipping" type bugs where a fallback
+  player handles the action wrong.
+- **RPC track-change diagnostics** — log raw `pos`, `dur`, `start_ts`
+  on every recompute so duration mismatches (browser MPRIS reporting
+  preview-clip lengths, etc.) are visible in the live log.
+
+### Changed
+
+- **Settings window UI overhaul** — every tab uses a consistent
+  `QGroupBox` + form-layout with left-aligned titles via stylesheet
+  (overrides Plasma Breeze's centered default). Inputs are
+  fixed-width: 220 px default, 360 px for the Discord group whose
+  Client ID placeholder + privacy-mode labels need more room.
+  `FieldsStayAtSizeHint` + per-widget `setFixedWidth` is the only
+  combo that holds across both Fusion (offscreen tests) and Breeze
+  (Plasma) — `AllNonFixedFieldsGrow` was ignoring fixed-width caps.
+- **Discord RPC reconnect cap lowered to 15 s** — autostart launches
+  refrain before Discord is ready; the previous 60 s ceiling meant
+  the user could sit there for almost a minute after Discord
+  finished loading before refrain noticed and connected.
+- **Atomic config writes** — `Config.save` now writes to a `.tmp`
+  sibling and `os.replace`s into place. A crash mid-write would
+  otherwise leave an empty / half-written TOML and refrain
+  silently falls back to defaults on parse error, losing every
+  setting the user picked.
+- **Discord client_id Apply re-init** — wired `restartRequested`
+  emission so picking up a new client_id no longer requires a
+  manual restart.
+
+### Fixed
+
+- **Notification cover flicker** — `notify-send -i` now carries the
+  same image as the `--hint string:image-path:...` payload. KDE
+  Plasma briefly rendered the `-i refrain` brand badge (~50–100 ms)
+  while it loaded the image-path file from disk; using the same
+  file for both makes the transition invisible.
+- **Discord activity-card cover flicker** — defer the first RPC
+  update for a new track until the iTunes-search cover URL is in
+  cache, capped at 3 polls (~3 s). Without this, Discord briefly
+  rendered the `refrain` brand fallback before the real cover
+  paint, exactly the issue cover-fetcher was supposed to fix.
+- **Group titles centered on Plasma Breeze** — explicit stylesheet
+  overrides Breeze's default centered `QGroupBox::title`.
+
+### Removed
+
+- **Dead `dbus_watcher` module** — 155 lines of `MPRISWatcher` /
+  `BluetoothWatcher` machinery that was never wired up after the
+  signal-driven path was abandoned for v0.2.x. The companion
+  `_refresh_watchers` and `_on_external_change` slots in
+  `Daemon` went with it.
+- **`.ts` translation sources from the wheel** — only the compiled
+  `.qm` files ship now. Linguist sources stay in the source tree
+  for translator PRs.
+
 ## [0.2.0] - 2026-05-06
 
 First minor-version bump. Five planned v0.2 features land together
@@ -365,7 +684,14 @@ 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.1.2...HEAD
+[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/Rockykln/refrain/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/Rockykln/refrain/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/Rockykln/refrain/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/Rockykln/refrain/compare/v0.1.5...v0.2.0
+[0.1.5]: https://github.com/Rockykln/refrain/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/Rockykln/refrain/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/Rockykln/refrain/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/Rockykln/refrain/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/Rockykln/refrain/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/Rockykln/refrain/releases/tag/v0.1.0

{refrain-0.2.0 → refrain-0.2.3}/CONTRIBUTING.md

@@ -122,31 +122,34 @@ descriptions instead.
 
 ## Translations
 
-User-visible strings live wrapped in `tr()` calls; the source list is
-maintained in `src/refrain/i18n/refrain_<lang>.ts` (Qt Linguist format).
-German is shipped complete. French, Spanish, Italian, Portuguese, Dutch,
-Polish, Japanese, and Simplified Chinese have stub `.ts` files with all
-source strings already extracted, marked
-`<translation type="unfinished"></translation>` — those are the ones we'd
-love community PRs for.
+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.
 
-To translate one of the stub languages end-to-end:
+To add a new language end-to-end:
 
 ```sh
-# 1. Pick a language file. Linguist (the GUI) is friendlier than
-#    editing XML by hand.
-pyside6-linguist src/refrain/i18n/refrain_fr.ts
+# 1. Copy the German translation as a starting point (gives you all
+#    the strings already extracted).
+cp src/refrain/i18n/refrain_de.ts src/refrain/i18n/refrain_fr.ts
 
-# 2. Replace each "unfinished" translation with the real string.
+# 2. Open it in Qt Linguist (friendlier than editing XML by hand) and
+#    replace each German line with your translation.
+pyside6-linguist src/refrain/i18n/refrain_fr.ts
 
-# 3. Compile to .qm and run the result locally.
+# 3. Compile to .qm.
 make i18n
+
+# 4. Add your code to settings_window.py's language combo so users can
+#    pick it from the Localization group, then run Refrain locally to
+#    smoke-test.
 LANG=fr_FR.UTF-8 refrain
 ```
 
-If you've wrapped any new strings on the source side, run
-`make i18n-update` first — it refreshes every `.ts` file's
-source-string list while preserving existing translations.
+If you've wrapped any new English strings on the source side, run
+`make i18n-update` first — it refreshes the `.ts` file's source-string
+list while preserving existing translations.
 
-PRs that just translate a `.ts` (no source changes) are very welcome.
-So is native-speaker review of an existing translation.
+PRs that add a new language (or fix typos in an existing one) are
+very welcome.

{refrain-0.2.0 → refrain-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refrain
-Version: 0.2.0
+Version: 0.2.3
 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
@@ -134,9 +134,10 @@ and `~/.local/share/icons/`. To undo: `refrain --uninstall-desktop`.
 
 ### Tested on
 
-- KDE Plasma 6 (Wayland) — primary target
-- KDE Plasma 6 (X11)
-- GNOME (with the [AppIndicator and KStatusNotifierItem](https://extensions.gnome.org/extension/615/appindicator-support/) extension)
+See [`docs/test-matrix.md`](docs/test-matrix.md) for the full Tier-1 / Tier-2 list, the per-row smoke checks, and which distros are explicitly out-of-scope (Python or glibc floor too low).
+
+- **Tier 1 (must pass every release):** CachyOS, Arch Linux, Fedora 42, Ubuntu 24.04 LTS, Debian 13, openSUSE Tumbleweed, Linux Mint 22, Manjaro Stable.
+- **Desktops:** KDE Plasma 6 (Wayland is the primary target, X11 also covered), GNOME with the [AppIndicator and KStatusNotifierItem](https://extensions.gnome.org/extension/615/appindicator-support/) extension, XFCE / Cinnamon / LXQt / Budgie via their native or AppIndicator-bridged tray, MATE with `mate-applet-statusnotifier`, tiling WMs (Hyprland / Sway / i3 / river) via a SNI-capable status bar.
 
 ## First-time setup
 
@@ -162,7 +163,9 @@ same file; you almost never need to touch it by hand.
 
 ```toml
 [discord]
-client_id = ""                     # paste your own Application ID here
+client_id = ""                     # default Application ID — paste yours here
+client_id_mpris = ""               # optional per-source override (browser / Apple Music)
+client_id_bluetooth = ""           # optional per-source override (Bluetooth headphones)
 
 [sources]
 mpris_enabled = true
@@ -177,12 +180,28 @@ autostart = false
 notifications = true
 cover_art = true
 show_buttons = true
+notify_delay_ms = 0                # 0 = fire ASAP; the cover-art retry loop still waits up to ~2 s
 
 [advanced]
-poll_interval_ms = 1000
+poll_interval_ms = 500
 log_level = "INFO"
+cover_cache_size = 200             # disk cap for cached covers
+idle_grace_s = 30                  # clear status when same track plays past duration + grace; 0 disables
+language = "system"                # "system" follows QLocale; "en" / "de" / … force a translation
 ```
 
+Per-source `client_id_*` fields let Apple Music render under one Discord
+application (with the album-grid as artwork) and Bluetooth headphones under
+another (with a generic Bluetooth glyph). Empty falls back to the default
+`client_id`.
+
+## MPRIS server
+
+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.
+
 ## Tray
 
 <p align="center">

{refrain-0.2.0 → refrain-0.2.3}/README.md

@@ -100,9 +100,10 @@ and `~/.local/share/icons/`. To undo: `refrain --uninstall-desktop`.
 
 ### Tested on
 
-- KDE Plasma 6 (Wayland) — primary target
-- KDE Plasma 6 (X11)
-- GNOME (with the [AppIndicator and KStatusNotifierItem](https://extensions.gnome.org/extension/615/appindicator-support/) extension)
+See [`docs/test-matrix.md`](docs/test-matrix.md) for the full Tier-1 / Tier-2 list, the per-row smoke checks, and which distros are explicitly out-of-scope (Python or glibc floor too low).
+
+- **Tier 1 (must pass every release):** CachyOS, Arch Linux, Fedora 42, Ubuntu 24.04 LTS, Debian 13, openSUSE Tumbleweed, Linux Mint 22, Manjaro Stable.
+- **Desktops:** KDE Plasma 6 (Wayland is the primary target, X11 also covered), GNOME with the [AppIndicator and KStatusNotifierItem](https://extensions.gnome.org/extension/615/appindicator-support/) extension, XFCE / Cinnamon / LXQt / Budgie via their native or AppIndicator-bridged tray, MATE with `mate-applet-statusnotifier`, tiling WMs (Hyprland / Sway / i3 / river) via a SNI-capable status bar.
 
 ## First-time setup
 
@@ -128,7 +129,9 @@ same file; you almost never need to touch it by hand.
 
 ```toml
 [discord]
-client_id = ""                     # paste your own Application ID here
+client_id = ""                     # default Application ID — paste yours here
+client_id_mpris = ""               # optional per-source override (browser / Apple Music)
+client_id_bluetooth = ""           # optional per-source override (Bluetooth headphones)
 
 [sources]
 mpris_enabled = true
@@ -143,12 +146,28 @@ autostart = false
 notifications = true
 cover_art = true
 show_buttons = true
+notify_delay_ms = 0                # 0 = fire ASAP; the cover-art retry loop still waits up to ~2 s
 
 [advanced]
-poll_interval_ms = 1000
+poll_interval_ms = 500
 log_level = "INFO"
+cover_cache_size = 200             # disk cap for cached covers
+idle_grace_s = 30                  # clear status when same track plays past duration + grace; 0 disables
+language = "system"                # "system" follows QLocale; "en" / "de" / … force a translation
 ```
 
+Per-source `client_id_*` fields let Apple Music render under one Discord
+application (with the album-grid as artwork) and Bluetooth headphones under
+another (with a generic Bluetooth glyph). Empty falls back to the default
+`client_id`.
+
+## MPRIS server
+
+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.
+
 ## Tray
 
 <p align="center">