O Claude Code consegue escrever o código que renderiza um filme, uma demo de produto ou um jogo. O que ele não consegue é ouvir o que fez. Ele não percebe que um clique soa barato, que uma batida cai 80 milissegundos depois do corte ou que a música cresce no lugar errado. O som entra no vídeo às cegas.
O earshot é um projeto aberto, com licença MIT, que dá ouvido ao agente. Ele transforma som em evidência que o agente consegue ler: descreve em palavras como um arquivo soa, acha o melhor momento dentro de uma gravação longa, diz se um efeito bate com o corte do vídeo e dá nota a um vídeo inteiro contra filmes de lançamento profissionais. Roda no processador, sem placa de vídeo, como linha de comando, como biblioteca Python e como servidor MCP, que é o jeito de ligar uma ferramenta externa ao Claude Code.
Este guia traz o que o vídeo cortou: o comando de instalação, o passo a passo para ligar no Claude Code, prompts prontos para criticar um vídeo e para pedir efeitos sonoros. Os dados vêm do README do projeto (github.com/Leonxlnx/earshot), conferido em 28/10/2026. O projeto é novo, foi criado em 15/10/2026, e muda rápido; se um comando estiver diferente na sua tela, vale o README.
Comando de instalação e do servidor MCP
Você precisa de Python 3.10 ou mais novo e do ffmpeg instalados na máquina. Sem eles o earshot não roda. No terminal:
git clone https://github.com/Leonxlnx/earshot && cd earshot
python -m venv .venv
.venv/bin/python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
.venv/bin/python -m pip install -e ".[mcp,llm,dev]"
.venv/bin/python -m earshot doctor --load
Em Windows, troque .venv/bin/python por .venv/Scripts/python. O comando que liga o earshot ao Claude Code como servidor MCP, trocando o caminho pelo da sua pasta:
claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /caminho/para/earshot/.venv/bin/python -m earshot mcp
Passo a passo para ligar no Claude Code
- Confira que
python --versionmostra 3.10 ou mais e queffmpeg -versionresponde. - Rode os cinco comandos de instalação acima, um de cada vez, dentro da pasta onde quer guardar o projeto.
- O último deles,
earshot doctor --load, baixa dois modelos abertos de escuta (cerca de 1,1 GB) e confere se carregam. A primeira vez demora. Se quiser baixar antes de usar,earshot doctor --fetchfaz só o download. Depois disso o earshot lê os modelos do cache local e não contata mais o Hub. - Rode o
claude mcp addcom o caminho real da pasta do earshot. - Abra o Claude Code e peça: "liste as ferramentas do servidor earshot". Se aparecerem, está ligado.
Duas dicas do README: os modelos carregam na primeira chamada e ficam em memória, então o servidor MCP é o caminho certo quando você vai fazer várias chamadas (cada chamada solta pela linha de comando recarrega os modelos, de 20 a 40 segundos). E em máquina lenta, abra o Claude Code com MCP_TIMEOUT=60000 para o servidor ter tempo de subir.
Prompts para criticar um vídeo e achar o momento certo
Com o servidor ligado, você pede em português e o agente chama a ferramenta certa. Prompts de partida:
Use o earshot para criticar o vídeo renders/video.mp4. Me diga o veredito e a lista do que corrigir primeiro, com os tempos.
Use o earshot para achar, na gravação sessao.wav, os melhores momentos em que aparece "uma tecla de teclado mecânico sendo apertada". Me dê os tempos de início e fim.
Use o earshot para descrever o arquivo clique.wav e dizer se ele soa como "um clique de mouse" ou como "uma tecla de teclado".
O que cada comando entrega, segundo o README:
critiquedá uma nota contra o perfil de 7 filmes de lançamento profissionais, com o veredito e uma lista "FIX FIRST" com os tempos. O exemplo do projeto diz que 21 de 23 métricas medidas estão na faixa e aponta, como primeiro conserto, que nada chega ao nível de corpo antes de 1,01 segundo.findacha os melhores trechos dentro de uma gravação longa e devolve início e fim em segundos.describeconta em palavras como o arquivo soa, com a leitura mais provável e as alternativas.timelineesyncmostram o transcript de escuta do filme, segundo a segundo, e se o som bate com os cortes da imagem.
Como pedir efeitos sonoros feitos em código
O forge é o pulo do gato. Em vez de procurar um efeito pronto, o agente escreve o som como código: uma receita de síntese física, sem nenhuma gravação dentro. O forge gera candidatos, o earshot escuta e dá nota a cada um, e o agente reescreve a receita e roda de novo até ficar bom. O filme de lançamento de 22 segundos do próprio projeto foi sonorizado assim, sem gravação e sem trilha.
Prompts de partida:
Use o forge do earshot para criar o som de um clique de interface curto e macio. Rode a busca, escute o resultado e me mostre os melhores candidatos com a nota de cada um.
Crie um whoosh rápido para o corte em 0:03.2 do meu vídeo. Use o banco de efeitos do earshot, confira a sincronia com o corte e ajuste se estiver fora.
Duas coisas para saber antes: o forge usa um conjunto de gravações de referência para comparar, e as do autor não vêm no repositório, então traga as suas com --refs PASTA. Sem referências, ele roda em modo de design, e o critério de "parece real" deixa de ser exigido. E o README é honesto sobre o limite: a busca otimiza os próprios modelos do earshot, então um som pode agradar o crítico sem melhorar de verdade. Vale sempre ouvir o resultado.
Limites
- O earshot não compõe música. Ele descreve, compara, mede e gera efeitos sonoros.
- Precisa de Python 3.10 ou mais novo e de ffmpeg no computador.
- Só a crítica por modelo de linguagem de áudio (
llm_critique) é paga: ela usa uma chave da Gemini que você mesmo fornece, com consentimento explícito a cada envio. Tudo o mais roda local e de graça. Nunca escreva a chave dentro de um arquivo. - Em um teste do próprio autor, com uma pessoa e 15 tentativas, os sons feitos em código foram distinguidos dos reais em 8 de 15 vezes, o que é um sorteio. É um teste pequeno, não uma prova.
Fontes
- Repositório do earshot: https://github.com/Leonxlnx/earshot (README conferido em 28/10/2026)
- Filme de lançamento e versão 0.1.0: https://github.com/Leonxlnx/earshot/releases/tag/v0.1.0