Ouvidos para o Claude Code

O que é e porque importa

Se fazes os vídeos de lançamento com código, por exemplo com o Remotion, ou os montas com o Claude Code, há um buraco: o Claude escreve o vídeo, mas não o ouve. Põe uma batida onde acha que cai o corte, e não sabe se chega 80 milésimos atrasada. E um som fora de tempo ouve-o qualquer pessoa.

O earshot dá-lhe ouvidos. É um projeto open source gratuito no GitHub (licença MIT) que transforma o som em coisas que o Claude consegue ler: um som descrito por palavras, o que se ouve no vídeo segundo a segundo, por quantos milésimos cada batida falha o corte, o que corrigir primeiro. E os sons que faltam constrói-os em código.

É para quem faz sozinho os vídeos do próprio produto, sem técnico de som. Mas é muito novo: saiu a 15 de outubro de 2026, está marcado como alfa e é escrito por uma só pessoa, com o Claude como coautor. Experimenta-o primeiro num vídeo de teste, não no vídeo de lançamento.

1. O que precisas

Tudo corre no teu computador. Antes de o instalares, confirma que tens:

• Python 3.10 ou mais recente.
• ffmpeg e ffprobe, dois programas gratuitos que leem áudio e vídeo.
• Cerca de 1,1 GB livres para os dois modelos abertos que descarrega no primeiro uso.
• Nenhuma placa gráfica e nenhuma chave. Há uma análise extra com o Gemini, mas só corre com a tua própria chave e o teu consentimento explícito para enviar o ficheiro.

2. Pede ao Claude Code para o instalar

A instalação são cinco comandos, mas não precisas de os escrever tu. Abre o Claude Code na pasta onde guardas as tuas ferramentas e cola isto:

Instala o earshot a partir de https://github.com/Leonxlnx/earshot seguindo a secção Install do README. Primeiro confirma Python 3.10 ou mais recente, ffmpeg e ffprobe: se faltar alguma coisa, para e diz-me como instalar. Usa um ambiente virtual .venv, o torch na versão só CPU e o extra mcp. No fim corre earshot doctor --load e diz-me em palavras simples se está tudo bem.

O Claude cria uma pasta .venv, ou seja, um ambiente virtual: fica tudo lá, sem mexer no Python do sistema. Da primeira vez descarrega os dois modelos e demora um pouco (para os descarregar logo há o earshot doctor --fetch). Depois ficam na pasta do repositório e não volta a procurá-los na rede.

3. Junta-o como ferramenta do Claude Code

Cada comando no terminal volta a carregar os modelos: cerca de 20-40 segundos antes de responder, e um vídeo precisa de várias chamadas. É por isso que o ligas como servidor MCP, um programa que dá ferramentas novas ao Claude Code: os modelos carregam uma vez e ficam prontos.

No terminal escreve isto, com o caminho verdadeiro da pasta no lugar do que está entre < >:

claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- <pasta do earshot>/.venv/bin/python -m earshot mcp

• --scope user torna-o disponível em todos os teus projetos, só para ti.
• EARSHOT_THREADS=3 diz quantos núcleos do processador pode usar: assim o computador não bloqueia enquanto ouve.
• Depois no Claude Code escreve /mcp: o earshot tem de aparecer como ligado. Se num computador lento não aparecer, arranca o Claude Code com MCP_TIMEOUT=60000 claude.

4. Põe-no a ouvir o vídeo

Três ferramentas fazem a maior parte do trabalho:

• describe: dás-lhe um som a ouvir e ele descreve-o por palavras, com medidas.
• timeline: dás-lhe o vídeo inteiro e ele escreve o que se ouve, segundo a segundo, com os cortes de imagem e a batida que responde a cada um. O desvio é em milissegundos: negativo quer dizer que o som chega antes do corte.
• sheet: uma imagem com fotogramas, forma de onda e eventos. Cada corte tem uma cor: verde se o som cai dentro de um fotograma, âmbar dentro de 100 milissegundos, vermelho se falta.

Com o earshot ouve o out/video.mp4. Faz a timeline e o sheet, abre a imagem e diz-me em palavras simples: o que se ouve nos momentos principais, que cortes não têm som, e que batidas chegam antes ou depois do corte, por quantos milissegundos. Ainda não mudes nada.

Se o vídeo é feito mais de animações do que de cortes secos, faz com que passe os momentos-chave como cues (a opção --cues): um movimento dentro do mesmo plano não conta como corte.

5. A ficha e as correções

O critique compara a banda sonora com um perfil medido em sete vídeos de lançamento profissionais: para cada medida diz se estás dentro do intervalo, acima ou abaixo. Depois dá um veredicto e a lista FIX FIRST, as correções a fazer primeiro, com o segundo exato.

Com o earshot faz a critique da banda sonora do out/video.mp4 e explica-me veredicto e FIX FIRST em palavras simples. Depois corrige no código do vídeo a sincronia das batidas com os cortes, uma correção de cada vez: depois de cada uma volta a fazer o render, corre de novo timeline e critique e mostra-me os números antes e depois. Não mexas na música.

Mas esses sete vídeos foram escolhidos pelo autor e descrevem um só estilo: lançamentos de software e de IA, texto animado, demos da interface. Uma curta cinematográfica vai quebrar regras que não se lhe aplicam. Se o teu estilo é outro, com o earshot profile constróis um perfil a partir dos vídeos que admiras.

6. Os sons que faltam, feitos em código

Se um corte fica mudo, não precisas de procurar sons em mil sites. O earshot tem um banco de mais de 250 efeitos escritos como código (whooshes, batidas, cliques, pops, notas), que se geram em poucos segundos, sem modelos e sem rede.

• sfx: pega num som do banco e aponta-o à imagem, com a duração e o ponto de pico que escolhes.
• kit: um conjunto de sons para o vídeo todo, um por função, a partir de um preset (calm, crisp, minimal ou launch, para vídeos montados sobre música).
• forge: constrói um som novo em código e melhora-o a ouvi-lo. Para dar o melhor quer gravações reais de referência, que trazes tu.

Na timeline do out/video.mp4 há cortes sem som. Primeiro olha para o sheet para teres a certeza de que não há já um whoosh suave. Depois, para cada um, escolhe do banco do earshot um efeito adequado, gera-o com sfx para cair no corte e junta-o ao vídeo. Mostra-me a lista antes de a montares.

Sobre o forge o próprio autor avisa: a pesquisa tenta agradar aos modelos do earshot, e os modelos contentam-se mesmo que o som não melhore (é a lei de Goodhart). Julga um som feito com o forge pelas medidas, pelo espectrograma ao lado das referências e com os teus próprios ouvidos.

Os erros mais comuns

• Usá-lo pela primeira vez no vídeo de lançamento a sério. É alfa e é feito por uma só pessoa: primeiro um vídeo de teste, depois o importante.
• Confiar nas etiquetas dentro de uma mistura cheia. Tempos e níveis são fiáveis; o nome de cada batida por baixo da música é uma pista, certa mais ou menos uma vez em cada quatro.
• Tomar a ficha como uma lei. Mede a proximidade ao estilo de sete vídeos, não se o teu vídeo é bom ou se a música serve o teu produto: isso decides tu.

Checklist

• earshot doctor --load diz que está tudo bem
• No Claude Code, /mcp mostra o earshot ligado
• Primeiro teste feito num vídeo de teste
• Olhei para o sheet com os meus próprios olhos
• Cada correção verificada a correr de novo timeline e critique

Perguntas frequentes