sptlrx prints time-synced lyrics for whatever is playing on your desktop

What sptlrx does in one sentence

sptlrx is described as synchronized lyrics in your terminal, and the demo in the README is a track by Crystal Castles playing with the current line highlighted as the song progresses. The feature list is short: compatibility with Spotify, MPD, Mopidy, MPRIS and browsers, good handling of long lines and Unicode characters, easy customisation, the ability to pipe to stdout, and a single cross-platform binary. That last pair of points is what makes it more than a novelty. A single binary means there is no runtime to install, and piping to stdout means the lyric line can be embedded in a status bar rather than occupying a terminal window of its own. The topics confirm the scope, with lyrics, mopidy, mpd, spotify, spotifyd, synced-lyrics and terminal, and the primary language is Go with the module named github.com/raitonoberu/sptlrx. Releases are v1.3.1 from 2026-04-05, v1.3.0 from 2026-04-02 and v1.2.3 from 2025-04-02.

Where the lyrics come from, and the local mode that overrides everything

The primary source is lrclib.net, and it is also possible to use local .lrc files. The local mode is the more interesting of the two, because of what it changes. You specify a folder to scan, for example your music directory, and the application uses files with the most similar name, and all other lyrics sources will be disabled. That is a clean design rather than a fallback, since scanning your own collection gives you the sync you want and removes the network dependency entirely. The configuration section for it is a single key.

local:
  folder: ""

The player selection is separate from the lyric source, and that separation is what allows a local lyrics folder to work with any of the five player backends. The global player key accepts spotify, mpd, mopidy, mpris and browser.

The five player backends and their configuration

Each backend has its own section in the config, and each is a small block. For MPD there is an address with a port and an optional password.

player: mpd
mpd:
  address: 127.0.0.1:6600
  password: ""

Mopidy uses the same shape with its own default port.

player: mopidy
mopidy:
  address: 127.0.0.1:6680

MPRIS is Linux only, and takes a whitelist of players with the first available used if the list is empty.

player: mpris
mpris:
  players: []

The browser mode runs a small local server that the extension talks to.

player: browser
browser:
  port: 8974

That mode needs a browser extension installed, and if you change the default port you have to create a custom adapter in the extension settings. The README warns that you can only run one instance on one port. The MPRIS backend has a nice touch for anyone on Linux, since the whitelist accepts names you can list with playerctl -l, and the example given includes rhythmbox, spotifyd and ncspot.

Spotify, and the one-time OAuth dance

Spotify is the only backend that needs credentials, and the README walks through it. You create a new app on the Spotify developer dashboard and set the redirect URI to http://127.0.0.1:8888/callback, then grab your Client ID and Client Secret. Then you run sptlrx login, passing the credentials in one of three ways: as the environmental variables SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET, as the CLI parameters --client-id and --client-secret, or interactively by running the login command without credentials and being prompted. A browser window opens, you log in, and you wait for the success message. It is a one-time step, since your credentials are then saved to $XDG_STATE_HOME/sptlrx/spotify-auth.json. That path is worth noting, because state and cache directories are separate on Linux and keeping the OAuth token out of the config directory means it does not travel with a configuration backup.

The style system, and overriding it from the command line

Styling is done in the config file, which is created at first launch and lives at ~/.config/sptlrx/config.yaml on Linux, with sptlrx -h showing the full path. The style section has an hAlignment of left, center or right, and then before, current and after blocks that each carry background, foreground and a set of boolean attributes for bold, italic, underline, strikethrough, blink and faint. The current line is bold, and the after lines are faint, which is the classic karaoke contrast. Colours can be in HEX format or ANSI 0-255. Each style can also be overridden per invocation, which is the part that makes the tool scriptable.

sptlrx --current "bold,#FFDFD3,#957DAD" --before "104,faint,italic" --after "104,faint"

The argument order is style attributes first, then foreground colour, then background colour, and the README lists the allowed style names and says the first colour represents the foreground and the second the background. Run sptlrx --help to see all the flags.

Piping, and the configuration keys that control timing

The piping mode is the most composable part. Run sptlrx pipe to start printing the current lines to stdout, and the README says this can be used in various status bars and other applications. On the timing side there are two intervals in the global settings. timerInterval is the interval of the internal timer, which determines how often the terminal is updated, and defaults to 200. updateInterval is the interval for checking the position, which the README says does not really affect the precision, and defaults to 2000. So the display redraws five times a second while the position is polled twice a second, which is the sensible split. There is also an ignoreErrors flag, false by default, described as whether to ignore errors instead of showing them, and the pipe section has a length of 0 meaning unlimited and an overflow handling of word, none or ellipsis. The repository layout shows the Go packages behind this, with player, lyrics, pool, services, config, cmd, ui and man directories, and a .goreleaser.yaml for the cross-platform release builds.

Where sptlrx is the wrong choice

Three limits. The first is that every backend is local or requires a bridge. MPD, Mopidy and MPRIS are local daemons on your machine, and the browser mode needs a companion extension and a local server, so a service that only exists behind a web player or a mobile app needs the extension path or nothing. The second is that the lyrics are only as good as lrclib.net's coverage, and the local mode is limited to files you already have as .lrc on disk. The README does not describe a fallback chain or a cache-and-retry policy, so a network failure during a song with no local file leaves you with nothing, and the ignoreErrors flag exists precisely because errors do surface. The third is that the tool is a terminal program with a config file, not a library, so embedding synced lyrics in another Go program means reimplementing rather than importing it. The realistic alternative is a desktop lyric application or a browser extension that overlays lyrics on a player, both of which give you a graphical result with less configuration, and the case for sptlrx is specifically that you want the lyrics in a terminal, in a status bar, or piped into something else you already run.

Editorial conclusion

Adopt sptlrx if you want karaoke-style lyrics for desktop playback in a terminal, and if you already run one of the supported players. Skip it if your music comes from a service with no local player, since the browser mode depends on a separate extension and a local port. Before you configure it, decide whether lyrics come from lrclib.net or from your own .lrc folder, because the local mode disables all other sources.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. raitonoberu/sptlrx on GitHub
4. README
5. Releases