jhonny-editor/code/engine/integracoes/visual/README.md

Análise visual local

Configuração no painel

A configuração do Scanner é apresentada na aba Scanner do painel CEP em code/cep-plugin/. O perfil salvo segue o contrato versionado de ConfiguracaoVisualDoScanner; ele define amostragem, faixas, recursos Vision, cenas, continuidade, reenquadramento e interpretação antes de montar os adapters.

Acesso à timeline do Premiere

Quando a análise precisar ler a timeline, a sequência ativa, as faixas ou os clipes do Premiere, use sempre a classe existente engine.integracoes.premiere.leitura.AcessoAoEditor. O módulo visual não deve criar chamadas MCP, abrir processos do Premiere ou acessar o bridge diretamente.

O acesso deve seguir esta composição:

from engine.integracoes.premiere.leitura import AcessoAoEditor, AcessoATimeline
from engine.scanner import DescobertaDaTimeline
from engine.integracoes.premiere.conversores import ConversorDeTimeline

acesso_ao_editor = AcessoAoEditor(AcessoATimeline(cliente_mcp))
descoberta = DescobertaDaTimeline(acesso_ao_editor, ConversorDeTimeline())

Depois, a timeline convertida entra no ContextoDeAnalise e o Scanner executa AnaliseVisualDaTimeline. A classe de acesso isola o MCP e preserva a separação entre a integração com o Premiere e os analyzers locais.

Não duplicar esse acesso em novos adapters ou analyzers. Para testes, injetar um fake de AcessoAoEditor/AcessoATimeline ou usar uma timeline de domínio pronta.

Captura para análise visual

A análise visual não exporta um frame renderizado pelo Premiere. Para cada clipe de vídeo, o fluxo usa os campos retornados pelo MCP em get_active_sequence:

1. sourceFile identifica o arquivo original do projectItem.
2. inPoint e outPoint delimitam o trecho usado pelo clipe.
3. O extrator abre sourceFile localmente e amostra o primeiro frame do trecho, usando inPoint como tempo inicial na origem.
4. Vision/OpenCV/ONNX recebem esse frame persistido, mantendo o timestamp de origem; nenhum frame é exportado da timeline do Premiere.

Portanto, start/end são tempos da timeline e inPoint/outPoint são tempos do arquivo original. Não misturar esses relógios ao analisar um clipe.

O Scanner usa apenas as interfaces em contratos.py. As bibliotecas externas ficam em adapters concretos, para que possam ser habilitadas, substituídas ou testadas isoladamente.

Papel	Adapter
Extrair frames	ExtratorDeQuadrosOpenCV
Medir qualidade	AnalisadorDeQualidadeOpenCV
Rosto e olhos visíveis	AnalisadorDeRostosOpenCV
Composição e área para legendas	AnalisadorDeComposicaoOpenCV
Tremor/movimento de câmera	AnalisadorDeTremorOpenCV
Continuidade e frame congelado	AnalisadorDeContinuidadeOpenCV
Detectar objetos	AnalisadorDeObjetosONNX
Detectar pose e mãos	AnalisadorDePoseMediaPipe
Reconhecer a mesma pessoa entre tomadas (assinatura facial)	AnalisadorDeRostosInsightFace
OCR e faces macOS	AnalisadorAppleVision
Vision + Apple Intelligence (Swift isolado)	AnalisadorAppleVisionNativo
Similaridade temporal por feature print	AnalisadorSequenciaAppleVisionNativo
Extrair frames para Vision sem OpenCV	ExtratorDeQuadrosFFmpeg
Detectar cenas	DetectorDeCenasPySceneDetect

AnalisadorDeObjetosONNX exige dois adapters específicos do modelo: preparar(imagem, entradas) e decodificar(saidas, quadro). Isso mantém os detalhes de cada arquivo ONNX fora do Scanner e permite trocar de modelo sem alterar a interface do domínio.

AnalisadorDePoseMediaPipe recebe caminhos explícitos para os arquivos .task de pose e mãos. Os modelos ficam em /Volumes/Merongo/SISTEMAS/MODELOSIA/mediapipe/ e não são acoplados ao pacote Python. Ele executa em subprocesso: falhas nativas do MediaPipe são contidas e retornam como indisponibilidade do adapter, sem encerrar o processo do Scanner.

AnalisadorDeRostosOpenCV usa os arquivos locais haarcascade_frontalface_default.xml e haarcascade_eye.xml. Quando a distribuição do OpenCV não os incluir, forneça diretorio_de_modelos apontando para a pasta que os contém. Ele entra automaticamente no detector local (criar_detector_visual_local) quando "faces" está em recursos_vision (padrão do perfil).

AnalisadorDeRostosInsightFace resolve o que nem o OpenCV nem o Apple Vision fazem: reconhecer que o rosto de um clipe é a mesma pessoa de outro clipe. Ele devolve duas evidências por rosto — rosto (mesma forma de bounding box dos outros adapters) e identidade_facial (com assinatura_facial, um vetor de 512 posições, mais idade_aproximada/genero_aparente quando o modelo os estimar). Aceita tanto o frame decodificado em quadro.imagem (pipeline OpenCV) quanto um frame persistido em quadro.caminho (pipeline Apple Vision/FFmpeg), lendo o PNG com OpenCV nesse segundo caso. Por ser mais pesado (baixa o modelo buffalo_l na primeira execução), só entra nos detectores locais e no detector Apple Vision quando perfil.identidade_facial=True — desligado por padrão.

AnalisadorAppleVisionNativo é a opção Apple recomendada. Seu runner Swift executa faces/landmarks, qualidade facial, pessoas, pose, mãos, OCR, classificação e estética de forma independente. A interpretação editorial pelo FoundationModels só é criada a partir dessas evidências e é salva em separado. Falhas nativas por recurso viram diagnostico_apple_vision, sem derrubar o Scanner nem descartar os fatos que funcionaram.

Além de rostos, pessoas, pose, mãos, OCR, categorias e estética, o runner Apple retorna códigos/QR, horizonte, retângulos, densidade de contornos, ocupação da máscara de pessoas e similaridade visual entre frames. Os valores são fatos normalizados; descrição, contexto e ação devem ser derivados depois, a partir dessas evidências temporizadas.

Montagem

from engine.integracoes.visual import (
    AnalisadorDeQualidadeOpenCV,
    AnalisadorDeRostosOpenCV,
    AnalisadorDeComposicaoOpenCV,
    AnalisadorDeTremorOpenCV,
    AnalisadorDeContinuidadeOpenCV,
    DetectorDeCenasPySceneDetect,
    ExtratorDeQuadrosOpenCV,
)
from engine.scanner.visual import DetectorDeCenas

detector = DetectorDeCenas(
    ExtratorDeQuadrosOpenCV(intervalo_em_segundos=1.0, diretorio_de_cache=".frames"),
    analisadores_de_frame=[
        AnalisadorDeQualidadeOpenCV(), AnalisadorDeRostosOpenCV(),
        AnalisadorDeComposicaoOpenCV(),
    ],
    analisadores_de_sequencia=[
        AnalisadorDeTremorOpenCV(), AnalisadorDeContinuidadeOpenCV(),
    ],
    detectores_de_intervalo=[DetectorDeCenasPySceneDetect()],
)

Depois, passe esse DetectorDeCenas para AnaliseVisualDaTimeline ao montar o PipelineDoScanner.

Para o caminho local padrão, a montagem pode ser reduzida a:

from engine.scanner import AnaliseVisualDaTimeline, PipelineDoScanner, criar_detector_visual_local

pipeline = PipelineDoScanner([AnaliseVisualDaTimeline(criar_detector_visual_local())])
contexto = pipeline.executar(contexto)

O resultado fica em contexto.caracteristicas_visuais (por clipe), contexto.cenas_visuais (cenas com observações) e contexto.avisos. Quando OpenCV/FFmpeg ou outro adapter opcional não estiver disponível, o clipe é marcado com disponivel=False e os demais continuam sendo processados.

Montagem recomendada para Apple Vision

from engine.scanner import AnaliseVisualDaTimeline, PipelineDoScanner, criar_detector_apple_vision

pipeline = PipelineDoScanner([
    AnaliseVisualDaTimeline(criar_detector_apple_vision(intervalo_em_segundos=1.0)),
])

Esse detector extrai PNGs do arquivo original com FFmpeg, usando o intervalo inPoint/outPoint do clipe, e não exporta imagens renderizadas pelo Premiere. Ele também recua a amostra no fim de vídeos muito curtos quando não há um frame decodificável exatamente no timestamp solicitado.

Os analyzers de sequência não tentam concluir a intenção de uma pessoa. Eles retornam indícios temporais (possivel_tremor, possivel_descontinuidade e possivel_frame_congelado) para que a camada editorial decida como tratá-los.