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.

```text
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

```text
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`

## `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:

```text
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:

```text
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

```text
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.**