How rockykln/refrain works
Refrain is a Linux desktop companion that reads Apple Music playback metadata from MPRIS (including browser players) or Bluetooth AVRCP, then publishes track status to Discord. Its daemon coordinates playback polling, track timing, cover lookup, local history, and optional Last.fm scrobbling; Qt tray, status, history, welcome, and settings interfaces expose controls and configuration. The README documents these capabilities, while sampled daemon excerpts confirm source setup, cover lookup, and history updates. Other links are limited to explicit source-index references or README statements; unsampled implementation details are not inferred.
Main entry points: daemon.py Playback daemon · app.py Application startup · settings_window.py Settings window · bluetooth.py Bluetooth source
Components 28
Playback and coordination
- Application startup
src/refrain/app.py - Playback daemon
src/refrain/daemon.py - Track model
src/refrain/sources/base.py - MPRIS source
src/refrain/sources/mpris.py - Bluetooth source
src/refrain/sources/bluetooth.py - MPRIS publishing
src/refrain/sources/mpris_server.py - Track timing
src/refrain/timing.py - Cover lookup
src/refrain/cover_fetcher.py
Status and scrobbling
- Discord IPC
src/refrain/discord_rpc.py - Discord app lookup
src/refrain/discord_app.py - Last.fm scrobbling
src/refrain/scrobble.py - Offline queue
src/refrain/scrobble_queue.py - Service status
src/refrain/service_status.py
Desktop experience
- System tray
src/refrain/ui/tray.py - Status window
src/refrain/ui/status_window.py - Settings window
src/refrain/ui/settings_window.py - Welcome wizard
src/refrain/ui/welcome_dialog.py - Recently played UI
src/refrain/ui/history_window.py
Local data and setup
- Listening history
src/refrain/history.py - Configuration
src/refrain/config.py - Runtime paths
src/refrain/paths.py - Cover art cache
src/refrain/cover_art.py - Update checking
src/refrain/updater.py
Other components
- User
- Browser player
- Bluetooth device
- Discord client
- Last.fm
Connections 37
- User → Application startup: launches
- Browser player → MPRIS source: publishes metadata
- Bluetooth device → Bluetooth source: reports track
- Application startup → Playback daemon: starts
src/refrain/app.py - Application startup → System tray: wires controls
src/refrain/app.py - Application startup → Configuration: loads settings
src/refrain/app.py - Application startup → Welcome wizard: shows setup
src/refrain/app.py - Playback daemon → MPRIS source: polls
src/refrain/daemon.py - Playback daemon → Bluetooth source: polls
src/refrain/daemon.py - Playback daemon → Discord IPC: updates status
src/refrain/daemon.py - Playback daemon → Cover lookup: looks up cover
src/refrain/daemon.py - Playback daemon → Listening history: records tracks
src/refrain/daemon.py - Playback daemon → Last.fm scrobbling: scrobbles tracks
src/refrain/daemon.py - Playback daemon → MPRIS publishing: publishes playback
src/refrain/daemon.py - Playback daemon → Track timing: resolves position
src/refrain/daemon.py - MPRIS source → Track model: produces tracks
src/refrain/sources/mpris.py - Bluetooth source → Track model: produces tracks
src/refrain/sources/bluetooth.py - Playback daemon → Service status: reports state
src/refrain/service_status.py - Service status → System tray: shows state
src/refrain/ui/tray.py - Service status → Status window: shows state
src/refrain/ui/status_window.py - Discord IPC → Discord client: sends presence
- Last.fm scrobbling → Last.fm: sends scrobbles
- Last.fm scrobbling → Offline queue: queues offline
src/refrain/scrobble.py - System tray → Playback daemon: controls playback
src/refrain/app.py - User → Settings window: configures
- User → System tray: controls playback
- Status window → Recently played UI: opens history
src/refrain/ui/status_window.py - Recently played UI → Listening history: reads entries
src/refrain/ui/history_window.py - Playback daemon → Cover art cache: uses artwork
- Settings window → Configuration: edits settings
src/refrain/ui/settings_window.py - Settings window → Discord app lookup: resolves app
src/refrain/ui/settings_window.py - Settings window → Bluetooth source: selects device
src/refrain/ui/settings_window.py - Settings window → Update checking: checks updates
src/refrain/ui/settings_window.py - Welcome wizard → Discord app lookup: checks application
src/refrain/ui/welcome_dialog.py - Cover lookup → Cover art cache: uses cache
- Configuration → Runtime paths: uses paths
src/refrain/config.py - Listening history → Runtime paths: stores locally
src/refrain/history.py