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](https://developer.apple.com/documentation/vision), [VNSequenceRequestHandler](https://developer.apple.com/documentation/vision/vnsequencerequesthandler), [feature prints](https://developer.apple.com/documentation/vision/generateimagefeatureprintrequest) e [thumbnails de vídeo](https://developer.apple.com/documentation/vision/generating-thumbnails-from-videos).

### 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](https://developer.apple.com/documentation/foundationmodels), [geração e tarefas](https://developer.apple.com/documentation/foundationmodels/generating-content-and-performing-tasks-with-foundation-models), [prompting multimodal](https://developer.apple.com/documentation/foundationmodels/analyzing-images-with-multimodal-prompting), [context window](https://developer.apple.com/documentation/technotes/tn3193-managing-the-on-device-foundation-model-s-context-window) e [SystemLanguageModel](https://developer.apple.com/documentation/foundationmodels/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.

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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](https://developer.apple.com/documentation/vision)
- [Processar vídeo e gerar thumbnails](https://developer.apple.com/documentation/vision/generating-thumbnails-from-videos)
- [AVAssetReader](https://developer.apple.com/documentation/avfoundation/avassetreader)
- [Foundation Models](https://developer.apple.com/documentation/foundationmodels)
- [Analisar imagens com prompting multimodal](https://developer.apple.com/documentation/foundationmodels/analyzing-images-with-multimodal-prompting)
- [Gerar conteúdo e executar tarefas](https://developer.apple.com/documentation/foundationmodels/generating-content-and-performing-tasks-with-foundation-models)
- [Janela de contexto do modelo on-device](https://developer.apple.com/documentation/technotes/tn3193-managing-the-on-device-foundation-model-s-context-window)
- [SystemLanguageModel](https://developer.apple.com/documentation/foundationmodels/systemlanguagemodel)
- [Disponibilidade e dispositivos compatíveis com Apple Intelligence](https://support.apple.com/en-us/121115)