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,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