jhonny-editor/code/engine/ARQUITETURA.md

Instrução de Arquitetura da Engine

Este documento define o papel de cada classe, suas responsabilidades e o que ela não deve fazer.

Estrutura do módulo scanner

O módulo scanner será responsável por analisar uma timeline completa antes que qualquer decisão de edição seja tomada.

Ele deverá apenas descobrir, processar, organizar e salvar informações sobre o material audiovisual.

O scanner não deverá decidir quais trechos serão cortados, nem aplicar cortes na timeline. Essas responsabilidades pertencem aos módulos posteriores, como o motor de decisão, o gerador de plano e o aplicador.

scanner/
├── coordenacao/
├── descoberta/
├── metadados/
├── audio/
├── transcricao/
├── visual/
├── cenas/
├── eventos/
├── retakes/
└── persistencia/

---

1. Submódulo coordenacao

O submódulo coordenacao será responsável por organizar a execução do scanner.

Ele não fará a análise técnica dos vídeos. Sua função será controlar o fluxo, compartilhar o contexto e garantir que as análises sejam executadas na ordem correta.

AnalisadorDeTimeline

Papel

Será a classe principal de entrada do scanner.

Ela receberá uma timeline ou uma representação dela e iniciará o processo completo de análise.

Responsabilidades

• Receber a timeline que será analisada.
• Criar o contexto inicial da análise.
• Montar ou receber o pipeline de análises.
• Iniciar a execução do pipeline.
• Retornar o resultado completo da análise.
• Informar o status geral do processo.
• Tratar erros gerais de execução.
• Permitir que a análise seja iniciada, interrompida ou retomada futuramente.

Não deve fazer

• Extrair áudio diretamente.
• Transcrever vídeos.
• Detectar cenas.
• Analisar imagens.
• Detectar retakes.
• Decidir cortes.
• Alterar a timeline original.

---

PipelineDoScanner

Papel

Será responsável por executar as análises na ordem definida.

Ele funcionará como o controlador do fluxo interno do scanner.

Responsabilidades

• Receber uma lista de componentes de análise.
• Executar cada componente na ordem correta.
• Entregar o mesmo contexto para a próxima análise.
• Registrar quais análises já foram executadas.
• Permitir execução parcial ou completa.
• Identificar falhas em etapas específicas.
• Permitir que determinadas análises sejam opcionais.
• Permitir futuramente execução paralela quando não houver dependências entre as análises.

Exemplo de ordem

Descoberta da timeline
        ↓
Descoberta de clipes
        ↓
Extração de metadados
        ↓
Extração de áudio
        ↓
Transcrição
        ↓
Análise visual
        ↓
Detecção de cenas
        ↓
Detecção de eventos
        ↓
Detecção de retakes
        ↓
Persistência

Não deve fazer

• Implementar algoritmos de análise.
• Conhecer detalhes do Whisper, OpenCV, FFmpeg ou outros providers.
• Fazer chamadas diretas para APIs de IA.
• Tomar decisões de edição.

---

ContextoDeAnalise

Papel

Será o objeto que transportará todos os dados durante o processo de análise.

Ele funcionará como um estado compartilhado entre as classes do scanner.

Responsabilidades

• Armazenar a timeline analisada.
• Armazenar sequências, faixas e clipes.
• Armazenar caminhos dos arquivos.
• Armazenar metadados técnicos.
• Armazenar áudios extraídos.
• Armazenar transcrições.
• Armazenar quadros extraídos.
• Armazenar cenas detectadas.
• Armazenar eventos encontrados.
• Armazenar possíveis retakes.
• Armazenar avisos, erros e status.
• Armazenar informações de execução.
• Permitir que os resultados sejam serializados.

Não deve fazer

• Executar análises.
• Chamar providers diretamente.
• Decidir cortes.
• Alterar a timeline no editor.

---

2. Submódulo descoberta

O submódulo descoberta será responsável por identificar o que existe na timeline e onde os arquivos estão localizados.

DescobertaDaTimeline

Papel

Será responsável por descobrir a estrutura lógica da timeline.

Responsabilidades

• Identificar a sequência ativa.
• Identificar outras sequências, quando necessário.
• Identificar as faixas de vídeo.
• Identificar as faixas de áudio.
• Identificar os clipes presentes em cada faixa.
• Identificar a ordem dos clipes.
• Identificar o posicionamento temporal dos clipes.
• Identificar os vínculos entre áudio e vídeo.
• Identificar transições e elementos existentes.
• Identificar clipes desativados ou ocultos.
• Criar uma representação interna da timeline.

Não deve fazer

• Analisar o conteúdo visual.
• Transcrever o áudio.
• Detectar retakes.
• Decidir se um clipe será mantido ou removido.

---

DescobertaDeClipes

Papel

Será responsável por transformar os elementos encontrados na timeline em objetos de clipe que possam ser analisados pelo sistema.

Responsabilidades

• Criar uma representação individual para cada clipe.
• Registrar o identificador do clipe.
• Registrar a faixa em que o clipe está.
• Registrar o tempo de início e fim na timeline.
• Registrar o tempo de início e fim no arquivo original.
• Registrar a duração.
• Registrar a posição relativa.
• Registrar vínculos com outros clipes.
• Identificar clipes de vídeo, áudio, imagens ou outros tipos de mídia.

Não deve fazer

• Analisar o conteúdo do clipe.
• Gerar transcrição.
• Detectar cenas.
• Alterar a posição do clipe.

---

DescobertaDeArquivos

Papel

Será responsável por localizar os arquivos físicos relacionados aos clipes.

Responsabilidades

• Resolver o caminho original do arquivo.
• Verificar se o arquivo existe.
• Identificar arquivos offline.
• Identificar arquivos duplicados.
• Identificar arquivos substituídos ou relinkados.
• Normalizar caminhos.
• Registrar permissões de acesso.
• Identificar o tipo de mídia.
• Preparar os arquivos para os providers.

Não deve fazer

• Extrair metadados detalhados.
• Transcrever áudio.
• Analisar imagens.
• Corrigir automaticamente arquivos ausentes sem autorização.

---

3. Submódulo metadados

ExtracaoDeMetadados

Papel

Será responsável por extrair informações técnicas dos arquivos de mídia.

Responsabilidades

• Identificar resolução.
• Identificar largura e altura.
• Identificar taxa de quadros.
• Identificar duração.
• Identificar codec de vídeo.
• Identificar codec de áudio.
• Identificar quantidade de canais.
• Identificar taxa de amostragem.
• Identificar profundidade de bits.
• Identificar orientação.
• Identificar timecode.
• Identificar tamanho do arquivo.
• Identificar formato do contêiner.
• Identificar informações de gravação, quando disponíveis.
• Registrar erros de leitura.

Não deve fazer

• Avaliar se a imagem está boa.
• Avaliar se o áudio está ruim.
• Detectar retakes.
• Decidir quais arquivos serão usados na edição.

---

4. Submódulo audio

ExtracaoDeAudio

Papel

Será responsável por preparar o áudio dos vídeos para as demais análises.

Responsabilidades

• Extrair o áudio dos arquivos de vídeo.
• Gerar arquivos temporários ou intermediários.
• Normalizar o formato de áudio quando necessário.
• Definir taxa de amostragem adequada.
• Separar canais quando necessário.
• Associar o áudio extraído ao clipe original.
• Registrar o caminho do áudio gerado.
• Evitar extrações repetidas.
• Controlar arquivos temporários.
• Validar se o áudio foi extraído corretamente.

Não deve fazer

• Transcrever o áudio.
• Avaliar o conteúdo da fala.
• Decidir se há um retake.
• Alterar o áudio da timeline.

---

AnaliseDeAudio

Papel

Será responsável por analisar tecnicamente e temporalmente o áudio.

Responsabilidades

• Detectar silêncio.
• Detectar pausas.
• Medir volume.
• Medir energia sonora.
• Identificar picos de áudio.
• Identificar possíveis distorções.
• Identificar ruído.
• Identificar clipping.
• Identificar trechos com baixa inteligibilidade.
• Identificar início e fim de fala.
• Identificar sobreposição de vozes, quando possível.
• Produzir marcadores temporais de eventos sonoros.

Não deve fazer

• Transcrever o áudio.
• Decidir automaticamente quais trechos serão cortados.
• Substituir a análise de conteúdo feita pela transcrição.

---

5. Submódulo transcricao

TranscricaoDeAudio

Papel

Será responsável por transformar o áudio em texto sincronizado com o tempo do vídeo.

Responsabilidades

• Enviar o áudio para o provider de transcrição.
• Receber segmentos transcritos.
• Registrar texto, início e fim de cada segmento.
• Registrar palavras individuais, quando disponíveis.
• Registrar nível de confiança.
• Identificar locutores, quando suportado.
• Associar a transcrição ao clipe correto.
• Detectar falhas de transcrição.
• Permitir transcrição parcial.
• Reaproveitar transcrições já existentes.
• Preservar a sincronização temporal.

Não deve fazer

• Decidir se uma fala deve ser cortada.
• Interpretar sozinho se o trecho é um retake.
• Alterar a timeline.
• Implementar diretamente o modelo de transcrição.

O modelo utilizado deverá ficar no módulo providers/transcricao/.

---

6. Submódulo visual

Regra de acesso ao Premiere

Sempre que o Scanner precisar acessar a timeline, a sequência ativa, as faixas ou os clipes, deve utilizar AcessoAoEditor em engine.integracoes.premiere.leitura. Essa classe já encapsula o cliente MCP e é a única porta de leitura do Premiere para o Engine.

O submódulo visual recebe uma Timeline de domínio pelo ContextoDeAnalise; seus adapters não devem chamar o MCP, o CEP ou o UXP diretamente. Em testes, injete uma timeline pronta ou um fake de AcessoAoEditor na etapa de descoberta.

ExtracaoDeQuadros

Papel

Será responsável por selecionar e extrair quadros representativos dos vídeos.

Responsabilidades

• Extrair o primeiro quadro.
• Extrair o quadro central.
• Extrair o último quadro.
• Extrair quadros em intervalos regulares.
• Extrair quadros próximos a eventos.
• Extrair quadros próximos a mudanças de cena.
• Redimensionar imagens para análise.
• Evitar extrações duplicadas.
• Associar cada quadro ao tempo exato do vídeo.
• Armazenar os quadros temporariamente ou em cache.

Não deve fazer

• Interpretar o conteúdo da imagem.
• Classificar a qualidade visual.
• Detectar retakes.
• Escolher o melhor quadro para a edição.

---

AnaliseVisual

Papel

Será responsável por coordenar a interpretação do conteúdo visual dos quadros e dos vídeos.

Responsabilidades

• Analisar enquadramento.
• Identificar objetos.
• Identificar pessoas.
• Identificar rostos, quando permitido e necessário.
• Avaliar foco.
• Avaliar exposição.
• Avaliar estabilidade.
• Identificar movimentos de câmera.
• Identificar mudanças de composição.
• Descrever o conteúdo visual.
• Comparar quadros.
• Gerar características visuais que possam ser utilizadas na detecção de cenas e retakes.

Não deve fazer

• Detectar cortes diretamente, salvo quando isso fizer parte do provider visual.
• Decidir quais tomadas serão utilizadas.
• Alterar o vídeo.
• Implementar diretamente os modelos de visão.

---

7. Submódulo cenas

DeteccaoDeCenas

Papel

Será responsável por identificar mudanças de cena e possíveis limites entre tomadas.

Responsabilidades

• Detectar cortes abruptos.
• Detectar transições.
• Detectar mudanças graduais.
• Identificar possíveis inícios e finais de tomadas.
• Combinar resultados de diferentes providers.
• Comparar mudanças visuais entre quadros.
• Utilizar informações de áudio quando necessário.
• Registrar o tempo de cada cena.
• Registrar o nível de confiança.
• Identificar cenas semelhantes.
• Evitar duplicidade entre resultados de providers.

Não deve fazer

• Decidir qual cena será utilizada na edição.
• Excluir clipes.
• Aplicar cortes.
• Depender de apenas uma ferramenta específica.

A classe deverá trabalhar com contratos de providers, por exemplo:

DeteccaoDeCenas
        ↓
ProviderDeDeteccaoDeCenas
        ├── ProviderPySceneDetect
        ├── ProviderOpenCV
        └── ProviderModeloDeIA

---

8. Submódulo eventos

DeteccaoDeEventos

Papel

Será responsável por identificar acontecimentos relevantes dentro dos clipes.

Responsabilidades

• Identificar início de fala.
• Identificar fim de fala.
• Identificar pausas.
• Identificar silêncio.
• Identificar risadas.
• Identificar tosse.
• Identificar interrupções.
• Identificar erros de fala.
• Identificar mudanças de assunto.
• Identificar entrada ou saída de pessoas.
• Identificar alterações importantes de imagem.
• Identificar problemas técnicos.
• Registrar cada evento com início, fim e confiança.

Não deve fazer

• Decidir automaticamente o corte.
• Remover eventos.
• Alterar a timeline.
• Confundir evento detectado com decisão de edição.

O evento será apenas uma informação para o motor de decisão utilizar posteriormente.

---

9. Submódulo retakes

DeteccaoDeRetakes

Papel

Será responsável por identificar possíveis repetições ou versões alternativas de uma mesma gravação.

Responsabilidades

• Comparar transcrições.
• Comparar características visuais.
• Comparar áudio.
• Comparar duração.
• Comparar sequência de falas.
• Comparar enquadramento.
• Identificar tomadas próximas temporalmente.
• Identificar grupos de tomadas semelhantes.
• Identificar possíveis erros repetidos.
• Identificar versões alternativas da mesma fala.
• Calcular nível de similaridade.
• Registrar evidências que justificam a possibilidade de retake.
• Classificar o resultado como possível, provável ou confirmado, quando houver evidências suficientes.

Não deve fazer

• Decidir qual retake será utilizado.
• Excluir automaticamente uma tomada.
• Aplicar cortes.
• Considerar apenas a similaridade visual.
• Tratar toda repetição como erro.

O resultado deverá ser algo semelhante a:

Grupo de retakes:
- Tomada 01
- Tomada 02
- Tomada 03

Evidências:
- Transcrição semelhante
- Enquadramento semelhante
- Áudio semelhante
- Intervalo temporal próximo

Confiança:
0.87

---

10. Submódulo persistencia

PersistenciaDaAnalise

Papel

Será responsável por salvar os resultados produzidos pelo scanner.

Responsabilidades

• Salvar a estrutura descoberta da timeline.
• Salvar os metadados.
• Salvar os caminhos dos arquivos.
• Salvar as transcrições.
• Salvar os resultados visuais.
• Salvar as cenas.
• Salvar os eventos.
• Salvar os possíveis retakes.
• Salvar logs e avisos.
• Permitir retomada de uma análise interrompida.
• Evitar processamento duplicado.
• Versionar os resultados quando necessário.
• Exportar os dados em formato estruturado, como JSON.

Não deve fazer

• Gerar plano de corte.
• Aplicar alterações no editor.
• Decidir quais clipes serão mantidos.
• Alterar os arquivos originais.

---

Visão final das responsabilidades

AnalisadorDeTimeline
    Inicia a análise completa.

PipelineDoScanner
    Controla a ordem de execução.

ContextoDeAnalise
    Transporta e armazena os dados.

DescobertaDaTimeline
    Descobre a estrutura da timeline.

DescobertaDeClipes
    Representa os clipes encontrados.

DescobertaDeArquivos
    Localiza os arquivos físicos.

ExtracaoDeMetadados
    Obtém informações técnicas.

ExtracaoDeAudio
    Prepara o áudio.

AnaliseDeAudio
    Analisa características sonoras.

TranscricaoDeAudio
    Converte fala em texto sincronizado.

ExtracaoDeQuadros
    Seleciona quadros para análise.

AnaliseVisual
    Interpreta o conteúdo visual.

DeteccaoDeCenas
    Identifica limites e mudanças de cena.

DeteccaoDeEventos
    Identifica acontecimentos relevantes.

DeteccaoDeRetakes
    Identifica possíveis repetições.

PersistenciaDaAnalise
    Salva todos os resultados.

A regra mais importante para o programador será:

Nenhuma classe do scanner deverá tomar decisões de edição. O scanner apenas coleta e organiza evidências. A decisão sobre cortar, manter, substituir ou reorganizar trechos será feita por outro módulo.