Synced lyrics viewer for Linux, built with GTK 4 and libadwaita. It shows the lyrics of whatever is playing in your music player and highlights the current line.
It works with any player that supports MPRIS2, which covers most Linux players: G4Music, Rhythmbox, VLC, Amberol, Lollypop, Tauon, Spotify and others.
- Highlights the current line and scrolls along with the song. Lines further from the current one are dimmer.
- Click a line, or drag the seek bar, to jump to that point in the song.
- Play/pause, previous and next buttons, album art and track progress.
- Lyrics come from lrclib.net and are cached locally, so they load instantly and work offline after the first play.
- Uses local
.lrcfiles: one next to the audio file is picked up automatically, and you can add folders to scan. - Manual search: if the lyrics are wrong or missing, search lrclib.net and pick a result. It's saved for that track.
- Sync offset: shift the lyrics earlier or later in 0.25 s steps if the timing is off. The offset is saved per track.
- If several players are running, it follows the one that started playing most recently. You can also pick one from the menu.
- Dark and light themes, adjustable text size, keyboard shortcuts.
- Python 3.9 or newer with PyGObject
- GTK 4.12 or newer and libadwaita 1.5 or newer
| Distro | Supported |
|---|---|
| Fedora 40+, Arch, Ubuntu 24.04+, Debian 13, openSUSE Tumbleweed | Yes |
| Ubuntu 22.04, Debian 12 and older | No, libadwaita is too old |
It runs on any desktop (GNOME, KDE, …) under Wayland or X11. There are no pip dependencies.
git clone https://github.com/Mischou01/lyricsync.git
cd lyricsync
./install.shThe installer:
- Checks that the GTK 4 and libadwaita Python bindings are installed. If they aren't, it shows the command for your package manager (dnf, apt, pacman or zypper) and asks before running it. This is the only step that uses sudo.
- Copies the app to
~/.local/bin/lyricsync. - Adds a launcher to
~/.local/share/applications/, so LyricSync shows up in your app menu.
To update, run git pull and then ./install.sh again.
To try it without installing, run python3 lyricsync.py.
Start playing a song, then open LyricSync. It finds the player and loads the lyrics.
If you scroll away from the current line, auto-scroll pauses. Click Current Line, or wait 4 seconds, to go back.
The main menu (☰) contains:
- Text Size:
−and+. Click the value to reset it. - Sync Offset:
+shows lyrics earlier,−later. The current offset is shown under the track title, e.g.lrclib.net · Synced · +0.50 s. - Player: Automatic follows whichever player is playing. Pick a player to stay on it.
- Search and reload lyrics, Preferences, Keyboard Shortcuts, About.
Click the search button or press Ctrl+F. The search box is filled in from the current track. Results are marked Synced (with timestamps) or Plain (text only). Clicking one uses it for the track that's playing and saves it to the cache.
| Shortcut | Action |
|---|---|
Ctrl+F |
Search lyrics |
Ctrl+R / F5 |
Reload lyrics, ignoring the cache |
Ctrl+] / Ctrl+[ |
Lyrics earlier / later |
Ctrl+\ |
Reset sync offset |
Ctrl++ / Ctrl+- / Ctrl+0 |
Larger / smaller / default text size |
Ctrl+Space |
Play / pause |
Alt+→ / Alt+← |
Next / previous track |
Ctrl+, |
Preferences |
Ctrl+? |
Shortcuts overview (libadwaita 1.8+) |
Ctrl+W / Ctrl+Q |
Close / quit |
Open ☰ → Preferences or press Ctrl+,.
| Setting | Description |
|---|---|
| Style | Follow the system, light or dark |
| Lyrics Text Size | Same as the stepper in the main menu |
| Cache | Use lyrics saved from earlier plays |
| Local Files | Use .lrc files next to the audio file or in your lyrics folders |
| lrclib.net | Download lyrics from lrclib.net |
| Lyrics Folders | Folders to search for .lrc files |
| Save Fetched Lyrics | Turn caching on or off |
| Saved Lyrics | Number of cached tracks, with buttons to open the folder or clear it |
Sources are tried in the order listed: Cache, then Local Files, then lrclib.net.
If your player reports file paths (most local players do), a .lrc file with the same name as the audio file is used automatically, e.g. Song.flac → Song.lrc. Local Files must be enabled.
Files in your lyrics folders are matched by name. The file name has to contain the track title, and files that also contain the artist are preferred, so Artist - Title.lrc and Title.lrc both work.
Local files are read again each time a track starts, so edits show up the next time it plays.
| Path | Contents |
|---|---|
~/.config/lyricsync/settings.json |
Preferences, sync offsets, window size |
~/.local/share/lyricsync/cache/ |
Cached lyrics (.lrc and .txt) |
~/.local/bin/lyricsync |
The app |
~/.local/share/applications/io.github.Mischou01.LyricSync.desktop |
App menu entry |
./install.sh --uninstallThis keeps your settings and cached lyrics. To delete those too:
rm -rf ~/.config/lyricsync ~/.local/share/lyricsync| Issue | Cause | Workaround |
|---|---|---|
| Sync is only approximate with Spotify and phone players (GSConnect / KDE Connect) | These players don't report the playback position correctly, so LyricSync keeps its own timer from the start of the track | It's accurate if LyricSync was open when the track started. Otherwise click the line being sung to re-align it. |
| Lyrics are slightly early or late | The timestamps in the lyrics file are off | Use Sync Offset in the main menu |
| No lyrics found | lrclib.net doesn't have the track | Use manual search, or add an .lrc file |
| Couldn't fetch lyrics | lrclib.net is unreachable or busy | Click Retry, or try again later |
LyricSync reads standard .lrc files with [mm:ss.xx] timestamps:
[00:12.34] First line
[00:15.80] Second line
[00:19.00]
[00:19.50] Line after a pause
A line can have several timestamps ([00:12.00][01:30.00]Chorus), and the [offset:+500] tag is supported. Empty lines are shown as ♪.
Lyrics are provided by lrclib.net, a free, community-run lyrics database.
Released under the MIT License. See LICENSE.

