how-i-build

LyricsLens

Overlay de letras sincronizadas para Linux, que fica por cima de qualquer janela lendo do MPRIS o que está tocando.

2026No arPúblicoAutor único
RustRust

Letra acompanhando a música, numa janela que fica por cima do que estiver na tela — num desktop onde o gerenciador de janelas é quem decide se isso pode ou não.

Linux primeiro, por um motivo simples: aqui a parte difícil é a janela, não os dados. Descobrir o que está tocando é só ler uma propriedade. Conseguir ficar por cima de uma aplicação em tela cheia é o que realmente decide se a ideia funciona.

O protocolo escolhe o toolkit

No Wayland, um cliente não pode simplesmente escolher onde colocar sua janela ou mandar ela ficar acima de outra. Isso faz parte do protocolo, e quem toma essa decisão é o compositor. Para um overlay que precisa continuar visível sobre uma janela em tela cheia, existe então um caminho específico: wlr-layer-shell, um protocolo que permite que uma superfície seja tratada como uma camada da tela, em vez de uma janela comum.

E aí a escolha do toolkit fica bem mais específica: quais toolkits conseguem usar esse protocolo a partir de Rust hoje?

Dois acabaram ficando de fora por motivos que não eram questão de preferência. O Slint é Rust puro e tem uma API bem agradável, mas usa o winit para desenhar, e o winit não implementa layer-shell. Existe uma solução de terceiro, mas o próprio crate diz que ainda não está pronto para produção.

Qt com Kirigami também não encaixou. Não existe uma API Rust oficial para esse caminho: a opção suportada usa cxx-qt junto com CMake, enquanto a interface é feita em QML. Isso colocaria uma segunda linguagem e um segundo sistema de build no projeto.

Decisão

gtk4-rs, com gtk4-layer-shell desde o primeiro commit, em vez de deixar isso como uma opção para depois. Assim o projeto continua com uma linguagem só, sem node_modules, e com um binário que fica na casa de poucos megabytes.

Trade-offs

  • Aprender GTK4 é um custo real no começo, principalmente nas primeiras semanas.
  • A interface é feita em Rust e Pango em vez de CSS, então chegar num acabamento visual bom demora mais.
  • Escolher wlr-layer-shell também limita os desktops. O Mutter, usado pelo GNOME, não implementa layer-shell e não pretende implementar. No GNOME, portanto, é preciso pensar em outro caminho.
  • A libadwaita deixaria a janela de preferências bem mais fácil de fazer, mas o fundo dela entra em conflito com a transparência que o overlay precisa. Por isso ela acaba fazendo sentido em uma janela, mas não na outra.
  • Os crates precisam estar alinhados nas versões. Quando há um descasamento, o erro que aparece pode ser um erro de tipo bem confuso em vez de simplesmente dizer que as versões não combinam.

O relógio se ancora na virada do segundo

O player informa a posição da faixa, e é daí que sai a linha certa. O problema é que quase todo player informa isso arredondado para o segundo inteiro, e alguns só respondem quando perguntados. Perguntar de vez em quando e acreditar na resposta dá uma letra que anda aos trancos, meio segundo à frente ou atrás.

Decisão

A posição é lida num timer curto, mas o que vale não é o valor: é o instante em que ele muda. Quando a leitura pula de 41 para 42, aquele momento é 42 exato, e o relógio se ancora ali e segue sozinho a partir do próprio tempo da máquina. Uma leitura que pula demais é um seek, e aí a âncora se refaz.

Trade-offs

  • O Firefox não informa posição nenhuma em parte do que toca. Não há o que ancorar, e o overlay diz isso na tela em vez de fingir que sabe.
  • O erro medido ficou abaixo de 8 ms, mas isso é contra um player falso que eu escrevi para o teste. Contra um player de verdade eu só tenho o olho.

As linhas são uma coluna que rola

A primeira versão trocava o texto da linha atual e desenhava a próxima embaixo. No papel é uma transição; na tela é um piscar. Tentei corrigir mudando duração e easing umas três vezes, e não era isso: o problema era estrutural. O widget que subia estava ancorado no rodapé de uma caixa que crescia exatamente a distância que ele subia, então o movimento se cancelava sozinho.

Decisão

As linhas viraram uma coluna única dentro de uma janela de rolagem, e a animação rola essa janela por uma altura de linha. Nenhum texto troca de lugar: a mesma linha que estava embaixo, menor e apagada, é a que chega ao centro grande e acesa.

Trade-offs

  • A altura da janela é calculada a partir das linhas visíveis. Uma linha que quebra em duas mede diferente, e a conta tem que usar a altura que ela tem na tela, não a que ela pediria.
  • Rolar à mão significa cuidar do caso em que a rolagem ainda está correndo quando a música já mudou de linha.

O karaokê pinta faixas do mesmo texto

Para acender as palavras já cantadas, o caminho óbvio é desenhar uma segunda cópia da linha por cima, cortada na largura certa. Fiz isso e a cópia sempre cobria a linha inteira: uma caixa cresce até caber o que está dentro dela, e set_size_request é um mínimo, não um máximo.

Decisão

Uma linha só, com duas faixas de bytes pintadas de maneiras diferentes — o que já foi cantado em cheio, o resto apagado. O LRCLIB dá um tempo por linha, não por palavra, então onde cada palavra cai é estimado pelo tamanho dela.

Trade-offs

  • Estimar pelo tamanho da palavra erra em linha com pausa longa no meio.
  • A estimativa acende por palavra, não por letra. Varrer suave parecia melhor no papel e na tela não parece karaokê.

Uma janela sem nada para desenhar não manda quadro

Fechar o player deixava a última linha na tela. O programa tinha parado de desenhar, o que parecia certo, e era justamente o defeito: uma superfície que não manda quadro novo faz o compositor continuar mostrando o último. Some o conteúdo, não some a imagem.

Decisão

Um pixel quase invisível atrás da tarja, sempre desenhado. Com ele há sempre algo a mandar, e a tela esvazia de verdade. No mesmo caminho entrou outra regra: um player fechado para de responder antes de o nome sair do barramento, então seis leituras sem resposta contam como ido embora.

Trade-offs

  • É um truque, e alguém que leia o código sem o comentário vai querer apagar esse pixel.

A tag empurrada por um workflow não acorda ninguém

Eu queria que todo merge na main virasse release sozinho. Montei um workflow que calcula a próxima versão, escreve nos arquivos e empurra a tag, e outro que escuta tags e publica. Funcionou zero vezes: o GitHub não dispara workflow a partir de tag empurrada com o token dele mesmo, para os workflows não ficarem se chamando em círculo.

Decisão

O que cria a tag chama o que constrói, em vez de esperar. E a release passou a ser criada junto com os arquivos numa chamada só, porque antes ela nascia vazia e ficava alguns minutos no ar sem o que o instalador vai buscar.

Trade-offs

  • Cada merge vira uma versão, então o número da versão não quer dizer quase nada. Ele diz quantas vezes eu mergeei, não o quanto mudou.

Os pacotes moram numa página, assinados

Publicar .deb e .rpm num release resolve o primeiro download e nada depois dele: quem instalou assim não recebe atualização junto com o resto do sistema. Um repositório de verdade resolve, e repositório sem assinatura o apt recusa.

Decisão

O GitHub Pages do próprio projeto serve os dois repositórios, montados no CI a partir dos arquivos do release e assinados com uma chave guardada como secret. A mesma página publica a chave pública e a impressão digital dela, para quem quiser conferir antes de confiar.

Trade-offs

  • A chave privada existe num secret do GitHub. Se a conta cair, o repositório inteiro precisa ser reassinado com outra chave, e quem já confiou na antiga precisa trocar à mão.
  • Conferi que o índice do apt lista a versão certa e que a assinatura fecha, mas nunca instalei o .deb num container limpo.

Compilar no sistema mais antigo que ainda compila

O binário publicado era compilado na imagem mais nova do CI, e por isso pedia uma glibc que quase nenhuma máquina instalada tem. O erro que a pessoa via não explicava nada.

Decisão

A release é compilada no Ubuntu 24.04, o sistema mais antigo cujo GTK e libadwaita ainda conseguem compilar isto. Isso fixa o piso em glibc 2.39, que o README agora diz junto com as distribuições que atendem. O gtk4-layer-shell é compilado junto e linkado para dentro do binário, porque o Ubuntu só passou a empacotá-lo na 25.10 — pedir essa biblioteca em tempo de execução quebrava justamente as máquinas que essa mudança queria atender.

Trade-offs

  • O AppImage era a outra saída e foi descartado: ele embute o GTK, mas não a glibc, então o piso seria o mesmo com um download muito maior.
  • O piso sobe sozinho no dia em que eu usar algo que só existe em GTK mais novo.

A tecla se pede ao compositor

No Wayland um programa comum não reserva atalho: quem manda nas teclas é o compositor. O README pedia para a pessoa editar a configuração dela à mão. O programa até tentava pedir sozinho, e a tentativa estava quebrada de um jeito silencioso: desde a versão 0.56 o Hyprland recusa o comando antigo, mas sai com código de sucesso, então a recusa passava por acerto.

Decisão

O pedido passou a ser feito pelo caminho novo, que é o próprio Hyprland que indica na mensagem de recusa; o caminho antigo continua sendo tentado depois, para versões mais velhas. Quem decide agora é o que o programa responde, não o código de saída. E o atalho é desfeito antes de ser feito, senão reiniciar o programa deixava dois atalhos na mesma tecla, que se anulavam.

Trade-offs

  • O atalho vive enquanto o compositor viver: nada é escrito na configuração de ninguém, e a cada início o programa pede de novo. Quem quiser que sobreviva a um reinício do compositor continua colando a linha à mão.
  • Desfazer antes de fazer apaga um atalho que a pessoa já tivesse naquela combinação, até o compositor reiniciar.

Referências