feat: criado repositório jhonny-editor no Gitea
criado repositório jhonny-editor no Gitea adicionado script admin/deploy.command com commit automático atualizado admin/DEV-NOTES.md com template limpo Resumo: - 48 arquivos alterados - 26 novos - 19 modificados - 3 removidos 22 files changed, 658 insertions(+), 568 deletions(-) Arquivos: - AGENTS.md - admin/DEV-NOTES.md - admin/OpenCut.command - admin/commit.command - admin/deploy.command - admin/update.command - code/cep-plugin/index.html - code/cep-plugin/main.js - code/cep-plugin/styles.css - code/engine/ARQUITETURA.md - code/engine/arquitetura/README.md - code/engine/gerar_relatorio_timeline.py - code/engine/integracoes/apple_speech/apple_speech_transcriber.swift - code/engine/integracoes/apple_speech/provider_de_transcricao_apple.py - code/engine/integracoes/midia/__init__.py - code/engine/integracoes/whisper/provider_de_transcricao_local.py - code/engine/scanner/__init__.py - code/engine/scanner/coordenacao/__init__.py - code/engine/scanner/descoberta/__init__.py - code/engine/scanner/modelos.py - code/engine/scanner/transcricao_da_timeline.py - code/src/tools/discovery.ts - :memory:.ses - admin/Jhonny.command - admin/inativos/OpenCut.command - admin/inativos/update.command - code/docs/glossario-analise-emocional.md - code/docs/levantamento-apple-vision-e-apple-intelligence.md - code/docs/levantamento-ferramentas-analise-visual-local.md - code/engine/arquitetura/biblioteca-inteligente-de-videos.md - code/engine/executar_scanner.py - code/engine/integracoes/huggingface/ - code/engine/integracoes/midia/extracao_de_metadados.py - code/engine/integracoes/visual/ - code/engine/requirements-visual.txt - code/engine/scanner/configuracao_visual.py - code/engine/scanner/descoberta/descoberta_de_arquivos.py - code/engine/scanner/metadados.py - code/engine/scanner/relatorio_visual.py - code/engine/scanner/retakes/ - code/engine/scanner/visual.py - code/engine/testes/test_analise_visual_local.py - code/engine/testes/test_arquivos_e_metadados.py - code/engine/testes/test_provider_de_transcricao_apple.py - code/relatorios/analise-brools/ - code/relatorios/analise-visual/ - code/relatorios/audio/arquivos/ - code/relatorios/transcricao-timeline.md
This commit is contained in:
João Henrique
@@ -0,0 +1,50 @@
|
||||
# Glossário da análise emocional
|
||||
|
||||
## Modelo utilizado
|
||||
|
||||
O classificador local é `superb/wav2vec2-base-superb-er`, executado com
|
||||
`transformers` e PyTorch. O modelo foi treinado para classificação de emoção
|
||||
em fala e retorna quatro classes: `neu`, `hap`, `ang` e `sad`.
|
||||
|
||||
## Campos do JSON
|
||||
|
||||
### `emocao`
|
||||
|
||||
Classe emocional mais provável para o segmento de áudio.
|
||||
|
||||
### `confianca_emocao`
|
||||
|
||||
Probabilidade atribuída pelo classificador à classe escolhida, entre `0` e
|
||||
`1`. Não é uma certeza nem uma medida de qualidade da transcrição. Um valor
|
||||
de `0.58`, por exemplo, indica uma classificação fraca/moderada; valores
|
||||
próximos de `1` indicam maior segurança relativa do modelo.
|
||||
|
||||
### `palavras`
|
||||
|
||||
Lista de palavras reconhecidas pelo Whisper, cada uma com seu intervalo de
|
||||
tempo no arquivo original ou na timeline projetada.
|
||||
|
||||
### `caracteristicas_acusticas`
|
||||
|
||||
Campo reservado para medidas como pitch, energia, velocidade da fala e
|
||||
pausas. Ainda não é preenchido pelo classificador atual.
|
||||
|
||||
## Glossário das classes
|
||||
|
||||
| Código | Significado | Interpretação editorial |
|
||||
|---|---|---|
|
||||
| `neu` | Neutral | Fala sem sinal emocional forte ou com expressão equilibrada. |
|
||||
| `hap` | Happy | Sinal acústico associado a alegria, animação ou entusiasmo. |
|
||||
| `ang` | Angry | Sinal acústico associado a irritação, tensão ou intensidade agressiva. |
|
||||
| `sad` | Sad | Sinal acústico associado a tristeza, abatimento ou baixa energia. |
|
||||
|
||||
Os códigos são abreviações do modelo: `hap` significa *happy* e `ang`
|
||||
significa *angry*. Eles não devem ser interpretados como diagnóstico do
|
||||
estado emocional real da pessoa. Ruído, sotaque, idioma, contexto, atuação,
|
||||
ironia e qualidade da gravação podem alterar a classificação.
|
||||
|
||||
## Decisão de uso no editor
|
||||
|
||||
A emoção é calculada por segmento/frase, enquanto as palavras mantêm seus
|
||||
timestamps individuais. Isso permite usar a emoção como sinal editorial para
|
||||
ordenar ou sugerir cortes sem atribuir uma emoção artificial a cada palavra.
|
||||
@@ -0,0 +1,287 @@
|
||||
# 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)
|
||||
@@ -0,0 +1,217 @@
|
||||
# Levantamento de ferramentas locais para análise visual
|
||||
|
||||
Data: 2026-09-08
|
||||
Escopo: escolher a base para implementar um `ProviderDeAnaliseVisual` real no `engine/scanner`.
|
||||
|
||||
## Recomendação executiva
|
||||
|
||||
Adotar uma arquitetura em camadas:
|
||||
|
||||
1. **Apple Vision + Core ML** como provider principal para macOS: OCR, rostos, pessoas, poses, códigos, classificação, qualidade e similaridade visual.
|
||||
2. **PySceneDetect** para detectar cortes e delimitar cenas no arquivo de origem.
|
||||
3. **ONNX Runtime com CoreML Execution Provider** como runtime de modelos customizados, mantendo a possibilidade de usar os mesmos modelos em outras plataformas.
|
||||
4. **MediaPipe Tasks** como alternativa especializada para pose, mãos, rosto e rastreamento quando o resultado do Vision não for suficiente.
|
||||
5. **Modelo multimodal local** somente como uma etapa semântica opcional, posterior às análises determinísticas; não deve ser a fonte primária de eventos temporais.
|
||||
|
||||
Essa composição aproveita o Apple Silicon sem enviar mídia para a nuvem, separa fatos observáveis de interpretação e permite evoluir os modelos sem alterar o contrato do Scanner.
|
||||
|
||||
## Critérios usados
|
||||
|
||||
- execução local e offline;
|
||||
- integração com macOS/Apple Silicon;
|
||||
- possibilidade de obter intervalos temporais e confiança;
|
||||
- suporte a frames, vídeo e processamento em lote;
|
||||
- integração com Python ou bridge nativa pequeno;
|
||||
- licença adequada para produto comercial;
|
||||
- maturidade e manutenção do projeto;
|
||||
- adequação ao nosso domínio: cenas, objetos, pessoas, OCR, qualidade e possíveis retakes.
|
||||
|
||||
## Candidatos
|
||||
|
||||
### 1. Apple Vision + Core ML — recomendação principal
|
||||
|
||||
O Vision oferece APIs pré-treinadas para análise de imagens e vídeo, incluindo texto, códigos, rostos, pessoas, poses, classificação, qualidade e similaridade visual. O processamento ocorre no dispositivo. Core ML executa modelos usando CPU, GPU e Neural Engine, também sem exigir conexão de rede.
|
||||
|
||||
**Pontos fortes**
|
||||
|
||||
- melhor alinhamento com o ambiente macOS existente;
|
||||
- privacidade e execução local;
|
||||
- bons blocos prontos para OCR, faces, pessoas, poses e qualidade;
|
||||
- suporte nativo a tracking entre frames;
|
||||
- possibilidade de usar modelos próprios convertidos para Core ML;
|
||||
- sem dependência de um servidor Python pesado.
|
||||
|
||||
**Limitações**
|
||||
|
||||
- a API é Swift/Objective-C, não Python;
|
||||
- será necessário um processo auxiliar Swift ou uma pequena bridge JSON;
|
||||
- não substitui um detector geral de objetos com classes customizadas;
|
||||
- os resultados são observações de visão, não uma noção editorial pronta de “take bom” ou “retake”.
|
||||
|
||||
**Uso recomendado no Scanner**
|
||||
|
||||
- `ProviderDeAnaliseVisualApple` executando um helper Swift;
|
||||
- entrada: arquivo + lista de timestamps;
|
||||
- saída: observações por frame, cada uma com `timestamp`, tipo, bounding box, label, confiança e provider;
|
||||
- usar `VNGenerateImageFeaturePrintRequest`/similaridade visual para apoiar comparação de takes;
|
||||
- usar análise de qualidade para foco, exposição e problemas técnicos quando disponível.
|
||||
|
||||
Fontes: [Apple Vision](https://developer.apple.com/documentation/vision), [detecção de objetos no Vision](https://developer.apple.com/documentation/vision/detecting_objects_in_still_images), [reconhecimento de texto](https://developer.apple.com/documentation/vision/recognizing-text-in-images) e [Apple Core ML](https://developer.apple.com/documentation/coreml).
|
||||
|
||||
### 2. PySceneDetect — recomendação para cortes de cena
|
||||
|
||||
Biblioteca Python/BSD-3 para detectar mudanças de cena. Possui `ContentDetector`, `AdaptiveDetector` e `ThresholdDetector`, retorna pares de início/fim e oferece integração com FFmpeg.
|
||||
|
||||
**Pontos fortes**
|
||||
|
||||
- integração direta com o engine Python;
|
||||
- contrato temporal já próximo do nosso `Cena`;
|
||||
- simples de testar com arquivos reais e fixtures;
|
||||
- licença BSD-3-Clause;
|
||||
- mais apropriado para “onde a cena muda” do que um VLM.
|
||||
|
||||
**Limitações**
|
||||
|
||||
- detecta transições visuais, não entende o conteúdo sem um segundo modelo;
|
||||
- pode gerar falsos positivos com movimento de câmera, flashes e mudanças de iluminação;
|
||||
- deve operar sobre o arquivo de origem e depois ser projetado para os intervalos da timeline.
|
||||
|
||||
Fonte: [repositório oficial PySceneDetect](https://github.com/Breakthrough/PySceneDetect).
|
||||
|
||||
### 3. ONNX Runtime + CoreML Execution Provider — recomendação como runtime extensível
|
||||
|
||||
ONNX Runtime fornece API Python e permite executar modelos ONNX com `CoreMLExecutionProvider`. As wheels oficiais para macOS incluem o provider Core ML; há opções para CPU, GPU e Neural Engine quando suportadas pelo modelo e pelo dispositivo.
|
||||
|
||||
**Pontos fortes**
|
||||
|
||||
- desacopla o Scanner do framework de treinamento;
|
||||
- permite plugar modelos de detecção, classificação, pose ou embeddings;
|
||||
- mantém uma rota futura para Windows/Linux por outros execution providers;
|
||||
- cacheia modelos compilados do Core ML;
|
||||
- API Python direta.
|
||||
|
||||
**Limitações**
|
||||
|
||||
- a compatibilidade depende dos operadores e do formato do modelo;
|
||||
- precisamos controlar conversão, pré-processamento, pós-processamento e versionamento;
|
||||
- usar Core ML não garante que 100% do grafo rode na Neural Engine.
|
||||
|
||||
**Uso recomendado no Scanner**
|
||||
|
||||
- runtime para modelos licenciados de forma compatível com o produto;
|
||||
- um `ModeloVisualONNX` interno com adaptadores para detecção/classificação;
|
||||
- fallback CPU explícito e registro do device usado no resultado.
|
||||
|
||||
Fonte: [ONNX Runtime — CoreML Execution Provider](https://onnxruntime.ai/docs/execution-providers/CoreML-ExecutionProvider.html).
|
||||
|
||||
### 4. MediaPipe Tasks — alternativa especializada
|
||||
|
||||
MediaPipe oferece tarefas de visão com APIs para Python e modelos prontos, incluindo detecção de objetos, classificação, segmentação, rosto, mãos, pose e holístico.
|
||||
|
||||
**Quando usar**
|
||||
|
||||
- pose corporal, mãos, gestos e landmarks;
|
||||
- tracking de pessoas em trechos curtos;
|
||||
- quando quisermos manter o mesmo componente em macOS, Linux e Windows.
|
||||
|
||||
**Limitações**
|
||||
|
||||
- exige escolher e distribuir arquivos de modelo;
|
||||
- a cobertura e o formato de resultados são diferentes do Vision;
|
||||
- não deve ser adicionado apenas por sobreposição: primeiro precisamos de um caso que o Vision não resolva.
|
||||
|
||||
Fonte: [Google AI Edge — MediaPipe Object Detector para Python](https://ai.google.dev/edge/mediapipe/solutions/vision/object_detector/python).
|
||||
|
||||
### 5. Ultralytics YOLO — tecnicamente forte, com risco de licença
|
||||
|
||||
Ultralytics oferece detecção, segmentação, pose, classificação e tracking em Python, com modelos pré-treinados e treinamento customizado.
|
||||
|
||||
**Vantagens técnicas**
|
||||
|
||||
- integração rápida;
|
||||
- ecossistema amplo;
|
||||
- bom caminho para objetos específicos do nosso domínio;
|
||||
- suporta tracking e modelos customizados.
|
||||
|
||||
**Risco decisivo**
|
||||
|
||||
O código e os artefatos são apresentados sob AGPL-3.0, e a própria documentação indica licença Enterprise para desenvolvimento e produção que não possam cumprir as obrigações da AGPL. Não devemos incorporar Ultralytics ao produto sem uma decisão jurídica/licenciamento explícita.
|
||||
|
||||
**Decisão**
|
||||
|
||||
Usar apenas em benchmark/protótipo isolado até resolver a licença. Para produção, preferir modelos e runtimes com licença compatível ou adquirir a licença Enterprise.
|
||||
|
||||
Fontes: [documentação oficial Ultralytics](https://github.com/ultralytics/ultralytics), [licença e opções comerciais](https://github.com/ultralytics/ultralytics/blob/main/docs/en/index.md).
|
||||
|
||||
### 6. OpenCV — fundação de processamento, não provider semântico
|
||||
|
||||
OpenCV é útil para decodificação de frames, resize, cor, blur, histograma, métricas técnicas, comparação de imagens e pré/pós-processamento. Também pode executar modelos via DNN, mas não deve ser tratado sozinho como a solução de reconhecimento semântico.
|
||||
|
||||
**Uso recomendado**
|
||||
|
||||
- extração/amostragem de frames;
|
||||
- foco, exposição, contraste, ruído e estabilidade;
|
||||
- diferenças entre frames;
|
||||
- suporte aos providers Vision, ONNX e MediaPipe.
|
||||
|
||||
Fonte: [licença oficial OpenCV](https://opencv.org/license/).
|
||||
|
||||
## O que não recomendar como núcleo
|
||||
|
||||
Um VLM local pode produzir descrições como “pessoa falando em uma sala”, mas é menos determinístico, mais caro em memória e menos adequado para localizar cortes com precisão. Ele pode entrar depois para gerar descrição semântica de cenas já delimitadas, nunca substituir `PySceneDetect`, Vision ou um detector temporal.
|
||||
|
||||
Também não devemos começar pelo YOLO/Ultralytics como dependência central antes de resolver AGPL/licença comercial.
|
||||
|
||||
## Matriz resumida
|
||||
|
||||
| Ferramenta | Melhor uso | Python direto | Apple Silicon | Offline | Licença/risco | Decisão |
|
||||
|---|---|---:|---:|---:|---|---|
|
||||
| Vision | OCR, faces, pessoas, pose, qualidade, similaridade | Não | Excelente | Sim | Framework Apple | Adotar |
|
||||
| Core ML | Modelos próprios no hardware Apple | Via bridge/runtime | Excelente | Sim | Framework Apple | Adotar |
|
||||
| PySceneDetect | Cortes e intervalos de cena | Sim | Boa | Sim | BSD-3-Clause | Adotar |
|
||||
| ONNX Runtime + CoreML EP | Runtime de modelos customizados | Sim | Excelente | Sim | MIT | Adotar como extensão |
|
||||
| MediaPipe Tasks | Pose, mãos, rosto, holístico | Sim | Boa | Sim | Apache-2.0 no framework; conferir cada modelo | Avaliar por caso |
|
||||
| OpenCV | Frames e métricas técnicas | Sim | Boa | Sim | Apache-2.0 | Adotar como base auxiliar |
|
||||
| Ultralytics YOLO | Objetos/pose/tracking | Sim | Boa | Sim | AGPL ou Enterprise | Protótipo somente até decisão |
|
||||
|
||||
## Desenho proposto para o nosso código
|
||||
|
||||
```text
|
||||
Clipe/arquivo
|
||||
↓
|
||||
ExtratorDeQuadros (FFmpeg/OpenCV)
|
||||
↓
|
||||
ProviderDeAnaliseVisual
|
||||
├── AppleVisionProvider
|
||||
├── PySceneDetectProvider
|
||||
├── ONNXCoreMLProvider (opcional)
|
||||
└── MediaPipeProvider (opcional)
|
||||
↓
|
||||
EvidenciaVisual(timestamp, intervalo, tipo, valor, confianca, provider)
|
||||
↓
|
||||
ContextoDeAnalise.caracteristicas_visuais / cenas / eventos
|
||||
```
|
||||
|
||||
O contrato atual `ProviderDeAnaliseVisual.analisar(clipe, quadros)` é suficiente para o primeiro passo, mas a saída precisa evoluir de um `dict` livre para evidências temporais. A unidade mínima deveria conter:
|
||||
|
||||
- `tipo`: `ocr`, `pessoa`, `objeto`, `pose`, `qualidade`, `similaridade` ou `mudanca_de_cena`;
|
||||
- `inicio` e `fim` ou `timestamp`;
|
||||
- `valor` estruturado;
|
||||
- `confianca` quando fornecida pelo modelo;
|
||||
- `provider` e `modelo`;
|
||||
- versão do modelo e hash opcional;
|
||||
- referência ao arquivo/frame analisado.
|
||||
|
||||
## Ordem recomendada de implementação
|
||||
|
||||
1. Criar `ExtracaoDeQuadros` usando FFmpeg/OpenCV, com amostragem por intervalo e cache por hash do arquivo.
|
||||
2. Implementar um helper Swift pequeno para Apple Vision e um `ProviderDeAnaliseVisualApple` Python que troca JSON por stdin/stdout.
|
||||
3. Adicionar PySceneDetect como etapa própria de detecção de cenas.
|
||||
4. Criar testes com fixture curta para OCR, presença de pessoa, qualidade e mudança de cena.
|
||||
5. Medir tempo, memória, cobertura e estabilidade dos resultados em Apple Silicon.
|
||||
6. Só depois adicionar ONNX/MediaPipe para lacunas concretas.
|
||||
7. Avaliar um VLM local apenas para descrição semântica de cenas já delimitadas.
|
||||
|
||||
## Conclusão
|
||||
|
||||
Para o produto atual, a melhor escolha não é uma única biblioteca. É **Vision/Core ML + PySceneDetect + OpenCV**, com **ONNX Runtime/CoreML** como ponto de extensão. Essa combinação cobre a maior parte do Scanner com processamento local, preserva a privacidade e evita amarrar o domínio a uma biblioteca de modelos com licença problemática.
|
||||
Reference in New Issue
Block a user