community-plugins/lyrics

Lyrics

Lyrics adds a synchronized status-bar lyric display with album artwork, karaoke highlighting, animated line changes, and configurable online or local sources.

Plugin

Field	Value
ID	h465855hgg/lyrics
Entries	Bar widget: lyrics; service: service

Requirements

Install playerctl, python3, and cp on PATH. The active media player must expose MPRIS metadata for automatic track and playback detection.

Noctalia installs the plugin files; it does not install system packages for you. To check or install the runtime packages automatically, run:

sh scripts/setup-deps.sh --check
sh scripts/setup-deps.sh

Use --yes for unattended installs. The script supports apt, dnf, pacman, zypper, apk, and xbps-install.

Usage

Enable h465855hgg/lyrics, then add the lyrics bar widget in Noctalia's bar settings. The background service detects the active MPRIS player, resolves lyrics, downloads or caches album artwork, and publishes playback state to the widget.

When several players are available, the service prefers a playing player, then a paused player, and keeps the current player when priorities are equal. The optional allowlist and blocklist match player names or instances and support * wildcards.

Left-click the widget to switch between lyrics and track information. Right-click to pause or resume the active player. Paused content is dimmed and all lyric, transition, and marquee animation stops until playback resumes.

When synchronized lyrics are unavailable, the widget displays track title + artist. Long lines pause at each end while scrolling. Intro and instrumental gaps can show a configurable cue such as •••••.

Screenshots

Status-bar widget:

Plugin settings:

Settings

Setting	Type	Default	Description
player_allowlist	string_list	empty	Only uses matching MPRIS player names or instances; supports * wildcards.
player_blocklist	string_list	empty	Ignores matching MPRIS player names or instances; takes priority over the allowlist.
lyrics_source	select	auto	Selects automatic fallback, LRCLIB, public NetEase, MPRIS text, custom HTTP, or external IPC.
custom_url	string	empty	HTTP URL template with {title}, {artist}, {album}, and {duration} placeholders.
custom_json_field	string	syncedLyrics	Dotted field path containing an LRC string or timed-lines array in a JSON response.
cue_text	string	•••••	Characters highlighted through long intro or instrumental gaps.
cue_font_mode	select	follow	Follows Noctalia's interface font or uses a custom installed font for intro/interlude characters.
cue_font_family	string	sans-serif	Installed font family used for intro/interlude characters in custom-font mode.
scroll_mode	select	auto	Enables automatic marquee, forced marquee, or static truncation.
marquee_speed	int	30	Approximate long-line scroll speed in logical pixels per second.
max_lines	int	1	Number of lines shown on a vertical bar, from 1 to 3.
gradient	bool	true	Enables progressive per-character highlighting.
animation	select	karaoke	Chooses karaoke, cascade, wave, fade-only, or no line transition.
max_chars	int	15	Number of visible Unicode characters before marquee scrolling starts.
char_width	int	9	Estimated logical-pixel character width used for scroll timing and minimum layout width.
glyph	glyph	music	Fallback icon shown when album artwork is unavailable.
show_artist	bool	true	Includes the artist in track-information mode.
hide_when_paused	bool	false	Hides the widget instead of dimming it while paused.
show_cover	bool	true	Shows circular album artwork beside the lyrics.
active_color	color	on_surface	Colors the current and already-sung lyric characters.
inactive_color	color	on_surface_variant	Colors upcoming lyrics, paused playback, and secondary lines.

IPC

External players can set lyrics_source to external and address the singleton service with:

noctalia msg plugin h465855hgg/lyrics:service all <event> '<payload>'

Supported events:

• push-lrc: accepts synchronized or plain LRC text.
• push-json: accepts JSON with a lines timed array or a lyrics LRC string.
• push-state: also accepts track, position, playing, and cover fields.
• clear: clears the currently published lyrics.

Line timestamps and character timestamps are milliseconds. MPRIS track duration and playback position are microseconds:

{"lines":[{"time":1200,"duration":1800,"text":"Hello","chars":[1200,1500,1800,2100,2400]}]}

Notes

Automatic mode requests LRCLIB first, then the public NetEase Music API. Custom HTTP mode contacts only the configured endpoint. The plugin never reads browser cookies or player credentials.

The service runs playerctl to select, read, and control MPRIS playback, python3 for the LRCLIB helper and dynamic-lyric parser, and cp to preserve temporary local cover files. Public NetEase requests use Noctalia's HTTP API. Query scratch files and downloaded cover images are written inside the plugin runtime directory. Remote code is never downloaded or executed.