jhonny-editor/docs/PLANO-EDICAO-DE-VIDEO-POR-VOZ.md

# Plano de edição de vídeo por voz

Documento vivo para integrar o Scanner, o banco SQLite, a tela **Editar vídeo**, a decisão assistida por IA e a aplicação segura do plano na timeline do Premiere Pro.

Status: desenho aprovado para implementação incremental.

## 1. Objetivo

Permitir que a tela **Editar vídeo** reutilize uma análise já executada pelo Scanner, sem transcrever o mesmo material novamente. A tela buscará no banco somente os dados necessários, montará um contexto compacto para a IA, receberá decisões editoriais em JSON, validará essas decisões pela engine e aplicará o plano na timeline ativa.

O fluxo não deve enviar o banco inteiro, o relatório completo ou o áudio para a IA. A IA recebe somente o contexto editorial solicitado.

## 1.1. Protocolo de edição solicitado pelo chat

Quando o usuário disser **“editar vídeo”**, o chat deve tratar isso como um
pedido de execução do fluxo deste documento.

O pedido deve separar três identificadores:

1. **Vídeo/análise**: qual análise do Scanner será usada. Preferir `video_id`
   ou o caso exibido na tela, nunca confundir com o perfil editorial.
2. **Perfil editorial**: número ou identificador da personalidade/estilo da
   edição. Esse número representa como editar, não qual arquivo editar.
3. **Tipo e objetivo do vídeo**: depoimento, entrevista, redes sociais,
   educativo, institucional ou perfil personalizado.

Exemplo de pedido normalizado:

```json
{
  "intencao": "editar_video",
  "video_id": "12669c9c-038d-4a3f-99f9-fe6f6827b5f4",
  "perfil_editorial_id": 3,
  "tipo_de_video": "depoimento",
  "objetivo": "preservar autenticidade e remover repetições",
  "intervalo": {"inicio": 0.0, "fim": null}
}
```

Se o número informado ainda não estiver cadastrado, o chat deve pedir a
descrição do perfil ou registrar o perfil antes de gerar decisões. O número
não deve ser interpretado como `video_id`, `clipe_id` ou número de faixa.

### Ordem de execução no chat

Quando os dados estiverem disponíveis, o chat deve:

1. identificar o vídeo/análise correta;
2. carregar o perfil editorial pelo número;
3. consultar o resumo do vídeo localmente;
4. consultar falas, clipes, cenas e métricas necessárias;
5. montar um contexto editorial compacto;
6. aplicar as regras do perfil e o tipo do vídeo;
7. gerar diretamente o plano de edição;
8. validar o plano contra a análise e a timeline;
9. entregar o plano JSON e um resumo das decisões;
10. deixar a aplicação no Premiere para a etapa de confirmação do usuário.

O chat não deve devolver apenas uma sugestão textual quando o pedido for
“editar vídeo”. Deve gerar um plano estruturado, salvo em arquivo, pronto para
ser lido pelo `LeitorDePlanoDeEdicao`.

### Leitura dos registros sem desperdício de contexto

O banco pode ser lido integralmente pela engine em lotes, sem enviar todos os
registros para o chat ou para a IA. A leitura deve ser progressiva:

- primeiro, resumo, faixas, clipes e contagens;
- depois, falas do intervalo ou do objetivo escolhido;
- depois, métricas de voz quando o perfil depender de ritmo, intensidade ou
  pausas;
- depois, palavras somente para decisões que exigem precisão;
- por fim, cenas e evidências visuais relacionadas aos trechos candidatos.

“Ler na íntegra” significa garantir que a engine tenha acesso aos registros
necessários, não despejar o banco inteiro no contexto do modelo.

### Consultas criadas durante a edição

Quando surgir uma necessidade nova, a consulta deve ser criada como parte da
engine e documentada neste MD, contendo:

- nome da intenção consultada;
- parâmetros aceitos;
- SQL parametrizado;
- formato compacto de retorno;
- teste de regressão;
- perfil editorial que utiliza a consulta.

Consultas temporárias podem ser usadas para investigar um caso, mas não devem
virar parte do fluxo do chat sem serem transformadas em um método reutilizável
de `ConsultasDeAnalises` ou de um módulo de aplicação.

## 2. Vocabulário do domínio

- **Vídeo analisado**: registro de uma timeline no banco, identificado por `video_id`.
- **Faixa**: trilha de áudio ou vídeo pertencente ao vídeo analisado.
- **Clipe**: intervalo de uma faixa na timeline, com referência ao arquivo de origem.
- **Fala**: segmento de transcrição associado a um clipe, com início, fim e texto.
- **Palavra**: unidade sincronizada dentro de uma fala.
- **Métrica de voz**: sinal acústico calculado para uma fala, como energia, pitch, velocidade e pausas. Não é uma emoção classificada.
- **Cena**: intervalo visual identificado pelo Scanner.
- **Evidência**: observação visual ou sonora com intervalo e confiança.
- **Contexto editorial**: pacote compacto de fatos enviado à IA para apoiar uma decisão de edição.
- **Decisão editorial**: ação proposta pela IA, como corte, zoom, texto ou marcador.
- **Plano de edição**: conjunto ordenado e validado de decisões editoriais.
- **Aplicador**: módulo que executa o plano na timeline do Premiere.

Transcrição, análise, decisão e aplicação são etapas diferentes. Uma transcrição não deve ser interpretada automaticamente como uma decisão de corte.

## 3. Fluxo completo

```text
Premiere Pro
    │
    ├─ Scanner: lê a timeline e salva análise
    │       ├─ vídeos, faixas e clipes
    │       ├─ transcrição e palavras
    │       ├─ métricas acústicas opcionais
    │       ├─ cenas e evidências visuais
    │       └─ versão da análise
    │
    └─ Editar vídeo
            ├─ seleciona um vídeo analisado
            ├─ define objetivo e regras editoriais
            ├─ pede contexto editorial compacto à engine
            ├─ envia contexto à IA
            ├─ recebe plano JSON
            ├─ valida plano e origem
            ├─ mostra prévia das decisões
            └─ aplica plano pela engine
```

O Scanner produz fatos. A IA decide. A engine valida e aplica. A interface coordena e apresenta.

## 3.1. Fluxo pós-Scanner na tela Editar vídeo

Depois que o Scanner concluir, a tela **Editar vídeo** será a etapa de decisão
e aplicação:

```text
Scanner concluído
    ↓
Editar vídeo seleciona a análise do Scanner
    ↓
Usuário copia o JSON devolvido pela IA
    ↓
Cola o JSON no campo do plano
    ↓
Painel valida o formato e mostra as ações
    ↓
Usuário clica em Executar plano
    ↓
Painel salva um arquivo temporário UTF-8
    ↓
aplicar_plano_de_edicao.py
    ↓
LeitorDePlanoDeEdicao
    ↓
validação contextual e backup
    ↓
AplicadorDePlanoDeEdicao
    ↓
resultado ação por ação na tela
```

O clipboard serve somente para transportar o texto JSON até o painel. Ele não
deve ser executado como código nem enviado diretamente ao Premiere.

### Comportamento do campo de plano

Ao colar o JSON, a tela deve:

- fazer `JSON.parse` localmente;
- verificar se existe `source` e `actions`;
- mostrar quantidade e tipos de ações;
- mostrar erros de estrutura antes de liberar o botão;
- aceitar metadados extras como `schema`, `analysis` e `target`;
- não modificar o plano colado silenciosamente;
- salvar uma cópia com data e hora para auditoria.

### Comportamento do botão Executar plano

O botão deve chamar a entrada da engine, e não interpretar as ações no
JavaScript. A entrada é:

```text
code/engine/aplicar_plano_de_edicao.py <caminho-do-plano.json>
```

Essa entrada usa as mesmas classes do fluxo de aplicação da engine:

- `LeitorDePlanoDeEdicao` lê e valida o contrato;
- `BackupDaSequencia` cria uma cópia antes da mutação;
- `ConversorDeTimeline` lê a sequência ativa;
- `MapeadorDeTempoDeOrigemParaTimeline` encontra os clipes corretos;
- `AplicadorDePlanoDeEdicao` ordena e aplica as ações;
- `EscritaNoEditor` executa as alterações pelo bridge do Premiere;
- `ResultadoDaAplicacao` devolve sucesso ou falha por ação.

O painel deve exibir o resultado recebido, incluindo ações aplicadas, ações
que falharam, detalhes da falha e caminho do plano salvo.

### Diferença entre testar e executar

O fluxo **Testar ações** é um protótipo de validação manual do formato. O
fluxo definitivo **Executar plano** deve usar a entrada Python da engine para
compartilhar o mesmo domínio, mapeador, backup e aplicador. Não devem existir
duas implementações diferentes para cortar a mesma timeline.

### Segurança e confirmação

Antes de iniciar:

- confirmar que a sequência correta está ativa;
- conferir o arquivo de origem do plano;
- conferir a quantidade de ações;
- criar backup;
- pedir confirmação quando houver cortes.

Durante a execução, o painel deve permitir cancelar o processo e informar se o
cancelamento ocorreu antes ou depois de alguma ação. O resultado parcial deve
ser preservado para diagnóstico.

## 4. Situação atual do código

### Já existe

- `code/cep-plugin/`: painel CEP com **Editar vídeo** e **Scanner**.
- `code/engine/persistencia/esquema.py`: tabelas SQLite de timeline, transcrição, palavras, cenas e evidências.
- `code/engine/persistencia/repositorio_de_analises_sqlite.py`: persistência das análises.
- `code/engine/persistencia/consultas.py`: consultas de leitura compactas.
- `code/engine/scanner/transcricao_da_timeline.py`: transcrição projetada para os clipes da timeline.
- `code/engine/editor/modelos.py`: `PlanoDeEdicao` e `AcaoDeEdicao`.
- `code/engine/editor/leitura/leitor_de_plano.py`: validação do plano externo.
- `code/engine/editor/aplicador_de_plano_de_edicao.py`: aplicação das ações.
- `code/engine/aplicar_plano_de_edicao.py`: entrada da engine para aplicar um plano.
- `code/cep-plugin/main.js`: geração de `dados-para-ia.json` e aplicação do plano recebido.

### Lacunas conhecidas

- `listar_falas_no_intervalo()` não retorna métricas acústicas por padrão.
- Editar vídeo aceita o JSON de ações colado no painel ou carregado por arquivo e grava uma cópia local antes da aplicação.
- O contexto editorial ainda não é um módulo explícito da engine.
- O plano atual identifica a origem principalmente por nome e tempo; com várias faixas e clipes, precisa também de `video_id` e `clipe_id`.
- A validação contextual com `video_id`, versão da análise e `clipe_id` ainda precisa ser conectada ao aplicador.

## 5. Consultas SQL compactas

As consultas ficam na engine. O painel não abre SQLite nem monta SQL.

### 5.1. Listar vídeos analisados

```sql
SELECT id AS video_id, nome, duracao, criado_em
FROM videos
ORDER BY criado_em DESC
LIMIT :limite;
```

### 5.2. Resumo do vídeo

```sql
SELECT
    v.id AS video_id, v.nome, v.duracao, v.taxa_de_quadros,
    v.largura, v.altura,
    (SELECT COUNT(*) FROM faixas f WHERE f.video_id = v.id) AS total_faixas,
    (SELECT COUNT(*) FROM clipes c WHERE c.video_id = v.id) AS total_clipes,
    (SELECT COUNT(*) FROM segmentos_de_transcricao s WHERE s.video_id = v.id) AS total_falas,
    (SELECT COUNT(*) FROM cenas c WHERE c.video_id = v.id) AS total_cenas,
    (SELECT COUNT(*) FROM evidencias_visuais e WHERE e.video_id = v.id) AS total_evidencias
FROM videos v
WHERE v.id = :video_id;
```

### 5.3. Falas para edição

Consulta padrão, sem palavras e sem métricas:

```sql
SELECT s.id AS fala_id, s.clipe_id, s.inicio, s.fim, s.texto,
       s.confianca, s.falante, s.emocao, s.confianca_emocao
FROM segmentos_de_transcricao s
WHERE s.video_id = :video_id
  AND s.fim >= :inicio
  AND (:fim IS NULL OR s.inicio <= :fim)
ORDER BY s.inicio, s.id;
```

Consulta com métricas acústicas:

```sql
SELECT s.id AS fala_id, s.clipe_id, s.inicio, s.fim, s.texto,
       s.confianca, s.falante,
       s.caracteristicas_acusticas AS metricas_de_voz
FROM segmentos_de_transcricao s
WHERE s.video_id = :video_id
  AND s.fim >= :inicio
  AND (:fim IS NULL OR s.inicio <= :fim)
  AND s.caracteristicas_acusticas IS NOT NULL
  AND s.caracteristicas_acusticas <> '{}'
ORDER BY s.inicio, s.id;
```

`metricas_de_voz` deve ser convertido de texto JSON para objeto dentro da engine. O SQL não deve conhecer a estrutura variável das métricas.

### 5.4. Palavras sob demanda

```sql
SELECT p.segmento_id AS fala_id, p.ordem, p.texto, p.inicio, p.fim,
       p.confianca, p.falante
FROM palavras_de_transcricao p
WHERE p.segmento_id IN (:fala_ids)
ORDER BY p.segmento_id, p.ordem;
```

Na implementação, `:fala_ids` deve ser expandido com parâmetros SQLite individuais. Nunca interpolar valores da interface no SQL.

### 5.5. Cenas e evidências

```sql
SELECT clipe_id, inicio, fim, confianca
FROM cenas
WHERE video_id = :video_id
  AND (:clipe_id IS NULL OR clipe_id = :clipe_id)
ORDER BY inicio;
```

```sql
SELECT clipe_id, tipo, inicio, fim, valor, confianca, provider, modelo
FROM evidencias_visuais
WHERE video_id = :video_id
  AND (:clipe_id IS NULL OR clipe_id = :clipe_id)
  AND (:tipo IS NULL OR tipo = :tipo)
  AND (:confianca_minima IS NULL OR confianca IS NULL OR confianca >= :confianca_minima)
ORDER BY inicio;
```

## 6. Interface profunda da engine

O módulo principal deve esconder SQL, agrupamento, conversão de JSON, ordenação e redução de contexto.

Interface proposta:

```python
contexto = montador.montar(
    video_id=video_id,
    objetivo=objetivo_editorial,
    inicio=inicio,
    fim=fim,
    incluir_metricas=True,
    incluir_palavras=False,
)
```

Responsabilidades de `MontadorDeContextoEditorial`:

- validar `video_id` e intervalos;
- localizar o resumo do vídeo;
- buscar falas no intervalo;
- incluir métricas somente quando solicitado;
- buscar palavras somente quando solicitado;
- agrupar falas por clipe;
- anexar cenas e evidências relevantes;
- remover campos vazios;
- normalizar números e intervalos;
- produzir um contrato estável para a IA;
- informar a versão da análise usada.

O painel chama uma entrada da engine e recebe JSON. Não conhece tabelas nem SQL.

## 7. Contexto enviado à IA

```json
{
  "schema": "contexto_editorial_v1",
  "analysis": {
    "video_id": "12669c9c-038d-4a3f-99f9-fe6f6827b5f4",
    "versao": "hash-da-analise",
    "fonte": "scanner"
  },
  "video": { "nome": "Cópia de 0E6A8829", "duracao": 120.0 },
  "objetivo": {
    "tipo": "depoimento",
    "instrucao": "Remover pausas longas e repetições sem perder autenticidade.",
    "preservar": ["contexto", "frases completas", "pausas emocionais"],
    "remover": ["silêncios longos", "repetições", "erros explícitos"]
  },
  "falas": [
    {
      "fala_id": 42,
      "clipe_id": "000f476b",
      "inicio": 12.45,
      "fim": 15.82,
      "texto": "Eu comecei esse processo no ano passado.",
      "falante": "SPEAKER_00",
      "metricas_de_voz": {
        "energy_rms": 0.084,
        "pitch_hz_median": 187.5,
        "pitch_hz_std": 32.8,
        "speaking_rate_wps": 2.4,
        "longest_internal_pause_s": 0.42,
        "gap_before_s": 0.18
      }
    }
  ],
  "cenas": [],
  "evidencias_visuais": []
}
```

Perfis de tamanho:

- `resumo`: metadados, contagens e intervalos principais;
- `fala`: falas, locutores e métricas, sem palavras;
- `precisao`: falas, palavras e evidências do intervalo selecionado;
- `completo`: somente para diagnóstico local, nunca como padrão para IA.

O fluxo normal começa com `resumo` ou `fala` e consulta `precisao` somente quando necessário.

## 8. Decisões e plano de edição

O plano mantém o contrato já validado pela engine e recebe metadados para impedir aplicação em outra análise:

```json
{
  "schema": "plano_edicao_v2",
  "source": "Cópia de 0E6A8829",
  "analysis": {
    "video_id": "12669c9c-038d-4a3f-99f9-fe6f6827b5f4",
    "versao": "hash-da-analise"
  },
  "actions": [
    {
      "id": "acao-001",
      "kind": "cut",
      "target": {
        "clipe_id": "000f476b",
        "arquivo_de_origem": "/caminho/video.mp4"
      },
      "start": 20.4,
      "end": 23.8,
      "reason": "Pausa longa sem conteúdo entre duas frases.",
      "params": { "tipo": "silencio", "confianca": 0.91 }
    }
  ]
}
```

Regras para a IA:

- não inventar tempos fora do material analisado;
- não cortar fala sem `reason`;
- usar segundos na origem;
- não usar tempo relativo ao JSON;
- não alterar a transcrição original;
- indicar confiança baixa quando houver dúvida;
- não aplicar o plano diretamente no Premiere.

## 9. Validação antes da aplicação

### Validação estrutural

Responsável: `LeitorDePlanoDeEdicao`.

- JSON válido;
- `source` preenchido;
- `actions` não vazio;
- tipo conhecido;
- início e fim numéricos;
- fim maior que início;
- motivo obrigatório.

### Validação contextual

Novo comportamento a adicionar:

- `video_id` do plano igual ao vídeo selecionado;
- versão da análise ainda válida;
- `clipe_id` existente;
- arquivo de origem compatível;
- intervalo contido no clipe ou na origem;
- nenhuma ação duplicada;
- nenhuma ação já aplicada;
- plano compatível com a sequência ativa.

## 10. Fluxo da tela Editar vídeo

O Scanner acontece antes da tela de edição. Dentro da tela **Editar vídeo**,
o fluxo terá somente três etapas, mantendo a experiência já conhecida:

### Etapa 3 — Revisar falantes e áudio (opcional)

Esta etapa recebe a análise do Scanner e permite:

- revisar ou nomear falantes quando a diarização estiver disponível;
- conferir a transcrição e os intervalos;
- conferir métricas de voz quando tiverem sido calculadas;
- definir ou revisar o perfil editorial;
- definir o tipo e o objetivo do vídeo;
- escolher regras como remoção de silêncios, repetições e hesitações.

Quando a edição usar somente transcrição, a revisão de falantes continua
opcional. O botão de avanço não deve exigir diarização.

### Etapa 4 — Gerar arquivo JSON

Esta etapa reúne:

- a análise selecionada do Scanner;
- as falas e palavras necessárias;
- as métricas solicitadas;
- o perfil editorial;
- o tipo e objetivo do vídeo;
- as regras de edição.

A engine gera o contexto editorial para a IA. Depois que a IA devolver o plano,
o usuário poderá colar o JSON no campo da etapa ou selecionar um arquivo. O
painel valida a estrutura e mostra a quantidade de `actions` antes de liberar
a etapa seguinte.

O arquivo gerado/devolvido deve continuar sendo UTF-8 e conter `source` e
`actions`, podendo também conter `analysis`, `schema`, `target` e metadados
editoriais.

### Etapa 5 — Aplicar na timeline

Esta etapa:

- mostra o resumo das ações;
- confirma a sequência ativa;
- cria backup;
- valida a origem e os intervalos;
- chama `aplicar_plano_de_edicao.py`;
- usa as classes oficiais da engine;
- exibe o resultado ação por ação;
- preserva o relatório em caso de falha ou cancelamento.

Não criar novas etapas para seleção de fonte, contexto ou aplicação. Essas
responsabilidades devem aparecer dentro das três etapas existentes.

## 11. Classes e módulos planejados

### Domínio

`code/engine/editor/contexto_editorial/modelos.py`

- `ContextoEditorial`;
- `FalaEditorial`;
- `MetricaDeVozEditorial`;
- `ObjetivoEditorial`.

Essas classes não conhecem SQLite, JSON de transporte ou Premiere.

### Aplicação

`code/engine/editor/contexto_editorial/montador.py`

- `MontadorDeContextoEditorial`.

Essa é a interface profunda: recebe filtros editoriais e devolve contexto compacto, escondendo consultas, agrupamento e normalização.

### Persistência

Estender `ConsultasDeAnalises` com:

- `listar_videos_analisados()`;
- `consultar_contexto_editorial()`;
- `listar_falas_editoriais()`;
- `listar_palavras_das_falas()`.

### Transporte

Criar `code/engine/gerar_contexto_editorial.py` para ler pedido JSON, validar entrada, chamar o montador e escrever resposta JSON.

### Plano

Reutilizar `LeitorDePlanoDeEdicao`, `PlanoDeEdicao` e `AplicadorDePlanoDeEdicao`, adicionando a validação contextual antes do aplicador.

## 12. Versionamento e idempotência

Cada execução do Scanner deve ter uma identidade de análise. O editor deve guardar essa identidade no contexto e no plano.

Recomendações:

- usar `analises_versao` para registrar etapa e hash da entrada;
- incluir configuração, modelo, idioma e faixas no hash;
- invalidar o plano quando a timeline ou o vídeo mudar;
- substituir ou versionar segmentos ao reprocessar;
- não acumular silenciosamente duas transcrições iguais.

Antes do editor, corrigir a política de reprocessamento para evitar duplicidade em `segmentos_de_transcricao`.

## 13. Testes obrigatórios

- consultas filtram por vídeo e intervalo;
- métricas aparecem somente quando solicitadas;
- palavras não aparecem por padrão;
- contexto compacto agrupa falas por clipe;
- campos vazios são removidos;
- palavras são carregadas sob demanda;
- plano de outro vídeo é rejeitado;
- plano de análise antiga é rejeitado;
- ação fora do clipe é rejeitada;
- aplicação cria backup e não repete ação;
- interface seleciona análise, importa plano e mostra validação;
- cancelamento interrompe a geração/aplicação.

## 14. Ordem de implementação

- [ ] Consultas de vídeos analisados.
- [ ] Consulta de falas com opção de métricas.
- [ ] Consulta de palavras sob demanda.
- [ ] Modelos de `ContextoEditorial`.
- [ ] `MontadorDeContextoEditorial`.
- [ ] `gerar_contexto_editorial.py`.
- [ ] Versionamento e reprocessamento no banco.
- [ ] Origem “Usar análise do Scanner” na tela Editar vídeo.
- [ ] Renderização do contexto e das falas.
- [ ] Exportação do contexto para IA.
- [ ] Plano com `video_id`, `clipe_id` e versão.
- [ ] Validação contextual.
- [ ] Aplicação pela engine.
- [ ] Teste em cópia da sequência.
- [ ] Revisão final do código.

## 15. Critério de conclusão

O recurso estará pronto quando o usuário conseguir executar o Scanner uma vez, abrir Editar vídeo, escolher o vídeo analisado, buscar somente as falas necessárias, gerar contexto compacto, importar um plano, validá-lo contra a análise correta, revisar as ações e aplicá-las na timeline com backup, sem repetir a transcrição.

Este documento deve ser atualizado a cada etapa implementada, especialmente quando um contrato JSON ou uma consulta SQL mudar.