primocode 10.16.0 → 10.17.0

package/editor/references/revisao.md

@@ -0,0 +1,335 @@
+# Revisão sem retrabalho
+
+Para quando o vídeo já existe e precisa de ajuste, diagnóstico ou conferência antes da entrega. A regra geral:
+achar a causa, mexer no mínimo, conferir o que mudou e o que não podia mudar, e dizer a verdade sobre o que foi
+feito.
+
+| a pessoa diz | seção |
+|---|---|
+| "tá poluído", "tá confuso", "o que eu tiro?" | Diagnóstico só de leitura |
+| "entre 00:12 e 00:18, arruma tal coisa" | Conserto num trecho |
+| "de novo o mesmo erro" | Tentativa repetida |
+| "tem chiado", "a voz sobe e desce" | Voz |
+| "confere a legenda antes de eu postar" | Legendas checadas no áudio |
+| "não pode aparecer nome de cliente", "confere se não vazou nada", vídeo com tela gravada ou borrão | Dado pessoal no arquivo exportado |
+| "tenho uma pasta cheia de arquivo, o que uso?" | Triagem dos materiais |
+| "faz um antes e depois" | Comparação justa |
+| "quanto isso custou?" | Custo, sem inventar |
+
+## Ordem de prioridade
+
+Quando há vários problemas, nesta ordem (a não ser que a pessoa destaque outra coisa):
+
+1. sentido e informação (o que é dito e mostrado está certo e fiel ao material);
+2. voz e sincronia;
+3. enquadramento e leitura;
+4. acabamento.
+
+## Cada problema em quatro partes
+
+- **Onde:** o intervalo ou a frase, com o tempo conferido no vídeo.
+- **O que está errado:** separe defeito (texto errado, palavra cortada, rosto coberto) de preferência nova ("quero
+  mais rosa").
+- **A mudança:** algo que dá para conferir depois ("a legenda sobe 80 px entre 00:12 e 00:15").
+- **O que preservar:** o que não pode mudar junto.
+
+"Não ficou bom" sem detalhe: olhe o vídeo e aponte problemas concretos. Só pergunte a intenção se houver saídas
+que não combinam entre si. Não invente defeito para justificar mais uma rodada.
+
+Ideia nova de estilo não é correção: é decisão nova, e se decide com a pessoa. Correção pequena e que dá para
+desfazer não precisa de confirmação.
+
+Reaproveite o que continua válido: projeto, transcrição, rostos medidos, recorte, sons. Mudar posição ou fonte
+não pede recorte novo nem animação redesenhada.
+
+## Diagnóstico só de leitura
+
+Nesta etapa você não mexe no projeto. Só olha e escreve.
+
+1. Toque o vídeo inteiro com som, no tamanho do celular. Depois olhe uma folha com 1 quadro por segundo e tiras
+   densas nas trocas:
+   `uv run --directory "<SKILL>" python helpers/tira_de_quadros.py '<VIDEO>' 0 <fim> --fps 1 --colunas 8 --saida '<PROJETO>/quadros/folha.jpg'`
+2. Confira a fala real e diga, bloco a bloco, qual mensagem manda ali.
+3. Marque, com início e fim:
+   - onde rosto, textos, legenda, animações e imagens disputam o olho;
+   - onde falta contexto para entender;
+   - onde algo inserido não acrescenta nada.
+4. Separe erro objetivo (texto cobre o rosto, legenda repete o lettering) de gosto.
+5. Dê a cada problema uma saída só, escolhida da mais leve para a mais forte: **deixar** (fica como está; era
+   gosto, não erro), **mover** (vai para outro canto da tela), **encolher** (menor, mais curto ou mais baixo),
+   **atrasar** (entra depois, quando o que disputa com ele já saiu) ou **remover**.
+6. Escreva `diagnostico.md` no projeto: até cinco correções, da mais importante para a menos, e para cada uma o
+   jeito mais rápido de aplicar sem quebrar o que já está bom.
+
+| # | de | até | problema | tipo | saída | como aplicar |
+|---|---|---|---|---|---|---|
+| 1 | 00:08,2 | 00:11,0 | lista e legenda brigando no mesmo lugar | erro | atrasar | a legenda volta só depois que a lista sai |
+| 2 | 00:14,0 | 00:15,5 | carimbo que não corresponde a nenhuma frase | erro | remover | apagar a peça do `projeto.json` |
+
+Não sugira fala nova, trilha nova, oferta nova nem material comprado. Arquivo que não abriu vira limite declarado,
+não suposição.
+
+## Conserto num trecho
+
+Entrada: a versão atual, o problema, o início e o fim, e como saber que ficou certo.
+
+1. **Ache a peça que causa.** Camada, arquivo ou valor. Texto em cima do rosto pode ser a posição, a ordem das
+   camadas ou uma máscara: corrija o mecanismo certo, não o sintoma.
+2. **Mude o mínimo.** Fora do intervalo nada se mexe: enquadramento, trilha, cores, fonte, emendas, duração, fala.
+3. **Se precisar sair do trecho,** pare, explique a dependência e mostre o menor alcance possível antes de fazer.
+4. **Mostre o trecho corrigido** no estúdio com 1 a 2 s de margem antes e depois.
+5. **Depois do render, compare com a aprovada.** Fora do trecho, imagem e som têm que ser os mesmos. Grave este
+   script no projeto e rode:
+
+   ```python
+   # comparar_versoes.py  uso: python3 comparar_versoes.py aprovada.mp4 nova.mp4 <de> <ate>
+   import subprocess, sys, tempfile
+   from pathlib import Path
+   aprovada, nova, de, ate = sys.argv[1], sys.argv[2], float(sys.argv[3]), float(sys.argv[4])
+   tmp = Path(tempfile.mkdtemp())
+
+   def duracao(v):
+       return float(subprocess.run(["ffprobe", "-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", v],
+                                   capture_output=True, text=True).stdout)
+
+   def fora(t0, t1):                        # não encosta no trecho consertado (com 0,1 s de folga)
+       return t1 <= de - 0.1 or t0 >= ate + 0.1
+
+   avisos = []
+   if abs(duracao(aprovada) - duracao(nova)) > 0.05:
+       avisos.append(f"duração mudou: {duracao(aprovada):.2f} s para {duracao(nova):.2f} s")
+   subprocess.run(["ffmpeg", "-v", "error", "-i", aprovada, "-i", nova, "-lavfi",
+                   f"[0:v][1:v]ssim=stats_file={tmp / 'ssim.log'}", "-f", "null", "-"], check=True)
+   num, den = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=r_frame_rate",
+                             "-of", "csv=p=0", aprovada], capture_output=True, text=True).stdout.strip().split("/")
+   fps = float(num) / float(den)
+   ruins = []
+   for linha in open(tmp / "ssim.log"):
+       c = dict(p.split(":") for p in linha.split() if ":" in p)
+       t = (int(c["n"]) - 1) / fps
+       if fora(t, t + 1 / fps) and float(c["All"]) < 0.98:
+           ruins.append(t)
+   if ruins:
+       avisos.append(f"imagem mudou fora do trecho em {len(ruins)} quadros, de {ruins[0]:.2f} a {ruins[-1]:.2f} s")
+
+   def rms(v, nome):                        # volume a cada 0,5 s
+       log = tmp / f"{nome}.log"
+       subprocess.run(["ffmpeg", "-v", "error", "-i", v, "-map", "0:a:0", "-af",
+                       f"aresample=48000,asetnsamples=n=24000,astats=metadata=1:reset=1,"
+                       f"ametadata=print:key=lavfi.astats.Overall.RMS_level:file={log}", "-f", "null", "-"], check=True)
+       out, t = [], None
+       for l in open(log):
+           if "pts_time:" in l:
+               t = float(l.split("pts_time:")[1])
+           elif "RMS_level=" in l:
+               out.append((t, float(l.split("=")[1])))
+       return out
+
+   for (t, x), (_, y) in zip(rms(aprovada, "a"), rms(nova, "b")):
+       if fora(t, t + 0.5) and abs(x - y) > 1 and max(x, y) > -60:
+           avisos.append(f"som mudou fora do trecho em {t:.1f} s ({x:.1f} dB para {y:.1f} dB)")
+   print("\n".join(avisos) or "fora do trecho, nada mudou")
+   ```
+
+   Qualquer aviso fora do trecho é mudança sem querer: ache a causa antes de entregar. Olhe também a emenda do
+   trecho com a tira de quadros a 30 qps, para ver se continua lisa.
+6. **Versão nova, nunca por cima.** O nome diz o que mudou (`final_v2_legenda-00m12.mp4`). Na entrega, uma linha
+   do que mudou e o intervalo conferido.
+
+Correção não é pretexto para redesenhar o vídeo.
+
+## Tentativa repetida
+
+O mesmo erro voltou depois de uma correção:
+
+1. Antes da próxima tentativa, compare o que devia sair com o que saiu. Escreva a diferença em uma frase.
+2. Teste uma hipótese por vez, num trecho curto: o menor em que o defeito ainda aparece (uma amostra de 2 s, não o
+   vídeo inteiro).
+3. Se a correção repete a falha sem nada novo aprendido, pare esse ciclo. Conte o que testou, o que descobriu e o
+   que falta (uma informação da pessoa ou uma capacidade que o computador não tem). Siga com as correções que não
+   dependem disso.
+4. Refazer o vídeo todo não é jeito automático de consertar.
+
+## Voz
+
+Chiado, picos, voz que estourou, eco de sala ou volume subindo e descendo que atrapalham entender.
+
+- **Relate só o que achou de verdade.** `helpers/noise_check.py` mede o ruído de fundo, a saturação e o eco de sala
+  de cada vídeo (só a voz: `helpers/voz_check.py VIDEO`); `helpers/voice_levels.py` mede o volume desigual entre
+  frases. São medidas: ouça os tempos que a saída cita antes de afirmar, e diga "medi", não "ouvi".
+- **Correção moderada** com o que é local: limpeza de ruído leve ou forte (`helpers/denoise.py`), ganho por
+  trecho. Mantenha o timbre, as pausas com intenção e o alinhamento com a imagem.
+- **Saturação** (`voz SATURADA` ou `possível saturação`): a voz bateu no teto e a parte de cima da onda se perdeu.
+  **Não se recupera por inteiro.** Diga isso e não prometa recuperar: dá para suavizar o áspero dos picos, não
+  para desfazer. Baixar o volume não conserta (a saturação fica, só mais baixa). Se a frase saturada importa,
+  pergunte se dá para regravar com o celular mais longe da boca ou o ganho mais baixo. Saturação leve que foi
+  abaixada depois pode sair como `possível` ou nem aparecer: na dúvida, ouça os picos.
+- **Eco de sala** (`eco de sala leve` ou `forte`): a voz continua soando depois que a pessoa para (a saída diz
+  quanto tempo leva para sumir) ou volta repetida alguns ms depois. **Trate leve:** tire um pouco do grave
+  embolado e abaixe só a cauda nas pausas, sem apagar:
+
+  ```bash
+  ffmpeg -i original.mp4 -c:v copy -af "highpass=f=90,equalizer=f=300:t=q:w=1.2:g=-3,agate=threshold=LIMIAR:ratio=2:range=0.3:attack=5:release=150" tratado.mp4
+  ```
+
+  `LIMIAR` fica 25 dB abaixo da voz medida no `noise_check` (voz -16 dB: 10^(-41/20), uns 0.009). Numa sala
+  sintética de 0,70 s essa receita levou a medida para 0,64 s: melhora pouco, e é isso mesmo, porque a sala não sai
+  do arquivo. Porta de ruído forte ou redução pesada apaga a cauda e picota a voz (o fim das palavras some e o
+  fundo liga e desliga): não use. Eco forte que atrapalha entender: diga e sugira regravar num cômodo com cortina,
+  sofá ou tapete.
+- **Amostra com três situações:** um trecho de voz mais fraca, um de voz mais forte e um silêncio. Ponha o
+  original e o tratado um depois do outro, os dois igualados no mesmo volume percebido, para o ouvido não ser
+  enganado pelo mais alto (a receita de eco acima deixou o tratado quase 1 LU mais baixo; sem igualar, ele
+  pareceria pior só por isso):
+
+  ```bash
+  ffmpeg -ss 12 -t 6 -i original.mp4 -vn -ac 1 -ar 48000 -af loudnorm=I=-20:TP=-2 voz_original.wav
+  ffmpeg -ss 12 -t 6 -i tratado.mp4 -vn -ac 1 -ar 48000 -af loudnorm=I=-20:TP=-2 voz_tratado.wav
+  ffmpeg -i voz_original.wav -f lavfi -t 0.7 -i anullsrc=r=48000:cl=mono -i voz_tratado.wav \
+    -filter_complex "[0:a][1:a][2:a]concat=n=3:v=0:a=1" comparar_voz.wav
+  ```
+
+  Depois meça de novo o tratado com `helpers/voz_check.py` e registre as duas medidas.
+- **Saída sem clipping:** pico verdadeiro de -1 dBTP ou menos (`-af ebur128=peak=true`).
+- Se a pessoa pediu para ouvir antes, trate o vídeo inteiro só depois do ok. Se já autorizou, a comparação é
+  conferência sua.
+- Nunca sintetize palavra nem troque a voz. Registre as medidas que fez e o que continuou com problema.
+
+## Legendas checadas no áudio
+
+Antes de entregar, principalmente com nomes, números e termos técnicos.
+
+1. Confronte cada legenda com o áudio. Ouça de verdade os trechos com nome, número, marca e termo técnico.
+2. Glossário: a lista de nomes e termos da pessoa. Use na transcrição (`--prompt` do `transcribe.py`) e nas
+   correções do projeto (`"correcoes"` no `projeto.json`). O roteiro serve para grafia; não substitui o que foi
+   dito.
+3. Corrija erro de reconhecimento e pontuação. Negação, condição, ressalva e número nunca somem.
+4. Palavra que continua duvidosa não se completa como certa: vai para `palavras-duvidosas.md`, com o tempo, o que
+   você ouviu e as opções. Entregue essa lista junto.
+5. Legenda em pedaços de até 3 palavras, numa linha, que se leem naturalmente (o projeto corta assim:
+   `legenda.max_palavras` 3 e `max_letras` por linha). Cada uma aparece e some com a voz; nenhuma fica pendurada
+   no silêncio, e nenhuma pisca (uma palavra solta de 0,1 s): junte com a vizinha.
+6. Confira no formato de entrega: lugar, quebra de linha, tamanho e contraste. A legenda não pode ficar em cima
+   do rosto, das mãos nem do que a pessoa está mostrando. Lettering aprovado fica; sobreposição que não se lê se desfaz.
+7. Prévia focada nas legendas mais compridas ou mais difíceis.
+
+Nunca edite o áudio da fala para ele concordar com o texto.
+
+## Dado pessoal no arquivo exportado
+
+Obrigatório antes de entregar quando o vídeo tem tela gravada, conversa, print, painel, e-mail ou qualquer
+borrão. É a última conferência, no arquivo exportado (o estúdio não serve: é o arquivo que vai para o mundo).
+
+1. Monte a lista do que não pode aparecer, olhando a gravação bruta: nomes de pessoas, de conversas, de
+   projetos e de clientes, loja, endereço, o que a pessoa pediu para esconder. Nome dela e da marca dela,
+   se podem aparecer, vão em `--ignorar`.
+2. Rode no arquivo exportado:
+   `uv run --directory '<SKILL>' python helpers/conferir_dados.py '<PROJ>/renders/final.mp4' --termos 'Maria Souza, Projeto X' --ignorar 'Vitória'`
+   Ele lê pelo OCR todos os quadros até 3 min de vídeo (nos mais longos, 4 por segundo; `--todos` lê todos) e
+   procura os termos, e-mail, CPF, CNPJ, telefone, cartão, @perfil e nome comum com sobrenome. No Mac usa o
+   leitor da Apple; fora dele, o Tesseract, se estiver instalado. Sem leitor, ele diz: aí a conferência é no olho,
+   com a tira de quadros a 30 qps em cada troca de tela.
+3. Cada achado vem com o texto lido, o tempo, os quadros (de e até) e a caixa em pixels. Alargue o borrão
+   (caixa e janela de tempo) ou tire o trecho, renderize e rode de novo até sair `0 achado(s)`. Os vazamentos
+   que já aconteceram: o primeiro quadro (borrão com fade de entrada), um quadro antes de o borrão entrar, uma
+   linha que mudou de lugar no menu, um menu que abre nos últimos 0,15 s.
+4. `possível nome` é palpite (um nome comum seguido de outra palavra com maiúscula): confira se pode aparecer.
+5. Zero achado não prova que não tem dado: o leitor erra letra pequena, borrada, girada ou em movimento. Olhe
+   também o primeiro e o último quadro.
+6. **O que ainda tem o dado fora do vídeo final.** O `borrar` do projeto queima o borrão na cópia do corte do
+   projeto (`assets/cut.mp4`), mas o `<EDIT>/cut.mp4`, as gravações brutas e o original de uma prova com
+   `arquivo` continuam com o dado legível. Se a pasta do projeto vai para alguém (zip, estúdio compartilhado),
+   mande sem a `edit/` e sem esses originais, e rode o `conferir_dados.py` também no `assets/cut.mp4`. Para
+   borrar um arquivo fora do projeto (o corte da `edit`, uma gravação), com o ffmpeg:
+
+   ```bash
+   ffmpeg -i cut.mp4 -filter_complex "[0:v]split[a][t];[t]crop=LARG:ALT:X:Y,boxblur=RL:2:RC:2[b];[a][b]overlay=X:Y:enable='between(t,DE,ATE)'" -c:a copy cut_borrado.mp4
+   ```
+
+   O `split` é obrigatório: usando `[0:v]` duas vezes o ffmpeg não reclama e o borrão não sai (visto no teste).
+   `RL` é no máximo metade do menor lado da caixa e `RC` no máximo um quarto (o `boxblur` recusa mais: numa
+   caixa de 26 px de altura, `boxblur=13:2:6:2`). Várias caixas: repita o trio em cadeia, cada um com o seu
+   `split` (`...overlay=...[v1];[v1]split[a2][t2];[t2]crop=...,boxblur=...[b2];[a2][b2]overlay=...`). Depois,
+   `conferir_dados.py` no `cut_borrado.mp4` também.
+
+Na entrega, diga que rodou a conferência de dados, em quantos quadros, e o que não dá para garantir.
+
+## Triagem dos materiais
+
+Pasta cheia de arquivos e nenhuma certeza do que usar. Nesta etapa não altere nada, não procure, não
+compre e não gere nada.
+
+1. Faça o inventário da pasta (grave no projeto e rode com `python3 inventario.py '<PASTA>'`):
+
+   ```python
+   import hashlib, json, subprocess, sys
+   from pathlib import Path
+   pasta, vistos = Path(sys.argv[1]), {}
+   for arq in sorted(p for p in pasta.rglob("*") if p.is_file() and not p.name.startswith(".")):
+       h = hashlib.sha256()
+       with open(arq, "rb") as f:
+           for bloco in iter(lambda: f.read(1 << 20), b""):
+               h.update(bloco)
+       sha = h.hexdigest()[:12]
+       r = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
+                           "stream=width,height:format=duration", "-of", "json", str(arq)], capture_output=True, text=True)
+       info = json.loads(r.stdout or "{}")
+       s = (info.get("streams") or [{}])[0]
+       tam = f"{s['width']}x{s['height']}" if "width" in s else "sem imagem"
+       dur = info.get("format", {}).get("duration")
+       dup = f"  IGUAL A {vistos[sha]}" if sha in vistos else ""
+       vistos.setdefault(sha, arq.name)
+       print(f"{arq.relative_to(pasta)} · {tam}" + (f" · {float(dur):.1f} s" if dur and float(dur) > 0.1 else "") + dup)
+   ```
+
+2. Confira a fala e olhe cada arquivo. Classifique em quatro tipos, sem misturar:
+   - **prova de verdade:** mostra de fato o que a fala afirma, e é da pessoa;
+   - **demonstração:** mostra como algo funciona;
+   - **inspiração visual:** referência de estilo, não entra no vídeo;
+   - **ilustração:** desenho, imagem de banco ou gerada. Ilustra, nunca prova.
+3. Aponte duplicatas (o inventário acha as iguais; as quase iguais, olhando), baixa resolução (menor que a área que
+   vai ocupar na tela), citação na fala a material que não está na pasta e origem ou direito desconhecido
+   (marcado para conferir; arquivo na pasta não quer dizer direito de uso).
+4. Faltou material: antes de buscar ou gerar, sugira deixar a própria gravação limpa na tela, ou um esquema
+   simples que seja fiel à fala. Buscar ou gerar imagem só com o ok da pessoa, e o que vier é ilustração.
+5. Escreva `materiais.md`: cada arquivo escolhido, a frase que ele sustenta, como vai aparecer e por quê. Depois a
+   lista de lacunas, duplicatas e itens a conferir.
+
+## Comparação justa (antes e depois, ou A e B)
+
+1. Os dois lados mostram a mesma situação? Se não, explique e não monte como confronto direto.
+2. Iguale velocidade, enquadramento, escala e sincronia. Não piore um lado em cor, som ou nitidez.
+3. Rótulos neutros e literais ("Antes", "Depois", "Versão A").
+4. Comparando som, iguale o volume percebido (como na seção Voz). Comparando imagem, nada de texto em cima do
+   detalhe.
+5. Lado a lado ou um depois do outro: o que se lê melhor no formato final.
+6. Se há fala gravada sobre aquilo, é ela que acompanha. Nenhum resultado ou número inventado.
+7. Entregue a amostra e diga o que ela deixa ver e o que ela não comprova.
+
+## Custo, sem inventar
+
+Quando perguntarem quanto saiu, a resposta vem de conta feita, nunca de impressão. Número que você não viu (token,
+crédito, saldo, preço por vídeo) vira "não medi".
+
+Cada gasto tem a sua origem e o seu jeito de conferir. Não some tudo num número só:
+
+| gasto | de onde sai o número |
+|---|---|
+| serviço cobrado por uso (voz sintética, imagem ou vídeo gerado por IA) | o extrato, ou o saldo antes e depois |
+| uso do plano de IA | o painel de uso do plano; sem ele aberto, "não medido" |
+| compra avulsa (música, fonte, banco de imagem) | o recibo |
+| render no Mac | os minutos com a máquina presa: não é de graça, custa tempo |
+| trabalho de gente | as horas anotadas |
+
+Também conta como dado de verdade quanto tempo ficou esperando render e quantas peças passaram. O que for palpite
+aparece com a palavra "estimativa" do lado. Promessa do tipo "economiza 80%" ou "a assinatura dá tantos vídeos
+por mês" não entra.
+
+Um ajuste pedido não libera, sozinho, nada que cobra (API paga, crédito, compra). Se o conserto não sai sem isso,
+explique o motivo, mostre o caminho sem custo que existir e como ela vê o preço antes de gastar. Teto que ela já
+liberou vale até acabar, sem perguntar de novo.
+
+## Entrega de uma revisão
+
+Uma nota curta: os pontos corrigidos, o intervalo que você conferiu de verdade, o que ficou pendente e do que
+depende, o nome da versão nova e a garantia de que a anterior continua intacta.

package/editor/references/som-e-trilha.md

@@ -0,0 +1,146 @@
+# Som e trilha
+
+Dois trabalhos, nesta ordem:
+
+1. **Efeitos sonoros** casados com o que aparece na tela: `helpers/plano_sfx.py`.
+2. **Trilha** contínua por baixo da voz, no fim de tudo: `helpers/mixar_trilha.py`.
+
+Rode os helpers com o Python desta skill (tem numpy): `uv run --directory "<SKILL>" python helpers/<nome>.py`.
+Precisam do ffmpeg. Com o `--directory` o comando roda dentro da pasta da skill: passe cada arquivo com o caminho completo, entre aspas.
+
+## O caminho no projeto (um só)
+
+No projeto-modelo (`<PROJ>`, a cópia do `modelo-projeto`), os sons vão pelo `projeto.json`. Nunca cole tag
+`<audio>` no `index.html`: o build reescreve o arquivo a cada vez.
+
+1. `cd '<PROJ>' && python3 build.py completo`: o vídeo com as animações, **sem trilha**. O build grava
+   `sons_sugeridos.json` com o som que cada animação, zoom, troca de cena e entrada de prova pede, com o tempo do
+   PICO (o quadro em que o movimento bate). As cenas próprias não entram sozinhas: anote o quadro de cada
+   mudança num `<PROJ>/eventos.json` (`[{"t": 12.4, "tipo": "pop"}]`).
+2. `uv run --directory "<SKILL>" python helpers/plano_sfx.py --projeto "<PROJ>"`: lê o `sons_sugeridos.json`
+   (e o `eventos.json`), monta o plano (um som por animação, espaço mínimo de 0,65 s, fica o mais forte), mede a
+   voz no `cut.mp4`, copia os sons para `<PROJ>/assets/sfx` (com `LICENCAS.txt`) e escreve o campo `sons` do
+   `projeto.json`: arquivo, `em` (o pico), `pico_no_arquivo`, `inicio_no_arquivo` (quando o pico vem antes do
+   começo do vídeo, só a cabeça do som sai), `dur`, `volume` e `fade`. Grava também `<PROJ>/plano_sfx.json`.
+3. `python3 build.py completo` de novo: os sons entram no `index.html`, cada um na sua faixa. O estúdio toca
+   todos; confira ali com som. O build nunca descarta um som calado: o que não cabe sai com `aviso:`.
+4. Render: `python3 build.py hf render --quality delivery --output renders/final.mp4`. Os sons já vêm no arquivo.
+5. Corte seco, se precisar (`references/corte-seco.md`). Ele lê o `plano_sfx.json` pra não cortar em cima de
+   um efeito.
+6. Trilha por último, no arquivo renderizado (e já cortado): `helpers/mixar_trilha.py`. Assim a música não pula
+   nas emendas.
+
+Se a trilha entrar antes do corte seco, a música pula em cada emenda e o corte seco deixa de enxergar as pausas.
+
+Mudou uma animação de lugar? Rode o `completo`, o `plano_sfx.py --projeto` e o `completo` de novo: o plano troca
+só os sons que ele mesmo escreveu (`"plano": true`); som escrito à mão no `projeto.json` fica. Com o
+`sons_sugeridos.json` de uma amostra, ele troca só os sons daquele trecho e avisa.
+
+Fora do projeto-modelo (vídeo já pronto, sem HyperFrames): monte o plano com um `eventos.json` e junte os sons
+por cima com `--aplicar` (seção abaixo).
+
+## Efeitos sonoros
+
+### A regra
+
+- **Vídeo com animação**: cada animação que importa ganha o seu som, combinando com o movimento. Pop no pop, whoosh no deslize, impacto no carimbo, ding na notificação. O pico do som cai no quadro em que o movimento bate, nunca na palavra. Não tem teto de quantidade (o André aprovou 23 sons em 56 s): quem tira é o espaço mínimo.
+- **Vídeo sem animação** (só a pessoa falando): uns 5 ou 6 sons no vídeo inteiro de 1 a 1min30. Um na abertura, um no maior número de dinheiro (e no segundo maior, se estiver longe), um em cada grande virada de assunto (no máximo 2) e um na chamada.
+- Nunca som em cada palavra, nem em cada item de lista sem animação.
+- Espaço mínimo de 0,65 s entre dois sons. Se dois caem perto, fica o mais forte.
+- Os pequenos ficam baixinhos. Só os momentos-chave ficam altos.
+
+Tabela completa, níveis e quando **não** pôr som: `references/tabela-de-sons.md`.
+
+### Passo a passo
+
+1. **Liste os eventos visuais** com o tempo do quadro em que cada movimento bate: o pouso do pop (fim do crescimento), o meio do deslize, o impacto do carimbo, o instante em que a notificação aparece. No projeto-modelo, o `sons_sugeridos.json` já faz isso para as peças do catálogo; você só escreve os das cenas próprias. Pegue esse tempo do código da animação (início do movimento + tempo até o pouso), nunca do começo da palavra. Salve em `eventos.json` (modelo em `references/exemplo-eventos.json`):
+
+   ```json
+   [{"t": 1.20, "tipo": "pop"},
+    {"t": 3.40, "tipo": "impacto", "nivel": "destaque"},
+    {"t": 7.64, "tipo": "whoosh-grande", "forcar": true, "nota": "tela cheia vira moldura"}]
+   ```
+
+2. **Monte o plano**:
+
+   ```bash
+   uv run --directory "<SKILL>" python helpers/plano_sfx.py --projeto "<PROJ>"                  # projeto-modelo
+   uv run --directory "<SKILL>" python helpers/plano_sfx.py eventos.json --video final.mp4      # vídeo pronto
+   ```
+
+   Ele lista os sons que ficaram, os que saíram e o motivo, e confere onde o pico caiu. O desvio tem que ficar abaixo de 1 quadro (33 ms a 30 fps). Com `--video` (ou, no `--projeto`, o `cut.mp4` do edit), ele também acerta os níveis pela voz do vídeo.
+
+3. **Coloque os sons**, de um destes jeitos:
+   - **No projeto-modelo**: o `--projeto` já escreveu o campo `sons` do `projeto.json`. Rode `python3 build.py completo` e o render.
+   - **No vídeo pronto**: `--aplicar final.mp4 --video-saida final_sons.mp4`. A voz fica no lugar e o volume final vai pra -14 LUFS.
+
+4. **Guarde o `plano_sfx.json`**. O corte seco usa ele.
+
+Detalhes do plano:
+
+- `--tipos` lista os tipos e os sons de cada um. Apelidos em português funcionam ("aparece", "deslize", "carimbo", "riscar", "moedas").
+- Som específico num evento: `"som": "woven:ID"` (`assets/sfx/woven` desta skill), `"kit:NOME"` (kit de `assets/sfx` desta skill), `"bib:categoria:nome"` (biblioteca de 445 sons CC0 em `~/.editor-video/efeitos`, ex. `bib:impacto:boom`) ou um caminho de arquivo.
+- `"nivel"`: `destaque`, `medio`, `discreto` ou um número em dBFS de pico.
+- `"forcar": true`: o som fica mesmo perto de outro e mesmo passando do máximo. Use em momento-chave e pra disfarçar uma emenda de corte visível.
+- `"dur"`: quanto tempo toca (digitação, aplauso).
+- `--modo motion` (padrão: um som por animação; só o espaço mínimo tira) ou `--modo fala` (sem animação, 1 a cada 15 s). `--max N` põe um teto. `--espaco 0.7` troca o espaço mínimo. `--variar` alterna os sons do mesmo tipo.
+- Mais de um arquivo de eventos: `plano_sfx.py sons_sugeridos.json eventos.json --projeto "<PROJ>"` (sem arquivo, o `--projeto` lê os dois da pasta).
+- O `--html` antigo saiu: ele gravava um `sfx_audio.html` na raiz do projeto (dois erros no lint do estúdio) para colar no `index.html`, que o build reescreve.
+- `--medir SOM` mostra duração, pico e começo de qualquer som.
+
+## Trilha
+
+### A regra
+
+- A trilha fica **22 dB abaixo da voz** (padrão). A faixa boa é de 20 a 24. Com 28 ou mais ela some no celular.
+- Sempre medida contra a voz, em LUFS. Um número de ganho sozinho ("-40 dB") não diz nada, porque depende de quão alta a música veio.
+- A trilha abaixa quando a pessoa fala (duck) e volta nas pausas longas e no final.
+- Entra contínua por cima do vídeo já cortado.
+- "A música sumiu": suba 3 dB (`--abaixo-da-voz 19`). "Tá competindo com a minha voz": desça 3 (`--abaixo-da-voz 25`).
+
+### Passo a passo
+
+```bash
+uv run --directory "<SKILL>" python helpers/mixar_trilha.py --video final_seco.mp4 --trilha musica.wav \
+    --abaixo-da-voz 22 --saida final_trilha.mp4
+```
+
+Opções:
+
+- `--entrada-em 12.0`: a música entra no segundo 12 do vídeo (ex.: quando a pessoa fala "trilha sonora").
+- `--respiro` (ou `--respiro 3`): a música entra mais alta por 2 s (ou 3), 10 dB acima (`--respiro-db`), e depois assenta. Bom na entrada da música.
+- `--duck 8`: quanto ela abaixa na fala, no máximo.
+- `--fade-fim 1.5`: fade no fim. `--inicio-trilha 30`: começa a música do segundo 30 dela.
+- Música mais curta que o vídeo repete sozinha, com crossfade de 1 s.
+
+A resposta traz: quantos dB a trilha ficou abaixo da voz, quanto o duck abaixou, a duração da imagem e do som (têm que bater com a entrada), o desvio da voz (tem que dar 0 ms) e o volume final (-14 LUFS). Os números ficam também em `SAIDA.trilha.json`.
+
+### Onde achar trilha
+
+- Biblioteca de trilhas desta skill em `~/.editor-video/trilhas`, por humor (animada, calma, épica, inspiradora...). Liste e escolha com o `helpers/trilhas.py`. São de uso próprio da pessoa: não redistribua o arquivo.
+- Música que a pessoa mandar: pergunte se ela tem direito de usar em anúncio.
+
+## Como falar com a pessoa
+
+- Antes: "Vou pôr um som em cada animação, baixinho, e os mais fortes só nos momentos importantes. A música fica por baixo da sua voz e abaixa quando você fala."
+- Depois: diga quantos sons entraram, quais momentos têm som forte e quantos dB a música ficou abaixo da voz. Uma linha cada.
+- Ofereça um ajuste por vez: "quer a música um pouco mais alta?", "quer tirar algum som?".
+- Pedido pra tirar um som: apague o evento (ou mude pra `"nivel": "discreto"`) e rode de novo. Não mexa no resto.
+
+## Pegadinhas conhecidas
+
+- **HyperFrames**: quando o `<audio>` tem `data-automation` com lane de volume, o `data-volume` é ignorado. O build não usa lane: o ganho vai no `data-volume` (no máximo 3,98, +12 dB) e as descidas em `data-fade-out`/`data-fade-in`.
+- **HyperFrames**: cada som com o seu `data-track-index`. O build numera.
+- **Som cujo pico vem antes do começo do vídeo** (um clique logo no quadro 0): o build começa o som no 0 e pula a cabeça do arquivo (`data-media-start`), com uma subida de 10 ms. Nunca some.
+- **ffmpeg 8**: o `sidechaincompress` corta a saída quando uma das entradas acaba antes. O `mixar_trilha.py` passa todas as entradas por `apad` e `atrim` na duração exata do vídeo.
+- **Som com vários picos parecidos** (glitch, risco de disco, impacto saturado): o "pico" usado é o começo do trecho mais forte (a 1 dB do máximo). É onde o ouvido sente a batida.
+- **Pico real depois do AAC**: o codificador pode passar do teto em até 2 dB. Os scripts medem depois de gravar e, se passou de -0,5 dBTP, gravam de novo com um limitador leve só nos picos. O volume integrado continua -14 LUFS.
+- **Trilha que já veio mixada no vídeo**: não dá pra tirar. Renderize de novo sem trilha.
+
+## Arquivos
+
+- `helpers/plano_sfx.py`: plano de sons, `--projeto`, `--aplicar`, `--tipos`, `--medir`.
+- `helpers/mixar_trilha.py`: trilha com duck, medida contra a voz.
+- `references/tabela-de-sons.md`: tipo de animação e som, densidade, níveis em dB, quando não pôr som, medidas de cada arquivo.
+- `references/exemplo-eventos.json`: modelo de eventos.
+- `assets/sfx/woven/`: 35 sons do Woven SFX (CC0, domínio público). Licença em `assets/sfx/woven/LICENCA.md`.

package/editor/references/tabela-de-sons.md

@@ -0,0 +1,130 @@
+# Tabela de sons
+
+Níveis em dBFS de **pico de amostra, medido no próprio arquivo**, com a voz do vídeo perto de -14 LUFS. O `plano_sfx.py` usa esses números como padrão e corrige sozinho se a voz do vídeo estiver mais alta ou mais baixa (passe `--video`).
+
+## Tipo de animação e som que combina
+
+| O que acontece na tela | tipo | som padrão | nível |
+|---|---|---|---|
+| Texto, ícone, cartão ou balão aparece | `pop` | woven:pop-hand | -18,5 |
+| Algo desliza, entra ou sai rápido | `whoosh` | woven:fast-whoosh | -17,5 |
+| Troca grande: tela cheia vira moldura, câmera gira, painel entra | `whoosh-grande` | woven:swish-whoosh-large | -12,5 |
+| Palavra grande, número final ou carimbo pousa com força (com tremida) | `impacto` | woven:bass-impact | -11,5 |
+| A grande revelação: logo, produto, placa final | `revelacao` | woven:base-drop | -11,5 |
+| Item que empilha ou encaixa, sem drama | `batida` | woven:dull-thud | -14,5 |
+| Algo riscado, cancelado, negado | `risco` | woven:record-needle-scratch | -12 |
+| Notificação, venda que cai, celular recebendo | `notificacao` | woven:notification-ding | -12,5 |
+| Balão de conversa, botão final, resposta | `mensagem` | woven:message-pop-reply | -15,5 |
+| Tela liga, IA entra, falha digital | `glitch` | woven:glitch-logo | -13,5 |
+| Cursor clica, dedo toca no botão | `clique` | woven:mouse-click-2 | -18 |
+| Texto sendo digitado (passe `"dur"`) | `digitar` | woven:keyboard-typing-realistic | -22 |
+| Check, item marcado, contagem | `tique` | woven:tick-sound | -19 |
+| Bipe de interface | `beep` | woven:beep-short | -19 |
+| Moedas, preço que aparece | `dinheiro` | woven:several-coins | -15 |
+| Print, foto, captura de tela | `camera` | woven:camera-shutter-1-shot | -15 |
+| Suspense que cresce até a revelação (o pico é o fim da subida) | `subida` | kit:rise | -15 |
+| Deu certo, meta batida | `sucesso` | kit:success | -15 |
+| Errado, o que não fazer | `erro` | kit:error | -15 |
+| Reação de espanto (usar pouco) | `surpresa` | woven:female-gasp | -17 |
+| Conquista, fim de história (usar pouco) | `aplauso` | woven:cheers-and-applause | -22 |
+
+Níveis prontos pra usar no evento: `destaque` -12, `medio` -15, `discreto` -18, `baixo` -20.
+
+Onde o som alinha: quase todos alinham o **pico** no tempo do evento. `digitar` e `aplauso` alinham o **começo** do som. Sons do kit desta skill e da biblioteca usam o ponto forte que já vem anotado no índice deles (`anchor_s`).
+
+Cauda: cada som toca até 0,8 s depois do pico (0,3 s na `subida`, 1,2 s na `revelacao`, 2 s no `aplauso`) e sai com fade. Assim a cauda de um impacto não passa por cima da fala.
+
+## Densidade
+
+- **Com animação**: um som por animação que importa. Referência aprovada: IMG_1498 v2, 23 sons em 56 s ("gostei"). O teto do script é 1 som a cada 2 s (`--modo motion`).
+- **Sem animação**: 5 ou 6 sons num vídeo de 1 a 1min30 (`--modo fala`, 1 a cada 15 s). Abertura, maior número de dinheiro, até 2 viradas de assunto, chamada.
+- Espaço mínimo de 0,65 s entre picos. Se dois caem perto, fica o mais forte. Os forçados (`"forcar": true`) sempre ficam.
+- Passou do máximo: saem os mais fracos primeiro.
+- Momento em nível `destaque`: no máximo um a cada 6 ou 8 s. Se tudo é destaque, nada é.
+
+## Volumes em dB
+
+| O quê | Valor |
+|---|---|
+| Voz (referência) | -14 LUFS integrado |
+| Efeito em momento-chave | pico -11 a -13 dBFS |
+| Efeito médio | pico -15 dBFS |
+| Efeito pequeno (pop, clique, tique) | pico -17 a -19 dBFS |
+| Som contínuo (digitação) | pico -22 dBFS |
+| Trilha | 22 dB abaixo da voz (faixa boa 20 a 24) |
+| Duck da trilha na fala | até 8 dB |
+| Respiro da trilha na entrada | +10 dB por 2 s |
+| Final do vídeo | -14 LUFS, pico real até -1 dBTP |
+
+De onde vêm esses números:
+
+- IMG_1498 v2 (aprovado): no código os sons estavam marcados de -10 a -17, mas medidos no arquivo de verdade eles ficaram uns 3 dB abaixo disso, com a voz em -15,5 LUFS. Trazendo pra voz em -14, dá os valores da tabela.
+- Reel "uma IA editou": trilha uns 24 dB abaixo da voz, com sidechain, mixada no pós. Uma tentativa 28,5 dB abaixo ficou praticamente inaudível no celular.
+- IMG_1527: trilha com ganho 0.14 (uns -17 dB) e 0.07 competiu com a voz. O que conta é a distância até a voz, medida em LUFS.
+- DJI_0033: trilha uns 30 dB abaixo da voz, com respiro de 11 dB na entrada. Pelo que se viu no reel, 28 dB ou mais já some no celular. Por isso o padrão aqui é 22, com a faixa de 20 a 24.
+
+## Quando NÃO pôr som
+
+- Em cada palavra, ou em cada item de lista que não tem animação.
+- Na legenda palavra por palavra (ela anda o tempo todo).
+- Em movimento contínuo e lento: zoom devagar, câmera flutuando, fundo girando.
+- Duas animações a menos de 0,65 s: um som só, o mais forte.
+- Em cima de uma palavra importante dita baixinho: o som cobre a palavra. Adiante o evento pra logo antes dela ou empurre pra logo depois.
+- Em frase emotiva ou história séria. Silêncio também é direção.
+- Sons de humor (sapo, espanto, aplauso) em vídeo sério ou de oferta cara.
+- `subida` (riser) só antes de uma revelação de verdade, no máximo 1 ou 2 por vídeo.
+- Vídeo sem animação: nada de som por enfeite. Siga os 5 ou 6 momentos.
+
+## Uso extra: disfarçar emenda
+
+Onde uma emenda de corte ficou visível (tomada errada tirada, pulo de imagem), um `whoosh` ou `pop` forçado em cima da emenda disfarça. Use `"forcar": true`.
+
+## Medidas dos arquivos
+
+Medido com `plano_sfx.py --medir`. Duração em segundos, "pico" é o ponto forte (começo do trecho a 1 dB do máximo), nível em dBFS.
+
+| som | duração | pico (s) | nível |
+|---|---|---|---|
+| woven:airplane-ding | 1,18 | 0,168 | 0,0 |
+| woven:applause | 12,91 | 0,503 | 0,0 |
+| woven:base-drop | 3,30 | 0,053 | -6,6 |
+| woven:bass-impact | 2,46 | 0,069 | 0,0 |
+| woven:beep-short | 0,70 | 0,026 | -12,0 |
+| woven:camera-analog | 0,86 | 0,069 | -1,3 |
+| woven:camera-flash | 6,46 | 0,310 | -0,1 |
+| woven:camera-shutter-1-shot | 0,28 | 0,105 | -1,5 |
+| woven:camera-shutter-8-shots | 1,11 | 0,114 | -0,3 |
+| woven:camera-shutter-release | 0,58 | 0,051 | -2,6 |
+| woven:cheers-and-applause | 4,09 | 0,251 | -1,4 |
+| woven:deep-whoosh | 3,23 | 0,516 | -2,2 |
+| woven:dj-scratch | 1,56 | 0,164 | -3,2 |
+| woven:dull-thud | 1,39 | 0,038 | -2,6 |
+| woven:elevator-ding | 2,00 | 0,003 | -2,9 |
+| woven:explosion | 3,18 | 0,087 | -0,1 |
+| woven:fast-whoosh | 0,39 | 0,112 | -8,1 |
+| woven:female-gasp | 0,49 | 0,106 | -7,4 |
+| woven:frog-ribbit | 0,70 | 0,126 | -1,4 |
+| woven:glitch-logo | 0,63 | 0,141 | -7,2 |
+| woven:keyboard-typing-realistic | 3,39 | 1,802 | -2,8 |
+| woven:keyboard-typing | 10,29 | 5,792 | -0,1 |
+| woven:male-gasp | 0,46 | 0,212 | -5,0 |
+| woven:message-pop-reply | 0,88 | 0,038 | -0,1 |
+| woven:money-chalking | 1,86 | 0,090 | -7,9 |
+| woven:mouse-click-1 | 0,77 | 0,361 | -1,2 |
+| woven:mouse-click-2 | 0,19 | 0,146 | -3,3 |
+| woven:notification-ding | 2,00 | 0,064 | -9,0 |
+| woven:pop-hand | 0,35 | 0,026 | -2,2 |
+| woven:record-needle-scratch | 1,65 | 0,237 | 0,0 |
+| woven:record-scratch | 1,28 | 0,482 | -1,7 |
+| woven:several-coins | 1,42 | 0,029 | -0,4 |
+| woven:sideways-record-needle | 0,58 | 0,435 | -0,6 |
+| woven:swish-whoosh-large | 0,79 | 0,134 | 0,0 |
+| woven:tick-sound | 0,56 | 0,028 | -10,4 |
+
+Kit desta skill (ponto forte do índice `assets/sfx/sfx.json`): `kit:pop` 0,003 s, `kit:whoosh` 0,15 s, `kit:rise` 1,228 s, `kit:metal_riser` 1,654 s, `kit:success` 0,023 s, `kit:error` 0,188 s, `kit:bass_drop` 0,016 s, `kit:metal_hit` 0,164 s, `kit:notification` 0,008 s, `kit:cash` 0,07 s, `kit:keyboard` 0,111 s, `kit:mouse_click` 0 s, `kit:tick` 0 s, `kit:data` 0,025 s.
+
+## Onde cada som mora
+
+- `woven:ID`: `assets/sfx/woven/ID.wav` desta skill (35 sons, CC0).
+- `kit:NOME`: `assets/sfx/` desta skill (índice `sfx.json`). Outra pasta: variável `SC_KIT_SFX`.
+- `bib:...`: `~/.editor-video/efeitos/` (índice `efeitos.json`, 445 sons CC0 por categoria: transicao, impacto, revelacao, interface, tecnologia, sucesso, erro, humor). Outra pasta: variável `SC_BIBLIOTECA_SFX` (ou `EDITOR_VIDEO_EFEITOS`). `bib:categoria` pega uma versão diferente a cada uso.