how-i-build

LyricsLens

A synced lyrics overlay for Linux that stays on top of any window, reading what is playing from MPRIS.

2026LivePublicSole author
RustRust

Lyrics that follow the song, in a window that stays on top of whatever is on the screen — on a desktop where the window manager is the one that decides whether that is allowed.

Linux first, for a simple reason: here the hard part is the window, not the data. Finding out what is playing is just reading a property. Being able to stay on top of a fullscreen application is what really decides whether the idea works.

The protocol picks the toolkit

On Wayland, a client cannot simply choose where to put its window, or tell it to sit above another one. That is part of the protocol, and the compositor is the one making that call. So for an overlay that needs to stay visible over a fullscreen window, there is one specific path: wlr-layer-shell, a protocol that lets a surface be treated as a layer of the screen, instead of an ordinary window.

And then the toolkit choice gets a lot more specific: which toolkits can actually use this protocol from Rust today?

Two of them ended up out for reasons that were not a matter of preference. Slint is pure Rust and has a pleasant API, but it uses winit to draw, and winit does not implement layer-shell. There is a third-party solution, but the crate itself says it is not ready for production yet.

Qt with Kirigami did not fit either. There is no official Rust API for that path: the supported option uses cxx-qt together with CMake, while the interface is written in QML. That would put a second language and a second build system into the project.

Decision

gtk4-rs, with gtk4-layer-shell from the first commit, instead of leaving it as an option for later. That way the project stays in a single language, without node_modules, and with a binary that sits in the range of a few megabytes.

Trade-offs

  • Learning GTK4 is a real cost at the start, especially in the first few weeks.
  • The interface is built in Rust and Pango instead of CSS, so getting to a good visual finish takes longer.
  • Choosing wlr-layer-shell also limits the desktops. Mutter, used by GNOME, does not implement layer-shell and does not intend to. On GNOME, then, another path has to be worked out.
  • libadwaita would make the settings window a lot easier to build, but its background conflicts with the transparency the overlay needs. So it ends up making sense in one window, but not in the other.
  • The crates need to stay aligned on versions. When there is a mismatch, the error that shows up can be a fairly confusing type error, instead of simply saying the versions do not match.

The clock anchors on the turn of the second

The player reports the track position, and that is where the right line comes from. The trouble is that nearly every player rounds it to the whole second, and some only answer when asked. Polling and believing the answer gives lyrics that lurch along, half a second ahead or behind.

Decision

The position is read on a short timer, but what counts is not the value: it is the instant it changes. When the reading jumps from 41 to 42, that moment is exactly 42, and the clock anchors there and runs on the machine's own time from then on. A reading that jumps too far is a seek, and the anchor is made again.

Trade-offs

  • Firefox reports no position at all for some of what it plays. There is nothing to anchor to, and the overlay says so on screen instead of pretending to know.
  • The measured error came out under 8 ms, but that is against a fake player I wrote for the test. Against a real one all I have is my eye.

The lines are one column that scrolls

The first version swapped the text of the current line and drew the next one below. On paper that is a transition; on screen it is a blink. I tried fixing it by changing the duration and the easing about three times, and that was not it: the problem was structural. The widget moving up was anchored to the bottom of a box that grew by exactly the distance it moved, so the movement cancelled itself out.

Decision

The lines became a single column inside a scrolling window, and the animation scrolls that window by one line's height. No text swaps places: the same line that was below, smaller and faded, is the one that arrives at the centre, large and lit.

Trade-offs

  • The window's height is worked out from the visible lines. A line that wraps measures differently, and the sum has to use the height it has on screen, not the one it would ask for.
  • Scrolling by hand means handling the case where the scroll is still running when the song has already moved on.

The karaoke paints ranges of the same text

To light up the words already sung, the obvious way is to draw a second copy of the line on top, cut to the right width. I did that and the copy always covered the whole line: a box grows to fit what is inside it, and set_size_request is a minimum, not a maximum.

Decision

One line, with two ranges of bytes painted differently — what has been sung at full strength, the rest faded. LRCLIB gives one timestamp per line, not per word, so where each word falls is estimated from how long it is.

Trade-offs

  • Estimating from word length gets it wrong on a line with a long pause in the middle.
  • The estimate lights a word at a time, not a letter. A smooth wipe looked better on paper and on screen it does not read as karaoke.

A window with nothing to draw sends no frame

Closing the player left the last line on the screen. The program had stopped drawing, which seemed right, and was exactly the fault: a surface that sends no new frame leaves the compositor showing the last one. The content goes, the image does not.

Decision

One almost invisible pixel behind the strip, always drawn. With it there is always something to send, and the screen really does empty. Another rule came in along the same path: a closed player stops answering before its name leaves the bus, so six unanswered reads count as gone.

Trade-offs

  • It is a trick, and anyone reading the code without the comment will want to delete that pixel.

A tag pushed by a workflow wakes nobody

I wanted every merge to main to become a release on its own. I built one workflow that works out the next version, writes it into the files and pushes the tag, and another that listens for tags and publishes. It worked zero times: GitHub does not start a workflow from a tag pushed with its own token, to keep workflows from calling each other in circles.

Decision

The one that creates the tag calls the one that builds, instead of waiting for it. And the release is now created together with its files in a single call, because before it was born empty and sat there for minutes without the archive the installer goes looking for.

Trade-offs

  • Every merge becomes a version, so the version number means almost nothing. It says how many times I merged, not how much changed.

The packages live on a page, signed

Publishing a .deb and an .rpm on a release solves the first download and nothing after it: whoever installed that way gets no update along with the rest of their system. A real repository solves it, and an unsigned repository is one apt refuses.

Decision

The project's own GitHub Pages serves both repositories, built in CI from the release files and signed with a key kept as a secret. The same page publishes the public key and its fingerprint, for anyone who wants to check before trusting it.

Trade-offs

  • The private key exists in a GitHub secret. If the account goes, the whole repository has to be signed again with another key, and everyone who trusted the old one has to change it by hand.
  • I checked that the apt index lists the right version and that the signature verifies, but I never installed the .deb in a clean container.

Build on the oldest system that still builds it

The published binary was built on the newest CI image, and so asked for a glibc almost no installed machine has. The error people saw explained nothing.

Decision

The release is built on Ubuntu 24.04, the oldest system whose GTK and libadwaita can still build this. That fixes the floor at glibc 2.39, which the README now states along with the distributions that meet it. gtk4-layer-shell is built alongside and linked into the binary, because Ubuntu only started packaging it in 25.10 — asking for that library at runtime broke exactly the machines this change was for.

Trade-offs

  • An AppImage was the other way out and was dropped: it bundles GTK but not glibc, so the floor would be the same for a much bigger download.
  • The floor rises on its own the day I use something that only exists in a newer GTK.

The key is asked of the compositor

On Wayland an ordinary program does not reserve a key combination: the compositor owns the keys. The README asked people to edit their own configuration by hand. The program did try to ask on its own, and the attempt was broken in a quiet way: since 0.56 Hyprland refuses the old command but exits successfully, so the refusal passed for success.

Decision

The request now goes through the new path, which is the one Hyprland names in its own refusal message; the old path is still tried after it, for older versions. What decides now is what the program answers, not its exit code. And the binding is dropped before it is made, or restarting the program left two bindings on one key, cancelling each other out.

Trade-offs

  • The binding lives as long as the compositor does: nothing is written into anyone's configuration, and the program asks again every time it starts. Anyone who wants it to survive a compositor restart still pastes the line by hand.
  • Dropping before making removes a binding the person already had on that combination, until the compositor restarts.

References