refrain 0.2.7__tar.gz → 0.3.0__tar.gz

{refrain-0.2.7 → refrain-0.3.0}/.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.2.3"
+      placeholder: "0.3.0"
     validations:
       required: true
 

{refrain-0.2.7 → refrain-0.3.0}/.github/workflows/security.yml

@@ -78,7 +78,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run TruffleHog
-        uses: trufflesecurity/trufflehog@17456f8c7d042d8c82c9a8ca9e937231f9f42e26  # v3.95.2
+        uses: trufflesecurity/trufflehog@37b77001d0174ebec2fcca2bd83ff83a6d45a3ab  # v3.95.3
         with:
           # --only-verified: a secret only counts as flagged when TruffleHog
           # successfully validates it against the live service. Drops the

{refrain-0.2.7 → refrain-0.3.0}/CHANGELOG.md

@@ -7,6 +7,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-19
+
+Last.fm scrobbling (opt-in, alongside the Discord status), with
+credentials kept in the OS keyring instead of plaintext, a
+crash-safe offline scrobble queue, the source-priority fix, the
+cover-replace notifications, a comment-preserving config writer, and
+a Settings reshuffle (Last.fm on its own tab, per-source Discord IDs
+behind an opt-in toggle). Folds in the accumulated v0.2.8 fixes
+(never separately tagged). A full `PRIVACY.md` documents every data
+flow.
+
+### Added
+
+- **Last.fm scrobbling** — opt-in, *alongside* the Discord Rich
+  Presence (never a replacement), off by default. Register your own
+  free Last.fm API account (same bring-your-own-credentials model as
+  the Discord Application ID), enter the key + shared secret in
+  *Settings → General → Last.fm scrobbling*, and **Connect** via the
+  in-app browser auth flow. A track is scrobbled at Last.fm's standard
+  threshold (half the track or four minutes, whichever first; > 30 s
+  only), with pause/seek-aware play-time accounting. Optional
+  `track.updateNowPlaying`. No new dependency — the signed API surface
+  is hand-rolled on `urllib` + `hashlib`. Walkthrough:
+  [`docs/lastfm.md`](docs/lastfm.md).
+- **Crash-safe persistent scrobble queue**
+  (`$XDG_STATE_HOME/refrain/scrobble_queue.jsonl`). A qualifying track
+  is queued the instant it earns it, so being offline, a Last.fm
+  outage, or quitting Refrain mid-song never loses a scrobble — it's
+  submitted (≤ 50-item batches) on the next opportunity. SHA-256
+  dedup, 1000-entry cap, atomic writes, corrupt-line tolerant. All
+  Last.fm network runs on a worker executor so the poll tick never
+  blocks; Privacy `Off` silences scrobbling too.
+- **Cover-art replacement notifications.** When iTunes is slow and the
+  ~2 s cover-retry window times out, Refrain now fires the
+  brand-fallback notification immediately, then re-issues it with
+  `notify-send --replace-id` once the cover finishes downloading — the
+  album art swaps into the *same* bubble instead of never appearing
+  (or a second popup).
+
+### Changed
+
+- **Per-source Discord Client IDs are now opt-in.** The General tab
+  showed three Client ID fields; most users need one. The two
+  per-source overrides (Apple Music / Bluetooth) are hidden behind a
+  *"Use a separate Discord application per source (advanced)"* toggle
+  (off by default, auto-enabled when an override is already
+  configured so existing setups are untouched).
+- **Source priority now prefers the actively-playing source.** A
+  stale *paused* Apple Music browser tab no longer masks music
+  actively playing over Bluetooth headphones (idle detection is
+  PLAYING-only, so the paused tab never cleared either). MPRIS keeps
+  the tie-break when neither is playing.
+- **Config saves preserve comments and unknown keys.** `Config.save()`
+  now rewrites only the `key = value` lines Refrain owns; hand-added
+  comments, ordering, and keys written by a newer Refrain survive the
+  daily silent update-check that stamps `last_check_ts`.
+- **More UI strings localised** — the Updates "last checked"
+  timestamp now formats in the active locale (`QLocale`) instead of a
+  hard-coded ISO string; the Bluetooth picker labels and the
+  live-log "ALL" sentinel are now translatable.
+
+### Fixed
+
+- `welcome_dialog.py` relied on `urllib.error` transitively via
+  `urllib.request`; an `except urllib.error.URLError` could have
+  raised `AttributeError` during handler matching. Imported
+  explicitly; dropped the unused `urllib.parse` import.
+- ROADMAP section ordering corrected — forward-looking sections no
+  longer sit above shipped releases.
+- Settings dialog no longer crushes/overlaps form rows: the Last.fm
+  controls moved to their own tab and every tab page is wrapped in a
+  scroll area; the default window size fits the tallest tab with no
+  visible scrollbar in English and German.
+
+### Security
+
+- **Last.fm credentials are never written to `config.toml`.** The
+  shared secret and session token are stored in the OS keyring
+  (freedesktop Secret Service — KWallet / GNOME Keyring), encrypted
+  at rest, hand-rolled on `dbus-python` (no new dependency). When no
+  keyring is reachable they fall back to a `0600`, owner-only file
+  separate from the config. `config.toml` itself is now written
+  `0600`, and a legacy plaintext secret left by an earlier build is
+  auto-migrated into the keyring and scrubbed from disk on the next
+  save. Secrets are never logged and only ever leave the machine to
+  Last.fm over HTTPS (which is scrobbling itself).
+
 ## [0.2.7] - 2026-05-07
 
 Tray-menu polish + Discord-RPC reliability fixes. Every tray action
@@ -1069,7 +1156,8 @@ 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.2.7...HEAD
+[Unreleased]: https://github.com/Rockykln/refrain/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/Rockykln/refrain/compare/v0.2.7...v0.3.0
 [0.2.7]: https://github.com/Rockykln/refrain/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/Rockykln/refrain/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/Rockykln/refrain/compare/v0.2.4...v0.2.5

{refrain-0.2.7 → refrain-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: refrain
-Version: 0.2.7
+Version: 0.3.0
 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
@@ -9,7 +9,7 @@ Project-URL: Changelog, https://github.com/Rockykln/refrain/blob/main/CHANGELOG.
 Author: Rockykln
 License-File: LICENSE
 Keywords: apple-music,bluetooth,discord,linux,mpris,rich-presence
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: X11 Applications
 Classifier: Intended Audience :: End Users/Desktop
 Classifier: License :: Other/Proprietary License
@@ -55,6 +55,8 @@ streaming from your iPhone over Bluetooth.
 - Reads playback metadata from **MPRIS** (Apple Music in any major Linux
   browser) and **BlueZ AVRCP** (any AVRCP-capable Bluetooth source).
 - Forwards track + cover art to Discord via the local IPC socket.
+- 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.
 - Provides a **settings window** (PySide6) for everything users typically want
   to tweak — privacy mode, sources, autostart, Bluetooth device picker.
@@ -197,6 +199,15 @@ 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", "es", "fr", "pt", "it", "ru", "pl", "ja", "zh_CN" force a translation
+
+[lastfm]
+enabled = false                    # opt-in, alongside (never replacing) the Discord RPC
+api_key = ""                       # register your own at last.fm/api/account/create
+username = ""                      # display only
+scrobble_now_playing = true        # also send the ephemeral "now playing" indicator
+# 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.
 ```
 
 Per-source `client_id_*` fields let Apple Music render under one Discord
@@ -295,14 +306,40 @@ Behavior is install-type-aware:
   own upgrade command (`flatpak update …` / `yay -Syu refrain`) so the
   package manager stays in charge.
 
+## Last.fm scrobbling
+
+Refrain can scrobble to [Last.fm](https://www.last.fm) **alongside** the
+Discord status — a second, independent channel, never a replacement.
+It's **opt-in** and off by default.
+
+Register your own free [API account](https://www.last.fm/api/account/create),
+then open the *Settings → Last.fm* tab: tick **Enable**, paste the
+**API key** + **shared secret**, click **Connect…** and approve the
+browser prompt. Scrobbling starts on the next track — no restart.
+
+The **shared secret and session token are stored in your OS keyring**
+(KWallet / GNOME Keyring), encrypted at rest — never in `config.toml`
+(which is itself written owner-only, `0600`). On a system with no
+keyring they fall back to a `0600` file. Credentials only ever leave
+the machine to Last.fm over HTTPS, which is what scrobbling *is*.
+
+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.
+
+Full walkthrough + troubleshooting: [`docs/lastfm.md`](docs/lastfm.md).
+
 ## File locations
 
-| What         | Where                                       |
-|--------------|---------------------------------------------|
-| Config       | `$XDG_CONFIG_HOME/refrain/config.toml`      |
-| Logs         | `$XDG_STATE_HOME/refrain/refrain.log` (rotates) |
-| Cover cache  | `$XDG_CACHE_HOME/refrain/covers/*.txt`      |
-| Autostart    | `$XDG_CONFIG_HOME/autostart/refrain.desktop` (when enabled) |
+| What          | Where                                       |
+|---------------|---------------------------------------------|
+| Config        | `$XDG_CONFIG_HOME/refrain/config.toml`      |
+| Scrobble queue| `$XDG_STATE_HOME/refrain/scrobble_queue.jsonl` |
+| Logs          | `$XDG_STATE_HOME/refrain/refrain.log` (rotates) |
+| Cover cache   | `$XDG_CACHE_HOME/refrain/covers/*.txt`      |
+| Autostart     | `$XDG_CONFIG_HOME/autostart/refrain.desktop` (when enabled) |
 
 ## Diagnostics — live log
 
@@ -317,22 +354,38 @@ without tailing it from a terminal.
 
 ## Privacy
 
-The cover-art lookup hits Apple's public iTunes Search API over HTTPS with
-just the artist + track name. Nothing else leaves your machine — track
-metadata goes to Discord's local IPC socket, not over the network.
+Refrain is **local-first**: no Refrain server, no account, **no
+telemetry**, and the author receives nothing. Data leaves your machine
+**only** when *you* enable an optional integration, and then it goes
+directly to that provider:
+
+- **Discord** — only if you set a Discord Application ID; track
+  metadata goes to the *local* Discord IPC socket (the Discord client
+  then broadcasts it under your account).
+- **Apple iTunes Search** (HTTPS) — artist + track name, only while
+  cover-art is enabled, to fetch album art. Untick it for zero egress.
+- **GitHub** (HTTPS) — a daily update check sends only the Refrain
+  version + your IP. Disable in *Updates*.
+- **Last.fm** (HTTPS) — opt-in scrobbling only; credentials live in
+  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.
 
-`Off` privacy mode disables the Discord status entirely while keeping the
-tray + controls running.
+Full data-flow, retention and erasure details — written to GDPR
+transparency expectations — are in [`PRIVACY.md`](PRIVACY.md).
 
 ## Documentation
 
 - [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
+- [Last.fm scrobbling](docs/lastfm.md) — API account + connect 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
+- [Privacy & data protection](PRIVACY.md) — every data flow, retention, erasure
 - [Security policy](SECURITY.md)
 - [Packaging guide](packaging/README.md) — AUR, Flatpak, AppImage build steps
 

refrain-0.3.0/PRIVACY.md

@@ -0,0 +1,148 @@
+# Privacy & Data Protection
+
+This document describes **every piece of data Refrain touches**, where it
+goes, why, and how to erase it. It is written to satisfy the
+transparency expectations of the EU GDPR (Arts. 13–14) and equivalent
+regimes, and as an honest plain-language overview for everyone.
+
+## TL;DR
+
+- Refrain is a **local desktop application**. There is **no
+  Refrain-operated server, no account, and no telemetry**. The author
+  receives **nothing** and has no access to any of your data.
+- Refrain does not profile you, does not make automated decisions about
+  you, shows no ads, and never sells or shares data.
+- Data leaves your machine **only** when *you* enable an optional
+  feature, and then it goes **directly** to the third party that
+  feature integrates with (Apple, Discord, GitHub, Last.fm) under
+  *their* privacy policy and *your* relationship with them — never via
+  the author.
+- Everything Refrain stores is on your own machine, in standard XDG
+  directories, and can be deleted at any time (see *Erasure*).
+
+## Who is the "controller"?
+
+Because Refrain runs entirely on your computer with no backend, **you**
+are effectively the controller of your own data. The Refrain author is
+not a processor of your data — the author never receives it. Each
+external transfer below is initiated solely by your own configuration
+choice (your consent / your own purposes) and is then subject to the
+receiving service's own privacy policy and your account there.
+
+## Data Refrain processes — and where it goes
+
+### 1. Stays on your machine, never transmitted by Refrain
+
+| Data | Purpose | Location |
+|---|---|---|
+| 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 |
+| 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 |
+| 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 never transmits any of the above over a network on its own.
+
+### 2. Sent to a third party — only when you enable that feature
+
+| Recipient | When | What is sent | Default | How to stop it |
+|---|---|---|---|---|
+| **Discord** (your local Discord client → Discord's servers) | Only if you set a Discord Application ID | Track title / artist / album, cover-art URL, optional "Listen on Apple Music" link | **Off** (no ID configured) | Leave the Client ID blank, or set *Privacy → Off*, or *Minimal* (only "Listening to music") |
+| **Apple** (`itunes.apple.com` + artwork CDN, HTTPS) | If "Fetch album cover art" is on **and** a track with artist+title plays | The **artist + track name** (to look up cover/duration/song URL) and your IP / User-Agent; then an image fetch. No account, no auth, no cookies | **On** | Untick *Notifications → Fetch album cover art from iTunes* |
+| **GitHub** (`api.github.com`, HTTPS) | If auto-update check is on: once per day on start, or a manual check | A `User-Agent` containing the Refrain version, and your IP. **No personal data, no account** | **On** | Untick *Updates → Automatically check on startup* |
+| **Last.fm** (`ws.audioscrobbler.com` / `last.fm`, HTTPS) | Only if you enable scrobbling **and** connect an account | Artist / track / album / timestamp, your Last.fm API key + session token + a request signature | **Off** (opt-in) | Don't enable it; or *Disconnect*; or set *Privacy → Off* |
+
+Notes:
+
+- **Privacy modes** (*Settings → General → Privacy*): `Full` sends full
+  metadata to Discord; `Minimal` sends only "Listening to music";
+  `Off` is the global **no-external-broadcasting** kill switch — it
+  disables the Discord status **and** silences Last.fm scrobbling.
+- The Apple cover-art lookup is gated by the *cover-art* toggle, which
+  is **independent of Privacy mode** — if you want zero network egress
+  even in `Off` mode, also untick "Fetch album cover art".
+- Discord itself then displays/broadcasts your status to your Discord
+  contacts. That processing is Discord's, under your Discord account
+  and Discord's policy — Refrain only writes to the **local** Discord
+  IPC socket.
+
+### 3. Never collected at all
+
+No analytics, no telemetry, no crash reporting, no advertising
+identifiers, no device/hardware fingerprinting, no machine ID, no
+contacts, no email, no location, no special-category data, no data
+about children. There is nothing to opt out of because none of it
+exists.
+
+## Legal basis (GDPR Art. 6)
+
+Every external transfer above happens **only** because you enabled the
+corresponding optional integration for your own purposes — i.e. your
+**consent / your own legitimate use**. No processing relies on the
+author having any legal basis, because the author processes nothing.
+
+## Recipients & international transfers
+
+When you enable an integration, data goes directly to that provider,
+which may process it outside your country under its own framework and
+policy. Refrain has no influence over this. Review their policies:
+
+- Apple — <https://www.apple.com/legal/privacy/>
+- Discord — <https://discord.com/privacy>
+- GitHub — <https://docs.github.com/site-policy/privacy-policies/github-general-privacy-statement>
+- Last.fm — <https://www.last.fm/legal/privacy>
+
+## Security of processing (GDPR Art. 32)
+
+- All network egress is **HTTPS** (the code refuses non-`https://`
+  endpoints for its lookups/updates).
+- Credentials are stored in the **OS keyring, encrypted at rest**;
+  the fallback file and `config.toml` are written **owner-only
+  (`0600`)**. Secrets are **never written to logs** or to
+  `config.toml`, and a legacy plaintext secret from an older build is
+  auto-migrated into the keyring and scrubbed from disk.
+- Refrain writes only inside `$XDG_CONFIG_HOME`, `$XDG_STATE_HOME`,
+  `$XDG_CACHE_HOME`.
+- See [`SECURITY.md`](SECURITY.md) for the threat model and how to
+  report a vulnerability.
+
+## Retention & your control
+
+- **Logs** rotate automatically (≤ 4 files of 1 MB); old data ages out.
+- **Cover cache** is capped and pruned oldest-first.
+- **Scrobble queue** entries are deleted once submitted; the queue is
+  capped at 1000.
+- Everything else persists until you change or delete it.
+
+## Erasure ("right to be forgotten", locally)
+
+To remove all data Refrain stored on your machine:
+
+```sh
+rm -rf "${XDG_CONFIG_HOME:-$HOME/.config}/refrain" \
+       "${XDG_STATE_HOME:-$HOME/.local/state}/refrain" \
+       "${XDG_CACHE_HOME:-$HOME/.cache}/refrain"
+```
+
+- **Last.fm credentials in the keyring:** click *Disconnect* in
+  *Settings → Last.fm* (then Apply), or delete the
+  `io.github.Rockykln.Refrain` entries in your keyring tool
+  (KWallet Manager / Seahorse).
+- **Data already sent to a third party** (your Discord activity
+  history, your Last.fm scrobbles, etc.) is held by *that* provider —
+  exercise your access/erasure rights with them directly via their
+  links above (e.g. Last.fm lets you delete individual scrobbles or
+  your account).
+- Autostart entry (if enabled):
+  `${XDG_CONFIG_HOME:-$HOME/.config}/autostart/refrain.desktop`.
+
+## Changes
+
+Material changes to data handling are recorded in
+[`CHANGELOG.md`](CHANGELOG.md) (notably under **Security**) and here.
+
+## Contact
+
+- General / privacy questions → **contact@rockykln.com**
+- Security reports → **report@rockykln.com** (see [`SECURITY.md`](SECURITY.md))

{refrain-0.2.7 → refrain-0.3.0}/README.md

@@ -21,6 +21,8 @@ streaming from your iPhone over Bluetooth.
 - Reads playback metadata from **MPRIS** (Apple Music in any major Linux
   browser) and **BlueZ AVRCP** (any AVRCP-capable Bluetooth source).
 - Forwards track + cover art to Discord via the local IPC socket.
+- 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.
 - Provides a **settings window** (PySide6) for everything users typically want
   to tweak — privacy mode, sources, autostart, Bluetooth device picker.
@@ -163,6 +165,15 @@ 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", "es", "fr", "pt", "it", "ru", "pl", "ja", "zh_CN" force a translation
+
+[lastfm]
+enabled = false                    # opt-in, alongside (never replacing) the Discord RPC
+api_key = ""                       # register your own at last.fm/api/account/create
+username = ""                      # display only
+scrobble_now_playing = true        # also send the ephemeral "now playing" indicator
+# 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.
 ```
 
 Per-source `client_id_*` fields let Apple Music render under one Discord
@@ -261,14 +272,40 @@ Behavior is install-type-aware:
   own upgrade command (`flatpak update …` / `yay -Syu refrain`) so the
   package manager stays in charge.
 
+## Last.fm scrobbling
+
+Refrain can scrobble to [Last.fm](https://www.last.fm) **alongside** the
+Discord status — a second, independent channel, never a replacement.
+It's **opt-in** and off by default.
+
+Register your own free [API account](https://www.last.fm/api/account/create),
+then open the *Settings → Last.fm* tab: tick **Enable**, paste the
+**API key** + **shared secret**, click **Connect…** and approve the
+browser prompt. Scrobbling starts on the next track — no restart.
+
+The **shared secret and session token are stored in your OS keyring**
+(KWallet / GNOME Keyring), encrypted at rest — never in `config.toml`
+(which is itself written owner-only, `0600`). On a system with no
+keyring they fall back to a `0600` file. Credentials only ever leave
+the machine to Last.fm over HTTPS, which is what scrobbling *is*.
+
+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.
+
+Full walkthrough + troubleshooting: [`docs/lastfm.md`](docs/lastfm.md).
+
 ## File locations
 
-| What         | Where                                       |
-|--------------|---------------------------------------------|
-| Config       | `$XDG_CONFIG_HOME/refrain/config.toml`      |
-| Logs         | `$XDG_STATE_HOME/refrain/refrain.log` (rotates) |
-| Cover cache  | `$XDG_CACHE_HOME/refrain/covers/*.txt`      |
-| Autostart    | `$XDG_CONFIG_HOME/autostart/refrain.desktop` (when enabled) |
+| What          | Where                                       |
+|---------------|---------------------------------------------|
+| Config        | `$XDG_CONFIG_HOME/refrain/config.toml`      |
+| Scrobble queue| `$XDG_STATE_HOME/refrain/scrobble_queue.jsonl` |
+| Logs          | `$XDG_STATE_HOME/refrain/refrain.log` (rotates) |
+| Cover cache   | `$XDG_CACHE_HOME/refrain/covers/*.txt`      |
+| Autostart     | `$XDG_CONFIG_HOME/autostart/refrain.desktop` (when enabled) |
 
 ## Diagnostics — live log
 
@@ -283,22 +320,38 @@ without tailing it from a terminal.
 
 ## Privacy
 
-The cover-art lookup hits Apple's public iTunes Search API over HTTPS with
-just the artist + track name. Nothing else leaves your machine — track
-metadata goes to Discord's local IPC socket, not over the network.
+Refrain is **local-first**: no Refrain server, no account, **no
+telemetry**, and the author receives nothing. Data leaves your machine
+**only** when *you* enable an optional integration, and then it goes
+directly to that provider:
+
+- **Discord** — only if you set a Discord Application ID; track
+  metadata goes to the *local* Discord IPC socket (the Discord client
+  then broadcasts it under your account).
+- **Apple iTunes Search** (HTTPS) — artist + track name, only while
+  cover-art is enabled, to fetch album art. Untick it for zero egress.
+- **GitHub** (HTTPS) — a daily update check sends only the Refrain
+  version + your IP. Disable in *Updates*.
+- **Last.fm** (HTTPS) — opt-in scrobbling only; credentials live in
+  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.
 
-`Off` privacy mode disables the Discord status entirely while keeping the
-tray + controls running.
+Full data-flow, retention and erasure details — written to GDPR
+transparency expectations — are in [`PRIVACY.md`](PRIVACY.md).
 
 ## Documentation
 
 - [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
+- [Last.fm scrobbling](docs/lastfm.md) — API account + connect 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
+- [Privacy & data protection](PRIVACY.md) — every data flow, retention, erasure
 - [Security policy](SECURITY.md)
 - [Packaging guide](packaging/README.md) — AUR, Flatpak, AppImage build steps