Skip to content
Mischou01Public

About

Synced lyrics viewer for MPRIS2 music players, built with GTK 4 and libadwaita

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

LyricSync

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.

LyricSync in dark mode   LyricSync in light mode

Features

  • 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 .lrc files: 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.

Requirements

  • 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.

Installation

git clone https://github.com/Mischou01/lyricsync.git
cd lyricsync
./install.sh

The installer:

  1. 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.
  2. Copies the app to ~/.local/bin/lyricsync.
  3. 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.

Usage

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.

Manual search

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.

Keyboard shortcuts

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

Settings

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.

Local .lrc files

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.

Files

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

Uninstalling

./install.sh --uninstall

This keeps your settings and cached lyrics. To delete those too:

rm -rf ~/.config/lyricsync ~/.local/share/lyricsync

Known issues

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

LRC format

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 ♪.

Credits and license

Lyrics are provided by lrclib.net, a free, community-run lyrics database.

Released under the MIT License. See LICENSE.

About

Synced lyrics viewer for MPRIS2 music players, built with GTK 4 and libadwaita

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages