LyricFlow: Lyrics for VS Code

Read song lyrics in the VS Code sidebar. On Linux, the extension reads player metadata through D-Bus/MPRIS and finds lyrics on LRCLIB, with lyrics.ovh as a plain-lyrics fallback. Manual search works on Linux, Windows, and macOS; automatic player detection is currently Linux-only.

Run from source

1. Open this folder in VS Code desktop.
2. Run npm ci --omit=optional (Node.js 22 or later for tooling).
3. Press F5 and choose Run Lyrics.
4. In the Extension Development Host window, click Lyrics in the Activity Bar or run Lyrics: Open Sidebar from the Command Palette.
5. On Linux, play music in a browser or player that publishes an MPRIS session, such as Brave, Firefox, Spotify, or VLC.

The extension does not require playerctl. For automatic detection, VS Code must run in the same Linux desktop session as the player and be able to access the session D-Bus. In Remote SSH, WSL, or Dev Containers, the extension runs on the local UI side, so automatic detection requires that UI host to be Linux.

Use

• The Player selector in the footer chooses a media source. Automatic follows the active source.
• Previous, Play/Pause, Next, and Seek control playback when the source supports them. Unsupported actions are disabled, and failed changes show a recovery message.
• Timestamped lyrics show a time column, highlight the current line, and follow playback. Singer or section headings appear when included in the lyrics. Scroll the lyrics to pause following, then select Follow lyrics to resume.
• The search field is open by default. Search by title or artist, press Enter or select the arrow, and choose a result. The search icon in the track header shows or hides the field.
• A manually selected lyric stays active until the selected track or player changes. Manual timestamped lyrics retain their timestamps without following the active player. Refresh returns to automatic lyrics for the current player.
• Reconnect retries the Linux media session connection when it fails.
• Artwork comes from the selected player when available; otherwise a music-note placeholder appears. Manual selections use the placeholder. A LIVE badge identifies explicitly labeled live versions.
• The layout adapts to narrow sidebars and VS Code light, dark, and high-contrast themes. In very short views, scroll the sidebar to reach all controls.

Support and privacy

The extension UI and manual lyrics search work on Linux, Windows, and macOS. Automatic player detection and playback controls currently use Linux MPRIS only. A browser or player is detected when it publishes a compatible MPRIS session; the extension does not inspect browser tabs, record audio, or recognize songs. Windows and macOS show disabled player controls and keep manual search available.

Incorrect or missing titles, artist metadata, and live/remix versions can prevent a match. Use manual search to select the right version. Players that do not provide a position cannot synchronize lyrics. If several sources are active, automatic selection keeps following the current active source; choose a source manually when needed.

Track title, artist, album, duration, and manual search queries are sent over HTTPS to LRCLIB. For automatic lookup, title and available artist metadata are also sent to lyrics.ovh if LRCLIB has no usable lyrics or its request fails. Artwork URLs provided by the player are loaded by the extension host over HTTPS or from a local file, with a 5 MiB limit and a five-second timeout. HTTPS artwork loading contacts the host named by the player. Only PNG, JPEG, WebP, and GIF artwork is accepted; missing or invalid artwork does not interrupt lyrics. The extension has no telemetry, account tokens, search history, or proxy server. A cache of up to 100 LRCLIB responses is kept in session memory. lyrics.ovh provides plain lyrics; availability, accuracy, and rights follow each source and the rights holders. Attribution is available in the sidebar footer.

Test and package

npm test
npm run check
npm run package

The package is written to vscode-lyrics-0.1.1.vsix. Install it through Extensions → … → Install from VSIX…, or run:

code --install-extension ./vscode-lyrics-0.1.1.vsix

Unit tests use node:test for LRC parsing and section headings, D-Bus metadata and player control (including backend shuffle/volume support), source selection, bounded artwork loading and stale covers, lyric matching, HTTP/cache behavior, lyrics fallback, manual search, and stale responses. Unit tests do not require a player, VS Code, or internet access. Verify the UI in the Extension Development Host and playback controls with a real Linux MPRIS player. macOS verification requires a Mac.

Project structure

• src/: VS Code integration, D-Bus, lyrics service, and session state.
• media/: Activity Bar icon and sidebar HTML/CSS/JavaScript.
• test/: Node.js logic tests.
• .vscode/launch.json: F5 debug configuration.

There is no frontend framework or app build step. dbus-next reads media; undici manages per-client HTTP connections. Both are runtime dependencies; @vscode/vsce is only used for packaging.