primocode 10.16.0 → 10.17.1

package/editor/references/corte-seco-como-funciona.md

@@ -0,0 +1,50 @@
+# Como o corte seco decide cada corte
+
+## 1. Achar as pausas
+
+- Envelope do som em janelas de 10 ms. Com `--voz`, mede no áudio só da voz. Sem ele, no áudio do próprio vídeo.
+- Limiar de silêncio: 30 dB abaixo da fala (percentil 90 do envelope), e pelo menos 10 dB acima do fundo (percentil 5). `--limiar` força outro valor.
+- Pausa é um trecho abaixo do limiar com pelo menos `--pausa-min` (0,25 s). A pausa depois da última fala fica intacta, porque ali costuma estar o cartão final.
+- Se a fala e o fundo estão a menos de 40 dB de distância, o script avisa. Quase sempre é trilha já mixada.
+
+## 2. Onde o corte pode cair dentro da pausa
+
+- Folga de 0,06 s depois do fim da palavra e 0,07 s antes da próxima (bordas no limiar).
+- Consoante fraca no começo da próxima palavra: a borda anda pra trás até 0,12 s enquanto o som ainda estiver acima do "som fraco" (12 dB abaixo do limiar, ou 6 dB acima do fundo, o que for maior). Esse trecho fica protegido, com mais 0,04 s de folga.
+- Quanto sai: a pausa menos `--pausa-max` (0,15 s), arredondado pra quadro inteiro. Se não couber entre as folgas, sai menos.
+- Começo do vídeo: sai tudo até 0,08 s (`--inicio`) antes da primeira palavra.
+- Trava final: se o trecho escolhido tiver qualquer janela de voz acima do limiar, o corte é descartado.
+
+## 3. Não cortar no ataque de efeito sonoro
+
+- Com `--sfx`: cada som do plano protege do começo do som (ou 0,3 s antes do pico, o que vier depois) até 0,06 s depois do pico. Aceita o `plano_sfx.json` do `helpers/plano_sfx.py`, uma lista de eventos (`t`) ou uma lista com `peak`.
+- Com `--voz`: onde o vídeo tem som acima do limiar e a voz não tem, é efeito. O começo desse som (até 0,10 s) fica protegido.
+- Se o melhor lugar pega um ataque, o corte encolhe um quadro por vez até sair de cima. Se não der, a pausa fica e aparece no relatório.
+
+## 4. Qual quadro escolher
+
+Entre as posições possíveis, fica a de menor mudança de imagem: soma da diferença entre quadros vizinhos no trecho que sai (imagem em 96 px, cinza). Com `--sem-grafismo`, mede só nos grafismos. Assim o pulo cai com os grafismos parados e a pessoa fica sendo a única coisa que "salta", o que parece um corte normal. Empate: fica a posição mais no meio da pausa.
+
+## 5. Montar o vídeo
+
+- Imagem: `select` pelos números dos quadros que ficam, `setpts` refeito, x264 CRF 16 (`slow` até 3 min, `medium` acima). Um decodificador só, exato no quadro.
+- Som: cortado em numpy nas mesmas posições (amostra = quadro × taxa ÷ fps), com micro fade de 8 ms em cada emenda.
+- Volume: -14 LUFS em 2 passadas, sempre linear. Se o pico real passar do teto, entra um limitador com atraso compensado (não desloca o som). Depois do AAC o pico é medido de novo; se passou de -0,5 dBTP, grava outra vez com o teto mais baixo.
+
+## 6. Conferência automática
+
+- Duração da imagem e do som contra a soma dos trechos mantidos.
+- Cada quadro da saída contra o quadro esperado da entrada e os vizinhos (±2). Um deslocamento de 1 quadro já aparece aqui: no teste, 2 trechos deslocados de propósito derrubaram a conta de 1657 pra 1615 quadros e o som pra 33 ms de desvio.
+- Cada trecho de som com mais de 0,7 s contra a entrada, por correlação.
+- Pausas acima de `--pausa-max` + 0,07 s que ficaram na saída.
+
+## Campos do relatório (`SAIDA.corte.json`)
+
+- `cortes`: `pausa` (começo e fim na entrada), `removido` (o que saiu), `dur`, `sobra` (silêncio que ficou), `imagem` (quanto a imagem mudava no trecho), `forcado` nos pedidos por `--cortar`.
+- `mantidas`: pausas que ficaram e o motivo.
+- `mapa`: `[início na entrada, fim na entrada, início na saída]` de cada trecho. Tempo novo = início na saída + (tempo antigo - início na entrada), pro trecho que contém o tempo antigo.
+- `conferencia`: os números do item 6.
+
+## Resultado de referência
+
+Reel "uma IA editou" (59,73 s, 30 fps, 47 efeitos, com `--voz`, `--sfx`, `--sem-grafismo` e a tomada repetida em `--cortar`): 19 pausas cortadas + 1 corte pedido, 4,5 s fora, saída 55,23 s. Imagem e som batendo com a entrada, 1657 de 1657 quadros no lugar, desvio de som 0,1 ms, -14 LUFS.

package/editor/references/corte-seco.md

@@ -0,0 +1,88 @@
+# Corte seco
+
+O vídeo já está pronto e aprovado, mas ficou espaço entre uma fala e outra. Este passo corta o vídeo final inteiro (imagem e som no mesmo quadro), então legenda, animação e efeito continuam grudados na fala. Em cada pausa maior que 0,25 s sobra só 0,15 s de silêncio, e o vídeo começa quase em cima da primeira palavra.
+
+É mais barato e mais seguro do que voltar, re-cortar e renderizar tudo de novo. Foi assim no reel "uma IA editou este vídeo", aprovado pelo André.
+
+## Quando usar aqui e quando voltar pro corte (Fase 1)
+
+| Situação | Onde resolver |
+|---|---|
+| Vídeo pronto e aprovado, pausas de 0,25 a 1 s entre as frases | **Aqui** |
+| A pessoa pediu "mais ritmo" depois de ver o vídeo final | **Aqui** |
+| Uma tomada repetida curta que passou (até ~1 s) e não tem animação em cima | **Aqui**, com `--cortar` |
+| O corte ainda não foi aprovado, ou ainda não tem animação | **Corte (Fase 1)**: re-corte lá. Sai mais barato e a legenda já nasce certa |
+| Palavra comida, respiro no meio da frase, barulho, tomada repetida grande | **Corte (Fase 1)** (`bordas_precisas.py`, `conferir_corte.py`). É problema do corte de base |
+| Quase toda frase tem pausa de mais de 1 s | **Corte (Fase 1)**: o corte de base está frouxo. Refaça lá |
+| Uma animação longa atravessa a pausa (câmera girando, contagem, gráfico subindo) | **Corte (Fase 1)** e renderize de novo. Aqui a animação daria um pulo. Ou aceite essa pausa |
+| Tirar mais de ~1 s num lugar com legenda ou animação em cima (frase inteira) | **Corte (Fase 1)** e remapeie os tempos (`remap_edit_data.py`). Aqui a legenda pularia |
+| A trilha já está mixada no vídeo e não dá pra renderizar sem ela | **Corte (Fase 1)**. Com música por baixo não dá pra achar as pausas direito |
+
+Regra do André pra pausa: o alvo é 0,12 a 0,20 s de silêncio na emenda. A partir de 0,25 s já incomoda. Nunca cortar a pessoa no meio da palavra, e nunca esticar trecho.
+
+## Antes de rodar
+
+1. **Vídeo sem trilha.** A trilha entra depois do corte seco (`references/som-e-trilha.md`). Se o vídeo já tem música, renderize de novo sem ela. O script avisa quando o fundo está alto demais.
+2. **Plano de sons** (`plano_sfx.json` do `helpers/plano_sfx.py`, em `references/som-e-trilha.md`), se os efeitos entraram por ele. Protege o ataque de cada efeito.
+3. **Áudio só da voz** no mesmo tempo do vídeo, se tiver: o `cut.mp4` do corte (Fase 1) quando o vídeo final começa no zero do corte. Com ele as pausas são medidas na voz limpa, e o ataque de qualquer som que não é voz fica protegido.
+4. **Render só com grafismo** (opcional, bom em vídeo com muita animação): o mesmo projeto renderizado sem a pessoa, com a mesma duração. No HyperFrames, esconda os vídeos da pessoa com CSS (`video{visibility:hidden!important}`) e renderize de novo. Com ele o corte cai onde os grafismos estão parados. Sem ele, o script usa a diferença entre quadros do próprio vídeo.
+
+## Rodar
+
+Com o `--directory` o comando roda dentro da pasta da skill: passe cada arquivo com o caminho completo, entre aspas.
+
+```bash
+# 1) só o plano, sem renderizar (confira o que vai sair)
+uv run --directory "<SKILL>" python helpers/corte_seco.py final.mp4 --sfx plano_sfx.json --voz edit/cut.mp4 --so-plano
+# 2) valendo
+uv run --directory "<SKILL>" python helpers/corte_seco.py final.mp4 --pausa-max 0.15 --sfx plano_sfx.json \
+    --voz edit/cut.mp4 --sem-grafismo final_so_grafismo.mp4 --saida final_seco.mp4
+```
+
+Opções:
+
+- `--pausa-max 0.15`: silêncio que fica entre as frases. Suba pra 0.20 se ficar corrido demais.
+- `--pausa-min 0.25`: só mexe em pausas a partir disso.
+- `--inicio 0.08`: silêncio antes da primeira palavra.
+- `--cortar 41.06-41.76,50.2-51.0`: trechos que saem de qualquer jeito (tempos do vídeo de entrada). Para tomada repetida escondida: a transcrição às vezes junta duas tomadas numa palavra só (palavra longa demais, duas rajadas de voz com silêncio no meio). Ache os tempos na onda, corte a primeira tomada e deixe a última.
+- `--limiar -42`: força o nível de silêncio (o padrão é medido no vídeo: 30 dB abaixo da fala).
+- `--crf 16`: qualidade da imagem.
+
+O vídeo de entrada nunca é alterado. A saída padrão é `<video>_seco.mp4`.
+
+## Ler o resultado
+
+O script mostra cada pausa cortada (quanto saiu, quanto sobrou) e as pausas que ficaram, com o motivo. No fim ele confere tudo sozinho:
+
+- **duração** da imagem e do som, que têm que bater com o esperado;
+- **imagem**: cada quadro da saída comparado com o quadro certo da entrada ("1657 de 1657 quadros no lugar certo");
+- **som**: cada trecho comparado com a entrada ("desvio máximo 0,1 ms"). Acima de 5 ms é voz escorregando: não entregue;
+- **volume**: -14 LUFS, pico real até -1 dBTP;
+- **pausas que sobraram** acima de 0,22 s: em geral são pausas com efeito sonoro no meio ou consoante fraca na borda.
+
+Se aparecer "ATENÇÃO", leia o aviso e não entregue sem conferir.
+
+O relatório `SAIDA.corte.json` tem os cortes e o **mapa de tempo** (`mapa`: início na entrada, fim na entrada, início na saída), pra converter qualquer tempo do vídeo antigo pro novo.
+
+## Depois
+
+- Assista aos trechos que o script marcou como pausa mantida e a 2 ou 3 emendas. Mande à pessoa só o vídeo, com uma linha: "tirei X pausas, o vídeo foi de A pra B segundos".
+- Trilha agora: `references/som-e-trilha.md`, `helpers/mixar_trilha.py` no vídeo seco.
+- Se alguma emenda ficou visível (pulo de imagem), um whoosh ou pop forçado em cima disfarça (`plano_sfx.py` com `"forcar": true` e `--aplicar`).
+
+## Como falar com a pessoa
+
+- "Vou tirar os espaços que ficaram entre as frases, deixando só um respiro curtinho. A legenda e as animações continuam no lugar."
+- Se ela achar corrido demais: `--pausa-max 0.20`. Se achar que ainda sobrou espaço: confira no relatório as pausas mantidas e o motivo antes de apertar mais.
+- Se a pausa que incomoda está no meio de uma animação longa, explique em uma frase e ofereça as duas saídas: deixar essa pausa ou re-cortar e renderizar de novo.
+
+## Pegadinhas conhecidas
+
+- **Trilha antes do corte**: a música pula em cada emenda e as pausas somem no meio dela. Sempre corte seco primeiro, trilha depois.
+- **Consoante fraca no começo da palavra** ("S" de "Só", "F"): o limiar pega a vogal e morderia a consoante. O script anda até 0,12 s pra trás enquanto ainda tem som fraco e protege esse trecho.
+- **Micro pausa dentro da frase** (menos de 0,25 s): não mexe. Cortar ali come consoante.
+- **Cauda de efeito sonoro** pode ser cortada (a emenda tem micro fade de 8 ms). O **ataque** nunca.
+- **Tomada repetida escondida**: palavra longa demais na transcrição ou uma rajada de voz com uma palavra só. Ouça antes de entregar e use `--cortar`.
+- O áudio é cortado por amostra e a imagem por quadro, nos mesmos instantes. Por isso a voz não escorrega, mesmo com dezenas de cortes.
+
+Como o script decide cada corte, em detalhe: `references/corte-seco-como-funciona.md`.

package/editor/references/corte.md

@@ -0,0 +1,290 @@
+# O corte
+
+O corte é a base de tudo: se ele muda, os tempos da legenda, das animações e dos sons mudam junto. Por isso
+ele vem primeiro e é revisto no estúdio antes de qualquer animação.
+
+A regra de pausa é a do André, e vale para todo vídeo falado curto (anúncio, Reels, VSL):
+- **Respiro é erro.** Nenhum silêncio de 0,25 s ou mais pode sobrar, nem entre frases nem dentro de um
+  trecho. A emenda fica com uns 0,12 s de silêncio.
+- **A tomada certa é a inteira e mais limpa**, quase sempre a última. A que para no meio, repete palavra
+  ("eu eu"), termina em "..." ou muda de ideia sai.
+- **Não corte a pessoa no meio.** Fechar o respiro não é comer o fim da palavra: o S de "demais", o E de
+  "YouTube" e a sílaba final ficam.
+- **Barulho na pausa sai junto** (cachorro, estalo de boca, respiração forte).
+- **Nunca emende criando frase que ninguém disse**, nem tire uma ressalva ou condição ("só se", "não é
+  pra todo mundo"). Em conversa, não troque a ordem das falas para fabricar uma afirmação.
+- Aula longa e tutorial podem guardar um respiro curto onde ajuda a entender. Pergunte no briefing.
+
+## 1. Transcrever
+
+```
+uv run --directory '<SKILL>' python helpers/transcribe_batch.py '<VIDEOS>' --prompt 'Hubla, Kiwify, Cakto'
+uv run --directory '<SKILL>' python helpers/pack_transcripts.py --edit-dir '<EDIT>'
+```
+
+- `--prompt` leva só os nomes de marca, produto e plataforma do briefing, separados por vírgula. Sem ele o
+  Whisper escreve "Cacto" em vez de Cakto e "Kiwi-Fi" em vez de Kiwify.
+- Na primeira vez baixa o modelo de voz (cerca de 1,6 GB): avise que leva alguns minutos. Depois fica em
+  cache (uns 3 s por minuto de áudio num Mac M; bem mais lento no Windows).
+- Se um arquivo falhar, os outros seguem. Conte qual falhou e por quê.
+- Dois vídeos com o mesmo nome (`video.mov` e `video.mp4`): nada é transcrito. Peça para renomear um.
+- **Arquivo só no iCloud** (Mac com "Otimizar armazenamento"; comum em Mesa e Documentos): o `ffmpeg` fica parado
+  minutos sem erro nele. O `transcribe_batch.py` confere a pasta antes de abrir qualquer vídeo, pede o download
+  ao macOS (`brctl download`) e espera um pouco; se não chegar, para com `só no iCloud` e nada é transcrito.
+  Peça para a pessoa baixar (no Finder, botão direito > Baixar Agora) ou copiar os vídeos para fora do iCloud,
+  e rode de novo. Para conferir qualquer pasta antes:
+  `uv run --directory '<SKILL>' python helpers/icloud.py '<VIDEOS>'`.
+- **`AVISO: só N palavra(s) para X s de voz`**: o Whisper devolveu o prompt ("E aí, olha só, sabe?") ou pulou
+  a fala. Acontece com trecho copiado de um vídeo maior que começa no meio de uma frase. Trecho copiado
+  começa numa pausa, antes da primeira palavra de uma frase: copie de novo e transcreva. Se não for isso, rode
+  `transcribe.py '<VIDEO>' --edit-dir '<EDIT>' --no-prompt --force`. Nunca escolha frases de uma transcrição
+  com esse aviso.
+
+**Ruído de fundo.** Logo depois, meça:
+`uv run --directory '<SKILL>' python helpers/noise_check.py '<VIDEOS>'`
+Se sair `ruído leve` ou `ruído forte` em algum vídeo, conte em uma frase e ofereça a limpeza (Leve ou Forte).
+Anote no `project.md`. A limpeza não muda o corte.
+Na mesma saída vem uma linha `Voz` por vídeo (`helpers/voz_check.py`): `voz SATURADA`, `possível saturação`,
+`eco de sala leve` ou `eco de sala forte`. É medida, não escuta: ouça os tempos citados antes de afirmar, conte
+em uma frase e anote no `project.md`. O que fazer com cada um está em `references/revisao.md`, seção Voz.
+Saturação não volta: se a frase saturada importa, pergunte se dá para regravar.
+
+## 2. Ler, olhar e escolher as frases
+
+Leia `<EDIT>/takes_packed.md` (nunca os `transcripts/*.json`).
+
+**Olhe cada vídeo** em 3 quadros (10%, 50% e 90% da duração):
+`uv run --directory '<SKILL>' python helpers/contact_sheet.py '<VIDEOS>/IMG_5262.mov' --times 3.4 17 31 -o '<EDIT>/verify/fonte_IMG_5262.png'`
+Procure legenda ou título já gravado na imagem (pergunte se quer a legenda da skill mesmo assim) e dado
+pessoal na tela que precise de borrão (e-mail, CPF, telefone, cartão, conversa de outra pessoa). Anote.
+
+**Roteiro.** Se a pessoa mandou o roteiro, ele serve para conferir palavras e a ordem, nunca para tirar
+tempo. Improviso sem erro fica. Roteiro (ou um índice de arquivos) e fala discordam ("no editor" no roteiro,
+"num editor" na gravação): **a fala gravada vence**. O `quote`, a legenda e o texto na tela escrevem o que
+foi dito; na dúvida entre o Whisper e o ouvido, ouça o trecho e anote em `palavras-duvidosas.md`.
+
+**Tomadas repetidas.** Transcrever o arquivo inteiro junta tomadas ("Foi assim que nós... Foi assim que
+nosso"). Na dúvida, veja em pedaços menores:
+`uv run --directory '<SKILL>' python helpers/pack_transcripts.py --edit-dir '<EDIT>' --silence 0.2 -o '<EDIT>/takes_fino.md'`
+Palavra longa demais (uma palavra de 1,5 s) ou uma rajada de voz com uma palavra só é tomada repetida
+escondida: ouça antes de decidir.
+
+**A ordem** segue a história, não a gravação:
+- Anúncio direto: GANCHO (0 a 3 s) → PROBLEMA → VIRADA → PROVA → CHAMADA.
+- Tutorial: GANCHO → PASSO 1 → PASSO 2 → PASSO 3 → RESULTADO → CHAMADA.
+- Depoimento ou UGC: GANCHO → CONTEXTO → EXPERIÊNCIA → RECOMENDAÇÃO → CHAMADA.
+- Gancho e corpo gravados em arquivos diferentes (lote de ganchos): um gancho + o corpo inteiro.
+Anúncio vertical rende bem entre 20 e 45 s. Sobrou material bom? Proponha versão curta e longa.
+
+**Conte a estratégia** em 3 a 6 linhas: as partes em ordem, com a frase de cada uma entre aspas, o que sai e
+por quê, e a duração estimada. Espere o sim só se a pessoa pediu para aprovar antes ou se você vai tirar algo
+que muda o sentido. Senão, siga e mostre no estúdio.
+
+## 3. O edl_manual.json: uma frase por trecho
+
+Escreva `<EDIT>/edl_manual.json`, com um trecho por frase (ou por pedaço de frase quando a tomada tem erro
+no meio), já na ordem final:
+
+```json
+{
+  "version": 1,
+  "sources": {"H01": "/caminho/absoluto/H01.MP4", "B02": "/caminho/absoluto/B02.MP4"},
+  "output": {"format": "vertical", "width": 1080, "height": 1920},
+  "grade": "",
+  "jcut": {"lead_frames": 4, "tail_trim_frames": 2},
+  "ranges": [
+    {"id": "m01", "source": "H01", "start": 3.7, "end": 6.0, "beat": "GANCHO",
+     "quote": "Esse é o fim dos editores de vídeo.", "reason": "última tomada inteira", "gain_db": 0},
+    {"id": "m02", "source": "B02", "start": 1.1, "end": 3.75, "beat": "PROBLEMA",
+     "quote": "Sabe a pior parte de ter editor?", "reason": "última tomada", "gain_db": 0}
+  ]
+}
+```
+
+- A chave de `sources` é o nome do arquivo sem extensão. Caminho absoluto.
+- `start` um pouco antes da primeira palavra e `end` um pouco depois da última (0,1 a 0,3 s de folga em
+  silêncio). Nunca deixe a folga entrar na tomada de antes ou de depois: o corte pela onda aperta o resto.
+- Retomada colada ("…profissional… Que") : comece e termine no vale da onda, nunca pegue o pedaço da
+  tomada anterior grudado no começo da nova. Na dúvida, veja no `timeline_view.py`:
+  `uv run --directory '<SKILL>' python helpers/timeline_view.py '<VIDEOS>/IMG_5262.mov' 7.5 13`
+- `"dry": false` num trecho que não pode ser partido nos respiros: vídeo tocando na tela, som saindo da
+  caixinha do celular, música que faz parte da cena. As bordas dele ficam exatamente como você escreveu: o
+  corte pela onda não mexe e o render não faz J-cut nele. O silêncio de dentro dele aparece na conferência como
+  `fica:` e não conta como respiro.
+- Tempo de leitura no fim (a última palavra é a conclusão e o texto precisa ficar na tela): use o
+  `segura_fim` do `projeto.json` (`modelo-projeto/LEIA.md`), não um trecho `dry: false` sem fala.
+- `beat` e `quote` aparecem nos relatórios: capriche. `gain_db` acerta o volume do trecho (passo 5).
+- Vídeo deitado num corte em pé (ou o contrário): o render enquadra pelo rosto. Se errar, ponha `"focus_x"`
+  (0 = esquerda, 1 = direita) ou `"focus_y"` no trecho.
+- `grade` fica "" por padrão. Cor lavada ou escura: compare antes (`helpers/grade.py --candidates`).
+- Conversa gravada com duas câmeras, ou com lapela: `"imagem_de": "CAM2"` no trecho mantém a voz da `source` e
+  tira a imagem da CAM2 no mesmo instante. Veja "Várias câmeras", no fim.
+
+## 4. Corte pela onda
+
+```
+uv run --directory '<SKILL>' python helpers/corte_por_onda.py '<EDIT>/edl_manual.json' -o '<EDIT>/edl.json'
+```
+
+Ele mede cada fonte na onda (volume em janelas de 10 ms, guardado em `regions/onda_<nome>.npy`) e, em cada
+trecho: começa 0,06 s antes do primeiro som de verdade (estalo de boca antes da frase não conta), recua se
+tiver consoante fraca no começo, parte o trecho em todo respiro de 0,22 s ou mais deixando 0,06 s de cada
+lado, apara o silêncio do fim (qualquer tamanho) para 0,06 s, estica o fim enquanto uma consoante fraca
+ainda soa e joga fora sobra de respiração ou estalo. O fim de um trecho nunca passa do começo do próximo trecho
+da mesma fonte (senão o mesmo som toca duas vezes). O limiar de pausa sai do chão de ruído de cada fonte; a
+primeira linha da saída mostra quanto ficou. Trecho `dry: false` sai como `inteiro: ... bordas como escritas`.
+
+Leia a saída:
+- `aviso: ... está em cima de fala; pode cortar palavra`: a borda que você escreveu no `edl_manual.json` cai
+  no meio de uma palavra. Mova para a pausa mais perto (termine a palavra ou tire a palavra inteira) e rode
+  de novo.
+- Sobrou respiro (a conferência do passo 6 mostra): rode com `--limiar` uns 3 dB mais alto que o da saída
+  (ex.: de -38 para `--limiar -35`) ou parta o trecho ali no `edl_manual.json`. Se ainda sobrar, vá até o limiar
+  que o `respiros.py` mede (em geral -29): ele é o juiz do portão, então um corte que fecha mais baixo que ele
+  deixa respiro que o portão reprova.
+- Mic baixo (gravação do OBS, lapela longe) pode comer fim de palavra fraca. Se a conferência mostrar palavra
+  mordida, rode com `--limiar` uns 4 dB mais baixo que o da saída (ex.: `--limiar -44`).
+- Nunca edite o `edl.json` à mão: ele é refeito a cada rodada. Mudanças vão no `edl_manual.json`.
+
+## 5. Volume da voz
+
+`uv run --directory '<SKILL>' python helpers/voice_levels.py --edl '<EDIT>/edl.json'`
+Trecho 5 dB ou mais fora da referência vem com `gain_db final X`: ponha o X no trecho do `edl_manual.json`
+e rode o passo 4 de novo.
+
+## 6. Renderizar e conferir
+
+```
+uv run --directory '<SKILL>' python helpers/render_cut.py '<EDIT>/edl.json'
+uv run --directory '<SKILL>' python helpers/conferir_corte.py '<EDIT>' --prompt 'Hubla, Kiwify, Cakto'
+```
+
+O render do corte leva uns 30 s por minuto. O `conferir_corte.py` transcreve o `cut.mp4` e roda ao mesmo
+tempo a medida dos respiros (`respiros.py`), o `verify_cut.py` e a folha das junções. No fim ele imprime a
+**fala do corte, trecho a trecho**: o `quote` que você escreveu e, embaixo, o que o corte diz, em frases curtas
+com o tempo de começo no corte. Trecho com palavras diferentes do quote vem marcado `≠ confira: falta "..."`,
+`a mais "..."`. A mesma fala fica em `<EDIT>/fala_do_corte.md` (ou
+`uv run --directory '<SKILL>' python helpers/pack_transcripts.py --edit-dir '<EDIT>' --corte`). Leia tudo:
+- palavra estranha no fim ou no começo de um trecho ("matrão" no lugar de "material") é borda mordendo a
+  palavra: volte ao passo 3 e dê folga naquela borda;
+- palavra repetida ou "eco" numa emenda é resto da tomada anterior: mova a borda para o vale da onda;
+- `≠` só porque o quote foi escrito de outro jeito (número por extenso, muleta que saiu): tudo bem, siga;
+- a transcrição do corte marca começo de palavra até 0,3 s adiantado. Tempo que dispara animação, som ou
+  corte na palavra vem da onda:
+  `uv run --directory '<SKILL>' python helpers/palavras_na_onda.py '<EDIT>' [--palavra 'éééé']`
+  mostra, para cada palavra que mudou, o tempo medido na onda (`pausa` é preciso; `vale` é aproximado, uns
+  0,03 s; `whisper` quer dizer que não havia marca na onda) e grava `<EDIT>/palavras_onda.json`. No
+  `projeto.json`, ponha esse tempo em segundos (`"em": 3.42`) no lugar do nome da palavra (`"em": "éééé"`,
+  que usa o tempo do Whisper). Refaça a cada corte novo.
+- Cada render do corte muda um pouco a transcrição ("o tudo" vira "o" e "tudo", "ééé" vira "éééé"). Cena
+  própria que monta uma linha por palavra tem que aguentar uma palavra a mais ou a menos.
+
+Avisos do verify que pedem ação: `EDGE-IN-SPEECH` e `EDGE-IN-WORD` (palavra cortada até provar o contrário),
+`CLICK` (mova a borda 0,02 a 0,05 s para dentro da pausa), `REPEAT` (dois trechos repetem a fala),
+`LOW-LEVEL`/`HIGH-LEVEL` (use o `gain_db` sugerido), `BLACK`, `SILENT`, `SOURCE-MISSING`. O `DEAD-AIR` não
+deveria aparecer depois do corte pela onda; se aparecer, o trecho tinha `"dry": false` ou o limiar ficou
+baixo demais. Refaça até sair limpo, no máximo 3 voltas; o que ficar, explique para a pessoa. O
+`verify_cut.py --aprovar` é do preview antigo: aqui não se usa. A aprovação do corte é a pessoa dizer no chat
+(passo 7).
+
+**Respiros:** a parte `Respiros que sobraram` lista todo silêncio de 0,25 s ou mais no corte, com o tempo. É a
+primeira coisa que a pessoa nota. Tem que sair vazia; o que está dentro de um trecho `dry: false` sai em
+linha própria, `fica: ...`, e não conta. Para medir qualquer vídeo pronto:
+`uv run --directory '<SKILL>' python helpers/respiros.py '<VIDEO>'`.
+
+## 7. Mostrar no estúdio e aprovar
+
+Meça onde está o rosto em cada trecho do corte (o projeto enquadra por isso; sem ele, enquadra pelo meio do
+quadro):
+`uv run --directory '<SKILL>' python helpers/face_layout.py --edit-dir '<EDIT>'`
+
+Crie o projeto do vídeo, se ainda não existe (copia o modelo e anota a skill e o corte), e abra o corte no
+estúdio, só com o vídeo e a legenda simples:
+
+```
+python3 '<SKILL>/modelo-projeto/build.py' novo '<PROJ>' --edit '<EDIT>'
+cd '<PROJ>' && python3 build.py corte && python3 build.py estudio --sem-abrir
+```
+
+Como abrir o estúdio em cada app: `references/estudio.md`. Mensagem curta: duração, as partes em ordem, o que
+saiu e o que você quer que ela olhe ("confere se não sobrou respiro e se nenhuma palavra ficou mordida").
+- **Ajuste por tempo** ("tira de 00:12,3 a 00:12,8", "a palavra 'então' em 00:20"): o tempo é do corte. Ache
+  em `cut_timeline.json` o segmento com `out_start <= t < out_end`; na fonte, o tempo é
+  `src_start + (t - out_start)`. Mude o `edl_manual.json` (partir um trecho em dois para tirar uma palavra
+  do meio, trocar de tomada, encurtar) e refaça os passos 4 a 7. O estúdio recarrega sozinho quando o
+  `build.py corte` roda de novo.
+- **"Ainda tem respiro"**: meça com `respiros.py` e rode o passo 4 com `--limiar` uns 3 dB mais alto e, se ainda sobrar, no limiar que o `respiros.py` mostra (em geral -29).
+- **Aprovação** é ela dizer no chat que aprovou ("aprovado", "pode seguir"). Anote no `project.md` com a
+  data e a nota dela. Se ela já tinha autorizado fazer tudo sem parar, este é um teste interno: siga para a
+  amostra e mostre o corte junto.
+
+Depois do corte aprovado, qualquer mudança de fala muda os tempos: refaça `transcribe.py` do `cut.mp4`
+(o `conferir_corte.py` já faz), o `palavras_na_onda.py` se algum tempo veio dele, e o `build.py` do projeto, e
+confira se as animações continuam na palavra.
+
+## Várias câmeras (conversa, entrevista, lapela)
+
+Duas ou mais câmeras (ou uma câmera e o gravador da lapela) gravaram a mesma conversa ao mesmo tempo. Cada trecho
+tem uma voz só (`source`) e a imagem pode vir de outra câmera no mesmo instante (`imagem_de`).
+
+**1. Sincronizar.** Com as câmeras (e a lapela) em `sources` do `edl_manual.json`:
+
+```
+uv run --directory '<SKILL>' python helpers/sincronizar_cameras.py --edl '<EDIT>/edl_manual.json' --principal CAM1 --prova
+```
+
+Sem EDL ainda: `sincronizar_cameras.py '<VIDEOS>/CAM1.MP4' '<VIDEOS>/CAM2.MP4' -o '<EDIT>/sincronia.json' --prova`
+(`LAPELA='<VIDEOS>/lapela.wav'` dá o nome da fonte; sem nome, vale o nome do arquivo sem extensão, como em
+`sources`). A principal é a de melhor som, a lapela se houver. Sai `<EDIT>/sincronia.json`, com o `deslocamento`
+de cada fonte em segundos (positivo: ela começou a gravar antes) e a confiança. Leia a saída:
+- `confiança boa`: siga. `confiança media`: confira a prova com cuidado. `confiança fraca` (sai com código 1): não
+  use. Ou não é a mesma conversa, ou o som de uma é quase só ruído (câmera longe, vento). Ache uma palma no vídeo
+  e escreva o `deslocamento` à mão no JSON.
+- `deriva de relógio`: as câmeras contam o tempo um pouco diferente (numa conversa longa, dezenas de ms no fim).
+  O render corrige pela `escala`; confira a prova no começo e no fim (`--em <segundo da principal>`).
+- `não é uma reta`: a câmera parou, perdeu quadros ou o arquivo foi dividido. Sincronize cada pedaço como uma
+  fonte à parte.
+- `outro deslocamento quase tão bom`: música ou som repetitivo por baixo. Confira no olho.
+- Fonte sem áudio: pela onda não dá. Sincronize no olho e escreva o deslocamento.
+
+**2. Conferir no olho.** Abra `<EDIT>/verify/sincronia_CAM2.png`: 5 quadros seguidos de cada câmera no instante da
+batida mais forte, a principal em cima. Numa palma, batida na mesa ou claquete, a mão fecha no mesmo quadro nas
+duas linhas. O `sincronia_CAM2.mp4` põe as duas lado a lado com o som da principal (boca e som juntos). Sem batida
+no vídeo, use `--em` num "p" ou "b" bem marcado. Se a linha de baixo fecha um quadro depois, ponha
+`"ajuste_s": 0.033` nessa fonte do `sincronia.json` (um quadro a 30 fps; um quadro antes, `-0.033`). O ajuste fica
+guardado quando a sincronia é refeita. A lapela não tem imagem: confira de ouvido, no corte.
+
+**3. Escrever os trechos.** `source` é de onde vem a voz; `imagem_de` é a câmera que aparece:
+
+```json
+"sources": {"CAM1": "/v/CAM1.MP4", "CAM2": "/v/CAM2.MP4", "LAPELA": "/v/lapela.wav"},
+"ranges": [
+  {"id": "m01", "source": "LAPELA", "start": 12.40, "end": 16.10, "imagem_de": "CAM1", "quote": "..."},
+  {"id": "m02", "source": "LAPELA", "start": 16.10, "end": 18.30, "imagem_de": "CAM2", "quote": "..."},
+  {"id": "m03", "source": "LAPELA", "start": 19.00, "end": 23.50, "imagem_de": "CAM1", "quote": "..."}
+]
+```
+
+- **Troque de câmera só numa fala ou numa reação de verdade:** quando a outra pessoa começa a falar, quando ela
+  reage (ri, se surpreende, discorda) ou quando só a outra câmera mostra o que está sendo dito. Nunca a cada
+  palavra, nem a cada frase só para dar ritmo. Cada câmera fica na tela pelo menos uns 2 s, fora a reação curta.
+- **Trocar no meio de uma fala** (m01 para m02 acima): dois trechos colados (o `end` de um igual ao `start` do
+  outro), mesma `source`, mesmo `gain_db`; só o `imagem_de` muda. O corte pela onda mede os dois como um trecho só
+  e parte na troca (sai `troca de câmera: ... a voz segue`); o render toca a voz direto, sem J-cut e sem fade ali,
+  e troca a imagem no quadro do tempo escrito (sai `voz continua do anterior`). Com `gain_db` diferente, a voz
+  leva um corte de 30 ms na troca (aviso). Troca escrita numa pausa de 0,22 s ou mais vira junção normal: a pausa
+  sai, como em qualquer corte. Pedaço de menos de 0,3 s de uma câmera vai para a vizinha.
+- Uma voz por vez. Com duas lapelas, `source` é a lapela de quem fala; quando os dois falam juntos, use o som da
+  câmera que pega os dois.
+- Lapela sem vídeo só entra com `imagem_de` em todos os trechos dela.
+- `focus_x`/`focus_y` valem para a imagem que o trecho mostra. O recorte da pessoa (tela verde) sai da câmera
+  certa de cada trecho.
+- Sincronia com outro nome: `"sincronia": "sincronia_tarde.json"` no topo do EDL (padrão: `<EDIT>/sincronia.json`).
+
+**4. Conferir.** Passos 4 a 7 como sempre, e mais:
+- `a CAM2 não tem imagem de ... a ... s`: ela começou depois ou parou antes. Use outra câmera nesse trecho.
+- `mediu CAM2 em outro arquivo`: o vídeo foi trocado ou reexportado. Rode a sincronia de novo.
+- Na folha das junções (`verify/contact_cut.png`) a troca aparece de um quadro para o outro; na fala do corte, a
+  frase segue inteira através da troca (nada repetido, nada faltando).
+- Olhe a boca logo depois de cada troca: atrasada ou adiantada é sincronia fora. Corrija o `ajuste_s` daquela
+  câmera e renderize de novo.