real-sfx: sons reais para vídeo em movimento

---

name: real-sfx description: Design de som para vídeos em movimento com sons reais gravados das próprias bibliotecas do usuário (um pacote principal organizado de whooshes, hits, risers, pops, chimes, keystrokes, foley, ambiências mais bibliotecas de fallback) e dicas de UI do uisfx, nunca sintetizados. Encontra os momentos a partir da própria lista de sugestões do projeto ou do script de sintetizador que gera seu som, de uma composição HyperFrames, de uma gravação de tela (regiões: digitação, toasts, scrolls, cliques) ou da própria imagem, seleciona e processa os sons, coloca-os no quadro exato no nível que os sons originais do autor tinham, mantém a música e a voz, remove uma camada sintetizada incorporada no render em vez de dobrá-la, e retorna um novo MP4, uma faixa WAV SFX separada, um relatório de sugestões e um quadro de pontuação de autocritica. Use sempre que o usuário pedir para adicionar efeitos sonoros ou SFX, design de som, "ozvuch'", "dobav' zvuki", "sfx", sons de whoosh/hit/riser/click/digitação, sons de UI, para substituir sons sintetizados ou gerados por reais, ou para melhorar o som de um motion graphic, promo, explainer, animação de UI, screencast, render HyperFrames, projeto After Effects ou Premiere, ou reclamar que o som é sintético, genérico ou fora de sincronia, mesmo que não digam "skill" ou nomeiem uma biblioteca.

real-sfx: sons reais para um vídeo em movimento

O objetivo: o filme soa como se uma pessoa com uma boa biblioteca o tivesse editado. Então:

• O som nunca é sintetizado. Fontes: as bibliotecas do usuário (config.json) e uisfx (um pacote CC0 pronto de sons de interface, ele mesmo sintetizado: a única exceção, apenas para momentos de interface; "no synthesis" o desliga: --ui library). Nenhum som adequado: o momento fica em silêncio e vai para o relatório. Isso substitui "no track: synthesize" do motion-standards.
• Você não pode ouvir. O som é lido como números, palavras e imagens (references/listening.md). Não apresente uma escolha como ouvida: diga o que foi verificado a olho e por medição, e o que o usuário deve ouvir.
• Mantenha a música e a voz quando elas carregam o filme. O resultado é sempre um novo MP4 e uma faixa WAV separada.
• Não duplique. A síntese incorporada no áudio do render é substituída pelos sons reais, não sobreposta a eles (passo 1). A crítica mede isso como um número (o eixo doubling).
• Não altere o projeto ou a pasta da skill. Coloque todos os arquivos de trabalho em sua própria pasta (work/, result/).

Dentro do Video Director

(Adicionado na cópia do Video Director; não no original do Clipwing. UPSTREAM.md lista cada alteração.) Esta cópia reside dentro da skill Video Director e é executada por seu estágio de Som: ../references/sound-stage.md, "Sound engineering". Essas etapas decidem quais momentos recebem um som, fornecem a esta skill apenas esses (build/audio/sfx/events.json), fixam as gravações que o usuário escolheu (sound_handoff.py pins), executam-na com --ui library, --no-loudnorm e sem camada de textura ou base, e recebem de volta apenas a faixa de efeitos e as sugestões resolvidas (sound_handoff.py collect). Siga-as e leia este arquivo apenas para opções que elas não cobrem. Defina REAL_SFX_CONFIG, REAL_SFX_INDEX, REAL_SFX_TASTE, REAL_SFX_RATINGS, REAL_SFX_STEADY e REAL_SFX_STYLES para caminhos dentro de ~/.config/real-sfx/ (o plugin instala cada versão em uma nova pasta, então qualquer coisa escrita aqui é deixada para trás na próxima atualização), e não use --remember, que escreve dentro desta pasta (assim como learn_style.py: copie um estilo aprendido para ~/.config/real-sfx/styles/).

Caminho rápido

Primeiro python scripts/setup.py check (ffmpeg, bibliotecas principal/extra, índice, uisfx) e python scripts/look.py FILM.mp4 --out work/look (quadros com tempo + o som original abaixo deles). Então, pelo que você tem:

# 1. o projeto tem uma lista de eventos (docs/cues.json, scripts/cues.json) OU um script que sintetiza seu som (audio.cjs)
python scripts/from_cues.py PROJECT_FOLDER|docs/cues.json --video RENDER.mp4 --out work/cues.json
# 2. gravação de tela sem lista: ui_events.py ... (references/screencast.md), então from_cues.py work/ui/events.json
# 3. apenas imagem:                    find_moments.py FILM.mp4 --out work/moments; suggest_cues.py work/moments/moments.json --out work/cues.json
# 3b. ANIMAÇÃO COLORIDA SUAVE sem lista (pré-visualização de UI, ilustração, motion graphics): a automação vê 5-6 movimentos de 40.
#     passo 2, "Animação silenciosa sem lista": find_moments.py FILM --out work/moments --fine; look.py FILM --at T --span 2.4
#     --step 0.1 --out work/at.png; SUA PRÓPRIA lista de eventos dos quadros (references/typed-cues.md) -> from_cues.py - --ui library
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --plan     # o que vai onde; depois sem --plan
python scripts/critique.py result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav
python scripts/levels.py   result/film_sfx_resolved_cues.json result/film_sfx_sfx_track.wav --json work/edits.json
# um filme cujo som é APENAS SFX (sem música ou voz própria): sons pequenos nos buracos, depois mix.py novamente (passo 4, "Camada de som pequeno")
python scripts/texture.py work/cues.json --moments work/moments/moments.json
# o mesmo filme: uma base (uma longa gravação real escura sob todo o filme; passo 4, "Base"), depois mix.py novamente
python scripts/bed.py work/cues.json [--list]
# números contra nove rolos SFX finalizados (passo 6, "Contra a referência"): sem pontuações, não afeta o veredito
python scripts/critique.py RESOLVED.json WAV --style clean-sfx-refs
# ouvidos humanos baratos (passo 6): uma página com as perguntas da crítica e um veredito de um toque; o modelo de mascaramento
python scripts/listen_page.py build work/listen --moments result/film_sfx.mp4 --critique RESOLVED.json WAV
python scripts/listen_page.py serve work/listen [--lan]        # então: listen_page.py results work/listen --log
python scripts/mix.py work/cues.json --out result/film_sfx.mp4 --masking        # quais sons o resto esconde (precisa do venv)

Uma pasta de projeto encontra sua própria lista de eventos (docs/, scripts/, assets/); o script sintetizador é lido apenas quando não há lista. Escolha todas as flags de from_cues.py antes de editar a planilha: executá-lo novamente apaga edições manuais (então sheet.py apply). Voz no filme: mix.py ... --voice-safe (profundidade normal; --voice-depth light quando há muitas texturas silenciosas, deep apenas para sons raros em pausas: ele remove a interface completamente da mixagem). Música que carrega o filme: --duck. Volume: uma base reconstruída corresponde ao original por padrão; o seu próprio: --target-lufs NUMBER. Nenhum índice, ou as bibliotecas foram movidas: python scripts/build_index.py, então python scripts/listen.py tag-index. Nenhum uisfx: setup.py init --uisfx. Outra máquina: setup.py scan FOLDER, setup.py add-library NAME PATH [--tier main|extra] --index. Execute scripts da pasta da skill; coloque caminhos com espaços ou caracteres não latinos entre aspas; seu próprio Python com caminhos não latinos no Windows: PYTHONUTF8=1. No PowerShell, aspas quebram argumentos JSON: coloque-os em um arquivo.

De onde vêm os sons

O que é necessário	De onde vem
A base: whooshes, hits, risers, pops, chimes, teclas, papel, foley, ambiência	a biblioteca principal (tier: main, caminho em config.json). Um pacote organizado com catalog.json / catalog.csv dá a cada som seu tipo e gravação de origem, o que é melhor do que adivinhar a partir de nomes de arquivo
O que falta na biblioteca principal: drops baixos, moedas, glitches curtos	bibliotecas de fallback (tier: extra, marcadas ~ nos resultados): apenas quando a biblioteca principal tem menos de três sons adequados
Pacotes projetados com suas próprias funções	funções granular, atmosphere, power, music_transition, voice nunca são solicitadas pela seleção automática: pegue-as explicitamente (--role, "pick": {"role": ...})
Um momento de interface: clique, tick, janela, notificação	uisfx (--ui auto) quando a própria lista nomeia tipos de interface (clique, chime...): from_cues diz por que e onde (routes: key -> library:click, pop -> uisfx:select)
Digitação	sempre o teclado real da biblioteca, mesmo com --ui auto; uma sequência de 8+ eventos click com 35–170 ms de intervalo é reconhecida como digitação pelo próprio from_cues (--no-typing-detect)
Contato físico: bola, passo, conta, objeto	sempre a biblioteca: uma bola no chão é um baque surdo, não select (receita abaixo)

Nenhuma biblioteca ainda: setup.py init --uisfx sozinho dá 78 dicas de UI CC0. Fontes gratuitas de gravações reais que valem a pena verificar (leia cada licença): Freesound (filtro CC0), pacotes Sonniss GDC, Mixkit, Pixabay sound effects.

"Da minha biblioteca", "sem síntese" ou "sons sintéticos": --ui library. Um acento no logotipo ou um "cha-ching" em um projeto com sons de interface uisfx: --from-library pop,bell (nomes de tipos da lista); para um som: sheet.py set --at T --label bell id=65. Sob música tonal:

• os passos de pitch de repetições uisfx e de sons tonais da biblioteca (chime, pop, glass, coin) desligam-se sozinhos quando o projeto tem uma partitura (--ui-pitch off|cycle);
• o pitch de um som real é afinado para as notas da música: mix.py pega o music_ref da planilha (a base sem efeitos, o stem de música) ou --music-ref FILE e desloca um som tonal por semitons inteiros até 2 mais os centavos que o colocam em uma nota (2,5 no total), se isso o colocar em uma nota; ruído é deixado em paz (--no-tonal-fit; scripts/tonal.py SOUND --music FILE --at T mostra as notas);
• os intervalos das frequências originais do autor (tick(t, 1800 * 2 ** (4 * i / 12))) tornam-se os passos de pitch da substituição (melody:).

Fluxo de trabalho

1. O que já está no som

look.py mostra o espectrograma do som nativo (voz são bandas de frases, música um tapete com batida, silêncio é preto); listen.py voice FILM.mp4 dá a parcela de fala e música. Três casos:

• A música ou voz do autor: elas ficam, SFX vão por cima (--duck / --voice-safe). Exceção (resposta de uma pessoa em um filme real, 2026-10-19): o filme foi enviado "para ser sonorizado", seu som nativo é apenas música (listen.py voice: fala 0 %), e a pessoa o quer sem a música, como seus próprios rolos SFX limpos. Faça uma versão sem música (from_cues.py ... --ui library --drop-original, então bed.py --id ... --level -46 com uma atmosfera favorita), e uma versão com música se for útil, e diga qual é qual. Em uma escolha cega de três (original / efeitos sobre música / apenas efeitos) a pessoa escolheu o último sem uma única reclamação. from_cues imprime BAKED: em tal filme embora não haja síntese cozida (fala 0 %, música 84 %, os ataques não correspondem aos eventos: 7 % contra 9 % por acaso): isso é um falso alarme.
• Síntese cozida na faixa (o projeto foi escrito para uma trilha sintetizada): sons reais sobre ela estão duplicando. from_cues.py verifica isso sozinho (BAKED:, unbake:) e remove a síntese da base sem tocar na música e voz; como exatamente, e o que fazer se o script falhar ou a síntese estiver dentro do stem de música (--extra-synth): references/project-audio.md (leia assim que a saída tiver BAKED, WARN stems, unbake: not possible, ou o projeto sintetizar seu som com um script). Após a construção, critique.py imprime o eixo doubling: a correlação da camada com o original e com o novo filme (deve ser cerca de 0).
• O som de clipes tocando dentro de uma janela de gravação de tela: nativo, fica; eventos dentro dessas janelas são descartados.

2. Encontre os momentos (da melhor fonte para a pior)

• A lista de eventos do projeto ou script sintetizador → from_cues.py (abaixo). Em detalhes: references/typed-cues.md.
• Uma gravação de tela → references/screencast.md (regiões de ui_events.py, correspondência de teclas a caracteres, som de clipe).
• HyperFrames com data-start e sem lista: from_hyperframes.py PROJECT --out work/moments.json. "1 moments" com 18 elementos significa que o movimento não segue data-start: procure um script sintetizador.
• Apenas vídeo: find_moments.py FILM --out work/moments [--roi x,y,w,h] [--from A --to B] [--fine]; tipos cut, burst, onset, settle (settle também dispara em um quadro vazio ou um loop em repouso: olhe para o quadro); look.py --moments ... desenha os quadros dos momentos. Esqueleto: suggest_cues.py (references/recipes.md); um rascunho é um começo, não uma resposta. --fine para animação colorida suave (gradientes, brilhos, formas pastel que mudam de cor em vez de brilho): ele também lê mudanças de croma, os momentos obtêm src=chroma|luma; em três desses filmes, ele encontra 33–69 % dos eventos que um agente escreveu a partir dos quadros (dentro de 80 ms), contra 13–25 % apenas do brilho; 3–4 vezes mais candidatos (15–25 por 10 s). Estes são candidatos: os quadros decidem.
• Sob música: beats.py FILM --out work/beats.json --plot work/beats.png; com usable: true, mix.py --snap-beats (±50 ms). A grade é verificada contra o kick (a banda baixa < 125 Hz separadamente): imprime quantas batidas caíram em um kick dentro de 40 ms. Uma grade próxima ao kick (o tracker sentou nos hats, "0.22 s off") é movida para ele; uma grade que cai em nada obtém usable: false, e --snap-beats a ignora. --plot desenha a banda, os kicks (marcas verdes) e a grade (linhas vermelhas): as marcas estão nas linhas, ou não confie na grade. Se a música é sua e pode ser ajustada à imagem: beats.py FILM --suggest-offset work/moments.json diz o quanto deslocar a música para que cortes e hits caiam nas batidas (apenas conselho; a música não é tocada).

from_cues.py: python scripts/from_cues.py LIST|PROJECT_FOLDER|SCRIPT.cjs|- --video RENDER.mp4 --out work/cues.json (- lê a lista do stdin; um BOM do PowerShell é compreendido). O que ele faz e diz por conta própria:

• é o render certo: a lista perde a imagem (VERDICT); uma lista em tempo de design contra um render cronometrado para a voz: um mapa de tempo das âncoras do projeto (timing.json com a

...

[truncado para tradução]