video-analysis
Convierte un video en lo que un modelo puede leer: una medición numérica de cada fotograma, hojas de contacto con marcas de tiempo, una transcripción, una línea de tiempo de sonido e imágenes de espectrograma, y luego un desglose escrito a partir de ellos. Es un procedimiento sobre la herramienta de análisis, no la herramienta (el script privado del propietario no se distribuye; el puerto para estudiantes sigue TOOLS_SPEC). Nunca edita, renderiza ni aplica un estilo.
Reglas que prevalecen sobre el resto de este archivo
- Las entradas son de solo lectura. Hash antes y después (
input.sha256=sha256_after); las salidas van solo bajoanalysis/<video>/. Descarga solo la URL que el usuario dio, nombrando la fuente y el archivo; es una copia de referencia, nunca redistribuida; una marca de agua de la plataforma, tarjeta final y jingle se excluyen de las estadísticas y se listan. - La cobertura se indica primero. Cada informe abre con un bloque de cobertura: completo vs muestreado, fotogramas decodificados de los esperados, qué se excluyó, qué NO se ejecutó. Una muestra nunca se presenta como cobertura completa. Una ejecución muestreada no puede citar conteos de cortes o ritmo como hechos medidos.
- Ejecuta la herramienta; nunca muestrees manualmente con ffmpeg. Si la herramienta falta, indica
blocked: tool_missingy pide; se permite una alternativa manual solo como una inspecciónsampledexplícitamente etiquetada sin conteos. - Lee antes de escribir: revisa CADA hoja y CADA imagen de audio; haz zoom 3-6 veces; decide cada punto de edición
checka partir de fotogramas; corrige conteos incorrectos y dímelo. - Local, gratuito, privado. Sin API de comprensión de video paga, sin subida del video o sus fotogramas o audio, sin identificación remota de canciones en material
private, sin una estimación fechada y aprobación previa (paid-generation-gate). El habla en hebreo se fuerza ahe; nunca confíes en una sola pasada de ASR para nombres, marcas y números. - Una coincidencia de canción no es una licencia. Informa "identificado como X, permiso de sincronización no establecido" o "no identificado"; nunca inventes un título. Las etiquetas de estilo AudioSet son suposiciones ("probablemente un whoosh"); el tempo y la tonalidad son estimaciones con auditoría de mitad/doble tiempo.
- Una tarea pesada a la vez bajo
render_lock; cualquier cosa de más de aproximadamente 2 minutos se ejecuta en segundo plano con un registro y una ETA; sin promesa de tiempo de ejecución (lote del propietario: 9-23 min por video bajo carga, dependiente de la máquina). Las habilidades son procedimiento, no permiso: las restricciones del usuario y del proyecto anulan este archivo.
Interfaz de herramienta que espera esta habilidad (TOOLS_SPEC video-analysis; verifica con --help)
python tools/analyze.py <video|URL|carpeta> --out analysis/<video> [--detail quick|standard|full]
[--asr auto|always|never] [--no-song-id] [--no-audio-ai] [--check]
python tools/frames.py <video> --at <t> --pad 0.25 --out analysis/<video> # cada fotograma de una ventana corta
Contrato de salida (references/output-contract.md): analysis/<video>/{measurements.json, frames.csv, sheets/ (index.json + images), transcript.json, audio.json} + breakdown.md.
Procedimiento
| # | Haz | Artefacto |
|---|---|---|
| 0 | Pregunta solo qué cambia en la ejecución: desglose completo o una pregunta (cortes / transcripción / canción)? ¿Material confidencial (private)? ¿Qué idioma para el desglose? ¿Una carpeta? Lista primero; nunca sobrescribas un análisis anterior | línea de alcance |
| 1 | Preflight (analyze --check / doctor): registra SO, ffmpeg, ruta ASR detectada (CPU / Vulkan / CUDA / MLX; none si no se detecta), el flag de entorno Vulkan; sin ruta = blocked solo para transcripción | bloque environment |
| 2 | Ejecuta en segundo plano bajo el bloqueo. --detail: quick para corpus/charla larga, standard por defecto, full para gráficos en movimiento, ediciones muy rápidas o una referencia para transferir (references/thresholds.md). Varios videos: un lote, luego un agente por video (solo su carpeta, breakdown.md como salida, fecha límite, respuesta <= 10 líneas) | carpetas de análisis |
| 3 | python scripts/validate_analysis.py analysis/<video> --stage produced | PASS o los componentes que fallan |
| 4 | Lee: todas las hojas, todas las imágenes de audio; haz zoom solo en dispositivos distintos; resuelve puntos check; corrige el conteo (pacing.override + review.corrections); audita tempo mitad/doble | bloque review |
| 5 | python scripts/validate_analysis.py analysis/<video> --video <source>; se requiere salida 0 para presentar números como hechos | informe de validación |
| 6 | Escribe breakdown.md en el idioma del usuario según references/reading-and-breakdown.md (cobertura primero, 7 secciones, incertidumbres al final) | breakdown.md |
| 7 | Informa: la ruta del archivo, 5-10 líneas, las correcciones, lo que no se pudo establecer; ofrece la siguiente habilidad (reference-style-transfer, una habilidad de tipo) en lugar de hacerlo | mensaje |
Puertas
Los estados son pass | fail | blocked | n/a con una razón. Un timeout, muestra vacía o entrada faltante es blocked, nunca pass. Una llamada exitosa de la herramienta es evidencia de ejecución; las hojas vistas son evidencia de apariencia.
| Puerta | Predicado | Evidencia | Si es falso | Propietario | Revisar cuando |
|---|---|---|---|---|---|
| G1 perfil de máquina | Ruta ASR detectada y registrada; la ruta Vulkan registra GGML_VK_DISABLE_COOPMAT (el controlador AMD del propietario necesita =1; otros controladores no probados) | measurements.environment de doctor/--check | recurre a la ruta CPU y dímelo; nunca asumas una GPU | esta habilidad + doctor | nueva máquina, controlador o modelo |
| G2 contrato válido | los cinco componentes pasan o son n/a con una razón | validate_analysis.py salida 0 (--video proporcionado) | arregla o vuelve a ejecutar el componente; informa INSUFICIENTE con la pieza faltante | validate_analysis.py | cualquier re-ejecución o edición manual |
| G3 declaración de cobertura | el informe abre con modo, fotogramas decodificados/esperados, exclusiones, lista de no ejecutados, claims_not_allowed | primer bloque de breakdown.md | agrégalo; degrada afirmaciones a "muestreado" | esta habilidad | cada informe |
| G4 regresión del detector de cortes | cualquier cambio en un umbral del detector mantiene F1 >= la línea base del conjunto etiquetado (histórico del propietario 0.89 = P 0.87 / R 0.91 en 20 anuncios verificados a mano, 339 puntos de edición, privados, no reproducidos; punto ciego conocido: tipo cinético y piezas de cámara continua) | cut_regression.py --pair ... --min-f1 0.89 salida 0 con >= 100 puntos de verdad | revierte el cambio de umbral | cut_regression.py | cada cambio de detector; nunca a simple vista |
| G5 entradas intactas | hash de fuente igual antes y después | validate_analysis.py --video | restaura el archivo desde el original, vuelve a ejecutar | validate_analysis.py | cada ejecución |
| G6 leer antes de escribir | cada hoja de fotogramas clave/panorámica e imagen de audio vista; cada punto check resuelto; conteos verificados en fotogramas | bloque review completo (etapa revisada) | vuelve y revísalos | esta habilidad | cada análisis |
| G7 privacidad y derechos | entrada private: sin identificación remota de canciones, sin ASR en la nube, sin subida de fotogramas; coincidencia = sin licencia | song_id.status, asr.route | elimina el registro de extracto, vuelve a ejecutar localmente | esta habilidad | cada ejecución |
Números y límites para citar con su alcance
- Detector de cortes: solo la afinación del propietario (G4); el conteo automático de cortes fue incorrecto en aproximadamente el 60 % de los videos promocionales hasta que se verificó en fotogramas; un ejemplo de tipo cinético leyó 108 cortes/min automáticamente frente a 42 de las hojas.
- ASR (máquina del propietario, E08, una pasada, habla leída): Vulkan 5.82 audio-s por wall-s, CPU CT2 int8 0.84, WER 17.7-19.4 %:
references/volatile-facts.md(fechado; caduca el 2026-12-31). - El análisis de sonido solo se ejecuta realmente: beats/BPM/tonalidad necesitan >= 3 s de música; voces cantadas necesitan la pasada de letras sin VAD (solo segmentos seguros, etiquetados "SUNG LYRICS").
Referencias (cargar cuando)
references/output-contract.md- escribir, portar o depurar cualquier archivo de salida; leer un informe de validación.references/thresholds.md- afinar o portar el detector, elegir--detail, explicar un conteo incorrecto.references/reading-and-breakdown.md- antes de leer hojas y antes de escribir el desglose.references/volatile-facts.md- antes de citar cualquier velocidad, WER, precio, licencia o hecho de herramienta (módulo fechado).agent-content/references/asr-routes.md(rutas ASR canónicas, propiedad de otro lugar) yhebrew-captions-asr(transcripciones de grado de subtítulos);reference-style-transferconsume las carpetas de esta habilidad.- Scripts:
scripts/validate_analysis.py(verificación de contrato,--self-check),scripts/cut_regression.py(puerta F1,--self-check); ambos fallan cerrados (salida 0 / 1 / 2).