# 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.**