how-i-build

LyricsLens

Un overlay de letras sincronizadas para Linux que se queda encima de cualquier ventana y lee de MPRIS lo que está sonando.

2026En líneaPúblicoAutor único
RustRust

Letras que siguen la canción, en una ventana que se queda encima de lo que haya en la pantalla — en un escritorio donde es el gestor de ventanas el que decide si eso está permitido.

Linux primero, por una razón simple: aquí la parte difícil es la ventana, no los datos. Saber qué está sonando es solo leer una propiedad. Poder quedarse encima de una aplicación en pantalla completa es lo que de verdad decide si la idea funciona.

El protocolo elige el toolkit

En Wayland, un cliente no puede simplemente elegir dónde poner su ventana, ni decirle que se coloque encima de otra. Eso es parte del protocolo, y es el compositor el que toma esa decisión. Así que, para un overlay que tiene que seguir visible sobre una ventana en pantalla completa, hay un camino concreto: wlr-layer-shell, un protocolo que permite tratar una superficie como una capa de la pantalla, en lugar de una ventana común.

Y entonces la elección del toolkit se vuelve mucho más concreta: ¿qué toolkits pueden usar este protocolo desde Rust hoy?

Dos de ellos quedaron fuera por razones que no eran de preferencia. Slint es Rust puro y tiene una API agradable, pero usa winit para dibujar, y winit no implementa layer-shell. Existe una solución de terceros, pero el propio crate dice que todavía no está listo para producción.

Qt con Kirigami tampoco encajaba. No hay una API oficial de Rust para ese camino: la opción soportada usa cxx-qt junto con CMake, mientras la interfaz se escribe en QML. Eso metería un segundo lenguaje y un segundo sistema de build en el proyecto.

Decisión

gtk4-rs, con gtk4-layer-shell desde el primer commit, en lugar de dejarlo como una opción para más adelante. Así el proyecto se queda en un solo lenguaje, sin node_modules, y con un binario del orden de unos pocos megabytes.

Compromisos

  • Aprender GTK4 es un costo real al principio, sobre todo en las primeras semanas.
  • La interfaz se construye en Rust y Pango en lugar de CSS, así que llegar a un buen acabado visual toma más tiempo.
  • Elegir wlr-layer-shell también limita los escritorios. Mutter, el que usa GNOME, no implementa layer-shell y no tiene intención de hacerlo. En GNOME, entonces, hay que buscar otro camino.
  • libadwaita haría mucho más fácil construir la ventana de configuración, pero su fondo choca con la transparencia que necesita el overlay. Así que termina teniendo sentido en una ventana, pero no en la otra.
  • Los crates tienen que mantenerse alineados en sus versiones. Cuando no coinciden, el error que aparece puede ser un error de tipos bastante confuso, en lugar de decir simplemente que las versiones no coinciden.

El reloj se ancla en el cambio de segundo

El reproductor informa la posición de la pista, y de ahí sale la línea correcta. El problema es que casi todos los reproductores la redondean al segundo entero, y algunos solo responden cuando se les pregunta. Consultar y creer en la respuesta da una letra que avanza a tirones, medio segundo adelantada o atrasada.

Decisión

La posición se lee con un temporizador corto, pero lo que cuenta no es el valor: es el instante en que cambia. Cuando la lectura salta de 41 a 42, ese momento es exactamente 42, y el reloj se ancla ahí y a partir de entonces corre con el tiempo de la propia máquina. Una lectura que salta demasiado es un seek, y el ancla se vuelve a hacer.

Compromisos

  • Firefox no informa ninguna posición para parte de lo que reproduce. No hay nada en qué anclarse, y el overlay lo dice en pantalla en lugar de fingir que sabe.
  • El error medido quedó por debajo de 8 ms, pero eso es contra un reproductor falso que escribí para la prueba. Contra uno real, lo único que tengo es mi ojo.

Las líneas son una columna que se desplaza

La primera versión cambiaba el texto de la línea actual y dibujaba la siguiente debajo. En el papel eso es una transición; en la pantalla es un parpadeo. Intenté arreglarlo cambiando la duración y la curva de aceleración unas tres veces, y no era eso: el problema era estructural. El widget que subía estaba anclado a la parte inferior de una caja que crecía exactamente la distancia que se movía, así que el movimiento se anulaba solo.

Decisión

Las líneas pasaron a ser una sola columna dentro de una ventana con scroll, y la animación desplaza esa ventana la altura de una línea. Ningún texto cambia de lugar: la misma línea que estaba abajo, más pequeña y apagada, es la que llega al centro, grande e iluminada.

Compromisos

  • La altura de la ventana se calcula a partir de las líneas visibles. Una línea que se parte en dos mide distinto, y la suma tiene que usar la altura que tiene en pantalla, no la que pediría.
  • Desplazar a mano significa manejar el caso en que el scroll todavía está corriendo cuando la canción ya siguió adelante.

El karaoke pinta rangos del mismo texto

Para iluminar las palabras ya cantadas, lo obvio es dibujar una segunda copia de la línea encima, recortada al ancho correcto. Lo hice y la copia siempre cubría la línea entera: una caja crece para caber lo que tiene dentro, y set_size_request es un mínimo, no un máximo.

Decisión

Una sola línea, con dos rangos de bytes pintados de forma distinta — lo que ya se cantó a plena intensidad, el resto apagado. LRCLIB da una marca de tiempo por línea, no por palabra, así que dónde cae cada palabra se estima a partir de su longitud.

Compromisos

  • Estimar por la longitud de la palabra falla en una línea con una pausa larga en el medio.
  • La estimación ilumina una palabra a la vez, no una letra. Un barrido suave se veía mejor en el papel y en la pantalla no se lee como karaoke.

Una ventana sin nada que dibujar no envía frame

Cerrar el reproductor dejaba la última línea en la pantalla. El programa había dejado de dibujar, lo que parecía correcto, y era exactamente la falla: una superficie que no envía un frame nuevo deja al compositor mostrando el último. El contenido se va, la imagen no.

Decisión

Un píxel casi invisible detrás de la franja, siempre dibujado. Con él siempre hay algo que enviar, y la pantalla de verdad se vacía. Otra regla entró por el mismo camino: un reproductor cerrado deja de responder antes de que su nombre salga del bus, así que seis lecturas sin respuesta cuentan como que se fue.

Compromisos

  • Es un truco, y cualquiera que lea el código sin el comentario va a querer borrar ese píxel.

Un tag empujado por un workflow no despierta a nadie

Quería que cada merge a main se convirtiera solo en un release. Armé un workflow que calcula la siguiente versión, la escribe en los archivos y empuja el tag, y otro que escucha los tags y publica. Funcionó cero veces: GitHub no inicia un workflow a partir de un tag empujado con su propio token, para evitar que los workflows se llamen entre sí en círculos.

Decisión

El que crea el tag llama al que hace el build, en lugar de esperarlo. Y el release ahora se crea junto con sus archivos en una sola llamada, porque antes nacía vacío y se quedaba así durante minutos sin el archivo comprimido que el instalador va a buscar.

Compromisos

  • Cada merge se vuelve una versión, así que el número de versión casi no significa nada. Dice cuántas veces hice merge, no cuánto cambió.

Los paquetes viven en una página, firmados

Publicar un .deb y un .rpm en un release resuelve la primera descarga y nada después de ella: quien instaló así no recibe actualizaciones junto con el resto de su sistema. Un repositorio de verdad lo resuelve, y un repositorio sin firmar es uno que apt rechaza.

Decisión

El propio GitHub Pages del proyecto sirve los dos repositorios, construidos en CI a partir de los archivos del release y firmados con una clave guardada como secreto. La misma página publica la clave pública y su huella digital, para quien quiera verificarla antes de confiar en ella.

Compromisos

  • La clave privada existe en un secreto de GitHub. Si se pierde la cuenta, hay que volver a firmar todo el repositorio con otra clave, y todos los que confiaron en la anterior tienen que cambiarla a mano.
  • Verifiqué que el índice de apt lista la versión correcta y que la firma se valida, pero nunca instalé el .deb en un contenedor limpio.

Hacer el build en el sistema más antiguo que todavía lo compila

El binario publicado se compilaba en la imagen de CI más nueva, y por eso pedía una glibc que casi ninguna máquina instalada tiene. El error que veía la gente no explicaba nada.

Decisión

El release se compila en Ubuntu 24.04, el sistema más antiguo cuyo GTK y libadwaita todavía pueden compilar esto. Eso fija el piso en glibc 2.39, que el README ahora indica junto con las distribuciones que lo cumplen. gtk4-layer-shell se compila al lado y se enlaza dentro del binario, porque Ubuntu recién empezó a empaquetarla en 25.10 — pedir esa biblioteca en tiempo de ejecución rompía justamente las máquinas para las que era este cambio.

Compromisos

  • Un AppImage era la otra salida y se descartó: empaqueta GTK pero no glibc, así que el piso sería el mismo con una descarga mucho más grande.
  • El piso sube solo el día en que use algo que solo existe en un GTK más nuevo.

La tecla se le pide al compositor

En Wayland, un programa común no reserva una combinación de teclas: las teclas son del compositor. El README le pedía a la gente que editara su propia configuración a mano. El programa sí intentaba pedirlo por su cuenta, y el intento estaba roto de una forma silenciosa: desde la 0.56, Hyprland rechaza el comando antiguo pero termina con éxito, así que el rechazo pasaba por éxito.

Decisión

La solicitud ahora va por el camino nuevo, que es el que Hyprland nombra en su propio mensaje de rechazo; el camino antiguo se sigue intentando después, para versiones anteriores. Lo que decide ahora es lo que el programa responde, no su código de salida. Y el atajo se elimina antes de crearse, porque si no, reiniciar el programa dejaba dos atajos en una misma tecla, anulándose entre sí.

Compromisos

  • El atajo vive mientras viva el compositor: no se escribe nada en la configuración de nadie, y el programa lo vuelve a pedir cada vez que arranca. Quien quiera que sobreviva a un reinicio del compositor todavía pega la línea a mano.
  • Eliminar antes de crear quita un atajo que la persona ya tenía en esa combinación, hasta que el compositor se reinicie.

Referencias