jhonny-editor/code/docs/levantamento-apple-vision-e-apple-intelligence.md

Levantamento: Apple Vision e Apple Intelligence para análise editorial de vídeo

Data: 2026-09-08
Escopo: analisar vídeos localmente, construir contexto confiável para o programa e, somente depois, pedir à IA uma seleção editorial revisável.

Resumo executivo

A ideia é viável, mas a primeira entrega deve ser um arquivo cronológico de contexto multimodal, não um motor de decisão editorial. Esse arquivo será a fonte que posteriormente poderá ser lida pelo editor humano ou por uma IA de decisão.

O pipeline tem duas camadas:

1. Apple Vision + AVFoundation leem os frames e produzem fatos temporais: texto, rostos, pessoas, pose, códigos, saliência, qualidade, similaridade e movimento.
2. Apple Intelligence via Foundation Models, inicialmente opcional, pode transformar os fatos em descrições de cena e resumos. Mais adiante, outra chamada de IA poderá ler o arquivo completo e decidir cortes, permanências e ordem.

O arquivo de contexto não deve ser confundido com a decisão. A precisão temporal vem do nosso pipeline de frames e da transcrição; a IA pode interpretar e decidir depois. Toda decisão futura deverá apontar de volta para os intervalos e evidências do arquivo, para que o editor saiba “cortar ou manter” e por quê.

O que cada tecnologia faz

AVFoundation: acessar o vídeo com timestamp correto

AVFoundation deve ser a camada de decodificação. Ela lê o AVAsset, duração, taxa de frames, orientação, dimensões e amostras de vídeo (CMSampleBuffer/CVPixelBuffer). O ponto importante é preservar o timestamp do arquivo de origem e a transformação de orientação antes de entregar a imagem ao Vision.

O projeto hoje extrai uma amostra via OpenCV. Isso é suficiente para o primeiro protótipo, mas um helper Swift com AVFoundation será melhor quando precisarmos de timestamps exatos, inclusive VFR; leitura de frames próximos a cortes; orientação, HDR e color space explícitos; processamento em streaming; e CVPixelBuffer direto para Vision e Foundation Models.

AVAssetReader é a API oficial para ler dados de mídia de um AVAsset.

Vision: fatos observáveis por frame

O Vision trabalha com o padrão “criar request → executar sobre imagem/frame → ler observations”. Também possui VNSequenceRequestHandler para requests que acompanham uma sequência de frames. As caixas usam coordenadas normalizadas; o adapter deve converter somente na borda do sistema e manter a convenção do domínio documentada.

Capacidade	API Vision	Evidência útil para edição
Texto em tela	RecognizeTextRequest / VNRecognizeTextRequest	texto, confiança, idioma e bounding box; localizar cartelas, placas, telas e erros de legenda
Regiões de texto	DetectTextRectanglesRequest	área de texto mesmo quando o OCR não consegue ler o conteúdo
Rostos	DetectFaceRectanglesRequest	quantidade, caixas e presença/posição de rosto
Landmarks faciais	DetectFaceLandmarksRequest	olhos, boca, sobrancelhas e contornos; útil para enquadramento e olhos fechados, não para inferir emoção
Qualidade facial	DetectFaceCaptureQualityRequest	sinal de nitidez/qualidade de captura do rosto
Pessoas	DetectHumanRectanglesRequest e requests de pessoa	presença, quantidade e ocupação aproximada
Pose corporal	DetectHumanBodyPoseRequest	juntas, posição e confiança; base para postura e ação simples
Mãos	DetectHumanHandPoseRequest	juntas da mão e confiança; base para gestos definidos por regras
Animais	RecognizeAnimalsRequest	presença de gato, cachorro e outros animais reconhecidos
Barcodes/QR	DetectBarcodesRequest	conteúdo, simbologia e localização
Classificação	ClassifyImageRequest / VNClassifyImageRequest	rótulos gerais e confiança; sinal de assunto, não verdade editorial
Similaridade visual	GenerateImageFeaturePrintRequest	distância entre frames; deduplicar quase-iguais e agrupar takes
Saliencia	GenerateAttentionBasedSaliencyImageRequest e GenerateObjectnessBasedSaliencyImageRequest	regiões que atraem atenção; apoiar crop e composição
Máscara de pessoa	GeneratePersonInstanceMaskRequest / segmentação	separar pessoa/fundo e medir ocupação
Estética	CalculateImageAestheticsScoresRequest	score auxiliar para escolher thumbnail ou frame representativo
Horizonte	DetectHorizonRequest	inclinação do horizonte; sinal técnico/compositivo
Movimento/tracking	TrackObjectRequest, TrackRectangleRequest, optical flow	continuidade de sujeito, deslocamento e movimento entre frames

Essas APIs não entregam, sozinhas, “essa é a melhor tomada”, “a pessoa está nervosa” ou “este trecho deve entrar no corte”. Elas entregam observações e scores. Conceitos editoriais precisam ser derivados por regras, comparação temporal ou Foundation Models.

Inventário ampliado da documentação

Além da tabela acima, o framework inclui estas famílias que podem entrar no Scanner conforme o caso:

Família	O que pode ser extraído
Documentos	estrutura de documento, palavras, linhas, parágrafos, listas, tabelas, regiões de texto e códigos; útil para cenas com prontuário, formulário, receita ou tela organizada
Segmentação interativa	máscara a partir de pontos, retângulo ou rabisco; útil quando o usuário indicar manualmente o sujeito
Pose 3D	pontos do corpo humano em espaço 3D relativo à câmera; exige validar se o vídeo e o dispositivo fornecem resultado estável
Pose animal	pontos/partes do corpo de animais; útil para identificar ação em cenas com animais
Trajetórias	trajetória de formas em movimento parabólico; caso especializado, não um detector geral de ação
Contornos	linhas/arestas da imagem; útil para medir forma, desenho e mudanças bruscas, mas gera muitos dados
Retângulos	quadriláteros/regiões retangulares projetadas; útil para telas, documentos, quadros e superfícies
Mancha na lente	indício de smudge na lente em frame ou vídeo; alerta técnico
Registro de imagem	transformação translacional, homográfica ou alinhamento entre imagens; útil para comparar takes e estabilidade
Subject lifting	máscara de objetos perceptíveis ou pessoas para separar primeiro plano e fundo
Modelo customizado	CoreMLRequest executa um modelo Core ML escolhido pelo produto; as classes e atributos passam a depender do modelo distribuído por nós

Os resultados normalmente são uma combinação de confidence, boundingBox/região normalizada, pontos/landmarks, rótulos, score, máscara, distância ou transformação. Para vídeo, cada resultado precisa receber o timestamp do frame; requests com estado devem usar o mesmo handler de sequência.

O que o Vision não oferece pronto: descrição livre de “o que está acontecendo”, emoção da fala, identidade da pessoa, intenção, qualidade narrativa, transcrição de áudio ou decisão de corte. Essas camadas vêm, respectivamente, de Foundation Models/VLM, análise de áudio, regras de privacidade, transcrição e um motor editorial posterior. O Vision pode fornecer os sinais que apoiam algumas dessas inferências, mas não deve receber esse significado como se fosse uma observação nativa.

Fontes: Vision, VNSequenceRequestHandler, feature prints e thumbnails de vídeo.

Foundation Models: interpretar evidências e gerar um plano

FoundationModels dá acesso ao SystemLanguageModel, o modelo de linguagem on-device que alimenta o Apple Intelligence, quando estiver disponível no dispositivo. Ele é bom para resumir transcrição e evidências; extrair entidades, assuntos e tags; classificar trechos segundo critérios fornecidos; comparar descrições de cenas; gerar JSON/Swift estruturado com @Generable; e propor títulos, capítulos, selects e versões para plataformas.

A documentação atual também descreve prompting multimodal: uma imagem pode ser anexada ao prompt e o modelo pode analisá-la. Isso permite enviar frames ou uma contact sheet, mas não transforma a sessão em um analisador de vídeo temporal. A orquestração de frames, timestamps e cenas continua sendo responsabilidade do nosso programa.

O desenho mais forte para nós é usar ferramentas: o modelo recebe contexto textual e pode chamar uma ferramenta controlada que consulta evidências Vision, OCR ou um índice local. A ferramenta retorna fatos; o modelo interpreta; o modelo não ganha permissão implícita para alterar o Premiere.

Limitações relevantes:

• verificar disponibilidade em runtime com SystemLanguageModel.default.availability;
• a janela on-device documentada é de 4096 tokens por sessão;
• registrar prompt e versão, pois o modelo muda com atualizações do sistema;
• validar respostas estruturadas; não usar texto livre como contrato de edição;
• limitar imagens por sessão, pois muitas imagens aumentam custo, latência e contexto;
• manter fallback quando o modelo local estiver indisponível.

Fontes: Foundation Models, geração e tarefas, prompting multimodal, context window e SystemLanguageModel.

Como analisar frame a frame sem desperdiçar processamento

“Frame a frame” deve significar que cada frame escolhido tem timestamp e evidências próprias — não necessariamente processar todos os 24/30/60 frames por segundo na primeira passagem.

Vídeo original
   ↓ AVFoundation / sampler
Frames de baixa cadência + frames ao redor de cortes
   ↓ Vision barato
Mapa temporal de cenas, movimento, qualidade, faces e similaridade
   ↓ seleção de candidatos
Frames representativos + contact sheet + transcrição por intervalo
   ↓ Foundation Models
Descrição, tags, ranking e plano editorial estruturado
   ↓ revisão
Operações Premiere com IDs e guards de revisão

Passagem 1 — cobertura: 1 frame por segundo, ou cadência ajustada à duração, mais frames imediatamente antes/depois de mudanças de cena. Usar qualidade, faces/pessoas, OCR curto, feature print e diferença entre frames.

Passagem 2 — refinamento: subdividir somente as cenas candidatas. Aumentar a cadência para localizar entrada/saída do sujeito, fala, gesto, olho fechado, blur, troca de enquadramento e continuidade.

Passagem 3 — semântica: enviar ao Foundation Models uma descrição compacta por cena e, quando necessário, uma contact sheet com poucos frames etiquetados por timestamp. A IA escolhe entre evidências já localizadas, não inventa intervalos.

O exemplo oficial da Apple para thumbnails combina score estético por amostra e feature prints para evitar frames visualmente semelhantes. É um bom ponto de partida para “melhor frame da cena”, mas o score estético deve continuar sendo somente um sinal auxiliar.

Produto inicial: arquivo cronológico de contexto

O primeiro produto deve ser um arquivo único por projeto ou vídeo, ordenado cronologicamente. Ele funciona como um “roteiro técnico aumentado”: cada intervalo contém o que foi falado, o que aparece na imagem e os sinais que podem ajudar uma decisão futura.

Pode haver duas representações do mesmo conteúdo:

• contexto-video.json: formato completo, estável e consumível por máquina;
• contexto-video.md ou .srt enriquecido: leitura humana, com timestamp, transcrição e descrição da cena no mesmo bloco.

O JSON é a fonte de verdade. Markdown e SRT são visões derivadas e não devem substituir os IDs, timestamps, confiança e revisões do JSON.

Exemplo de unidade cronológica:

{
  "segment_id": "clip-07@42.100-49.800",
  "source_id": "project-item-123",
  "start": 42.1,
  "end": 49.8,
  "transcription": {
    "text": "A frase falada neste intervalo.",
    "speaker": "speaker-01",
    "confidence": 0.93
  },
  "caption": {"text": "A frase falada neste intervalo."},
  "visual": {
    "description": "Pessoa em plano médio falando para a câmera.",
    "objects": ["person", "microphone"],
    "faces": 1,
    "text_on_screen": [],
    "composition": {"face_well_framed": true, "caption_area_available": true},
    "technical_alerts": []
  },
  "speech_signals": {
    "emotion": "calm",
    "confidence": 0.61,
    "provider": "speech_emotion_provider"
  },
  "representative_frames": [
    {"frame_id": "clip-07@44.000", "timestamp": 44.0, "path": "frames/...jpg"}
  ],
  "evidence_ids": ["clip-07@44.000:face-01"],
  "status": "observed"
}

A descrição visual deve ser marcada como observed, inferred ou unknown. “Pessoa em plano médio” pode ser uma descrição apoiada por Vision; “parece confiante” é uma interpretação e deve carregar confiança e provider. Emoção de fala também é um sinal probabilístico, não um fato psicológico. Nunca esconder incerteza dentro de uma frase narrativa.

Esse arquivo permite ao editor navegar cronologicamente e responder, em uma etapa posterior:

• manter ou cortar este intervalo;
• escolher entre takes semelhantes;
• remover repetição, silêncio, erro técnico ou retake;
• preservar uma fala importante mesmo quando o frame não é o mais bonito;
• reorganizar trechos para uma intenção editorial específica.

Contexto que o programa deve montar

Cada evidência deve ser persistida separadamente da interpretação:

{
  "evidence_id": "clip-07@12.480:face-01",
  "clip_id": "clip-07",
  "source_id": "project-item-123",
  "timestamp": 12.48,
  "interval": {"start": 12.0, "end": 13.0},
  "kind": "face",
  "value": {"bounding_box": {"x": 0.31, "y": 0.18, "width": 0.22, "height": 0.42}},
  "confidence": 0.97,
  "provider": "apple_vision",
  "model_or_revision": "vision-revision-x",
  "source_revision": "sha256:..."
}

O arquivo deve conter intenção opcional do usuário; metadados do clipe e da timeline; transcrição temporal; legenda correspondente; intervalos de cena; OCR consolidado; presença/posição de pessoas e rostos; qualidade e composição; movimento, similaridade e possíveis retakes; sinais de emoção da fala; frames representativos; limitações, falhas de provider e confiança.

Não enviar uma lista gigantesca de observações repetidas. Consolidar eventos contínuos, por exemplo rosto presente de 12.0s a 18.4s, mantendo os frames brutos para auditoria.

Etapa posterior: decisão editorial por IA

Depois que o arquivo cronológico estiver validado, podemos entregá-lo a uma IA de decisão. Essa IA será complementar ao contexto, não parte obrigatória da primeira análise. Ela poderá receber:

1. o JSON completo, quando couber no contexto;
2. chunks cronológicos com estado resumido entre eles;
3. uma intenção editorial, como “vídeo de 60 segundos para apresentação”;
4. regras explícitas, como preservar falas sobre determinado assunto;
5. autorização para produzir somente uma decisão ou também um plano de edição.

Quando o arquivo for grande, não devemos simplesmente truncá-lo. O programa deve fazer chunking cronológico, consolidar o estado e gerar um resultado final com referências globais aos segment_id e evidence_ids originais.

Contrato da saída editorial

A saída posterior da IA de decisão deve ser um artefato de planejamento, não uma edição aplicada:

{
  "scene_id": "scene-04",
  "decision": "candidate",
  "score": 0.84,
  "reasons": ["fala cobre o tema", "rosto bem enquadrado", "sem alerta técnico"],
  "selected_range": {"start": 42.1, "end": 49.8},
  "evidence_ids": ["clip-07@42.1:...", "clip-07@47.0:..."],
  "warnings": [],
  "requires_review": true
}

Regras: selected_range só aponta para timestamps/evidências existentes; toda decisão tem evidence_ids; ausência de evidência vira unknown; a IA sugere trim, descarte, agrupamento e ordem, mas não escreve diretamente no projeto; o aplicador confere source_revision e timeline_revision; decisões de alto impacto exigem confirmação.

Isso encaixa no que já existe em EditorialContextPack e EditorialPlan: ambos são revision-aware, citáveis e read-only antes da aplicação.

Situação atual do projeto

Já temos QuadroDeVideo com timestamp, índice, dimensões, imagem e caminho; AnalisadorDeFrame e AnalisadorDeSequenciaDeQuadros; DetectorDeCenas; análises OpenCV de qualidade, composição, movimento e continuidade; adapter inicial AnalisadorAppleVision para OCR e faces via PyObjC; adapters ONNX/Core ML e MediaPipe; e contexto editorial/plano com evidência, revisões e revisão obrigatória.

Gaps para a implementação Apple completa:

1. ampliar o adapter Vision para pose, mãos, qualidade facial, feature print, saliência, pessoa e estética;
2. adicionar runner Swift/AVFoundation para timestamps e CVPixelBuffer, mantendo PyObjC como protótipo;
3. consolidar evidências contínuas e gerar contact sheets etiquetadas;
4. criar FoundationModelsProvider separado, com disponibilidade, timeout, versão, token budget e saída tipada;
5. criar store de frames/evidências por hash do arquivo e revision;
6. testar orientação, VFR, HDR, vertical/horizontal e falha parcial de requests;
7. medir precisão editorial em fixtures reais antes de permitir aplicação automática.

Ordem recomendada

Fase 1 — Vision determinístico

Implementar OCR, faces, pessoas, qualidade, feature print e estética. O resultado deve ser JSON versionado por frame. Manter OpenCV para métricas existentes e comparar resultados, em vez de substituir tudo de uma vez.

Fase 2 — cenas e selects

Combinar cortes, similaridade e qualidade para produzir cenas e frames representativos. Criar visualização de auditoria com timeline, thumbnail, timestamp, observações e confiança.

Fase 3 — descrições de cena

Gerar descrições visuais sincronizadas com os intervalos da transcrição e produzir o JSON cronológico. Começar com descrições baseadas nos fatos Vision; usar Foundation Models somente para transformar evidências em linguagem curta, com marcação de confiança e origem.

Fase 4 — Apple Intelligence como decisão complementar

Enviar o arquivo cronológico ou seus chunks para uma IA separada. Começar por resumo e tags; depois manter/cortar; por fim plano de edição com saída guiada e validação estrita. Se o modelo estiver indisponível, o Scanner continua entregando o arquivo completo de contexto.

Fase 5 — Premiere

Usar o plano existente como camada de revisão. Somente depois da confirmação chamar operações de organização, stringout, rough cut, marcadores ou legendas, sempre com readback.

Decisão

Devemos implementar Vision como os olhos do Scanner e um arquivo cronológico multimodal como o produto central da primeira fase. O Foundation Models pode ajudar a escrever as descrições de cena. Mais tarde, uma IA de decisão poderá ler esse arquivo e sugerir “corta/mantém/usa este take”, sempre apontando para os intervalos e evidências que justificam a escolha.

Essa arquitetura aproveita o Apple Silicon, preserva privacidade, funciona com o modelo local quando disponível e mantém fallback para OpenCV/ONNX/Whisper e outros hosts. Também evita confundir Apple Intelligence com Media Intelligence do Premiere: são produtos e APIs diferentes.

Fontes oficiais

• Apple Vision
• Processar vídeo e gerar thumbnails
• AVAssetReader
• Foundation Models
• Analisar imagens com prompting multimodal
• Gerar conteúdo e executar tarefas
• Janela de contexto do modelo on-device
• SystemLanguageModel
• Disponibilidade e dispositivos compatíveis com Apple Intelligence