Discord Rich Presence for Apple Music on Linux.
Refrain shows what you're listening to on Apple Music as your Discord status
— whether the audio is playing in a browser tab on music.apple.com or
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.
┌─────────────────────────────────────────────────────────┐
│ Refrain │
│ │
│ ┌──────────┐ ┌──────────┐ ┌────────────────┐ │
│ │ MPRIS │ │ BlueZ │ │ Tray + │ │
│ │ source │ │ AVRCP │ │ Settings UI │ │
│ └────┬─────┘ └────┬─────┘ └───────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Background daemon │ │
│ └────────────────────┬────────────────────────┘ │
│ │ │
│ ▼ │
│ Discord Rich Presence (IPC) │
└─────────────────────────────────────────────────────────┘
- Linux with D-Bus
- Python ≥ 3.11
- Discord desktop client running (Refrain talks to its IPC socket)
- For Bluetooth: BlueZ with AVRCP enabled
| Channel | Install |
|---|---|
| PyPI (any distro with Python ≥ 3.11) | pip install refrain |
| AUR (Arch / CachyOS / Manjaro / EndeavourOS) | yay -S refrain (stable) or yay -S refrain-git (latest main) |
| AppImage (portable single-file, any glibc-based distro) | Download from the Releases page |
| From source | See below |
A Flatpak manifest exists under packaging/flatpak/ for users who want to
build it themselves; a Flathub submission is on the roadmap but not
currently active. Build files for the live channels live under
packaging/.
See packaging/README.md for build instructions.
git clone https://github.com/Rockykln/refrain.git
cd refrain
# On distros that already package Qt-for-Python and dbus-python (Arch, Fedora,
# openSUSE …) a venv with --system-site-packages avoids re-downloading them.
python -m venv --system-site-packages .venv
source .venv/bin/activate
pip install -e .
refrainIf your distro doesn't ship PySide6 or dbus-python, plain
python -m venv .venv works too — pip will pull PySide6 from PyPI and
build dbus-python against your system's D-Bus headers
(libdbus-1-dev on Debian/Ubuntu, dbus-devel on Fedora).
When installed via pip rather than a distro package, Refrain doesn't
register itself with your application menu. Run once after install:
refrain --install-desktopThis copies the .desktop file and icon to ~/.local/share/applications/
and ~/.local/share/icons/. To undo: refrain --uninstall-desktop.
See 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 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.
Refrain needs a Discord Application ID to push status updates. Each user registers their own (free, takes 30 seconds):
- Open https://discord.com/developers/applications and click New Application.
- Name it whatever you want — that name is what shows up under "Listening to ..." in your Discord status. You can also upload a square image as the application icon; Discord uses it as the fallback when there's no album cover.
- Copy the Application ID from the General Information page.
- Launch Refrain → Settings → General → Discord Client ID → paste, Apply.
The first time you launch Refrain without a configured ID, the welcome wizard pops up with the setup steps + a live diagnostics panel that probes your D-Bus session and Discord IPC socket so you know up front whether your environment can host the RPC at all.
That's it. The status will appear in Discord on the next track change.
Settings live at $XDG_CONFIG_HOME/refrain/config.toml
(typically ~/.config/refrain/config.toml). The settings window edits the
same file; you almost never need to touch it by hand.
[discord]
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
bluetooth_enabled = true
bluetooth_device = "" # empty = auto-detect, or "AA:BB:CC:DD:EE:FF"
[privacy]
mode = "full" # "full" | "minimal" | "off"
[behavior]
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 = 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", "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
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.
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.
Every item carries a theme-matched icon (freedesktop icon names on Plasma / GNOME / Breeze; bundled accent SVGs for Update and Quit) — no unicode-glyph prefixes.
| Item | What it does |
|---|---|
| Title | Currently playing track (click opens Settings) |
| Artist • Album | Currently playing artist + album (hidden when idle) |
| X:XX / Y:YY (–Z:ZZ) | Elapsed / track length / remaining (hidden when idle) |
| Discord: connected / not connected | Live Discord-RPC connection state |
| Previous | Skip backward on the active source |
| 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 |
| 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) |
| Quit Refrain | Stop the daemon and exit |
Left-click the tray icon opens Settings, middle-click toggles play/pause, right-click shows this menu. (DBusMenu keeps an open menu's text static, so the progress line is a snapshot from when you opened it — hover the tray icon for a live-updating tooltip.)
The settings window opens on first launch, and again any time you click
Settings… from the tray. Hitting Apply writes the change to
config.toml, hides the window, and keeps the daemon + tray running in
the background.
General
Discord client ID, privacy, autostart, notifications, cover art |
Sources
MPRIS / Bluetooth toggles + paired-device picker |
Updates
Auto-check, last-checked, manual Check for updates now |
Advanced
Poll interval, notification delay, cover cache size, log level, live-log, restart |
When a track changes, Refrain fires a desktop notification with the album cover, song title, artist and album — the same data that's going to your Discord status. Toggle off in Settings → General if you don't want them.
Refrain checks the GitHub Releases API once per day on startup. When a newer version exists, the tray menu shows an Update available item that opens this dialog:
Behavior is install-type-aware:
- AppImage — Refrain downloads the new
.AppImagefrom the release assets and replaces the running binary in place (atomic rename), then prompts a restart. - pip / venv — runs
pip install --upgrade refrainfor you. - Flatpak / AUR — never modifies system files; surfaces the distro's
own upgrade command (
flatpak update …/yay -Syu refrain) so the package manager stays in charge.
Refrain can scrobble to 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, 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.
Refrain can wipe everything it ever wrote — on any distro, any install method — with one command:
refrain --uninstall # asks for confirmation; -y to skipThis deletes the config, logs, cover cache, scrobble queue, autostart entry and menu entry, and purges the Last.fm credentials from your OS keyring, then prints the exact command to remove the program itself for your install type (pip / pipx / AUR / Flatpak / AppImage). There's also a Settings → Advanced → Uninstall Refrain… button.
Removing just the program (keeping your settings) is the package
command for how you installed it — pip uninstall refrain,
pipx uninstall refrain, yay -R refrain,
flatpak uninstall io.github.Rockykln.Refrain, or deleting the
.AppImage. (refrain --uninstall-desktop removes only the menu
entry + icon.)
| 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) |
Tray menu → Live log… (or launch with refrain --debug) opens a
streaming view of every log line as it happens, color-coded by level and
filterable. Same content as ~/.local/state/refrain/refrain.log, but
without tailing it from a terminal.
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.
Full data-flow, retention and erasure details — written to GDPR
transparency expectations — are in PRIVACY.md.
- Architecture overview — threads, D-Bus surface, file paths
- FAQ
- Bluetooth quick-start — pair + AVRCP setup walkthrough
- Last.fm scrobbling — API account + connect walkthrough
- Test matrix — supported distros, smoke-check checklist
- Roadmap
- Changelog
- Contributing — dev setup, testing, code style
- Privacy & data protection — every data flow, retention, erasure
- Security policy
- Packaging guide — AUR, Flatpak, AppImage build steps
See CONTRIBUTING.md for dev setup, testing, and the
source/UI architecture. PRs welcome — especially for distribution packaging
(Flatpak, AUR, AppImage) and for additional Bluetooth device shapes.
- General questions, feedback, feature ideas → [email protected]
- Security reports → [email protected] (also: GitHub private advisory)
- Bugs → please use the issue tracker
Refrain License (Use-Only) — see LICENSE.
Refrain is source-available but not open source. In short:
- ✅ Anyone may use, copy, and redistribute the unmodified Software.
- ✅ Anyone may read, study, and reference the source code.
- ❌ Modifications and derivative works (including forks) may not be redistributed.
- ❌ The "Refrain" name and logo may not be used to imply endorsement of or affiliation with modified versions.
Third-party dependencies (PySide6, pypresence, dbus-python) retain
their original licenses (LGPL / MIT).