O que real-sound faz?
Você é o supervisor de áudio de um filme que você não pode ouvir. A trilha sonora é construída APENAS a partir de áudio real, profissionalmente gravado ou produzido (uma faixa musical licenciada, foley e SFX reais, ambiências reais), colocada nos quadros de sinalização da imagem por um mixer determinístico, medida em vez de ouvida, criticada através de cinco lentes, corrigida por um agente, masterizada, creditada e multiplexada. O código seleciona, corta, posiciona, nivela, panoramiza, equaliza, altera o pitch por reamostragem, estica o tempo da música e masteriza; o código nunca gera um som.
O padrão é um filme de lançamento profissional: cada som causado por algo na tela, uma paleta de materiais, o 'drop' da música na revelação do herói, contenção em todo o resto, um logotipo resolvido, uma cauda em silêncio. Regras: references/sound-design.md (e o repositório earshot docs/launch-video-sound.md para o perfil de referência agrupado: 7 filmes de lançamento profissionais).
<skill> abaixo é esta pasta. Python: {{PY}} abaixo (e em cada modelo de prompt) é UM interpretador que possui numpy, scipy, soundfile e o pacote earshot: o venv do repositório earshot (<earshot repo>/.venv/Scripts/python.exe no Windows, <earshot repo>/.venv/bin/python em outros lugares), ou qualquer Python onde <python> -c "import earshot" funciona. python puro no Windows geralmente é o stub da Microsoft Store e falha. Substitua o caminho completo por {{PY}} quando você executar um comando ou passar um prompt para um subagente (os outros placeholders estão listados em references/process.md). Execute os scripts com -I (isolado: arquivos baixados nunca podem sombrear um módulo); todo script exceto scripts/licences.py (o módulo de política de licenças que audit.py e credits.py importam) imprime --help.
O processo
| passo | quem | saída | gate |
|---|---|---|---|
| 0. lista de sinais | lead | out/cues.json | quadros de sincronia computados a partir do código da imagem |
| 1. briefing | lead | audio/SOUND_BRIEF.md | cada sinal tem uma necessidade sonora (ou "nada") |
| 2. sourcing (por categoria, paralelo) | agentes de sourcing | audio/assets/<cat>/, manifestos | cada arquivo medido + realness do earshot "real ou profissional" no corte usado (um "incerto" apenas com sua evidência e uma re-verificação no nível do corte escrita no manifesto) |
| 3. auditoria de licenças | auditor | audit.json | audit.py exit 0 para o que o filme usa |
| 4. edição musical | supervisor musical | audio/design/music.json | grade verificada, drop na revelação, emendas limpas |
| 5. fragmentos de design (por categoria, paralelo) | designers | audio/design/<cat>.json | renderização solo + QA limpo |
| 6. integrar | lead | trilha sonora, stems, relatório, trace | gate de masterização (+-0.5 LU, <= -1.5 dBTP) |
| 7. QA + escuta | lead | out/qa/qa.json, timeline / sheet / critique do earshot | nenhuma falha de QA |
| 8. crítica (5 lentes, paralelo, somente leitura) | críticos | problemas classificados + operações testadas | |
| 9. corrigir | UM corretor | o design | QA: sem regressão |
| 10. master, créditos, mux | lead | CREDITS.md, texto de descrição, o filme | créditos exit 0, lag 0 |
O detalhe de cada passo, os papéis e o que cada crítico mede: references/process.md. Cada prompt de subagente é um briefing pronto para preencher em templates/prompts/.
0. Lista de sinais a partir da imagem
Cada som está em um quadro que o código da imagem computa: um quadro de contato, o quadro de 50% de um pop-in, o pico de velocidade de um movimento, o hit de um riser, o quadro em que a marca se torna legível. Filmes cinéticos já possuem out/cues.json (export-cues.ts); para qualquer outra coisa, escreva o mesmo formato (templates/cues.json) a partir das constantes da timeline. IDs estáveis (act:thing:n) permitem que regras correspondam a classes de ação com uma regex.
1. Briefing
Copie templates/SOUND_BRIEF.md para audio/SOUND_BRIEF.md: conceito (paleta, o arco da música, lugares), o mapa da imagem (cada sinal: o que está na tela, a necessidade sonora), zonas de ambiência, licenças permitidas, padrão de qualidade, layout de arquivos. É o contrato que cada subagente recebe literalmente. Escolha a linha de personalidade da marca (references/sound-design.md §3).
2. Sourcing, por categoria (templates/prompts/sourcing.md)
Categorias típicas de filmes de lançamento: ui (cliques, toques, alternâncias, pops), keyboard, motion (whooshes, risers), impacts (hits de revelação, o logotipo), ambience, music; um filme de personagem adiciona foley, seus mundos, seus objetos. Freesound (CC0 / CC BY; preview HQ cdn.freesound.org/previews/<id//1000>/<id>_<user>-hq.ogg), Mixkit (WAV assets.mixkit.co/active_storage/sfx/<id>/<id>.wav), bibliotecas de compositores para música; licenças lidas na própria página de cada item (references/licences.md); downloads sequenciais educados; todo arquivo medido:
{{PY}} -I <skill>/scripts/analyze.py audio/assets/ui/* --png out/audio-review/ui --out out/audio-review/ui.json
{{PY}} -m earshot realness audio/assets/ui/ # gate: "real ou profissional" (re-verificar cortes: --start --end)
{{PY}} -m earshot rank "um único clique de trackpad nítido" audio/assets/ui/ --top 5
{{PY}} -m earshot match <file> "um pop de cortiça suave" --alts "um tiro" "uma explosão de balão"
{{PY}} -m earshot find <long take> "uma única pressão de tecla mecânica" --top 8 # cortes; pule qualquer um marcado como head cut / tail cut
3. Auditoria de licenças (templates/prompts/licence_audit.md)
O auditor registra o que cada página diz (licence_seen, licence_confirmed) em audio/assets/manifests/audit.json; o script verifica o resto (classificação, ids vs URLs, arquivos decodificam, durações, linhas de crédito):
{{PY}} -I <skill>/scripts/audit.py --root . --report out/qa/mix_report.json [--fetch]
Permitido: CC0, domínio público, CC BY 2.0-4.0, licenças gratuitas Mixkit, Pixabay. Proibido: NC, ND, SA, Sampling+, pessoal, personalizado, disputado. Não verificado = bloqueado.
4. Música (templates/prompts/music_supervisor.md)
Uma faixa licenciada cuja estrutura se encaixa no filme. Escreva o arco por barra do filme (templates/arc.json), então:
{{PY}} -I <skill>/scripts/arrange.py audio/assets/music/<track> --film-bpm 120 --arc audio/arc.json --out out/audio-review/music/arrange.json
Ela ajusta o tempo, move a grade para os ataques medidos (beat trackers lagam 20-50 ms), propõe a fase do downbeat, ancora o drop da barra do filme no candidato a drop mais forte e rascunha segmentos nas linhas de compasso (um bloco music pronto para colar). O downbeat é o ponto fraco: quando imprime confiança BAIXA (em uma das duas faixas em que foi testada estava meia barra atrasada), decida entre as duas grades impressas a partir da primeira nota, das entradas de seção e das mudanças de acorde na tabela de barras, e re-execute com --phase N. Em seguida, edite por julgamento: harmonia continua em cada emenda, o downbeat do drop no quadro do herói, o acorde final no logotipo, tail_fade no final.
5. Fragmentos de design, por categoria (templates/prompts/designer.md)
audio/design/<category>.json com amostras (cortes), slices (cortar uma take de muitos hits em hits individuais), pools, regras em eventos de sinal, posicionamentos livres, camas de ambiência, o bloco de música. Referência com cada chave e exemplos reais: references/design-format.md; um exemplo completo de vídeo de lançamento: templates/design_fragment.json (seus nomes de arquivo são placeholders como mk-0000_mouse-click.wav: ele renderiza uma vez que cada um é substituído por uma gravação real de seus manifestos; mix.py para e lista os arquivos ausentes até lá).
Verifique sozinho:
{{PY}} -I <skill>/scripts/mix.py --only ui --dump out/audio-review/ui/dump # cada corte como WAV + números
{{PY}} -I <skill>/scripts/mix.py --only ui --trace out/audio-review/ui/adds.json --out out/audio-review/ui/solo.wav
{{PY}} -I <skill>/scripts/qa.py --only ui --report out/audio-review/ui/solo_report.json --stems out/audio-review/ui/solo_stems --trace out/audio-review/ui/adds.json --out out/audio-review/ui/qa.json
{{PY}} -m earshot timeline out/audio-review/ui/solo.wav --cues out/cues.json
6-7. Integrar, QA, escutar
{{PY}} -I <skill>/scripts/mix.py --root . --design audio/sounddesign.json --cues out/cues.json --trace out/qa/adds.json
{{PY}} -I <skill>/scripts/qa.py --layers # cliques, bordas, audibilidade, aspereza, volume, cobertura, sincronia, densidade
{{PY}} -I <skill>/scripts/qa.py --listen --realness --video out/film.mp4 # + timeline do earshot, sheet, critique, realness
{{PY}} -m earshot critique out/audio/soundtrack.wav --video out/film.mp4 # scorecard vs filmes de lançamento profissionais
{{PY}} -m earshot sheet out/audio/soundtrack.wav -o out/qa/sheet.png --video out/film.mp4 --cues out/qa/cues_sounded.json
qa.py vincula cada descoberta à regra e amostra que a causaram (o trace). É utilizável sem os modelos; --listen adiciona a transcrição do earshot (out/qa/qa_timeline.txt), a folha anotada e o scorecard.
8-9. Crítica e correção
Cinco críticos somente leitura em paralelo, cada um com seu prompt: critic_sync.md, critic_edges.md, critic_masking.md, critic_tonal.md, critic_director.md. Cada um testa suas correções como uma variante em sua própria pasta:
{{PY}} -I <skill>/scripts/variant.py --ops out/audio-review/critic_tonal/ops_v1.json --out out/audio-review/critic_tonal/v1 --render --qa
e retorna problemas classificados com operações exatas e números de antes -> depois. Em seguida, UM corretor (fixer.md) mescla as operações, resolve conflitos, verifica a variante mesclada em relação ao qa.json anterior e a aplica (variant.py --apply, originais com backup). Reconheça exceções deliberadas confirmadas com "qa_ok": "<motivo>". Pelo menos uma rodada; uma segunda quando os níveis ou a edição musical mudaram.
10. Master, créditos, mux
mix.py masteriza com master.py (-14 LUFS, limitador de pico verdadeiro, teto 0.77 linear; gate +-0.5 LU e <= -1.5 dBTP).
{{PY}} -I <skill>/scripts/audit.py --root . --report out/qa/mix_report.json # exit 0
{{PY}} -I <skill>/scripts/credits.py --root . --design audio/sounddesign.json --audit audio/assets/manifests/audit.json
node <skill>/scripts/mux.mjs --video out/film.mp4 --audio out/audio/soundtrack.wav --out out/film_sound.mp4
{{PY}} -m earshot timeline out/film_sound.mp4 --cues out/qa/cues_sounded.json # o arquivo finalizado, ouvido
CREDITS.md + out/CREDITS_description.txt (cole na descrição do vídeo: créditos CC BY são obrigatórios lá). mux.mjs copia em stream a imagem e corta o áudio AAC para a duração da imagem.
Vídeos de lançamento: o mapa sonoro
| imagem | som | posicionado em |
|---|---|---|
| cursor se move, pairar, rolar, progresso, texto em fluxo | nada (a música carrega) | |
| clique / toque | UMA voz de clique real para o filme, pressionar + soltar ~85 ms depois, mesmo nível sempre | o quadro de pressionar |
| digitação | um teclado real, fatiado; <= ~12 teclas/s, uma por palavra acima de ~25 chars/s; música diminui 6-10 dB | cada caractere soado |
| um card / chip / emblema aparece | um pop ou tique real suave, subindo em uma sequência | 50% de seu percurso |
| alternância, trava, valor final de um contador | uma trava / clique / tique nítido real | o quadro de contato / trava |
| movimento de escala da câmera, whip, zoom (~2 por filme) | um swish real, ápice no pico de velocidade | pico de velocidade |
| cortes secos | nada | |
| tensão até a revelação | a construção da música, ou um riser real terminando 30-250 ms antes do hit | o hit |
| revelação do herói | o DROP da música (edite a faixa para que seu downbeat caia aqui) + opcionalmente um impacto real | o quadro |
| logotipo / lockup | música para em uma linha de barra ou filtra para baixo, 0.2-0.7 s de quase-silêncio, UMA nota suave no tom, cauda para o silêncio | o quadro em que a marca se lê |
Níveis: -14 LUFS, pico verdadeiro <= -1 dBTP após AAC, LRA 5-9 LU, o momento mais alto no drop (30-60% de entrada), o logotipo 8-20 dB abaixo dele, cerca de 5 efeitos projetados a cada 10 s, efeitos secos e centralizados. Normas medidas e os sinais baratos: references/sound-design.md.
Ferramentas
| necessidade | ferramenta |
|---|---|
| medir gravações (formato, piso, largura de banda, onsets, picos, andamento / tom) + PNGs do espectrograma | scripts/analyze.py |
| ouvir gravações: real vs sintetizado, como soa, melhor correspondência, melhor take dentro de um arquivo longo | {{PY}} -m earshot realness / describe / match / rank / find / compare / ab |
níveis / brilho / onsets de um arquivo ou de um trecho dele (--start --end) | {{PY}} -m earshot measure (Python: from earshot import api; api.measure(...), da mesma forma api.find, api.realness ...) |
| auditoria de licenças + arquivos | scripts/audit.py (política em scripts/licences.py) |
| grade musical, downbeats, rascunho de edição nas linhas de compasso | scripts/arrange.py |
renderizar o design (+ solo --only, --dump cortes, --trace para QA) | scripts/mix.py |
| masterização e medição de volume | scripts/master.py (--measure) |
| QA objetiva vinculada aos posicionamentos | scripts/qa.py (--layers, --listen, --realness) |
| variantes de crítica, aplicação do corretor | scripts/variant.py |
| créditos para CREDITS.md e a descrição do vídeo | scripts/credits.py |
| colocar a trilha sonora na imagem | scripts/mux.mjs |
| ouvir um mix / filme inteiro; imagem anotada; scorecard de filme de lançamento | {{PY}} -m earshot timeline / sheet / critique |
Arquivos
audio/SOUND_BRIEF.md o contrato (templates/SOUND_BRIEF.md)
audio/assets/<category>/ gravações baixadas (<source>-<id>_<slug>.<ext>; nunca commitar ou publicar)
audio/assets/manifests/<cat>.json uma entrada por gravação (templates/manifest_entry.json)
audio/assets/manifests/audit.json auditoria de licenças (templates/audit_entry.json)
audio/sounddesign.json nível superior: includes, buses, master (templates/sounddesign.json)
audio/design/<category>.json um fragmento por designer (templates/design_fragment.json)
out/cues.json os eventos de sinal da imagem (templates/cues.json)
out/audio/soundtrack.wav, stems/ a master e seus stems
out/qa/ mix_report.json, adds.json, cues_sounded.json, master.json, qa.json
out/audio-review/ trabalho por categoria e por crítico, variantes, dumps (a trilha de auditoria)
CREDITS.md, out/CREDITS_description.txt
Referências
references/process.md: papéis, passos, o que cada crítico mede, limites e suas fontes