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, curl, and cp on PATH. The active media player must expose MPRIS metadata for automatic track and playback detection.

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.

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

Settings

Setting	Type	Default	Description
`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.
`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`	`24`	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.

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 read and control MPRIS playback, python3 for the LRCLIB helper and dynamic-lyric parser, curl for the public NetEase API, and cp to preserve temporary local cover files. Query scratch files and downloaded cover images are written inside the plugin runtime directory. Remote code is never downloaded or executed.