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.

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:

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 é:

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

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

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.