---
name: editar-por-voz
description: Skill canônica para editar por voz dentro do projeto Jhonny e do painel MCP for Adobe Premiere Pro, usando a transcrição e a configuração editorial do SQLite. Use neste projeto para escolher tomadas, limpar repetições ou montar o corte automático. Não use as skills portáteis edit-video-by-voice ou transcript-to-edit-actions neste fluxo persistido.
---

# Editar por voz

Transforma uma edição concluída no banco em um plano editorial revisável e, após aprovação, em uma alteração verificável no Premiere Pro.

## Fonte de verdade

O banco de análises é a fonte oficial. Não procure nem exija um arquivo
`*_voice_timeline.json` e não trate JSON temporário, cache ou estado do painel
como fonte independente.

Para carregar o contexto sem escrever SQL, execute:

```text
python3 code/engine/preparar_edicao_por_voz.py --banco .jhonny/analises.db
```

Depois de gerar o JSON de ações, registre-o no banco e use o identificador
retornado para aplicar exatamente esse plano:

```bash
python3 code/engine/registrar_plano_de_edicao.py plano.json \
  --banco .jhonny/analises.db --tipo-de-video depoimento
python3 code/engine/aplicar_plano_de_edicao.py plano.json \
  --banco .jhonny/analises.db --plano-id ID_RETORNADO
```

Use `--video-id` quando o usuário indicar um vídeo específico e
`--sem-palavras` somente quando os limites palavra a palavra não forem
necessários. A resposta válida vem em `contexto`; trate `ok: false` como
bloqueio do fluxo.

Use a edição concluída mais recente em `edicoes_de_video` como raiz do trabalho.
Recupere o restante pelo mesmo `video_id`:

- `videos`, `faixas` e `clipes`: mídia, sequência e estrutura;
- `analises_versao`: versão da análise usada;
- `segmentos_de_transcricao` e `palavras_de_transcricao`: falas e tempos;
- `evidencias_visuais`: contexto visual, quando disponível;
- `planos_de_edicao` e `acoes_do_plano`: decisões já geradas;
- `aplicacoes_do_plano`: histórico de execução.

Leia [criterios/00-fonte-de-dados.md](criterios/00-fonte-de-dados.md) antes de
consultar o banco ou quando houver dúvida sobre qual registro usar.

## Estados obrigatórios

Trate o trabalho como uma sequência de estados:

```text
edicao_concluida
→ contexto_validado
→ plano_gerado
→ preview_aprovado
→ aplicado
→ verificado
```

Não aplique um plano sem contexto validado e preview aprovado. Se algum estado
ou evidência obrigatória estiver ausente, pare e relate exatamente o que falta.

## Fluxo

1. Localize a edição concluída mais recente e confirme vídeo, sequência, tipo,
   origem, transcrição e versão da análise.
2. Reúna do banco a transcrição completa, palavras, falantes, tomadas,
   métricas e evidências disponíveis. Preserve os tempos da mídia original.
3. Leia a configuração editorial salva em `edicoes_de_video.configuracao` e
   extraia objetivo, narrativa, duração, tom, regras de corte e restrições.
4. Separe roteiro de conversa de bastidor pelo conteúdo. Depois agrupe frases
   repetidas e escolha a tomada completa, clara, natural e coerente.
5. Reanalise as ênfases apenas depois de definir o material sobrevivente. Se o
   banco não tiver métricas ou a camada correspondente estiver incompleta,
   decida pelo texto e registre a limitação.
6. Decida cortes, zooms, textos e marcadores somente quando o contrato de
   aplicação suportar a ação. Cada ação deve ter motivo verificável.
7. Antes de salvar, reconstrua o texto que sobreviverá a cada emenda. Um
   segmento do Whisper não equivale a uma frase: una segmentos adjacentes
   sempre que a gramática continuar. Exija frase completa e ao menos 0,30s de
   respiro junto a cada palavra mantida. Se uma borda interceptar palavra,
   deixar a fala sem fechamento ou retomar em continuação minúscula, corrija
   o plano; nunca delegue esse defeito à aplicação.
8. Gere um plano com tempos na mídia original. Salve o plano em
   `planos_de_edicao` e suas ações ordenadas em `acoes_do_plano`, associado ao
   `video_id`, ao tipo de vídeo e ao contexto editorial carregado.
9. Faça preview do texto sobrevivente, lendo em sequência a última frase antes
   e a primeira frase depois de cada corte. Apresente decisões e incertezas
   para revisão humana. Uma alteração no plano exige novo preview.
10. Após aprovação explícita, confirme a sequência atual, crie backup ou
   duplicata, aplique o plano pelo fluxo suportado do Premiere e registre o
   resultado em `aplicacoes_do_plano`.
11. Reconsulte a timeline, compare com o plano e registre a verificação. Separe
    o que foi comprovado automaticamente do que exige avaliação visual.

## Contrato da decisão

O JSON abaixo é uma representação de trabalho, não a fonte principal:

```json
{
  "source": "0E6A8829.MP4",
  "actions": [
    {
      "kind": "cut",
      "start": 12.4,
      "end": 16.8,
      "reason": "Repetição da frase anterior."
    }
  ]
}
```

`cut` remove um intervalo. Todos os tempos referem-se à mídia original. A
ação precisa ter `start < end`, estar dentro da duração e não sobrepor outra
ação incompatível. Use `reason` para registrar a fala, comparação ou evidência
que fundamentou a decisão.

Leia, conforme a etapa, [criterios/02-triagem-roteiro-vs-conversa.md](criterios/02-triagem-roteiro-vs-conversa.md),
[criterios/03-escolha-da-melhor-tomada.md](criterios/03-escolha-da-melhor-tomada.md),
[criterios/04-reanalise-do-material-restante.md](criterios/04-reanalise-do-material-restante.md),
[criterios/05-zoom.md](criterios/05-zoom.md),
[criterios/06-texto-corte-marcador.md](criterios/06-texto-corte-marcador.md),
[criterios/07-ritmo.md](criterios/07-ritmo.md) e
[criterios/10-revisao-humana.md](criterios/10-revisao-humana.md).

## Limites

- A skill decide a edição; o Premiere executa.
- Nunca invente falas, identidades, timecodes ou evidências.
- Não altere o áudio original, a transcrição ou a análise para forçar uma
  decisão.
- Nunca use o começo ou o fim de um segmento de transcrição como borda só
  porque o timestamp já existe. A unidade editorial é a frase completa.
- Não declare uma edição concluída com base apenas em um JSON, preview ou
  retorno de ferramenta; exija aplicação e verificação.
- Não execute cortes destrutivos sem aprovação e backup/duplicata.

## Relato

Relate sempre em português:

- edição, vídeo e versão da análise usados;
- tomadas encontradas e escolhidas, com motivo;
- falas descartadas como bastidor ou repetição;
- cortes, zooms, textos e marcadores propostos;
- decisões rejeitadas ou ambíguas;
- plano salvo, aplicação realizada e verificação pendente.