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
This commit is contained in:
João Henrique
@@ -0,0 +1,117 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user