jhonny-editor/code/engine/arquitetura/plano-apple-intelligence-video.md

# Plano de leitura de vídeo com tecnologias Apple

## Conclusão

O caminho recomendado é um pipeline híbrido, local e substituível:

1. `FFmpeg` continua extraindo áudio e amostras de vídeo.
2. `Speech` faz a transcrição temporal do áudio no macOS, preferencialmente com `supportsOnDeviceRecognition` e `requiresOnDeviceRecognition` quando disponíveis.
3. `Vision` analisa os quadros: OCR, pessoas/objetos, rostos, códigos, poses e mudanças de cena conforme a necessidade.
4. `FoundationModels` (Apple Intelligence) recebe um pacote compacto de evidências — transcrição, descrições dos quadros, OCR e metadados — e produz resumo, tópicos, classificação e sugestões editoriais estruturadas.

O modelo de linguagem não deve receber o arquivo de vídeo inteiro como entrada direta. A documentação do Foundation Models descreve geração e entendimento de texto, geração estruturada, ferramentas e análise de imagens; a análise de vídeo deve ser orquestrada pelo nosso pipeline, ou por um provider multimodal próprio no futuro.

## O que já existe no Engine

- `engine/scanner/analise.py` já define `ProviderDeTranscricao` e `ProviderDeAnaliseVisual`.
- `engine/scanner/transcricao_da_timeline.py` já divide o resultado por clipe e corrige os offsets das partes.
- `engine/integracoes/midia/extracao_de_audio.py` já gera WAV mono, 16 kHz e blocos de até 600 s.
- `engine/integracoes/apple_speech/` já possui um executável Swift usando `SFSpeechRecognizer` e um provider Python.
- `engine/integracoes/whisper/` fornece fallback local.

O relatório Apple atual confirma que o adaptador está integrado ao fluxo, mas também evidencia uma falha operacional a investigar: a execução reportada não encontrou fala em todos os intervalos. Antes de comparar qualidade, devemos validar permissão, disponibilidade do locale, formato/volume do WAV e se o modo on-device foi realmente ativado.

## Tecnologias disponíveis

### Speech

`SFSpeechRecognizer` aceita arquivos existentes com `SFSpeechURLRecognitionRequest`, fornece segmentos com timestamp e expõe `supportsOnDeviceRecognition`. Há limite documentado para tarefas longas, portanto a divisão existente em blocos é adequada. O provider deve manter os offsets, a confiança e o locale.

### Vision

Vision é a camada Apple para análise de fotos e vídeos. Para o primeiro corte, implementar apenas:

- `RecognizeTextRequest` para texto em tela;
- detecção de pessoas/objetos ou classificação, se a decisão editorial exigir;
- amostragem temporal de quadros e agrupamento de resultados semelhantes;
- detecção de mudança de cena, caso a implementação determinística atual ainda não cubra o caso.

Vision não deve ser chamado em todos os frames. O sampler deve escolher, por exemplo, um frame a cada 1–2 segundos e frames próximos a cortes, mantendo `timestamp`, `confidence` e a origem do frame.

### Foundation Models / Apple Intelligence

`FoundationModels` fornece o LLM local que alimenta Apple Intelligence. É adequado para resumir a transcrição, extrair entidades/tópicos, classificar trechos, sugerir títulos e gerar estruturas Swift com `@Generable`. A disponibilidade precisa ser verificada em runtime por `SystemLanguageModel.default`; Apple Intelligence precisa estar habilitado e o sistema/dispositivo precisa ser compatível.

O contexto deve ser limitado e particionado. A documentação técnica da Apple indica janela de contexto de 4096 tokens para o modelo on-device; enviar o vídeo inteiro ou uma transcrição longa em uma única solicitação não é seguro. O contrato deve prever `truncation`, `modelUnavailable`, `guardrail` e `timeout`.

### App Intents

É uma opção posterior para expor ações do Engine ao Siri/Apple Intelligence — por exemplo, “resumir o clipe selecionado” ou “encontrar trechos em que se fala de X”. Não é a API de leitura do vídeo; é a camada de descoberta e ação.

## Arquitetura proposta

```text
Timeline/clip
  ├─ AudioExtractor ──> AppleSpeechProvider | WhisperProvider
  ├─ FrameSampler ────> VisionProvider
  └─ MediaEvidenceStore
             └─ FoundationModelsProvider
                    └─ AnalysisResult / EditorialPlan
```

Adicionar interfaces no domínio, mantendo o scanner independente:

```python
class ProviderDeQuadros(Protocol):
    def amostrar(self, clipe: Any) -> list[QuadroDeVideo]: ...

class ProviderDeAnaliseSemantica(Protocol):
    def interpretar(self, evidencias: PacoteDeEvidencias) -> ResultadoSemantico: ...
```

`QuadroDeVideo` deve conter `timestamp`, caminho temporário ou bytes, dimensões e índice. `EvidenciaDeVideo` deve conter tipo (`transcricao`, `ocr`, `objeto`, `cena`), intervalo temporal, valor, confiança e provider. O resultado do Foundation Models deve ser estruturado e validado antes de entrar em `caracteristicas_visuais`, `cenas` ou plano de edição.

## Implementação em fases

### Fase 1 — endurecer Apple Speech

- Corrigir o build/instalação do executável Swift para o ambiente do usuário.
- Tornar `somente_no_dispositivo=True` a opção explícita de privacidade.
- Capturar stderr, código de saída, locale, disponibilidade e modo efetivo no resultado.
- Testar WAV com fala conhecida em `pt-BR`, inclusive blocos menores que um minuto.
- Comparar Apple Speech, Whisper e Groq usando o mesmo áudio e medir WER, latência e falhas.

### Fase 2 — Vision

- Criar um pequeno helper Swift ou um app/CLI macOS que receba vídeo, timestamps e operações.
- Usar AVFoundation para ler frames; usar Vision por frame.
- Devolver JSON versionado, com timestamp absoluto e confiança.
- Adicionar testes com fixtures de texto em tela, pessoa e quadro sem conteúdo.

### Fase 3 — Foundation Models

- Criar um processo Swift residente (mais eficiente que iniciar um processo por trecho).
- Receber JSON de evidências via stdin/stdout ou IPC existente.
- Usar `LanguageModelSession` e geração guiada para um `ResultadoSemantico` fixo.
- Fazer chunking da transcrição e uma segunda etapa de consolidação.
- Persistir prompt/model-version/evidence revision para reprodutibilidade.

### Fase 4 — integração editorial

- Alimentar o `EditorialContextPack` com evidências citáveis e intervalos temporais.
- Manter análise e plano como operações read-only até validação.
- Só depois conectar resultados a rough-cut, marcadores ou legendas via APIs já existentes do Premiere.

## Decisão recomendada agora

Implementar primeiro `AppleSpeechProvider` robusto e `VisionEvidenceProvider`; deixar `FoundationModelsProvider` como uma etapa semântica posterior. Isso entrega leitura real de áudio e imagem imediatamente, preserva fallback para Windows/Whisper e evita acoplar o Engine Python a APIs Apple que só existem no macOS.

## Fontes oficiais

- [Foundation Models](https://developer.apple.com/documentation/FoundationModels)
- [Generating content and performing tasks with Foundation Models](https://developer.apple.com/documentation/FoundationModels/generating-content-and-performing-tasks-with-foundation-models)
- [Foundation Models updates](https://developer.apple.com/documentation/Updates/FoundationModels)
- [Built-in intelligence](https://developer.apple.com/documentation/technologyoverviews/built-in-intelligence)
- [SFSpeechRecognizer](https://developer.apple.com/documentation/speech/sfspeechrecognizer)
- [Apple Intelligence para desenvolvedores](https://developer.apple.com/apple-intelligence/)
- [TN3193 — context window](https://developer.apple.com/documentation/Technotes/tn3193-managing-the-on-device-foundation-model-s-context-window)