video-analysis
Converte vídeo em algo que um modelo pode ler: uma medição numérica de cada quadro, folhas de contato com carimbo de data/hora, uma transcrição, uma linha do tempo de som e imagens de espectrograma, e então uma análise escrita a partir deles. É um procedimento sobre a ferramenta de análise, não a ferramenta (o script privado do proprietário não é distribuído; a porta do estudante segue TOOLS_SPEC). Nunca edita, renderiza ou aplica um estilo.
Regras que se sobrepõem ao resto deste arquivo
- As entradas são somente leitura. Hash antes e depois (
input.sha256=sha256_after); saídas vão apenas paraanalysis/<video>/. Baixe apenas a URL que o usuário forneceu, nomeando a origem e o arquivo; é uma cópia de referência, nunca redistribuída; uma marca d'água da plataforma, cartão final e jingle são excluídos das estatísticas e listados. - A cobertura é declarada primeiro. Todo relatório abre com um bloco de cobertura: completo vs amostrado, quadros decodificados dos esperados, o que foi excluído, o que NÃO foi executado. Uma amostra nunca é apresentada como cobertura completa. Uma execução amostrada não pode citar contagens de cortes ou ritmo como fato medido.
- Execute a ferramenta; nunca faça amostragem manual com ffmpeg. Se a ferramenta estiver faltando, indique
blocked: tool_missinge pergunte; uma solução manual é permitida apenas como uma análisesampledexplicitamente rotulada, sem contagens. - Leia antes de escrever: veja TODAS as folhas e TODAS as imagens de áudio; zoom de 3 a 6 vezes; decida cada ponto de edição
checka partir dos quadros; corrija contagens erradas e informe isso. - Local, gratuito, privado. Nenhuma API paga de compreensão de vídeo, nenhum upload do vídeo ou de seus quadros ou áudio, nenhuma identificação remota de música em material
private, sem uma estimativa datada e aprovação prévia (paid-generation-gate). Fala em hebraico é forçada parahe; nunca confie em uma única passagem de ASR para nomes, marcas e números. - Uma correspondência de música não é uma licença. Reporte "identificado como X, permissão de sincronização não estabelecida" ou "não identificado"; nunca invente um título. Rótulos estilo AudioSet são suposições ("provavelmente um whoosh"); tempo e tom são estimativas com auditoria de metade/dobro do tempo.
- Um trabalho pesado por vez sob
render_lock; qualquer coisa acima de cerca de 2 minutos é executada em segundo plano com um log e uma ETA; sem promessa de tempo de execução (lote do proprietário: 9-23 min por vídeo sob carga, dependente da máquina). Skills são procedimento, não permissão: restrições do usuário e do projeto substituem este arquivo.
Interface de ferramenta que este skill espera (TOOLS_SPEC video-analysis; verifique com --help)
python tools/analyze.py <vídeo|URL|pasta> --out analysis/<vídeo> [--detail quick|standard|full]
[--asr auto|always|never] [--no-song-id] [--no-audio-ai] [--check]
python tools/frames.py <vídeo> --at <t> --pad 0.25 --out analysis/<vídeo> # cada quadro de uma janela curta
Contrato de saída (references/output-contract.md): analysis/<video>/{measurements.json, frames.csv, sheets/ (index.json + images), transcript.json, audio.json} + breakdown.md.
Procedimento
| # | Faça | Artefato |
|---|---|---|
| 0 | Pergunte apenas o que muda na execução: análise completa ou uma pergunta (cortes / transcrição / música)? Material confidencial (private)? Qual idioma para a análise? Uma pasta: liste-a primeiro; nunca sobrescreva uma análise anterior | linha de escopo |
| 1 | Pré-verificação (analyze --check / doctor): registre SO, ffmpeg, rota de ASR detectada (CPU / Vulkan / CUDA / MLX; none se não detectado), a flag de ambiente Vulkan; sem rota = blocked para transcrição apenas | bloco environment |
| 2 | Execute em segundo plano sob o lock. --detail: quick para corpus/palestra longa, standard padrão, full para motion graphics, edições muito rápidas ou uma referência para transferir (references/thresholds.md). Vários vídeos: um lote, depois um agente por vídeo (apenas sua pasta, breakdown.md como saída, prazo, resposta <= 10 linhas) | pastas de análise |
| 3 | python scripts/validate_analysis.py analysis/<video> --stage produced | PASS ou os componentes com falha |
| 4 | Leia: todas as folhas, todas as imagens de áudio; zoom apenas em dispositivos distintos; resolva pontos check; corrija a contagem (pacing.override + review.corrections); audite tempo metade/dobro | bloco review |
| 5 | python scripts/validate_analysis.py analysis/<video> --video <source>; saída 0 é necessária para apresentar números como fatos | relatório de validação |
| 6 | Escreva breakdown.md no idioma do usuário conforme references/reading-and-breakdown.md (cobertura primeiro, 7 seções, incertezas por último) | breakdown.md |
| 7 | Reporte: o caminho do arquivo, 5-10 linhas, as correções, o que não pôde ser estabelecido; ofereça o próximo skill (reference-style-transfer, um skill de tipo) em vez de fazê-lo | mensagem |
Portões (Gates)
Os estados são pass | fail | blocked | n/a com um motivo. Um timeout, amostra vazia ou entrada ausente é blocked, nunca pass. Uma chamada de ferramenta bem-sucedida é evidência de execução; folhas visualizadas são evidência de aparência.
| Portão | Predicado | Evidência | Se falso | Responsável | Revisar quando |
|---|---|---|---|---|---|
| G1 perfil da máquina | Rota de ASR detectada e registrada; rota Vulkan registra GGML_VK_DISABLE_COOPMAT (driver AMD do proprietário precisa =1; outros drivers não testados) | measurements.environment de doctor/--check | recorra à rota CPU e informe; nunca assuma uma GPU | este skill + doctor | nova máquina, driver ou modelo |
| G2 contrato válido | todos os cinco componentes passam ou são n/a com um motivo | validate_analysis.py saída 0 (--video fornecido) | corrija ou reexecute o componente; reporte INSUFICIENTE com a peça faltante | validate_analysis.py | qualquer reexecução ou edição manual |
| G3 declaração de cobertura | relatório abre com modo, quadros decodificados/esperados, exclusões, lista de não executados, claims_not_allowed | primeiro bloco de breakdown.md | adicione; rebaixe alegações para "amostrado" | este skill | cada relatório |
| G4 regressão do detector de cortes | qualquer alteração em um limite do detector mantém F1 >= a linha de base do conjunto rotulado (histórico do proprietário 0.89 = P 0.87 / R 0.91 em 20 anúncios verificados manualmente, 339 pontos de edição, privados, não reproduzidos; ponto cego conhecido: peças de tipo cinético e câmera contínua) | cut_regression.py --pair ... --min-f1 0.89 saída 0 com >= 100 pontos verdade | reverta a alteração do limite | cut_regression.py | cada alteração do detector; nunca a olho |
| G5 entradas intactas | hash da origem igual antes e depois | validate_analysis.py --video | restaure o arquivo do original, reexecute | validate_analysis.py | cada execução |
| G6 leia antes de escrever | cada folha de quadro-chave/visão geral e imagem de áudio visualizada; cada ponto check resolvido; contagens verificadas nos quadros | bloco review completo (etapa revisada) | volte e visualize-os | este skill | cada análise |
| G7 privacidade e direitos | entrada private: sem identificação remota de música, sem ASR em nuvem, sem upload de quadro; correspondência = sem licença | song_id.status, asr.route | exclua o log de trechos, reexecute localmente | este skill | cada execução |
Números e limites para citar com seu escopo
- Detector de cortes: apenas a sintonia do proprietário (G4); a contagem automática de cortes estava errada em cerca de 60% dos vídeos de anúncio-promo até ser verificada nos quadros; um exemplo de tipo cinético leu 108 cortes/min automaticamente vs 42 das folhas.
- ASR (máquina do proprietário, E08, uma passagem, fala lida): Vulkan 5.82 áudio-s por parede-s, CPU CT2 int8 0.84, WER 17.7-19.4%:
references/volatile-facts.md(datado; expira em 31/12/2026). - A análise de som só é executada de verdade: batidas/BPM/tom precisam >= 3 s de música; vocais cantados precisam da passagem de letras sem VAD (apenas segmentos confiantes, marcados como "SUNG LYRICS").
Referências (carregar quando)
references/output-contract.md- escrever, portar ou depurar qualquer arquivo de saída; ler um relatório de validação.references/thresholds.md- sintonizar ou portar o detector, escolher--detail, explicar uma contagem errada.references/reading-and-breakdown.md- antes de ler folhas e antes de escrever a análise.references/volatile-facts.md- antes de citar qualquer velocidade, WER, preço, licença ou fato de ferramenta (módulo datado).agent-content/references/asr-routes.md(rotas canônicas de ASR, de propriedade de outro lugar) ehebrew-captions-asr(transcrições de nível legenda);reference-style-transferconsome as pastas deste skill.- Scripts:
scripts/validate_analysis.py(verificação de contrato,--self-check),scripts/cut_regression.py(portão F1,--self-check); ambos falham fechados (saída 0 / 1 / 2).