SonuSV7719/earshot

earshot: ouvidos para um agente

Você não pode ouvir. Nunca diga como um áudio soa, ou que um som "se encaixa", sem uma leitura do earshot por trás, e cite o número quando relatar ("forte correspondência, z +3,9; p_real 0,96; -14,2 LUFS"). O earshot é executado localmente na CPU (o áudio nunca sai da máquina, exceto com o comando opcional llm) e armazena em cache cada embedding e resultado em disco. Custo: cada chamada CLI é um novo processo que carrega os modelos primeiro (~20-40 s em um laptop ocupado, mesmo para um arquivo em cache); dentro do servidor MCP ou de um script Python, os modelos carregam uma vez e chamadas repetidas levam segundos. Para mais do que algumas chamadas, use MCP ou um script curto (from earshot import api; api.find(...); api.realness(...)).

Configuração (uma vez)

pip install -e "/caminho/para/earshot[mcp,llm]"   # ou o venv do repositório: /caminho/para/earshot/.venv/bin/python -m earshot ...
earshot doctor                           # pacotes, ffmpeg, modelos (revisão fixada, estado do cache); --load os cronometra

Duas formas de usar, mesmas funções:

• CLI: earshot <comando> ... [--json] [--out resultado.json]. A saída de texto começa com um resumo simples; os tempos são em m:ss,ss no texto e segundos no JSON.
• MCP (os modelos permanecem carregados entre chamadas): claude mcp add earshot --scope user -e EARSHOT_THREADS=3 -- /caminho/para/earshot/.venv/bin/python -m earshot mcp, ou no .mcp.json de qualquer cliente: {"mcpServers": {"earshot": {"command": "/caminho/para/earshot/.venv/bin/python", "args": ["-m", "earshot", "mcp"], "env": {"EARSHOT_THREADS": "3", "GEMINI_API_KEY": "${GEMINI_API_KEY:-}"}}}} (a linha da chave apenas para a ferramenta llm opcional; o Claude Code a preenche a partir do ambiente do usuário, outros clientes podem precisar que a chave seja definida no ambiente que os inicia: nunca escreva uma chave literal em um arquivo de projeto). Ferramentas: measure, describe, match, rank, find, compare, ab, realness, timeline, sheet, critique, doctor, llm_critique; o banco de sons (sem modelos): sfx_list, sfx_render, kit_render (Loop 5). Passe caminhos absolutos; full=true retorna todo o JSON. O servidor responde em alguns segundos, mais tempo em uma máquina fria ou ocupada; se o Claude Code não mostrar ferramentas earshot, inicie-o com MCP_TIMEOUT=60000 (PowerShell: $env:MCP_TIMEOUT=60000; claude). earshot mcp --warm pré-carrega os modelos na inicialização. Se a máquina for compartilhada, defina EARSHOT_THREADS=2-3 (ou --threads 2 em qualquer comando). A primeira chamada de modelo de um processo carrega CLAP + AST (~20-60 s); chamadas posteriores no mesmo processo são rápidas. Qualquer arquivo legível pelo ffmpeg funciona, incluindo o áudio de um mp4 (um vídeo sem faixa de áudio informa isso). Erros são uma linha no stderr: earshot <comando>: error: ..., exit 1.

Loop 1: escolher um ativo

1. earshot rank "um golpe suave de martelo de feltro em um bloco de madeira" downloads/sfx/ --top 5 - lista de selecionados de uma pasta.
2. earshot find vencedor.ogg "um único golpe de martelo limpo" --top 3 - os melhores momentos como amostras cortadas (início / fim em segundos). Cada segmento tem um tipo: stroke (um ataque até decair) e event (golpes que pertencem juntos, por exemplo, pressionar + soltar uma tecla) começam 5 ms antes do ataque e terminam após a decadência; window é um trecho cujas bordas se encaixam no som para consultas únicas (um trecho simples, para fazer crossfade, para bases). head / tail = o quão altos os primeiros 5 ms / últimos 10 ms são em relação ao pico do corte (-30 dB ou menos = limpo); um corte marcado como 'head cut' ou 'tail cut' começa ou termina dentro de um som: não o use como está. --kind event retorna apenas cortes baseados em ataque (batidas, cliques, passos), --kind texture apenas janelas simples (bases); o padrão lê a consulta.
3. earshot describe vencedor.ogg --start 1,12 --end 1,48 - como realmente soa; verifique se as principais tags se encaixam no que você precisa e se a forma (ataque / decadência) se encaixa na imagem. Os rótulos AudioSet são fracos em sons únicos com menos de ~0,5 s: 'tagger unsure' ou uma classe próxima (Zipper para um swish, Finger snapping para um clique) é neutro; apenas uma classe claramente diferente (Speech, Music, Engine, Vehicle) é uma bandeira vermelha.
4. earshot realness vencedor.ogg --start 1,12 --end 1,48 (ou uma pasta inteira) - julgue o corte que você usará: o p_real de um arquivo com várias tomadas é a média de cada tomada e do silêncio entre elas. Quando o usuário quiser som real ou produzido profissionalmente, não use um corte 'provavelmente sintetizado por código' e leia as evidências de um 'incerto' antes de usá-lo (escreva por que o manteve). Quando o som sintetizado é o objetivo (música procedural, tons de UI, sons feitos com earshot forge), a realidade é informação, não uma barreira. Os limites do veredito dependem da duração (cada resumo os nomeia): um som de até 6 s usa os limites do clipe (baixo 0,17 / alto 0,77), um arquivo mais longo usa a média de suas janelas de 4 s com limites de arquivo fracamente calibrados (baixo 0,40 / alto 0,77), então compare vereditos, não p_real bruto, entre arquivos de diferentes durações. Gravações reais e música e design de som produzidos profissionalmente geralmente parecem reais, mas realness ouve como um som soa, não de onde veio: tons limpos sintetizados profissionalmente (sons de UI, sinos, stabs de sintetizador) também parecem sintetizados por código. Se realness não estiver disponível (modelo ausente), diga claramente que real-vs-sintético não foi verificado; as classes AudioSet do describe (Sine wave, Beep, Synthesizer) são evidências mais fracas. Zeros digitais exatos por si só não provam nada (59% das gravações reais licenciadas do projeto têm alguma edição ou preenchimento de fade).
5. Para escolher entre dois candidatos: earshot ab a.ogg b.ogg --query "um swish de ar rápido e nítido", com --a-start/--a-end/--b-start/--b-end para cortes do find (A e B podem ser o mesmo arquivo de várias tomadas). Opcional: earshot match vencedor.ogg "um pressionamento de tecla profundo e oco" --alts "um switch azul clicável" "uma tecla de máquina de escrever" para testar uma afirmação, ou earshot compare vencedor.ogg --refs aprovados/ [--start --end] para verificar se encaixa na paleta.

Loop 2: revisar uma mixagem ou um filme

1. earshot timeline filme.mp4 --cues cues.json (ou trilha_sonora.wav --video filme.mp4) - a transcrição de audição: eventos com tempo, nível e tags, seções, curva de loudness, cortes de imagem, sincronia por corte / cue. --detail low é rápido, high marca até 96 eventos (mais importantes primeiro; o resumo diz quantos foram marcados, então um evento não marcado não é um som ausente). Leia as estatísticas de sincronia: offset_ms = som menos imagem (negativo = adiantado), e a fração 'chance' diz o que pontos de edição aleatórios pontuariam; apenas sincronia melhor que o acaso significa algo. Um corte listado sem batida ainda pode ter um swish suave: verifique-o na folha antes de adicionar um som.
2. earshot sheet filme.mp4 -o folha.png --cues cues.json (--from 10 --to 25 amplia, --detail low é mais rápido) - um PNG anotado: quadros, seções, eventos rotulados, espectrograma, loudness, batidas, marcadores de cue coloridos por sincronia (verde = dentro de um quadro, âmbar = dentro de 100 ms, vermelho = sem som). ABRA O PNG com seu leitor de imagens: lacunas, acúmulos, mascaramento e batidas atrasadas são óbvios à primeira vista.
3. earshot critique filme.mp4 (--fast pula as passagens AudioSet / realness) - cartão de pontuação contra a faixa medida de filmes de lançamento profissionais: cada métrica ok / baixa / alta com seu peso e ações com timestamps, e um veredito (nível de lançamento / próximo / precisa de trabalho / não nível de lançamento). Corrija linhas críticas primeiro, re-execute 1-3 no novo render. Sua parcela de "início em eventos visuais" conta apenas novos ataques dentro de +-100 ms (a definição das referências); suas correções e dicas nomeiam os cortes sem som algum, pelo mesmo correspondente do timeline. Se o arquivo for um dos próprios filmes de referência do perfil, critique diz isso e o pontua contra os outros.
4. Medidores exatos a qualquer momento (LUFS, pico verdadeiro dBTP, LRA, piso de ruído, ataque / decadência, brilho, bandas): earshot measure mix.wav [--music] ou a ferramenta MCP measure.

Loop 3: teste A/B de uma alteração

• earshot ab antes.wav depois.wav --query "bumbo quente e encorpado" ou --refs pro_refs/ - qual está mais próximo, e como B difere de A em palavras medidas (mais alto, mais brilhante, decadência mais longa). Para sons dentro de arquivos mais longos, passe os cortes (--a-start 1,217 --a-end 1,615 --b-start 7,881 --b-end 8,285): um teste A/B de arquivo inteiro de arquivos com várias tomadas compara cada tomada mais o silêncio entre elas. Em seguida, earshot timeline depois.wav e compare as linhas de evento e as estatísticas de sincronia com a execução antiga. Mude uma coisa de cada vez.

Loop 4: criar um som em código (earshot forge)

Use isso quando o usuário quiser um som criado, não escolhido: uma IA que ouve pode escrever código de síntese, ouvir e melhorá-lo. Cada amostra deve ser computada (nenhum áudio gravado dentro, nem mesmo uma resposta de impulso); gravações reais são apenas as referências que o crítico compara.

1. Escreva ou escolha uma receita em earshot/forge/recipes/<nome>.py: SPACE (intervalos de parâmetros), DEFAULTS, TARGET, ALTS (confusões realistas) e render(params, r) -> array de 48 kHz, construído a partir de earshot.forge.dsp (ressonadores modais, excitações de contato, cores de ruído, um SVF variável no tempo, uma sala computada, um microfone com piso de ruído). Modele a física da coisa real, medida nas referências: o que golpeia o quê, o que ressoa, por quanto tempo, em qual sala.
2. Execute uma rodada: earshot forge <receita> --refs <refs reais> --budget 144 --reps 2 --tone 1,5 --keep 4 --robust 8 --dir <diretório da rodada>, ou em um script Python por rodada que carrega os modelos uma vez: forge(recipe, critic=Critic(target, alts, refs, tone=1,5), reps=2, space={...}). --tone coloca o equilíbrio tonal e a cauda livres de modelo no objetivo. --reps 2 classifica cada candidato por 2 renders, contra renders sortudos. Leva cerca de 3-5 minutos por 160 renders em uma CPU de laptop ocupada, incluindo um aquecimento de modelo de 30-60 s.
3. Leia o que ele ouviu. O resumo de cada escolha diz, por exemplo, "soa como: um pop de cortiça, um tingido de vidro", "decadência +2,4 fora das refs" ou "tom 11,2 dB da mediana das refs: +16 dB em 500-630 Hz (acima de todas as refs)". Em seguida, verifique as escolhas de quatro maneiras: as palavras tone livres de modelo: quais bandas caem fora de todas as referências, as parcelas de energia, a cauda, a duração (o sinal mais confiável quando as pontuações do modelo são altas); robust: a média sobre novas sementes, não o melhor render sortudo; alt_zs: qual confusão está mais próxima; espectrogramas ao lado das referências: ffmpeg -i x.wav -lavfi showspectrumpic=s=900x360:scale=log:legend=0 x.png. As tags AudioSet no report.json são retidas apenas enquanto você não escolhe ou orienta por elas. Corrija uma regra de seleção (por exemplo, a média robusta) antes de olhar, e relate as tags depois.
4. Mude a estrutura da receita, não apenas seus intervalos, para o que está errado (um tique de liberação ausente, um anel metálico, uma cauda muito longa). Em seguida, repita. Mantenha um LOG de cada rodada: mudança e números.
5. Relate honestamente, ao lado das referências reais pontuadas pelo mesmo crítico (report.json ref_scores, leave-one-out).

Goodhart, diga claramente:

• A busca otimiza os próprios modelos do earshot. Sons criados rotineiramente superam as gravações reais neles, o que significa que o crítico está satisfeito, não que o som é melhor.
• p_real é fácil de enganar: ressonadores modais mais uma sala e um piso de ruído de microfone soam "reais".
• Tipicidade recompensa ser uma média das referências.
• As verificações do modelo saturam: após uma busca, cada verificação do modelo, frases retidas e conjuntos reais independentes incluídos, coloca o som criado dentro dos reais. Apenas medições e ouvidos ainda podem distingui-los.
• Julgue pela proximidade medida com as referências: equilíbrio tonal, bandas fora de cada referência, caudas, durações. Use também re-renders robustos e espectrogramas.
• Peça um teste cego humano (ordem aleatória, com loudness correspondente, tecla oculta) antes de chamar um som criado de "tão bom quanto real".

No primeiro teste (demo/forge-test) um juiz independente achou o pressionamento de tecla 8-13 dB fora do equilíbrio tonal real e os pops com banda ilimitada e caudas sibilantes longas, enquanto cada verificação do modelo os chamou de reais. Refabricados orientando pela verificação livre de modelo, eles agora estão dentro da faixa medida das gravações reais. O whoosh foi refeito como um realmente rápido. O impact (mais escuro, liderado por swell) e o clique (caudas curtas) não foram refeitos. Nenhum humano ouviu ainda.

Loop 5: criar o kit de som de um filme (earshot sfx / earshot kit)

Use isso quando um filme feito em código (um filme cinético, qualquer folha de cue) precisar de seus efeitos: renderize-os do banco fornecido do earshot em vez de escrever vozes de síntese. Nenhum modelo é carregado; um kit inteiro renderiza em cerca de um minuto e re-renderiza em segundos.

1. Comece de uma predefinição: earshot kit init --preset calm -o audio/kit.json (calm para filmes liderados por texto, crisp para filmes de produto energéticos, minimal para filmes com efeitos projetados apenas, launch para filmes cortados em música). A note de cada função diz por que seu som foi escolhido. calm / crisp / minimal mantêm riser, swell e suck off: um reveal resolve em um elemento, e o lockup é uma batida limpa. launch soa um riser ou reverse swell em uma mudança de seção e usa os sons de 0,4 feitos para filmes liderados por música (abaixo).
2. Ajuste-o ao filme: earshot sfx list --kind hit (ou --category) mostra os candidatos com durações, tempos de pico e knobs. Mude o sound de uma função, defina edits (pitch para a raiz do filme para a batida ou drop, dur / apex para um movimento fixo), takes (12 ou mais para digitação, 2-4 em outros lugares), level_db. Audition um candidato com earshot sfx render ID -o x.wav [--pitch E5] [--dur 0,8 --apex 0,32] e leia seu início / pico / fim medidos.
3. Renderize: earshot kit render audio/kit.json --out audio/kit. As takes e kit.lock.json (início, pico, fim, loudness por take medidos) são o que o mixer coloca nos quadros de cue: início no quadro para batidas e toques, o pico em um ápice de whoosh, o fim na batida de um riser (seu pico quando a função alinha no peak, como o riser e swell do launch fazem: esses membros caem após seu clímax; kit check observa um alinhado no fim).
4. Verifique: earshot kit check audio/kit.json --out audio/kit. Ele recusa o que um render não pode usar (um knob ou pitch que o som não pode assumir, um nível acima de 0 dBFS, uma duração que um whoosh não pode alcançar) ou que está faltando. kit check também lista as peças do kit que o render pode colocar e os joins (crossfades marcados) que a mixagem pode usar.
5. Para adicionar um som ao banco: earshot sfx add /caminho/para/som.wav --kind hit [--tags "whoosh" "rápido"] --out banco/.
   Os sons no banco são arquivos WAV de 48 kHz 24 bits com início e fim não cortados, mantendo o ataque natural de cada tomada. Cada som tem knobs: pitch (deslocamento de tom sem mudança de duração, limitado a ±12 semitons, após o qual as artefatos se tornam audíveis), dur (esticamento de tempo sem mudança de tom, limitado a 0,5×–2,0×), apex (deslocamento do ponto de pico como uma fração da duração do som, 0,0 = início, 1,0 = fim; a implementação atual é uma emenda linear, então leans acima de 0,15 ainda são artificiais).

Comandos de utilidade

• earshot doctor — verifica se os pacotes e modelos estão instalados; --load os cronometra.
• earshot info — dependências, informações da versão do modelo.
• --progress em comandos longos (rank, find, critique) mostra uma barra de progresso.
• --json em qualquer comando produz JSON analisável; --out <arquivo> o salva em um arquivo.
• --verbose mostra mais detalhes sobre o que está sendo computado.