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:

{
  "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

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.

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 ainda trabalha principalmente com transcricao.json e não seleciona diretamente uma análise do Scanner.
• 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.
• Reprocessamentos precisam de uma política explícita para não duplicar segmentos no banco.

5. Consultas SQL compactas

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

5.1. Listar vídeos analisados

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

5.2. Resumo do vídeo

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:

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:

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

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

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;

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:

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

{
  "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:

{
  "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

1. Selecionar origem: Transcrever este vídeo ou Usar análise do Scanner.
2. Listar análises disponíveis e mostrar modelo, idioma, diarização, métricas e data.
3. Escolher objetivo: depoimento, entrevista, redes sociais ou personalizado.
4. Definir regras: remover silêncio, remover repetição, preservar pausas emocionais, locutores e intensidade.
5. Carregar contexto compacto pela engine.
6. Mostrar falas, tempos, locutores, métricas e status da análise.
7. Exportar contexto para IA ou chamar um Provider de IA futuramente.
8. Importar o plano devolvido.
9. Mostrar cada ação com intervalo, texto, motivo, confiança e validação.
10. Criar backup, validar e aplicar pela engine.

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.