feat: initial commit - Jhonny Editor

- Adicionado estrutura completa do projeto - Configurado MCP server para Premiere Pro - Adicionado documentação e skills - Configurado Gitignore para o projeto
2026-09-08 09:59:31 -04:00
commit b541f502ba
1507 changed files with 387650 additions and 0 deletions
@@ -0,0 +1,641 @@
+# 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.**