spotify-lyrics by goatnath · Pull Request #214 · noctalia-dev/community-plugins

goatnath · 2026-08-02T04:09:38Z

Plugin

Id: <goatnath/spotify-lyrics>
New plugin
Update to an existing plugin (version bumped in plugin.toml)

What it does

Adds a seamless, time-synced scrolling lyrics panel for the Noctalia desktop shell. It integrates directly into the Noctalia bar via a small glyph next to the media widget, which toggle an auto-scrolling lyrics card pulled from a background daemon.

External dependencies

Requires playerctl and the syncedlyrics Python package. It uses a standalone background Python daemon (spotify_lyrics_daemon.py) to monitor media state and fetch lyrics without needing Spotify API keys. The plugin reads state locally from ~/.cache/noctalia/lyrics/current.json.

Testing

Tested on Niri
Tested on Hyprland
Tested on Sway
Tested on another compositor:
Noctalia version tested against: Latest
Plugin API level: 3

Screenshots / Videos

recording_20260805_213318.mp4

Checklist

The directory name matches the part of id after the / in plugin.toml exactly.
It ships plugin.toml, README.md, thumbnail.webp, and translations/en.json.
README.md follows the
README template, documents
every entry id and dependency, and includes exact panel IPC commands and launcher prefixes where applicable.
I created thumbnail.webp with the thumbnail generator.
version follows semver and is bumped in this PR; plugin_api is the oldest API level this plugin requires.
Every non-English translation in this PR uses a locale supported by Noctalia core, and I can read, write, and
understand that language well enough to review and maintain it (no unreviewed machine/LLM translations).
I did not edit catalog.toml; CI generates it.
This PR touches exactly one plugin directory.

Code review attestation

Plugins run as trusted, unsandboxed Luau in the user's session. Confirm:

The code is readable and not obfuscated, minified, or generated.
It does not download and execute remote code.
Every network call, filesystem write, and spawned process is something the description above accounts for.
I have the right to publish this code under the license declared in plugin.toml.

goatnath · 2026-08-02T04:12:01Z

I have made the required changes suggested in the previous PR and I request you to check this and feel free to point out anything you think needs to be changed

ItsLemmy · 2026-08-02T15:45:16Z

blocking - spotify-lyrics/plugin.toml:7

The manifest declares no dependencies, but spotify-lyrics/spotify_lyrics_daemon.py:6 requires the syncedlyrics Python package and spotify-lyrics/spotify_lyrics_daemon.py:101executes playerctl. The Python runtime is also required to run the daemon. spotify-lyrics/README.md:20 documents only part of this requirement outside the template's required
"## Requirements" section.

This hides mandatory runtime prerequisites from the catalog and plugin metadata. Declare all runtime requirements in dependencies and document the matching exact names under
"## Requirements".

…update README requirements

ItsLemmy · 2026-08-03T12:34:38Z

blocking - lyrics/lyrics.luau:85

Commit ef91e6f modifies the existing h465855hgg/lyrics plugin, although this PR declares itself as a new goatnath/spotify-lyrics plugin and attests that it touches exactly one plugin directory.

Remove the lyrics/lyrics.luau change from this PR. Any update to the existing lyrics plugin should be reviewed separately with its own manifest version bump and functional scope.

This reverts commit ef91e6f.

…g lines

… wrapped text

…rapping height prediction

…ng exclusively

…dimension animations

…font scaling

…base Root cause: the charUnits per-character width estimation consistently underestimated real rendered widths because the 0.80 multipliers in getLineWidth and getLinesCount cancelled each other out, making the effective calculation ignore the safety margin entirely. Fix: replaced the complex charUnits/toChars/getLineWidth machinery with a simple #text / chars-per-line heuristic using a conservative 0.60x character width factor. This reliably overestimates line count, ensuring the panel always allocates enough height for wrapped text. Quality of life improvements: - Split monolithic render() into renderEmpty/renderPaused/renderPlaying - Reduced update interval from 33ms (30 FPS) to 100ms (10 FPS) - Removed file-read timer (reads every frame at lower FPS instead) - Added clear section headers and inline documentation - Removed all dead code (charUnits, toChars, getLineWidth, etc.)

… fix The root cause of the lyrics spilling was never in the Lua code. Noctalia panels are sized exclusively by plugin.toml, not by minHeight on the column layout. Since we had removed width/height from plugin.toml to make sizing 'dynamic', noctalia used a tiny default that couldn't contain wrapped lyrics. minHeight on ui.column had zero effect on the actual panel window size. Set height=280 to comfortably fit 3 lyrics lines even when they wrap.

Long lyrics (>40 chars) now get progressively smaller fonts: - Every 15 chars beyond 40 reduces font by 2px - Minimum font: 10px (panel) / 11px (widget) This prevents vertical overflow regardless of container size by ensuring long lines take up less vertical space when they wrap.

- Updated bar.luau to toggle correct panel ID - Replaced ~ in noctalia.readFile with absolute path since Lua doesn't auto-expand it - Updated plugin.toml height to 280 and id to noctalia/spotify-lyrics

ItsLemmy · 2026-08-05T21:45:59Z

blocking - spotify-lyrics/plugin.toml:7

dependencies = [] is still empty. The plugin requires playerctl, python3,
and the syncedlyrics Python package to function (spotify_lyrics_daemon.py:6,
spotify_lyrics_daemon.py:101). The README "Requirements" section documents
these, but the manifest omits them from the machine-readable dependencies
field. This was flagged in the previous review and has not been addressed.

Declare all runtime dependencies in the dependencies array so the catalog
and plugin manager can surface them to users.
blocking - spotify-lyrics/plugin.toml:1

The manifest id is "noctalia/spotify-lyrics", using the "noctalia" author
namespace. The PR submitter is goatnath, and the PR template declares the
id as "<goatnath/spotify-lyrics>". The "noctalia" prefix implies official
provenance and is misleading. Change the id to "goatnath/spotify-lyrics".
blocking - spotify-lyrics/bar.luau:10

The file path is hardcoded to "/home/goatnath/.cache/noctalia/lyrics/current.json".
This will not work for any other user. Use a relative or home-directory-resolved
path (e.g. via noctalia.env or os.getenv("HOME")).
non-blocking - spotify-lyrics/widget.luau

This file implements a desktop widget (desktopWidget.render()) but the
manifest contains no [[desktop_widget]] entry. The file ships with the
plugin but will never be loaded by Noctalia. Either add a
[[desktop_widget]] section to plugin.toml or remove the file.
blocking - spotify-lyrics/README.md:11

The README "Plugin" section lists the id as "noctalia/spotify-lyrics",
which must be updated to match whatever the corrected manifest id becomes.
non-blocking - spotify-lyrics/README.md

The README does not follow the repository README template structure. It has
non-standard sections ("Why it's great", "Usage") instead of the template's
required sections. The "## Requirements" heading is present, which is the
minimum conditional section needed, but the overall structure diverges from
the template.

ItsLemmy · 2026-08-05T21:47:29Z

This PR is going backward now xD more stuff to fix than last time.

goatnath · 2026-08-06T01:33:14Z

Oh shucks I added the files from my personal repository into this

- Change plugin id from noctalia/ to goatnath/ namespace - Declare runtime dependencies: playerctl, python3, syncedlyrics - Replace hardcoded /home/goatnath path with noctalia.expandPath() - Add [[desktop_widget]] manifest entry for widget.luau - Rewrite README to follow README_TEMPLATE.md structure - Update all references to use corrected plugin id

goatnath · 2026-08-06T15:25:16Z

Finally 😭

goatnath and others added 9 commits July 12, 2026 18:45

Add spotify-lyrics plugin

f4e3220

Merge branch 'noctalia-dev:main' into main

d35264f

fix(spotify-lyrics): resolve race conditions and add plugin_api

5278a33

fix(spotify-lyrics): update plugin_api to 3

afd281e

fix(spotify-lyrics): resolve github actions validation errors

afc2aff

fix(spotify-lyrics): resize thumbnail to 960x540 to fix validation error

ca6b823

fix(spotify-lyrics): bump version to 1.2.1

552775a

Merge branch 'noctalia-dev:main' into main

202cb25

fix(spotify-lyrics): update namespace and replace misleading thumbnail

85b6c42

ItsLemmy marked this pull request as draft August 2, 2026 15:45

fix(spotify-lyrics): declare runtime dependencies in plugin.toml and …

2b754fa

…update README requirements

goatnath marked this pull request as ready for review August 3, 2026 04:58

feat(lyrics): implement dynamic panel width sizing

ef91e6f

ItsLemmy marked this pull request as draft August 3, 2026 12:34

goatnath added 13 commits August 3, 2026 22:19

Revert "feat(lyrics): implement dynamic panel width sizing"

8aa4ec5

This reverts commit ef91e6f.

feat(spotify-lyrics): implement dynamic panel width sizing

9299951

fix(spotify-lyrics): correct target width pre-calculation for upcomin…

41fbe58

…g lines

fix(spotify-lyrics): prevent vertical spill by enforcing maxLines=1

d653000

fix(spotify-lyrics): implement dynamic height resizing to encapsulate…

8031fcb

… wrapped text

fix(spotify-lyrics): remove horizontal cap to prevent vertical spill

d5a26bb

fix(spotify-lyrics): restore minHeight and implement perfectly safe w…

761fa99

…rapping height prediction

fix(spotify-lyrics): lock panel width and use vertical dynamic resizi…

4fbbf53

…ng exclusively

fix(spotify-lyrics): implement dynamic font scaling and remove panel …

9745026

…dimension animations

fix(spotify-lyrics): restore robust dynamic height logic and discard …

06178ee

…font scaling

goatnath added 3 commits August 5, 2026 11:23

fix(spotify-lyrics): fix plugin IDs and tilde path expansion

ec20ac2

- Updated bar.luau to toggle correct panel ID - Replaced ~ in noctalia.readFile with absolute path since Lua doesn't auto-expand it - Updated plugin.toml height to 280 and id to noctalia/spotify-lyrics

Fix UI bugs, implement reactive updates, and add album art

aa950a7

Fix plugin manifest validation errors

cb6c84c

goatnath marked this pull request as ready for review August 5, 2026 16:06

ItsLemmy marked this pull request as draft August 5, 2026 21:48

goatnath marked this pull request as ready for review August 6, 2026 01:38

ItsLemmy merged commit e439ccd into noctalia-dev:main Aug 6, 2026
1 check passed

Navigation Menu

Uh oh!

spotify-lyrics - #214

spotify-lyrics#214
ItsLemmy merged 28 commits into
noctalia-dev:mainfrom
goatnath:main

goatnath commented Aug 2, 2026 •

edited

Loading

Uh oh!

goatnath commented Aug 2, 2026

Uh oh!

ItsLemmy commented Aug 2, 2026

Uh oh!

ItsLemmy commented Aug 3, 2026

Uh oh!

ItsLemmy commented Aug 5, 2026

Uh oh!

ItsLemmy commented Aug 5, 2026

Uh oh!

goatnath commented Aug 6, 2026

Uh oh!

Uh oh!

goatnath commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

goatnath commented Aug 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Plugin

What it does

External dependencies

Testing

Screenshots / Videos

Checklist

Code review attestation

Uh oh!

goatnath commented Aug 2, 2026

Uh oh!

ItsLemmy commented Aug 2, 2026

Uh oh!

ItsLemmy commented Aug 3, 2026

Uh oh!

ItsLemmy commented Aug 5, 2026

Uh oh!

ItsLemmy commented Aug 5, 2026

Uh oh!

goatnath commented Aug 6, 2026

Uh oh!

Uh oh!

goatnath commented Aug 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

goatnath commented Aug 2, 2026 •

edited

Loading