Prismriver Lyrics

A CLI and terminal UI for searching song lyrics across multiple sources via a plugin system.

About

Prismriver Lyrics is a uv workspace with two packages built on a shared lyrics search engine (prismriver_lyrics):

• prismriver-lyrics — a CLI that takes an artist/title, queries the registered plugins, and prints results.
• prismriver-lyrics-tui — a Textual terminal UI that reads the active MPRIS player's state over D-Bus, searches for lyrics on each track change, and renders the result, highlighting the current line for time-synced (LRC) lyrics.

Features:

• 30+ lyrics source plugins (prismriver_lyrics.plugins, auto-discovered LyricsPlugin subclasses)
• On-disk SQLite cache of results, with a configurable TTL (--cache-ttl) and a bypass flag (--no-cache)
• Filtering by plugin id, language, translated/original, or synced/plain-text, and a result cap (--limit/-l)
• Results ranked best-first by estimated quality (how complete and clean the text looks and whether it's time-synced) or alphabetically by source (--sort)
• Time-synced (LRC) lyrics, with the current line highlighted in the TUI as the track plays
• TUI manual search dialog (for when no MPRIS player is active or the auto-detected metadata is wrong), theme switching, and vim-style keybindings

Built With

• Python 3
• Textual
• httpx
• Beautiful Soup
• dbus-next

Getting Started

Prerequisites

Prismriver Lyrics requires Python 3.12+.

Installation

Both packages are published on PyPI. Install either or both with pipx, pip, or uv:

$ pipx install prismriver-lyrics
$ pipx install prismriver-lyrics-tui

$ pip install prismriver-lyrics
$ pip install prismriver-lyrics-tui

$ uv tool install prismriver-lyrics
$ uv tool install prismriver-lyrics-tui

Alternatively, install from source using uv and pipx:

git clone https://github.com/anlar/prismriver-lyrics.git
cd prismriver-lyrics
make install-pipx

This builds both packages and installs each as its own isolated pipx app, exposing both the prismriver-lyrics and prismriver-lyrics-tui commands.

Usage

Search for lyrics from the CLI:

$ prismriver-lyrics --artist "The Clash" --title "Police and Thieves"

Or launch the terminal UI, which follows whatever's playing on an MPRIS-compatible media player:

$ prismriver-lyrics-tui

Check other command line options using the help command:

$ prismriver-lyrics --help
$ prismriver-lyrics-tui --help

View the available hotkeys for the Prismriver Lyrics TUI in the status bar.

Roadmap

See the open issues for a full list of proposed features (and known issues).

Contributing

Feel free to open bug reports and send pull requests.

License

Distributed under the MIT license. See LICENSE.txt for more information.