@esquadrao/cli 0.0.0-stage → 1.6.0

package/skill-media-producer/references/caption-templates.md

@@ -0,0 +1,194 @@
+# Catálogo de Templates de Legenda
+
+> **Status:** implementado no CLI **1.5.0**. Use `--caption-template <id>` em `studio auto-clip`/`studio render` ou `captions[].template` no EditPlan. Os estilos `impact`, `word` e `full` continuam disponíveis como legado via `--caption-style`.
+
+Este documento é a fonte canônica para fonte, cor, contorno, sombra, posição e animação das legendas. Ele descreve os nove estilos usados no grid de demonstração e serve de base para a implementação no `@esquadrao/cli`.
+
+---
+
+## 1. Princípios
+
+1. **Sem fundo sólido:** nenhum template usa caixa, tarja ou retângulo colorido atrás do texto. A legibilidade vem de preenchimento, contorno e sombra.
+2. **Duas linhas curtas:** o texto é dividido em `LEGENDA DO` / `SEU JEITO`; tamanho e quebra são calculados para caber em 90% da largura segura.
+3. **Contraste alto:** preenchimento claro com contorno escuro, ou preenchimento escuro com contorno claro; contorno mínimo de 5 px na referência 640×360.
+4. **Área segura:** margem mínima de 5% em cada borda. Nenhum texto encosta na borda da célula.
+5. **Escala relativa:** todos os valores são proporcionais à largura do canvas. A referência é **640×360**; o fator é `k = largura / 640`.
+6. **Sem áudio no grid:** o catálogo é visual; o grid de demonstração é renderizado com `-an`.
+7. **Fontes licenciadas:** Anton, Poppins e Bebas Neue são OFL (Google Fonts); Liberation Sans e DejaVu Sans Mono são fontes de sistema. O CLI deve empacotar as OFL ou aplicar fallback documentado.
+
+---
+
+## 2. Escala e coordenadas
+
+Referência de projeto: célula **640×360** (16:9). Para outro canvas, multiplique tamanhos por `k = largura / 640` e calcule `y` pela porcentagem da altura.
+
+| Token | Referência 640×360 | Fórmula | Equivalente 1080×1920 |
+| :--- | ---: | :--- | ---: |
+| `font_size` base | 64 px | `64 * k` | 108 px |
+| `stroke` base | 7 px | `7 * k` | 12 px |
+| `shadow` base | 4 px | `4 * k` | 7 px |
+| linha 1 (`y1`) | 100 px (27,8%) | `0.2778 * altura` | 533 px |
+| linha 2 (`y2`) | 170 px | `y1 + lineGap * font_size` | 651 px (heavy-white) |
+| lower third (`y`) | 276 px (76,7%) | `0.7667 * altura` | 1472 px |
+
+O motor deve arredondar para inteiro e garantir `stroke >= 2` e `font_size >= 12` em qualquer canvas. O `lineGap` é específico por template (1,0× a 1,4× o `font_size`) e mantém o bloco compacto em 9:16, em vez de abrir um vão proporcional à altura.
+
+---
+
+## 3. Catálogo
+
+| # | ID | Nome | Fonte | Preenchimento | Contorno | Sombra | Posição (640×360) | Uso |
+| ---: | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| 1 | `mrbeast-yellow` | MrBeast Yellow | Anton | `#FFE600` | `#000000` 7 px | 4 px, 4 px | 100 / 170 | Alto impacto, retenção |
+| 2 | `tiktok-white` | TikTok White | Poppins Bold | `#FFFFFF` | `#000000` 8 px | 3 px, 3 px | 105 / 175 | Padrão social, legível |
+| 3 | `gold-stroke` | Gold Stroke | Anton | `#FFF6D6` | `#FFC400` 5 px | 3 px, 3 px | 100 / 170 | Premium, luxo |
+| 4 | `green-stroke` | Green Stroke | Bebas Neue | `#FFFFFF` | `#00E676` 6 px | 3 px, 3 px | 108 / 176 | Karaokê, energia |
+| 5 | `neon-glitch` | Neon Glitch | Anton | `#FFFFFF` + offsets `#00E5FF` / `#FF00E5` | `#000000` 3 px no núcleo | halo 0 px, 70% | 100 / 170 | Gaming, tech |
+| 6 | `minimal-lower-third` | Minimal Lower Third | Liberation Sans Bold | `#FFFFFF` | `#000000` 3 px | 2 px, 2 px | 276 (linha única) | Corporativo, clean |
+| 7 | `red-stroke` | Red Stroke | Poppins Bold | `#FFFFFF` | `#E11D2E` 6 px | 3 px, 3 px | 105 / 175 | Alerta, ênfase |
+| 8 | `heavy-white` | Heavy White | Poppins Bold | `#FFFFFF` | `#000000` 8 px | 4 px, 4 px | 105 / 178 | Máxima leitura |
+| 9 | `mono-clean` | Mono Clean | DejaVu Sans Mono Bold | `#FFFFFF` | `#000000` 9 px | 4 px, 4 px | 112 / 178 | Técnico, typewriter |
+
+> **Sem fundo:** nenhum dos nove usa `box=1` ou `drawbox` atrás do texto. A linha horizontal do template 6 é um elemento gráfico, não um fundo.
+
+---
+
+## 4. Especificação por template
+
+### 4.1. `mrbeast-yellow`
+
+- **Fonte:** Anton Regular, 64 px (`k * 64`).
+- **Texto:** `LEGENDA DO` / `SEU JEITO`, caixa alta, centralizado.
+- **Preenchimento:** `#FFE600`.
+- **Contorno:** `#000000`, 7 px.
+- **Sombra:** `#000000` a 80%, deslocamento 4×4.
+- **Animação:** fade-in de 400 ms (`alpha='if(lt(t,0.4),t/0.4,1)'`).
+
+```bash
+drawtext=fontfile='Anton-Regular.ttf':text='LEGENDA DO':fontsize=64:fontcolor=#FFE600:borderw=7:bordercolor=black:shadowx=4:shadowy=4:shadowcolor=black@0.8:x=(w-text_w)/2:y=100:alpha='if(lt(t,0.4),t/0.4,1)'
+```
+
+### 4.2. `tiktok-white`
+
+- **Fonte:** Poppins Bold, 54 px.
+- **Preenchimento:** `#FFFFFF`.
+- **Contorno:** `#000000`, 8 px.
+- **Sombra:** `#000000` a 70%, 3×3.
+- **Uso:** estilo padrão de TikTok/Reels; máxima compatibilidade.
+
+### 4.3. `gold-stroke`
+
+- **Fonte:** Anton Regular, 64 px.
+- **Preenchimento:** `#FFF6D6` (creme).
+- **Contorno:** `#FFC400` (dourado), 5 px.
+- **Sombra:** preta a 85%, 3×3.
+- **Uso:** imobiliário, luxo, viagens.
+
+### 4.4. `green-stroke`
+
+- **Fonte:** Bebas Neue, 70 px.
+- **Preenchimento:** `#FFFFFF`.
+- **Contorno:** `#00E676`, 6 px.
+- **Sombra:** preta a 85%, 3×3.
+- **Uso:** karaokê, música, fitness.
+
+### 4.5. `neon-glitch`
+
+- **Fonte:** Anton Regular, 62 px.
+- **Núcleo:** `#FFFFFF`, contorno preto 3 px.
+- **Camada ciano:** `#00E5FF`, deslocada −4 px em X e +2 px em Y.
+- **Camada magenta:** `#FF00E5`, deslocada +4 px em X e −2 px em Y.
+- **Halo preto no núcleo:** sombra de 0 px a 70% para separar do fundo.
+- **Uso:** gaming, tecnologia, edição.
+
+### 4.6. `minimal-lower-third`
+
+- **Fonte:** Liberation Sans Bold, 40 px.
+- **Texto:** uma linha, `LEGENDA DO SEU JEITO`.
+- **Preenchimento:** `#FFFFFF`.
+- **Contorno:** `#000000` a 90%, 3 px.
+- **Sombra:** preta a 90%, 2×2.
+- **Elemento gráfico:** linha horizontal branca de 2 px, 500 px de largura, 24 px acima do texto.
+- **Uso:** corporativo, documentário, notícias.
+
+### 4.7. `red-stroke`
+
+- **Fonte:** Poppins Bold, 54 px.
+- **Preenchimento:** `#FFFFFF`.
+- **Contorno:** `#E11D2E`, 6 px.
+- **Sombra:** preta a 85%, 3×3.
+- **Uso:** alerta, erro, urgência.
+
+### 4.8. `heavy-white`
+
+- **Fonte:** Poppins Bold, 60 px.
+- **Preenchimento:** `#FFFFFF`.
+- **Contorno:** `#000000`, 8 px.
+- **Sombra:** preta a 90%, 4×4.
+- **Uso:** máxima legibilidade; é o template corrigido da posição inferior central.
+
+### 4.9. `mono-clean`
+
+- **Fonte:** DejaVu Sans Mono Bold, 48 px.
+- **Preenchimento:** `#FFFFFF`.
+- **Contorno:** `#000000`, 9 px.
+- **Sombra:** preta a 85%, 4×4.
+- **Uso:** técnico, tutorial, terminal.
+
+---
+
+## 5. Contrato CLI implementado (1.5.0)
+
+O motor nativo deve aceitar:
+
+```bash
+esquadrao studio auto-clip <video> --caption-template heavy-white
+esquadrao studio render <plan.json> --caption-template mrbeast-yellow
+esquadrao studio caption-templates --json
+```
+
+No `EditPlan`, o campo planejado é:
+
+```json
+{
+  "captions": [
+    {
+      "text": "LEGENDA DO SEU JEITO",
+      "timeline_start_ms": 0,
+      "duration_ms": 3000,
+      "template": "heavy-white"
+    }
+  ]
+}
+```
+
+Regras de contrato:
+- `template` é opcional; ausente usa `impact` (compatibilidade).
+- `template` inválido falha com código 1 e lista os IDs disponíveis.
+- `caption-templates --json` devolve `{ version, reference_canvas, templates: [...] }`.
+- O renderizador não deve introduzir fundo sólido em nenhum template do catálogo.
+- Fontes ausentes usam fallback explícito e registram aviso, nunca falham em silêncio.
+
+**Estado:** implementado no CLI 1.5.0. `--caption-template` e `captions[].template` são validados contra os nove IDs; ID inválido encerra com código 1 e lista os disponíveis.
+
+---
+
+## 6. Regras para agentes de IA
+
+1. Use `--caption-template <id>` para escolher um dos nove presets; `caption-templates --json` lista os IDs.
+2. `--caption-style impact|word|full` continua válido como legado quando nenhum template é informado.
+3. ID inválido deve ser tratado como erro, nunca ignorado.
+4. Nunca aplique `drawbox`/`box=1` atrás do texto ao recriar estes templates.
+5. Preserve a área segura de 5% e o contorno mínimo.
+
+---
+
+## 7. Checklist de QA do catálogo
+
+- [ ] Texto completo e sem corte em 640×360 e 1080×1920.
+- [ ] Contraste >= 4.5:1 entre preenchimento e contorno/fundo imediato.
+- [ ] Nenhum fundo sólido atrás das letras.
+- [ ] Fonte e fallback resolvidos no ambiente.
+- [ ] Fade-in de 400 ms sem flicker.
+- [ ] Nenhuma faixa de áudio no grid de demonstração.
+- [ ] Nove IDs únicos, nove estilos visualmente distintos.

package/skill-media-producer/references/composicoes-especiais.md

@@ -0,0 +1,99 @@
+# Composições especiais: split permanente e recorte de pessoa
+
+Status: **implementado no CLI 1.6.0**. O split permanente está operacional; o recorte de pessoa é experimental e depende de Python.
+
+## 1. Split permanente (orador no topo + pack na base)
+
+### Comando
+
+```bash
+esquadrao studio auto-clip entrada.mp4 \
+  --no-captions \
+  --broll pack.mp4 \
+  --layout split_bottom \
+  --overlay-duration full
+```
+
+Regras:
+
+- `--layout` aceita `fullscreen`, `pip` e `split_bottom`. `split_top` continua pendente (CLI-06).
+- `--overlay-duration inserts` (padrão) distribui B-rolls de 2–4 s; `full` usa o primeiro `--broll` durante toda a linha do tempo.
+- O pack é silenciado e repetido em loop; se for mais longo que o clipe, é cortado.
+- O áudio do orador é preservado; o pack não entra no mix.
+- `split_bottom` preenche a metade inferior com `scale` + `crop` (sem tarjas).
+- O plano gerado fica em `packages/autoclip-plan.json` e pode ser reproduzido com `studio render`.
+
+Limites:
+
+- Apenas o primeiro `--broll` é usado no modo `full`; os demais são ignorados com aviso.
+- O pack não é escolhido automaticamente por tema; a seleção é editorial.
+- `split_top` não está implementado.
+
+Critérios de aceite:
+
+- [x] `auto-clip --broll ... --layout split_bottom --overlay-duration full` gera 1080×1920 com duas metades.
+- [x] O pack cobre a metade inferior durante todo o clipe, em loop.
+- [x] Áudio original preservado; pack silenciado.
+- [x] `--help` documenta `--layout` e `--overlay-duration`.
+- [x] Teste de render em `tests/autoclip.test.js` verifica plano, loop e QA.
+- [ ] `split_top` (CLI-06).
+
+## 2. Recorte de pessoa com troca de fundo (cutout)
+
+### Comando
+
+```bash
+esquadrao studio cutout entrada.mp4 \
+  --background pack.mp4 \
+  --python python3 \
+  --fps 15
+```
+
+Pré-requisitos no interpretador Python escolhido:
+
+```bash
+python3 -m pip install "rembg[cpu]" onnxruntime opencv-python-headless numpy
+```
+
+Regras:
+
+- Saída 1080×1920 (9:16) nesta versão; `--format 16:9` é rejeitado.
+- `--fps` aceita 1–30; padrão 15.
+- O pack é silenciado, repetido/cortado para a duração.
+- Áudio original preservado; se a entrada não tiver áudio, o script adiciona uma faixa silenciosa para o QA.
+- O motor é `rembg` com `u2net_human_seg`.
+- A máscara do `u2net` é refinada com GrabCut e tem a borda suavizada; isso remove o halo escuro do fundo original.
+- Conversão obrigatória RGB→BGR antes da composição. Sem isso, vermelho e azul trocam e a pele fica azul.
+- O script fica em `scripts/cutout.py` e é chamado pelo comando Node.
+
+Custo e limites:
+
+- ~18–20 min de CPU para 60 s em 15 fps (1080×1920), sem GPU.
+- Halo residual possível em cabelo/fone em frames difíceis; não há matting temporal.
+- Sem cache de máscaras e sem aceleração GPU nesta versão.
+- Modelo `u2net_human_seg` (~176 MB) é baixado pelo `rembg` na primeira execução; não é empacotado no npm.
+- Sem segmentação de mãos/objetos finos garantida em todos os frames.
+- O pack de fundo é escolha editorial, não automática.
+
+Critérios de aceite:
+
+- [x] `studio cutout --background` gera 1080×1920 com áudio e passa no QA.
+- [x] Pele e cores originais preservadas (RGB→BGR).
+- [x] Pack silenciado; áudio original do podcast.
+- [x] Sem `rembg`: exit 1 com instrução de instalação.
+- [x] Teste de contrato em `tests/cutout.test.js` cobre validação e help.
+- [ ] Cache de máscaras.
+- [ ] Aceleração GPU / processamento em lote.
+- [ ] Matting temporal para eliminar halo em movimento.
+
+## 3. Regra de comunicação
+
+- Pode afirmar que o CLI 1.6.0 faz split permanente e cutout, **desde que** qualifique o cutout como experimental e informe as dependências Python e o custo de CPU.
+- Não prometa tempo real, qualidade de estúdio ou ausência total de halo.
+- `split_top` e ducking dinâmico continuam pendentes.
+
+## 4. Evidências
+
+- Split: `podpah-neymar-split-pack.mp4` (protótipo externo, 60 s, 1080×1920) e teste `split_bottom full loops a short b-roll`.
+- Cutout: `podpah-neymar-cutout-pack.mp4` (protótipo externo, 60 s, 1080×1920, cor corrigida) e teste de contrato do comando.
+- Suíte: 91 testes, lint em 38 arquivos.

package/skill-media-producer/references/configuracao-inicial.md

@@ -0,0 +1,239 @@
+# Configuração inicial do Esquadrão Studio
+
+Guia para Windows / PowerShell: instalar, escolher proporção, configurar cortes e legendas, renderizar e verificar o MP4. Execute os blocos na mesma sessão. O Studio executa localmente pelo CLI, com Node.js e FFmpeg.
+
+## 1. Pré-requisitos e instalação
+
+Use Node.js 18 ou superior. Confira:
+
+```powershell
+node --version
+npm --version
+ffmpeg -version
+ffprobe -version
+```
+
+Se precisar instalar FFmpeg:
+
+```powershell
+winget install --id Gyan.FFmpeg -e
+```
+
+Abra um novo PowerShell após instalar para atualizar o PATH.
+
+Se você já tem o repositório clonado, defina o caminho absoluto para `bin\cli.js`:
+
+```powershell
+$cli = "C:\caminho\esquadrao-cli\bin\cli.js"
+node $cli studio --help
+```
+
+Alternativamente, após a publicação do pacote no npm, instale com `npm install -g @esquadrao/cli` e substitua `node $cli` por `esquadrao` nos comandos deste guia.
+
+## 2. Criar o projeto e instalar as skills
+
+Escolha uma pasta exclusiva para o vídeo. `setup` copia as skills e atualiza as integrações de agentes detectadas nessa pasta; use uma pasta nova para preservar configurações de outros projetos.
+
+```powershell
+$projeto = Join-Path $env:USERPROFILE "Videos\StudioEsquadrao\meu-primeiro-video"
+New-Item -ItemType Directory -Force -Path $projeto | Out-Null
+Set-Location $projeto
+node $cli setup
+if ($LASTEXITCODE -ne 0) { throw "Falha ao instalar as skills." }
+node $cli studio init --dest $projeto
+if ($LASTEXITCODE -ne 0) { throw "Falha ao inicializar o Studio." }
+```
+
+Para Claude Code em um projeto novo, prepare a integração e execute novamente o setup:
+
+```powershell
+New-Item -ItemType Directory -Force -Path (Join-Path $projeto ".claude") | Out-Null
+node $cli setup
+if ($LASTEXITCODE -ne 0) { throw "Falha ao instalar as skills para Claude Code." }
+```
+
+Abra o agente nessa pasta em uma nova sessão para carregar `skill-media-producer`. `assets/` guarda cópias das fontes, `packages/` guarda os planos, `artifacts/` recebe os MP4 e `studio.json` registra as importações e resultados. `studio init` cria exclusivamente essas pastas e arquivos.
+
+Para experimentar o fluxo guiado com valores padrão, use `node $cli onboard --mode podcast_clip --file <video> --captions <legendas.srt>`. Sem SRT/OpenAI/motor local, o onboard aplica `--no-captions`, gera um corte real sem legendas e avisa. Para controlar proporção, cortes e legendas explicitamente, siga os próximos passos.
+
+## 3. Importar um vídeo com áudio
+
+Substitua o caminho por um arquivo com pelo menos 8 segundos e áudio. O original permanece preservado; a importação cria uma cópia.
+
+```powershell
+$origem = "C:\caminho\seu-video.mp4"
+$resultado = node $cli studio import $origem --dest $projeto --json
+if ($LASTEXITCODE -ne 0) { throw "Falha ao importar o vídeo." }
+$asset = ($resultado -join "`n") | ConvertFrom-Json
+$asset | Select-Object id, name, metadata
+if ($asset.metadata.duration_s -lt 8 -or !$asset.metadata.audio_codec) {
+    throw "O exemplo requer uma fonte com áudio e pelo menos 8 segundos."
+}
+```
+
+## 4. Criar o plano de edição
+
+Crie `packages/editplan.json` a partir deste modelo. Os tempos são inteiros em milissegundos: `1000` equivale a um segundo.
+
+```json
+{
+  "schema_version": 1,
+  "mode": "edit_only",
+  "output": {
+    "width": 1080,
+    "height": 1920,
+    "fps_num": 30,
+    "fps_den": 1,
+    "video_codec": "h264",
+    "audio_codec": "aac"
+  },
+  "clips": [
+    {
+      "kind": "video",
+      "clip_id": "corte-1",
+      "asset_id": "AST-SUBSTITUIR",
+      "in_ms": 0,
+      "out_ms": 4000,
+      "timeline_start_ms": 0
+    },
+    {
+      "kind": "video",
+      "clip_id": "corte-2",
+      "asset_id": "AST-SUBSTITUIR",
+      "in_ms": 4000,
+      "out_ms": 8000,
+      "timeline_start_ms": 4000
+    }
+  ],
+  "audio_tracks": [
+    { "kind": "source", "clip_id": "corte-1", "gain_db": 0 },
+    { "kind": "source", "clip_id": "corte-2", "gain_db": 0 }
+  ],
+  "captions": [
+    { "text": "Sua primeira frase", "timeline_start_ms": 0, "duration_ms": 4000 },
+    { "text": "Sua segunda frase", "timeline_start_ms": 4000, "duration_ms": 4000 }
+  ]
+}
+```
+
+Para criar o arquivo, execute e cole apenas o JSON acima no editor, depois salve e feche:
+
+```powershell
+$arquivoPlano = Join-Path $projeto "packages\editplan.json"
+notepad $arquivoPlano
+```
+
+Carregue o arquivo e vincule os dois cortes ao vídeo importado:
+
+```powershell
+$plano = Get-Content -Raw -Encoding UTF8 $arquivoPlano | ConvertFrom-Json
+$plano.clips[0].asset_id = $asset.id
+$plano.clips[1].asset_id = $asset.id
+```
+
+## 5. Escolher proporção e cortes
+
+> **Nota de Escolha do Usuário:** O formato e o estilo de edição são definidos livremente por você. O sistema não impõe fundo preto nem formato widescreen como padrão. Você escolhe entre a proporção vertical 9:16 (mobile) ou horizontal 16:9 (widescreen), e define se usará suas filmagens, packs de apoio ou telas tipográficas.
+
+| Formato | Largura | Altura | Uso |
+|---|---:|---:|---|
+| 9:16 | 1080 | 1920 | Reels, Shorts, TikTok |
+| 16:9 | 1920 | 1080 | Vídeo horizontal |
+
+Para vertical:
+
+```powershell
+$plano.output.width = 1080
+$plano.output.height = 1920
+```
+
+Para horizontal, use `width = 1920` e `height = 1080`. Estes são os dois formatos aceitos, a 30 fps com H.264/AAC. O enquadramento preserva a proporção da fonte e completa o espaço restante com bordas. Recorte automático e saída quadrada ficam fora das opções atuais.
+
+`in_ms` e `out_ms` selecionam o trecho do original. `timeline_start_ms` posiciona esse trecho no vídeo final. O modo `edit_only` exige exatamente dois cortes consecutivos na montagem, com uma faixa de áudio original por corte.
+
+Exemplo opcional para uma fonte de pelo menos 34 segundos: selecionar 10–14s e 30–34s, mantendo 8 segundos de montagem:
+
+```powershell
+$plano.clips[0].in_ms = 10000
+$plano.clips[0].out_ms = 14000
+$plano.clips[1].in_ms = 30000
+$plano.clips[1].out_ms = 34000
+$plano.clips[1].timeline_start_ms = 4000
+```
+
+Ao alterar a duração do primeiro corte, ajuste o início do segundo para a nova duração. Mantenha os pontos de saída dentro da duração da fonte.
+
+## 6. Configurar legenda e áudio
+
+Texto, início e duração são configuráveis:
+
+```powershell
+$plano.captions[0].text = "Veja como configurar seu vídeo"
+$plano.captions[0].timeline_start_ms = 0
+$plano.captions[0].duration_ms = 4000
+$plano.captions[1].text = "Agora é só renderizar"
+$plano.captions[1].timeline_start_ms = 4000
+$plano.captions[1].duration_ms = 4000
+```
+
+Use frases curtas de até 200 caracteres, sem HTML, com início e duração dentro do vídeo final. O renderizador atual usa texto branco, tamanho 48 pixels, centralizado horizontalmente e posicionado 200 pixels acima da borda inferior. A fonte é do sistema; no Windows, Arial é a primeira opção. As legendas ficam gravadas na imagem. O modo `dark` posiciona seus textos no centro da tela.
+
+Cor, tamanho, fonte, contorno, fundo, posição e quebra automática de linha ainda dependem de alterações no renderizador. Campos extras de estilo no JSON não configuram essas propriedades. Transcrição automática e importação SRT também ficam fora deste fluxo atual.
+
+Para remover as legendas, use `$plano.captions = @()`.
+
+O ganho de cada corte aceita -60 a +12 dB. Zero preserva o volume, valores negativos reduzem e valores positivos aumentam. Confira distorção ao aumentar o ganho. Caso utilize trilha musical (`music_tracks`) com `ducking: true`, a atenuação aplicada é fixa em `-22dB` via mixagem `amix`, e não ducking dinâmico via sidechain (previsto no backlog CLI-05).
+
+```powershell
+$plano.audio_tracks[0].gain_db = 0
+$plano.audio_tracks[1].gain_db = 0
+```
+
+## 7. Salvar, renderizar e verificar
+
+Após qualquer ajuste, salve em UTF-8 sem BOM para compatibilidade com o leitor JSON:
+
+```powershell
+$utf8 = [System.Text.UTF8Encoding]::new($false)
+[System.IO.File]::WriteAllText(
+    $arquivoPlano,
+    ($plano | ConvertTo-Json -Depth 10),
+    $utf8
+)
+$resultado = node $cli studio render $arquivoPlano --dest $projeto --json
+if ($LASTEXITCODE -ne 0) { throw "Falha ao renderizar o vídeo." }
+$render = ($resultado -join "`n") | ConvertFrom-Json
+$videoFinal = Join-Path $projeto $render.path
+node $cli studio qa $videoFinal --plan $arquivoPlano
+if ($LASTEXITCODE -ne 0) { throw "O vídeo falhou na verificação técnica." }
+Start-Process -FilePath $videoFinal
+```
+
+O QA compara dimensões, fps e duração com o plano e verifica os streams. Assista ao resultado para avaliar sincronização das frases, legibilidade, enquadramento e volume. Detecção de quadros pretos e avaliação visual de sincronização exigem revisão adicional.
+
+## Pedido pronto para o agente
+
+> Use skill-media-producer e o guia de configuração inicial. Pergunte o arquivo de origem, formato vertical ou horizontal, dois trechos, frases e horários das legendas e ganho do áudio. Prepare packages/editplan.json com as opções disponíveis. Antes de renderizar, mostre os cortes e a duração final para aprovação. Depois execute render e qa com --plan e informe o caminho do MP4.
+
+## 8. Esteira rápida de auto-corte de silêncios e legendas (`auto-clip`)
+
+Se você possui um vídeo falado (ex.: podcast, aula ou gravação direta) e deseja cortar pausas e silêncios maiores que 0.8s:
+
+```powershell
+# Auto-corte com arquivo SRT de legendas, gerando plano em packages/ e MP4 em artifacts/:
+node $cli studio auto-clip $origem --dest $projeto --captions (Join-Path $projeto "packages\legendas.srt")
+
+# Ou apenas analisar silêncios e pausas mortas antes de renderizar:
+node $cli studio detect-silence $origem
+```
+
+O comando expurga as pausas, transcreve o áudio caso um arquivo SRT ou provedor de transcrição esteja configurado, remapeia as legendas quando existentes para a linha de tempo pós-corte e valida o arquivo MP4 final em `artifacts/`.
+
+Três caminhos de legendas no `auto-clip`:
+1. `--captions <arquivo.srt>`: Determinístico, offline e testado (recomendado).
+2. `--openai`: Requer a variável de ambiente `OPENAI_API_KEY` para transcrição via API remota da OpenAI.
+3. `--local`: Utiliza `@xenova/transformers` + `Xenova/whisper-tiny`, declarada em `optionalDependencies`. Se o pacote opcional não estiver instalado, o comando falha com instrução acionável; use `--no-captions` para cortar sem legendas.
+
+> **Templates:** o catálogo de nove presets está em [`caption-templates.md`](caption-templates.md). Use `--caption-template <id>` no `auto-clip`/`render` ou `captions[].template` no EditPlan; `--caption-style impact|word|full` continua como legado.
+
+Caso adicione trilha de fundo (`--music`), a atenuação aplicada é fixa em `-22dB`, sem ducking dinâmico por sidechain.