EditAtlas/design-sonoro

Design sonoro: sons reais em um vídeo finalizado

O objetivo: o filme soa como se um editor com uma boa biblioteca o tivesse montado. Cada som é um arquivo real do EditAtlas, colocado em um quadro que você visualizou, em um nível que você pode justificar numericamente.

Duas coisas são verdade durante todo o processo, então planeje em torno delas:

• Você não pode ouvir. Você escolhe sons a partir de suas descrições e números medidos (sounds.py info), verifica posicionamento e níveis com check.py e entrega à pessoa uma lista curta de momentos para ouvir. Nunca diga que um som "soa bem"; diga o que foi medido e o que ainda precisa de ouvidos.
• Você não deve inventar. Trabalhe apenas no vídeo que a pessoa lhe deu. Se não houver vídeo, peça-o. Se um momento precisar de um som que a biblioteca não possui, deixe-o em silêncio e mencione isso no relatório.

Todos os scripts estão em scripts/ (Python 3.9+, numpy, Pillow para as folhas de quadros, FFmpeg com ffprobe no PATH). Execute-os com o caminho da pasta do skill, a partir de uma pasta de trabalho própria (work/, result/); nunca escreva dentro do projeto da pessoa ou desta pasta do skill.

python SKILL/scripts/moments.py FILM.mp4 --out work/moments             # moments.json, sheet.png, overview.png
python SKILL/scripts/moments.py FILM.mp4 --at 10.4 --out work/at        # quadros a cada 0,1 s em torno de um momento
python SKILL/scripts/sounds.py search "tilintar de vidro" --max-dur 2   # ids do índice público
python SKILL/scripts/sounds.py info sfx-ID sfx-ID                       # baixa uma vez, SHA-256, números medidos
python SKILL/scripts/sounds.py sheet sfx-ID sfx-ID --out work/c.png     # forma de onda + espectrograma dos candidatos
python SKILL/scripts/mix.py work/cues.json --out result/FILM_sfx.mp4    # MP4 + _track.wav + _resolved.json
python SKILL/scripts/check.py result/FILM_sfx_resolved.json --moments work/moments/moments.json --listen-out result/escute.wav

Os sons vêm de https://raw.githubusercontent.com/EditAtlas/sfx/main/ e são armazenados em cache em ~/.cache/editatlas-sfx (EDITATLAS_SFX_CACHE move-o). Com um clone local de EditAtlas/sfx, passe --mirror PATH (antes do subcomando para sounds.py) e nada é baixado.

1. Observe o filme e seu som

Execute moments.py. Ele informa o áudio existente (has_audio, LUFS, quanto dele é silêncio) e encontra três tipos de momento a partir de diferenças de pixel: cut (mudança de cena), move (movimento começa ou atinge o pico), land (movimento para: algo se acomoda). Em seguida, abra overview.png e sheet.png com a ferramenta de Leitura: os números ignoram animações suaves (um selo escalando sobre um rosto parado não gera corte) e superestimam tremores de câmera. Onde isso for importante, desenhe os quadros em torno de um momento com --at T e encontre o quadro exato onde a coisa aparece, pousa ou vira.

Decida qual é o áudio próprio do filme:

O que você vê nos números e na imagem	Folha de eventos
Sem áudio, ou silent_share próximo de 1	"keep_audio": false: os sons carregam o filme; ele é elevado para cerca de -16 LUFS
Apenas música	"keep_audio": true: os sons ficam cerca de 3 LU abaixo dela; coloque acentos na batida quando possível
Alguém falando (legendas, um rosto, um lavalier)	"keep_audio": true, "under_voice": true: cerca de 8 LU abaixo da voz; sons mais escassos e leves
Bipes sintetizados já embutidos na mixagem	pergunte: substituí-los requer as faixas separadas; sobrepor sons reais os duplica

Pergunte à pessoa quando não estiver claro se deve manter o áudio do filme.

2. Escreva a lista de eventos a partir do que você viu

Uma linha por momento que merece som: tempo, o que acontece, que tipo de som. Pense como um editor:

• Uma coisa que aparece (selo, chip, botão, cartão de legenda): um pop curto, clique ou ding suave, anchor: start.
• Uma coisa que se move ou uma transição: um whoosh cujo ponto mais alto cai na chegada, anchor: peak.
• Uma coisa que pousa com peso (logotipo, produto, carimbo): um impacto ou thud no quadro em que para, anchor: peak.
• Um objeto real na tela (vidro, gelo, papel, chaves, uma bebida): a foley correspondente, não um som de interface.
• Estados de sucesso/erro: um ding para sim, uma campainha curta ou alerta para não. Uma família de sons de interface por filme.
• Algo construindo: um riser cujo fim cai no payoff, anchor: end.

Nem todo movimento precisa de som. Ritmo e gosto com números estão em references/taste.md; leia-o antes da primeira folha de eventos de uma sessão.

3. Escolha sons: leia, meça, compare

1. Pesquise. Se o MCP do EditAtlas estiver conectado, search_sfx ranqueia melhor (ele também entende vietnamita); caso contrário, use sounds.py search. Os títulos evitam deliberadamente as palavras de seus arquivos de origem ("disparo de câmera" é "Lens Aperture Tick"), então pesquise pelo que o som é e tente sinônimos e o filtro de categoria.
2. sounds.py info em 2 a 4 candidatos. Leia: audible_s (quanto tempo ele é realmente ouvido; o arquivo pode ser mais longo), attack_s (0.0x = estala, 0.3+ = cresce), peak_t_s, centroid_hz (abaixo de ~1500 escuro, acima de ~6000 brilhante), mono_loss_db (abaixo de -6 os canais se cancelam em um telefone; mix.py então toca o canal mais alto).
3. sounds.py sheet quando dois candidatos leem o mesmo: uma linha vertical nítida é um clique, um borrão é um whoosh, energia na parte inferior é peso.
4. Escolha pelo que se move e o que toca, depois pelo comprimento: um pop de chip de 0,3 s não deve ser um pop de desenho animado de 1,8 s. Use max_len para cortar um arquivo longo, com fade.
5. Momentos repetidos de um tipo (três chips) querem takes diferentes de uma família (Tiny Plop 05, 06, Empty Plop 06), não o mesmo arquivo três vezes.

A biblioteca é escassa em alguns lugares (medido em 2026-11-07): sem líquido derramando ou efervescência, sem tom ambiente, sem carimbo, poucas gotas d'água e thuds. Escolha o som honesto mais próximo e nomeie a lacuna no relatório, em vez de forçar um errado.

4. Escreva a folha de eventos e renderize

{
  "video": "work/film.mp4",
  "keep_audio": false,
  "under_voice": false,
  "cues": [
    {"t": 0.30, "id": "sfx-988dafbd36", "role": "whoosh", "label": "título pousa"},
    {"t": 0.62, "id": "sfx-mi630472",  "role": "foley", "anchor": "start", "max_len": 0.9, "gain_db": -2, "label": "gelo no copo"},
    {"t": 8.30, "id": "sfx-fs339114",  "role": "hit", "label": "garrafa pousa"},
    {"t": 0.00, "id": "sfx-c7d271e90f", "role": "ambience", "bed": true}
  ]
}

• t é o quadro do momento em segundos. role define o nível e a âncora padrão (references/taste.md).
• anchor: start coloca o início audível em t, peak o ponto mais alto, end o fim audível.
• Por cue: gain_db (relativo ao nível do papel), max_len, fade_in, fade_out, offset_in, pan (-1..1).
• "bed": true: uma ambiência longa e constante sob todo o filme a -54 dBFS (quase inaudível). Apenas para filmes cujo som é apenas SFX; nunca sob voz ou música. Ele faz crossfade em si mesmo se o filme for mais longo.

Execute mix.py. Ele imprime cada som com seu tempo de pouso e nível de pico, e anota quando um momento foi tão cedo que o som teve que começar dentro de seu arquivo.

5. Verifique, corrija, verifique novamente

Execute check.py após cada renderização; código de saída 1 significa que sinalizou algo. Ele lê as faixas WAV que mix.py escreveu ao lado de _resolved.json, então mantenha esses arquivos juntos ao copiar os resultados. Ele encontra cada som na faixa renderizada por sua própria forma de onda, então sync é real: qualquer coisa com diferença maior que um quadro é um bug na folha. Ele também mede gestos a cada 10 s, a maior lacuna, impactos pesados, repetições, silêncio digital, loudness mestre e pico verdadeiro, redução para mono e quantos momentos fortes da imagem receberam um som.

Para cada sinalização, corrija-a (adicione um som à lacuna, troque uma repetição, mova uma cue) ou decida que está correta e diga por que no relatório ("a lacuna de 7,8 s é um trecho de fala, a voz a carrega"). Notas sobre ataques lentos são dicas: se o momento é o pico do som, mude essa cue para anchor: peak. Duas ou três rodadas são normais.

6. Entregue

Entregue à pessoa:

1. FILM_sfx.mp4 e FILM_sfx_track.wav (sons isolados, duração completa, para colocar sob a própria edição).
2. Uma tabela curta: tempo, momento, título e id do som, por que aquele som.
3. Os números de check.py (ritmo, maior lacuna, LUFS, pico verdadeiro) e o que cada sinalização restante significa.
4. A lista de escuta (listen.wav corta esses momentos em um arquivo): "ouça com fones de ouvido e uma vez no telefone".
5. As lacunas: momentos deixados em silêncio e sons que faltavam na biblioteca.

Escreva o relatório no idioma da pessoa. Não afirme que você ouviu.

Opcional: o motor real-sfx

O skill real-sfx da Clipwing (scripts MIT, por Alexander Korbanov) faz o mesmo trabalho com um motor mais pesado: listas de cues tipadas, remoção de camadas de sintetizadores, grades de batida, uma crítica de 9 eixos. Ele pode usar toda a biblioteca EditAtlas como seu pacote principal. Consulte references/real-sfx.md para o adaptador e o que foi verificado.