zenstory-ai/video-reference

1. Posicionamiento

Esta skill se utiliza para desglosar bajo demanda un vídeo de alta calidad ya terminado, extrayendo su ritmo de edición, la división del trabajo en la banda sonora y la estructura narrativa en fichas de método y métricas cuantitativas directamente utilizables para la próxima producción. Todo se ejecuta en local; solo se generan datos de medición, etiquetas de desglose y un archivo de referencia anonimizado. No se invoca MiMo ni se evalúa ni bloquea la línea de producción habitual.

El agente actúa aquí como editor de desglose: primero registra fielmente "cómo se editó y produjo exactamente este vídeo terminado" (hechos del original) y luego extrae de ahí "cómo se puede aplicar a un nuevo material" (métodos transferibles). Los hechos y los métodos deben estar completamente separados: los hechos que contengan nombres de personas, tramas y diálogos específicos del vídeo original solo permanecen en el directorio de desglose local; el production_reference.json final exportado solo contiene métodos genéricos y valores de ritmo medidos.

2. Entrada

• Archivo de vídeo terminado a desglosar (compatible con .mp4 / .mov / .mkv / .webm).
• Directorio U de productos de comprensión de vídeo generados para este vídeo (se recomienda configurar ASR_SEGMENT_SECONDS=5 en la fase de comprensión; cuanto más fina sea la ventana, más precisa será la velocidad de locución calculada). Esta skill leerá opcionalmente asr_result.json, asr_timing_evidence.json y background_research.json (los nombres de personajes, alias y diálogos ASR registrados allí se incluirán en el escaneo de prevención de spoilers); al hacer anotaciones manuales, el agente también debe revisar el storyboard y vlm_analysis.json.

Incluso sin haber ejecutado la comprensión de vídeo, esta skill puede ejecutarse de forma independiente, pero la velocidad de locución exportada estará vacía, el vocabulario de prevención de fugas dependerá únicamente de los entities escritos manualmente por el agente, y la verificación (check) emitirá las advertencias correspondientes; en ese caso, se puede usar frames --span 0,<duración> --step 2 para extraer fotogramas y generar un mosaico que ayude a visualizar el vídeo.

Todas las rutas scripts/... a continuación son relativas al directorio de esta skill.

3. Proceso de desglose

python3 scripts/reference.py measure <vídeo> --work-dir U        # Ejecuta una medición real de cortes y sonoridad con ffmpeg, almacena en caché por identidad de archivo
python3 scripts/reference.py frames  <vídeo> --work-dir U --review          # Genera imágenes fotograma a fotograma de posibles cortes suprimidos por el algoritmo para su revisión
python3 scripts/reference.py frames  <vídeo> --work-dir U --longest 5       # Extrae los 5 planos más largos y busca cortes no detectados en ellos
python3 scripts/reference.py check   --work-dir U [--json]      # Valida el desglose e imprime métricas derivadas
python3 scripts/reference.py export  --work-dir U --out <directorio_de_trabajo_del_próximo_proyecto>/production_reference.json

1. Medición de cortes y sonoridad (measure): El script genera U/reference_measurements.json (no modificar manualmente), registrando los puntos de corte del vídeo completo, distribución de duración de planos, cortes por minuto, curva de densidad de cortes en ventana deslizante de 10 segundos, sonoridad integrada (LUFS), rango dinámico de sonoridad (LRA), pico verdadero y sonoridad a corto plazo segundo a segundo. Este paso requiere decodificar completamente el vídeo terminado (un vídeo de 5 minutos a 720p tarda entre 15 y 70 segundos; un vídeo 4K tarda unos 7 minutos); mientras el archivo de vídeo no cambie, se reutilizará la caché; ajustar los umbrales --soft-score o --hard-score no requiere volver a decodificar.
   • Lógica de detección inicial de cortes: Los fotogramas con una puntuación de cambio de escena scdet ≥10 se clasifican directamente como cortes; los fotogramas con puntuación entre 4 y 10 solo se clasifican como cortes si su puntuación es al menos el doble de la puntuación máxima de los demás fotogramas no adyacentes en una ventana de 0,3 segundos antes y después (es decir, un pico local destacado). Esto permite filtrar la mayoría de los movimientos de cámara, zooms bruscos y destellos, colocando estos fotogramas dudosos en la ventana de revisión shots.review_windows. Además, dado que la puntuación scdet descuenta la variación de imagen del fotograma anterior, al pasar bruscamente de un plano con mucho movimiento a una escena estática, la puntuación scdet puede reducirse a solo 1 punto; por lo tanto, la herramienta también capturará los picos de diferencia de imagen entre fotogramas (mafd) en shots.review_windows para que el humano los revise visualmente, pero no los contará como cortes automáticos.
2. Revisión visual de cortes (frames): Cualquier umbral fijo tendrá problemas con vídeos reales (un corte brusco en una escena nocturna oscura puede tener solo 5-7 puntos, mientras que en una escena de lucha intensa, cada 0,2 segundos puede aparecer un pico de 7-8 puntos), por lo que es obligatoria la revisión visual. Ejecutar frames --review genera una imagen con todos los fotogramas de cada ventana de revisión; ejecutar frames --longest 5 extrae 12 fotogramas uniformemente espaciados de los 5 planos más largos; las imágenes se guardan en U/reference_frames/ y la terminal imprime los segundos correspondientes a cada fotograma. Después de revisar las imágenes, registrar las correcciones en labels.cut_fixes: add para cortes reales omitidos por el algoritmo, remove para cortes falsos detectados por el algoritmo (deben coincidir con los cortes medidos dentro de un margen de ±0,1 segundos); si se confirma que todo es correcto y no hay que añadir ni eliminar, escribir explícitamente "cut_fixes": {} para indicar que se ha revisado. Nota: si se vuelve a ejecutar measure y las ventanas de revisión cambian, los cut_fixes antiguos ya no son válidos; el agente debe volver a cotejar y actualizar con las nuevas ventanas. Una vez completada la revisión, todas las métricas estadísticas de planos, densidad de cortes por segmento y el producto final exportado se recalcularán con los cortes corregidos.
3. Etiquetado de pistas de audio y segmentos (labels): El agente rellena labels en U/reference_breakdown.json, incluyendo la pertenencia de pistas de audio audio_spans, segmentos de función narrativa sections, formato de subtítulos subtitles y la base de las anotaciones basis.
   • Los límites de las pistas de audio deben coincidir con los puntos reales de inicio y fin del sonido: los puntos de cambio de audio_spans deben situarse en el momento en que el oído realmente escucha que la voz comienza o termina, no copiar el momento en que aparece o desaparece el subtítulo (el punto final de la locución marcado según el fotograma de inicio del subtítulo suele ser 0,24–0,42 segundos más tarde que el final real del sonido). Si el directorio ya contiene U/speech_boundary_anchors.json, usar directamente sus acoustic_pauses (start es el punto final de la frase anterior, end es el punto inicial de la siguiente) para alinear los límites; porque la tasa de cambio de sincronización labial switch_on_cut_share solo reconoce errores de ±0,25 segundos alrededor del corte; si el límite está mal etiquetado, la tasa de cambio calculada será gravemente inexacta. Las voces en off o monólogos internos de los personajes del vídeo original siguen perteneciendo a la pista de audio original y se etiquetan como original_dialogue; si es necesario distinguirlos en la estrategia, se puede hacer en source_facts y methods.
   • Después de rellenar labels, ejecutar check una vez para ver los valores estadísticos derivados impresos en la terminal derived (proporción de duración de cada pista de audio, densidad de cortes por segmento, velocidad de palabras de la locución, proporción de cambios de voz que coinciden con cortes visuales, distribución temporal de los segmentos narrativos en el eje de tiempo structure, y la posición relativa de la primera aparición del original first_original_at).
4. Extracción de hechos y métodos transferibles (source_facts y methods): Basándose en los datos objetivos recién calculados, continuar rellenando en el mismo archivo reference_breakdown.json los hechos del vídeo original source_facts (deben anclarse a intervalos de tiempo específicos o rutas de medición, y enumerar explícitamente los nombres propios involucrados entities) y los métodos transferibles methods (que contienen la regla de acción rule, escenarios de aplicación applies_when, condiciones a evitar avoid_when, archivos posteriores a los que afecta applies_to, evidencia de respaldo evidence e indicadores cuantitativos de referencia targets). Nota: en targets solo se permiten rutas de referencia {"from": "<ruta_de_medición>"}; está estrictamente prohibido escribir números concretos en el texto de la regla; al exportar, el script rellenará automáticamente los valores medidos.
5. Validación y exportación (check → export): Ejecutar check para confirmar cero errores, luego ejecutar export para generar production_reference.json; antes de escribir en disco, el exportador realiza un escaneo completo de prevención de fugas en todos los campos del producto.

Las definiciones completas de campos, listas de enumeración y ejemplos de métodos buenos/malos se encuentran en references/reference-schema.md.

4. Reglas de validación y prevención de fugas

reference.py check se detiene con código de salida 1 ante cualquiera de los siguientes errores:

Regla	Requisito de validación
R1	Los niveles superior, labels, fact, method, target, cut_fixes utilizan conjuntos de claves estrictamente cerrados y enumeraciones cerradas; fact no debe mezclar campos de método, method no debe mezclar campos de hecho; los IDs deben tener la forma f1… / m1… y ser únicos globalmente; el tipo de campo subtitles es fijo; el motivo de skipped_dimensions debe ser una cadena no vacía
R2	audio_spans y sections deben estar ordenados cronológicamente de forma ascendente, no superponerse, con un espacio entre segmentos adyacentes ≤0,5 segundos y cubrir completamente toda la duración del vídeo; los puntos de tiempo de la evidencia de subtítulos deben estar dentro de la duración del vídeo; cut_fixes.remove debe coincidir con un corte medido, add no debe duplicar un corte existente
R3	Cada fact debe elegir entre un ancla temporal t: [a, b] (dentro de la duración del vídeo) y un ancla de medición measure: [ruta] (que se resuelva en un valor no cadena en shots / loudness / derived), y debe rellenar explícitamente el array entities
R4	Cada method debe tener al menos una evidencia de respaldo: haciendo referencia a un ID fact ya definido, o a measure:<ruta> (también limitado a las tres rutas raíz mencionadas)
R5	target solo permite la clave from, que apunta a un nodo hoja numérico o un objeto derivado de la lista blanca bajo shots, loudness o derived; está estrictamente prohibido usar índices de lista
R6	En rule, applies_when, avoid_when y los motivos de skipped_dimensions, está estrictamente prohibido: nombres propios del vídeo original (comparación ignorando espacios), 8 caracteres chinos consecutivos idénticos a los diálogos ASR / material de fondo / source_facts (se intercepta incluso si cruza puntuación o ventanas ASR adyacentes), o 5 palabras inglesas consecutivas, códigos de tiempo absolutos, "segundo N" o "N minutos M segundos" (incluyendo números en caracteres chinos), rutas absolutas locales
R7	Las cinco dimensiones principales de producción (narrative_structure, pacing, shots_editing, narration_subtitles, audio_visual); cada dimensión debe tener al menos un method extraído; si una dimensión no puede extraerse, se debe explicar el motivo en skipped_dimensions
R8	Al exportar production_reference.json, se vuelve a ejecutar el escaneo de prevención de fugas R6 en todos los nombres de clave y valores de cadena, y el producto exportado no debe contener en ningún nivel las claves source_facts, labels, entities, evidence, statement, from, path

El vocabulario de prevención de fugas agrega automáticamente source_facts[].entities, los personajes y alias de character_details en background_research.json, las entradas de cultural_notes de no más de 5 caracteres, y las palabras cortas entre comillas 《》「」 en los materiales. Si se detecta una coincidencia de 8 caracteres consecutivos con source_facts, simplemente reformule la expresión de edición genérica en uno de los lados.

Las siguientes situaciones solo generan advertencias (warning) y no bloquean la exportación: method sin applies_when; el texto de rule contiene directamente números arábigos; la precisión de ASR no es AVAILABLE_COARSE; el vídeo tiene diálogos en chino pero ni los productos de comprensión ni la base de datos proporcionan nombres de personas (en este caso, solo se basa en los entities escritos manualmente); basis está vacío; la identidad del archivo de vídeo registrada en los productos de comprensión no coincide con el vídeo medido actual; existen ventanas de revisión de cortes pendientes pero no se ha rellenado cut_fixes.

Nota: R6 solo puede detectar coincidencias literales, no puede detectar escritos que, aunque cambien las palabras, sigan relatando la trama del vídeo original; al redactar method, se debe resumir "qué hacer cuando se encuentre una característica de material determinada", nunca se debe escribir "cómo editar después de que el protagonista entre". Además, el validador no comprueba si el significado del lenguaje natural coincide con los datos; antes de escribir "qué tipo de segmentos tienen cortes más densos", primero se deben verificar los valores medidos de cuts_per_min impresos por check, evitando escribir conclusiones que contradigan los datos medidos basándose en la intuición.

5. Entregable y uso posterior

El production_reference.json exportado solo contiene: duración total del vídeo y tamaño del lienzo, cut_detection (parámetros de detección de cortes y número de cortes añadidos/eliminados manualmente), profile (indicadores clave de ritmo y sonoridad, con marca de procedencia de datos provenance: measured para medición puramente algorítmica, reviewed para revisión manual mediante cut_fixes, labeled para anotación manual de pistas/segmentos), distribución de posiciones relativas de los segmentos narrativos en el eje temporal structure, características de formato de subtítulos subtitles, lista de métodos transferibles methods y dimensiones omitidas skipped_dimensions.

Para usarlo: colocar el production_reference.json exportado en el work_dir de la próxima tarea de producción (o vincularlo a través de la plantilla production_reference del repositorio de recursos). Cuando la fase de redacción posterior detecte que el archivo existe, lo leerá activamente y registrará en el campo opcional reference_methods de recap_story_plan.json, una por una, las decisiones de adopción de cada método (adopt / adapt / skip). Al utilizar métodos de referencia, siempre basarse en las imágenes reales y la evidencia de diálogos del nuevo material; nunca copiar ciegamente la densidad de cortes o la proporción de silencio del vídeo de referencia como cuotas rígidas. Ningún script de producción validará mecánicamente este archivo, y su presencia o ausencia no cambiará el resultado de ninguna compuerta.

El directorio U/ contiene reference_breakdown.json y los mosaicos de fotogramas reference_frames/, que incluyen hechos de la trama e imágenes del vídeo original; se usan solo para el desglose local y no deben copiarse a nuevos proyectos ni enviarse a repositorios públicos.

6. Límites de capacidad

• Todo el cálculo es local; no se invoca MiMo ni ningún modelo grande; no se modifican los productos de comprensión de vídeo anteriores; no se evalúa la calidad del vídeo terminado ni se calcula una "brecha entre el nuevo vídeo y el de referencia".
• La detección de cortes se basa en la puntuación scdet de ffmpeg más la revisión visual humana: las transiciones lentas (fundidos encadenados) no pueden ser detectadas automáticamente por el algoritmo; dos cortes rápidos consecutivos con un intervalo inferior a 0,3 segundos, los cortes que están justo en el umbral soft_score (diferentes versiones de ffmpeg pueden calcular 4.00 y 3,989), y los cortes bruscos que pasan de un movimiento intenso a un campo oscuro (la puntuación puede ser tan baja como 0,9) no se contarán directamente como cortes automáticos, sino que se agruparán en la ventana de revisión para que el humano los revise visualmente. En una prueba real con un vídeo de reseña de 5 minutos, la detección inicial del algoritmo encontró 82 cortes y, en 11 ventanas de revisión, capturó los 5 cortes reales omitidos (las otras 7 ventanas eran zooms bruscos, pasos de página y planos con movimiento); después de que la revisión visual añadiera esos 5 cortes, la coincidencia fue del 100% con la verdad de campo manual (27 cortes en total) en tres puntos (inicio, campo oscuro, segmento medio), sin falsos positivos.
• La proporción de locución y la velocidad de palabras son de precisión de nivel labeled: se estiman a partir de intervalos de pista de audio anotados manualmente combinados con ventanas ASR de granularidad gruesa, no con marcas de tiempo palabra por palabra.
• El escaneo de prevención de spoilers se basa en la comparación literal de cadenas; el agente aún debe autoverificarse activamente al escribir, asegurándose de que los methods describan técnicas de creación generales y no el resumen de la trama del vídeo original.