refrain 0.2.3__tar.gz → 0.2.4__tar.gz

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

@@ -7,6 +7,134 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-05-07
+
+A polish + reliability release built on the v0.2.3 distro-portability
+work. The headline items are time-display consistency across all
+three surfaces (tray / Discord / Plasma panel), Snap/Flatpak Discord
+support out of the box, a full inline changelog in Settings, and
+~20 % more test coverage to lock the new behaviour in. No breaking
+changes — same config schema, same Python floor, same UI layout.
+
+### Added
+
+- **Inline release notes in Settings → Updates tab.** The tab
+  previously only had an auto-check toggle, last-checked label and a
+  "Check now" button — the actual release notes only showed up in
+  the popup when an update was available. The tab now carries a
+  QTextBrowser that renders the same Markdown the popup uses, plus
+  "Current version" and "Latest known" labels. `UpdateOrchestrator`
+  gained a `releaseInfoFetched(release | None)` signal that fires
+  after every check (auto or manual, success or failure) so the tab
+  refreshes its contents regardless of the result.
+- **`docs/bluetooth.md`** — first-time-setup walkthrough covering
+  bluez install per distro, pairing recipe, AVRCP verification,
+  per-source Discord profile setup, and a Troubleshooting section
+  for the common breakage modes (no AVRCP exposed, missing
+  control, multiple paired devices, empty dropdown).
+- **FAQ entries** for "Refrain isn't picking up my browser"
+  (covers the `playerctl` diagnostic, the Snap-confined-browser
+  workaround, and the Firefox `about:config` toggle), and
+  "How do I add a browser that isn't in the list".
+
+### Changed
+
+- **Tray progress + published MPRIS metadata + Discord activity
+  payload all use the iTunes-corrected duration.** v0.2.3 already
+  fixed Discord; the tray's "0:42 / 7:21 (-6:39)" ticker and the
+  `mpris:length` we publish to Plasma's panel were still using the
+  raw `mpris:length` and showed inconsistent numbers when MPRIS
+  briefly lied about a song's duration. Hoisted
+  `pick_effective_duration_ms` into `_dispatch` so all three
+  surfaces see the same value every tick. Tray position is also
+  now clamped to duration so a "2:30 / 0:14 (-0:00)" display can't
+  happen during a brief MPRIS preview-clip glitch on a longer song.
+- **`os.chmod(tmp, 0o755)` on AppImage update replaced by mode
+  preservation** — read the running AppImage's mode and mirror it,
+  with `0o700` as fallback. CodeQL's `py/overly-permissive-file`
+  warning is gone, and an AppImage that the user installed at
+  `0o700` stays `0o700` across upgrades.
+- **DiscordRPC dedupes identical consecutive payloads** instead of
+  hammering the IPC channel on every poll. The daemon ticks every
+  500 ms but Discord rate-limits presence updates to 5 per 20 s, so
+  ~75 % of those ticks were silently being dropped on the Discord
+  side anyway. Now the second-and-on identical payload is a no-op
+  on our side too.
+- **Cover-wait defer back to 3 polls (~1.5 s)**. v0.2.2 lowered it
+  to 1 poll to feel more "live", but that meant Discord briefly
+  rendered the `refrain` brand fallback as the *large* image while
+  iTunes search returned, then flipped to the cover — visible
+  flicker on every track change. With 3 polls Discord typically
+  transitions straight from "no activity" to the cover with no
+  flash. Bounded: songs that have no iTunes match still update
+  after 1.5 s with the brand fallback.
+- **Tray menu's "Update available" line now carries a coloured
+  icon** (Breeze accent blue, `assets/icons/menu-update.svg`)
+  instead of just a unicode `⬆` arrow in the same white as every
+  other line. Visually distinguishes the update notification from
+  Settings / Live log / Restart in the menu's icon column.
+- **Browser hint defaults expanded** with Floorp, Waterfox, Mullvad
+  Browser, Tor Browser and ungoogled-chromium. Existing configs
+  keep their saved list (no auto-migration); the new entries appear
+  unticked in Settings → Sources until the user toggles them.
+- **~20 English-only UI strings wrapped in `tr()`** —
+  `update_dialog.py` (status labels, button labels, header HTML),
+  `log_window.py` (toolbar Level/Auto-scroll/Copy/Clear/Close), and
+  `app.py` module-level QMessageBox calls (now via
+  `QCoreApplication.translate`). Re-ran `lupdate6` + `lrelease6`
+  against `refrain_de.ts`: 127/127 finished German translations.
+- **`docs/architecture.md` refreshed** to v0.2.x reality — the
+  diagram showed a "1 Hz tick" (default has been 500 ms since
+  v0.2.2), the worker-thread block was missing `MPRISServer`, the
+  GLib thread for dbus-python signal dispatch was undocumented, and
+  the "does not export any custom interfaces" line was wrong since
+  the v0.2.2 MPRIS-server publication. Plus a new section on
+  Discord IPC sandbox bridging (Snap/Flatpak).
+
+### Fixed
+
+- **Tray tooltip cleared on track change.** After a paused-to-paused
+  track switch, the tooltip briefly showed "Song B • 1:30 / 2:11"
+  using Song A's elapsed counter while the new track waited for its
+  first `progressTick`. `set_track` now drops the stale progress
+  line when the title text actually changed.
+- **`compute_idle_state` honours the iTunes-corrected duration.**
+  Previously the deadline keyed off `track.duration_ms` so a
+  7:21-playlist-total-on-a-2:11-song lie made dangling-tab cleanup
+  fire 5 minutes too late. New optional `effective_duration_ms`
+  parameter; the daemon passes the same value the RPC payload
+  uses.
+- **Snap and Flatpak Discord builds reachable out of the box.**
+  Their IPC socket lives inside the sandbox tree
+  (`$XDG_RUNTIME_DIR/app/com.discordapp.Discord/`,
+  `~/.var/app/com.discordapp.Discord/config/discord/`,
+  `~/snap/discord/current/.config/discord/`), so pypresence's stock
+  discovery never finds it. `_bridge_sandboxed_ipc_socket` symlinks
+  the first sandbox socket it finds into `$XDG_RUNTIME_DIR` before
+  each connect attempt, and sweeps stale symlinks left behind when
+  the sandbox path's target is removed (Snap uninstall, Flatpak
+  remove, host reboot).
+- **Config drops unknown TOML keys instead of nuking the whole
+  file.** A single typo or a key written by a *newer* Refrain that
+  the user has since downgraded from used to make
+  `Config.from_dict` raise `TypeError`, caught by the surrounding
+  `except` and falling back to defaults for *every* setting.
+  `_construct()` now filters the payload through dataclass fields
+  before `**`-splatting; the offending keys get a single WARNING in
+  the log naming the section, the rest of the section survives.
+- **Stale comments + doc references cleaned up.** Four "1 Hz" call-
+  outs in `mpris.py` / `daemon.py` (default has been 500 ms since
+  v0.2.2), plus one reference to the AppImage runtime that no
+  longer matches the AppRun layout.
+
+### Tests
+
+- **+13 unit tests** covering the new helpers — `DiscordRPC` payload
+  dedup (4), `_bridge_sandboxed_ipc_socket` (4), `compute_idle_state`
+  with `effective_duration_ms` (2), `cleanup_orphan_downloads` (3).
+  Total: 113 → 125, all green, ruff + bandit + pip-audit clean,
+  Dependabot 0 outstanding alerts.
+
 ## [0.2.3] - 2026-05-07
 
 A reliability + portability pass driven by hands-on testing across

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refrain
-Version: 0.2.3
+Version: 0.2.4
 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
@@ -319,6 +319,8 @@ tray + controls running.
 
 - [Architecture overview](docs/architecture.md) — threads, D-Bus surface, file paths
 - [FAQ](docs/faq.md)
+- [Bluetooth quick-start](docs/bluetooth.md) — pair + AVRCP setup walkthrough
+- [Test matrix](docs/test-matrix.md) — supported distros, smoke-check checklist
 - [Roadmap](ROADMAP.md)
 - [Changelog](CHANGELOG.md)
 - [Contributing](CONTRIBUTING.md) — dev setup, testing, code style

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

@@ -285,6 +285,8 @@ tray + controls running.
 
 - [Architecture overview](docs/architecture.md) — threads, D-Bus surface, file paths
 - [FAQ](docs/faq.md)
+- [Bluetooth quick-start](docs/bluetooth.md) — pair + AVRCP setup walkthrough
+- [Test matrix](docs/test-matrix.md) — supported distros, smoke-check checklist
 - [Roadmap](ROADMAP.md)
 - [Changelog](CHANGELOG.md)
 - [Contributing](CONTRIBUTING.md) — dev setup, testing, code style

{refrain-0.2.3 → refrain-0.2.4}/ROADMAP.md

@@ -219,6 +219,70 @@ What's done, what's next, what's deliberately not in scope.
   out-of-scope reasons for the floor of unsupported distros (RHEL 9
   / Rocky 9 / Alma 9 / Debian 11 / Ubuntu 22.04 / Alpine).
 
+## Done — v0.2.4
+
+- **Time-display consistency across tray + Plasma panel + Discord**.
+  v0.2.3 already fixed Discord; the tray's progress label and the
+  published MPRIS Metadata still keyed off the raw `mpris:length`
+  and showed inconsistent numbers when MPRIS briefly lied about a
+  song's duration. `pick_effective_duration_ms` is now hoisted into
+  `_dispatch` so all three surfaces see the same iTunes-corrected
+  value every tick. Plus position is clamped to duration so a
+  "2:30 / 0:14 (-0:00)" line can't render during a brief MPRIS
+  preview-clip glitch.
+- **Snap and Flatpak Discord builds reachable out of the box**.
+  Their IPC socket lives inside the sandbox tree
+  (`xdg-run/app/com.discordapp.Discord/`,
+  `~/.var/app/com.discordapp.Discord/.../`,
+  `~/snap/discord/current/.config/discord/`) which pypresence
+  doesn't probe. `_bridge_sandboxed_ipc_socket` symlinks the first
+  sandbox socket it finds into `$XDG_RUNTIME_DIR` before each
+  connect attempt + sweeps stale symlinks left behind when the
+  Discord install is removed.
+- **Inline release notes in Settings → Updates tab**. The tab
+  carries a QTextBrowser that renders the same Markdown as the
+  popup, plus "Current version" + "Latest known" labels.
+  `releaseInfoFetched(release | None)` signal fires after every
+  check (auto / manual, success / failure) so the tab refreshes
+  regardless of the result.
+- **Discord activity card always shows the Refrain brand badge as
+  small_image**. Previously the badge was only in `large_image` as
+  a fallback when cover-art lookup failed; now it's the small-icon
+  corner of every payload, so the cover gets the visual focus and
+  hovering reveals "Refrain" as the source app. Plus the
+  cover-wait defer is back to 3 polls (~1.5 s at 500 ms tick) so
+  Discord usually goes straight from "no activity" to "cover" with
+  no brand flash on the way.
+- **Config drops unknown TOML keys** instead of nuking the whole
+  file. A typo or a key written by a newer Refrain that the user
+  has since downgraded from used to make `Config.from_dict` raise,
+  caught by the surrounding except, and fall back to defaults for
+  every setting. Now the offending key gets a single warning, the
+  rest of the section survives.
+- **DiscordRPC dedupes identical consecutive payloads**. The
+  daemon ticks every 500 ms but Discord rate-limits presence
+  updates to 5/20 s — most ticks were silently dropped on the
+  Discord side anyway. Now the second-and-on identical payload
+  is a no-op on our side too.
+- **Browser hints expanded**: Floorp, Waterfox, Mullvad Browser,
+  Tor Browser, ungoogled-chromium.
+- **`docs/bluetooth.md`** — first-time-setup walkthrough covering
+  bluez install per distro, pairing recipe, AVRCP verification,
+  per-source Discord profile setup, and Troubleshooting.
+- **FAQ entries** for "Refrain isn't picking up my browser"
+  (covers `playerctl` diagnostic + Snap-confined-browser workaround
+  + Firefox `about:config` toggle) and "How do I add a browser
+  that isn't in the list".
+- **`docs/architecture.md` refreshed** to v0.2.x reality — diagram
+  no longer claims "1 Hz tick" (default has been 500 ms since
+  v0.2.2), `MPRISServer` block added, `org.mpris.MediaPlayer2.refrain`
+  publish documented, GLib thread for dbus-python signal dispatch
+  documented, new section on Discord IPC sandbox bridging.
+- **+13 unit tests**: `DiscordRPC` payload dedup (4),
+  `_bridge_sandboxed_ipc_socket` (4), `compute_idle_state` with
+  `effective_duration_ms` (2), `cleanup_orphan_downloads` (3).
+  Total: 113 → 125, all green.
+
 ## Up next — v0.3
 
 - **Polishing the wrapped i18n surface** — wrap the remaining

{refrain-0.2.3 → refrain-0.2.4}/docs/architecture.md

@@ -11,26 +11,33 @@ Refrain is one process with two threads and one external IPC socket.
 │  ├─ TrayIcon (QSystemTrayIcon)         ←─── status / track      │
 │  ├─ SettingsWindow (QDialog, hidden after Apply)                │
 │  ├─ LogWindow (QDialog, on-demand)                              │
+│  ├─ WelcomeDialog (first-run only)                              │
 │  ├─ UpdateOrchestrator                                          │
 │  └─ UpdateDialog                                                │
 │                                                                 │
 │  Worker thread (Qt event loop, QThread)                         │
 │  ├─ DaemonWorker                                                │
-│  │    ├─ MPRISSource         ──► Session DBus                   │
+│  │    ├─ MPRISSource         ──► Session DBus (read)            │
 │  │    ├─ BluetoothSource     ──► System DBus (org.bluez)        │
 │  │    ├─ CoverFetcher        ──► iTunes Search (HTTPS)          │
-│  │    └─ DiscordRPC          ──► Discord IPC socket             │
-│  └─ Timer (QTimer, 1 Hz tick)                                   │
+│  │    ├─ DiscordRPC          ──► Discord IPC socket             │
+│  │    └─ MPRISServer         ──► Session DBus (publish own)     │
+│  └─ Timer (QTimer, 500 ms default poll, configurable)           │
+│                                                                 │
+│  GLib thread (only when PyGObject is available)                 │
+│  └─ GLib.MainLoop — pumps dbus-python signals so Plasma's panel │
+│     PlayPause / Next / Previous reach our MPRISServer methods.  │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
 ## Why a worker thread?
 
-The polling loop (1 Hz) reads MPRIS / BlueZ properties via D-Bus. Some of
-those calls block briefly. iTunes Search lookups can take up to 5 s.
-Discord IPC writes can stall when Discord is restarting. Doing any of
-that on the GUI thread would make the tray icon and settings window
-freeze every poll.
+The polling loop (default 500 ms, configurable via
+`advanced.poll_interval_ms`) reads MPRIS / BlueZ properties via D-Bus.
+Some of those calls block briefly. iTunes Search lookups can take up
+to 5 s. Discord IPC writes can stall when Discord is restarting.
+Doing any of that on the GUI thread would make the tray icon and
+settings window freeze every poll.
 
 The worker thread runs a Qt event loop (driven by `QTimer`, *not* a
 `while/sleep` loop — that detail matters: a sleep loop blocks the event
@@ -84,6 +91,30 @@ to `/usr/share/applications/refrain.desktop` instead.
 | `org.mpris.MediaPlayer2.Player`         | session| Track metadata + Play/Next/Prev   |
 | `org.bluez.MediaPlayer1`                | system | AVRCP track + Play/Pause/Next/Prev|
 | `org.bluez.Device1` (via ObjectManager) | system | Paired-device enumeration         |
+| `org.freedesktop.DBus.NameHasOwner`     | system | Fast-fail check before activating `org.bluez` (avoids a 25 s service-activation timeout on hosts without bluez)|
+
+## D-Bus interfaces published
+
+Refrain publishes two well-known names on the **session** bus:
+
+| Bus name                              | Purpose                                        |
+|---------------------------------------|------------------------------------------------|
+| `io.github.Rockykln.Refrain`          | Single-instance lock. No object path; just the name reservation. |
+| `org.mpris.MediaPlayer2.refrain`      | Refrain itself as an MPRIS player. KDE Plasma's panel media controls applet, KDE Connect, GNOME Shell etc. drive the same Play/Pause/Next/Previous as the tray, and render the same track Discord renders. Implements the standard MPRIS root + Player interfaces. |
+
+The MPRIS-server publication needs PyGObject (`gi`) for a GLib main loop
+to pump dbus-python signal dispatch. When PyGObject isn't installed,
+Refrain logs a warning at startup and falls back to read-only mode —
+the rest of the app works, but Plasma's panel can't drive playback.
+
+## Discord IPC discovery
 
-Refrain also registers exactly one well-known name on the session bus
-for the single-instance lock; it does not export any custom interfaces.
+The standard path is `$XDG_RUNTIME_DIR/discord-ipc-N` (N=0..9). Snap
+and Flatpak Discord builds put their socket inside the sandbox tree
+instead (`$XDG_RUNTIME_DIR/app/com.discordapp.Discord/discord-ipc-N`,
+`~/.var/app/com.discordapp.Discord/config/discord/discord-ipc-N`,
+`~/snap/discord/current/.config/discord/discord-ipc-N`).
+`DiscordRPC._bridge_sandboxed_ipc_socket` symlinks the first sandbox
+socket it finds into `$XDG_RUNTIME_DIR` before each connect attempt,
+and sweeps stale symlinks left behind by previously-uninstalled
+Discord builds.

refrain-0.2.4/docs/bluetooth.md

@@ -0,0 +1,136 @@
+# Bluetooth quick-start
+
+Refrain's Bluetooth source reads playback metadata via BlueZ AVRCP —
+the standard Bluetooth audio metadata profile. Anything that pairs as
+an A2DP audio source and exposes `org.bluez.MediaPlayer1` over D-Bus
+will work: iPhones, Android phones, dedicated music players, even
+some car head-units.
+
+This guide walks through getting it set up the first time on KDE
+Plasma, GNOME, or any other desktop with `bluez` running. If
+something is missing on your distro, the
+[Troubleshooting](#troubleshooting) section at the end covers the
+usual suspects.
+
+## Prerequisites
+
+- BlueZ ≥ 5 with the AVRCP profile enabled (default on every modern
+  desktop distro).
+- A Bluetooth adapter that's powered on. `bluetoothctl show` should
+  list at least one controller.
+- Your desktop's Bluetooth applet running (KDE's
+  bluedevil-applet, GNOME's bluetooth-panel, blueman, …). Refrain
+  doesn't manage pairing itself — it only reads metadata from
+  already-connected devices.
+
+If `bluetoothctl` isn't installed, install it via your package
+manager:
+
+| Distro | Command |
+|---|---|
+| Arch / CachyOS / Manjaro | `sudo pacman -S bluez bluez-utils` |
+| Debian / Ubuntu / Mint | `sudo apt install bluez bluez-tools` |
+| Fedora / RHEL / Rocky | `sudo dnf install bluez bluez-tools` |
+| openSUSE | `sudo zypper install bluez` |
+
+## Pairing
+
+1. Put the phone (or other source) into pairing mode. On iOS this is
+   *Settings → Bluetooth*; on Android it's *Settings → Connected
+   devices*.
+2. Open your desktop's Bluetooth applet, scan for new devices, click
+   *Pair* on the phone entry, confirm the matching PIN on both ends.
+3. Enable *Audio*. Some applets surface this as a toggle after
+   pairing; others auto-enable it. Verify with:
+   ```sh
+   bluetoothctl info <MAC>
+   ```
+   Look for `UUIDs: ... A/V Remote Control Target ... AudioSource ...`
+   in the output. If those are missing, the phone is paired but not
+   advertising AVRCP — disconnect, repair, and tick the *Audio
+   profile* box this time.
+
+## First playback
+
+1. Make sure the phone is **connected** (not just paired). The
+   applet shows a connected indicator; CLI:
+   ```sh
+   bluetoothctl info <MAC> | grep "Connected:"
+   ```
+   should show `Connected: yes`.
+2. Start music on the phone. Spotify, Apple Music, the iOS Music
+   app, anything that publishes track metadata via the AVRCP
+   profile.
+3. In Refrain, open *Settings → Sources → Bluetooth*:
+   - Toggle **Enable Bluetooth source** on.
+   - Pick the device from the dropdown. It should show the phone's
+     Bluetooth name (e.g. *Rocky's iPhone*) and its MAC address.
+   - Hit **Apply**.
+4. Within ~1 s, the tray menu shows the track title + artist.
+   Within ~2 s, Discord renders the listening status.
+
+The dropdown's `(auto-detect)` entry picks whichever device is
+currently exposing AVRCP — useful if you switch between phone and
+headphones with the same Refrain config. The MAC-pinned variant is
+stricter but stable when multiple sources are connected at once.
+
+## Per-source Discord profile (optional)
+
+You can give Bluetooth its own Discord application so the status
+renders with a different icon than the browser's Apple Music
+playback:
+
+1. Register a second Discord application at
+   <https://discord.com/developers/applications> — call it e.g.
+   "Refrain (Bluetooth)" and upload a Bluetooth glyph as the icon.
+2. Copy the new Client ID.
+3. *Settings → General → Bluetooth Client ID* — paste, *Apply*.
+
+Refrain reconnects RPC under the per-source ID the moment a track
+arrives from Bluetooth.
+
+## Troubleshooting
+
+### Refrain says "no track" while music is clearly playing on the phone
+
+- Confirm AVRCP is actually working:
+  ```sh
+  busctl --system call org.bluez /org/bluez/hci0/dev_<MAC_with_underscores> \
+      org.freedesktop.DBus.Properties Get ss org.bluez.MediaPlayer1 Track
+  ```
+  This should return the current track. If it errors with
+  `org.bluez.Error.DoesNotExist`, the phone isn't exposing AVRCP — try
+  disconnect / reconnect, and verify the *Audio profile* box on the
+  pairing.
+- Check the tray-menu source label or the live log
+  (tray → *Live log…*). Look for `Track change [bluetooth]: …` lines.
+  If you see `[mpris]` instead, the browser is winning the source
+  race — close the music tab so Bluetooth becomes the only candidate.
+
+### `bluetoothd` D-Bus activation timeout warning in the log
+
+You'll see something like
+`Bluetooth: GetManagedObjects failed: ... service_start_timeout=25000ms`
+on a system without `bluez` installed (typical of VMs and minimal
+installs). v0.2.3+ fast-fails before the activation timeout fires;
+on older builds you'd want to disable the Bluetooth source toggle.
+
+### The dropdown is empty
+
+That means BlueZ is running but no `org.bluez.Device1` entries exist.
+Pair at least one device first (Section "Pairing" above), then click
+**Apply** in Refrain to refresh the dropdown.
+
+### Track shows but Play/Pause/Next/Previous don't work
+
+AVRCP control depends on the phone's app supporting
+`AVRCP-CT 1.4` or higher. iOS Music, Apple Music, and Spotify all
+do. Some Android battery-saver settings disable AVRCP control —
+check the per-app battery / background settings on the phone.
+
+### Multiple paired devices, wrong one gets picked
+
+Set *Settings → Sources → Bluetooth → Device* to the specific MAC.
+The `(auto-detect)` mode picks the first eligible AVRCP player from
+BlueZ's enumeration order, which isn't stable when several phones
+are paired.

{refrain-0.2.3 → refrain-0.2.4}/docs/faq.md

@@ -37,6 +37,50 @@ Install the **AppIndicator and KStatusNotifierItem** GNOME Shell
 extension. Refrain's tray uses `QSystemTrayIcon`, which on GNOME requires
 that extension to be visible.
 
+## Refrain isn't picking up my browser.
+
+Refrain reads track metadata from the browser's MPRIS publication. If
+nothing shows up while Apple Music is playing, run `playerctl -l` in a
+terminal — it lists every MPRIS player on your session bus.
+
+- **Empty list (or no Firefox / Chromium entry):** the browser isn't
+  publishing MPRIS at all. Common causes:
+  - **Firefox**: MPRIS is off by default on some installs. Open
+    `about:config` → set `media.hardwaremediakeys.enabled = true` →
+    fully quit Firefox (close all windows + wait for `pgrep firefox`
+    to be empty) → relaunch.
+  - **Snap-confined browsers** (Snap Firefox, Snap Chromium on
+    Ubuntu): the snap sandbox blocks D-Bus session-bus access for
+    MPRIS. Switch to a deb-channel browser:
+    - Mozilla's official Firefox deb:
+      <https://support.mozilla.org/en-US/kb/install-firefox-linux>
+    - Brave deb: <https://brave.com/linux/>
+    - Chromium from Debian/Ubuntu deb (not the Snap).
+  - **Flatpak browsers** without `--talk-name=org.mpris.MediaPlayer2.*`:
+    Flathub builds usually have it; self-built ones may not.
+- **Browser shows but track isn't picked up:** check that `xesam:url`
+  contains `music.apple.com`:
+  ```sh
+  playerctl --player=firefox metadata | grep xesam:url
+  ```
+  If the URL field is empty or points elsewhere, Apple Music's tab
+  isn't the active media tab — switch to it and start playback.
+
+## How do I add a browser that isn't in the Settings list?
+
+*Settings → Sources → Detected browsers → Other (comma-separated)*.
+Enter a substring of the browser's MPRIS bus name. Find it via
+`playerctl -l` while a media tab is playing — e.g. for Floorp the
+substring is `floorp`. Save with *Apply*.
+
+## Bluetooth: how do I get my iPhone / phone showing up?
+
+See the dedicated walkthrough at [`docs/bluetooth.md`](bluetooth.md).
+Quick version: pair the phone in your desktop's Bluetooth manager,
+connect it, start music on the phone, then in Refrain
+*Settings → Sources → Bluetooth* turn the toggle on and pick the
+device from the dropdown.
+
 ## Refrain is already running but the settings window won't reopen.
 
 Click the tray icon. The settings window is normally hidden, not closed —

{refrain-0.2.3 → refrain-0.2.4}/packaging/appimage/AppImageBuilder.yml

@@ -30,7 +30,7 @@ AppDir:
     id: io.github.Rockykln.Refrain
     name: Refrain
     icon: refrain
-    version: 0.2.3
+    version: 0.2.4
     exec: usr/bin/python3
     exec_args: -m refrain $@
 

{refrain-0.2.3 → refrain-0.2.4}/packaging/aur/refrain/.SRCINFO

@@ -1,6 +1,6 @@
 pkgbase = refrain
 	pkgdesc = Discord Rich Presence for Apple Music on Linux
-	pkgver = 0.2.2
+	pkgver = 0.2.3
 	pkgrel = 1
 	url = https://github.com/Rockykln/refrain
 	arch = any
@@ -13,7 +13,8 @@ pkgbase = refrain
 	depends = python-pypresence
 	depends = python-dbus
 	depends = pyside6
-	source = refrain-0.2.2.tar.gz::https://github.com/Rockykln/refrain/archive/v0.2.2.tar.gz
-	sha256sums = db07e0783b3f44a7c54d4b8ee2ebe33f3dc577707a03bd42f5958ddae3d5ac12
+	optdepends = python-gobject: enables MPRIS-server publication so Plasma media controls reach Refrain
+	source = refrain-0.2.3.tar.gz::https://github.com/Rockykln/refrain/archive/v0.2.3.tar.gz
+	sha256sums = 29f2371393d855f508730238a096cbdc85219616a9fab240745c1072a005b23d
 
 pkgname = refrain

{refrain-0.2.3 → refrain-0.2.4}/packaging/aur/refrain/PKGBUILD

@@ -1,7 +1,7 @@
 # Maintainer: Rockykln <contact@rockykln.com>
 
 pkgname=refrain
-pkgver=0.2.3
+pkgver=0.2.4
 pkgrel=1
 pkgdesc="Discord Rich Presence for Apple Music on Linux"
 arch=('any')
@@ -23,9 +23,6 @@ makedepends=(
     'python-wheel'
 )
 source=("$pkgname-$pkgver.tar.gz::https://github.com/Rockykln/refrain/archive/v$pkgver.tar.gz")
-# Placeholder — recompute after the GitHub release exists:
-#   curl -sLO "https://github.com/Rockykln/refrain/archive/v${pkgver}.tar.gz"
-#   sha256sum "v${pkgver}.tar.gz"
 sha256sums=('SKIP')
 
 build() {

{refrain-0.2.3 → refrain-0.2.4}/packaging/flatpak/io.github.Rockykln.Refrain.metainfo.xml

@@ -51,6 +51,28 @@
   <content_rating type="oars-1.1" />
 
   <releases>
+    <release version="0.2.4" date="2026-05-07">
+      <description>
+        <p>
+          Polish + reliability release on top of v0.2.3. Time-display
+          consistency across tray, Plasma panel media-controls applet
+          and Discord (all three now read the same iTunes-corrected
+          duration). Snap and Flatpak Discord builds reachable out of
+          the box via sandbox-aware IPC-socket bridging. Inline
+          release notes in Settings → Updates. Discord activity card
+          always carries the Refrain brand as small_image so the
+          cover gets the visual focus. Config drops unknown TOML
+          keys instead of nuking the whole file when a newer-version
+          key is encountered. DiscordRPC dedupes identical
+          consecutive payloads. Browser hints expanded with Floorp,
+          Waterfox, Mullvad Browser, Tor Browser, ungoogled-chromium.
+          New docs/bluetooth.md walkthrough and FAQ entries on
+          browser MPRIS troubleshooting. +13 unit tests, total now
+          125, all green; ruff + bandit + pip-audit + Dependabot all
+          clean.
+        </p>
+      </description>
+    </release>
     <release version="0.2.3" date="2026-05-07">
       <description>
         <p>

{refrain-0.2.3 → refrain-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "refrain"
-version = "0.2.3"
+version = "0.2.4"
 description = "Discord Rich Presence for Apple Music on Linux"
 readme = "README.md"
 requires-python = ">=3.11"

refrain-0.2.4/src/refrain/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.4"