video-script-reverse-engineering

Ingeniería inversa de guion de video de alta precisión

Convierte un video dinámico en un guion de texto estático que pueda replicarse en una grabación. Criterio central: el lector, sin ver el video, debe poder "verlo" —qué se dice, cómo se dice, cómo cambia el rostro, a quién mira y por qué lo dice.

Cuándo invocar

• El usuario proporciona un archivo de video y solicita "desglosar el guion / reconstruir el guion / análisis cuadro por cuadro / convertir a guion de texto / cómo se filmó este video"
• Se necesita extraer la estructura del discurso de venta de un video de referencia (dolor → empatía → prueba → precio → llamado a la acción)
• Se necesita proporcionar al actor/director una hoja de indicaciones de actuación (tono, cambios de expresión, puntos de mirada)
• Se necesita deducir la división de planos y ritmo de edición a partir de un video de referencia

No aplica: extracción pura de subtítulos (usar ASR), edición de video en sí misma, transcripción de partituras musicales.

Reglas de hierro (recuerda estas cinco)

1. Sin limpieza de líneas: Conserva "eh / ah / mm / oh / suspiro" —son evidencia clave para la naturalidad y la asignación de personajes; no los embellezcas ni elimines.
2. La mirada debe ser específica: Escribe "[A] dirige la mirada hacia [la identidad/parte específica de B] + duración de la pausa". Prohíbe expresiones vagas como "mirar al otro" o "mirada profunda".
3. Las expresiones deben tener "trayectoria de cambio": Escríbelas en fases [inicio] → [medio] → [final] (ejemplo: ojos abiertos → pupilas dilatadas → cejas relajadas, labios apretados). Prohíbe usar un solo adjetivo estático.
4. El tono debe describir la "textura de la voz": Tono, volumen, velocidad, respiración (voz aireada/roto/inhalación), acento en qué palabra, longitud de la pausa —al menos tres de los cinco.
5. El hablante debe pasar la cadena de verificación: La diarización de ASR siempre fallará → retranscripción dividida y comparación (P6) → tabla base de subtítulos segundo a segundo (P3.5) → verificación de fotogramas de movimiento de labios. Solo cuando las cuatro capas de evidencia coincidan, permite escribir [Hablante].

Flujo de ejecución (P0–P7)

P0 Sonda de material

ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height,r_frame_rate \
  -of default=noprint_wrappers=1 "<video>"

Define la densidad de muestreo (ver tabla) y confirma si existe pista de audio (sin audio, salta P1, infiere solo con imagen).

Duración	Estrategia de fotogramas	Límite de fotogramas	Descripción
≤2 min	1 fotograma/2s + segmentos clave 1 fotograma/s	60–80	Video corto/anuncio, todos los detalles
2–10 min	1 fotograma/5s	60–100	Cortometraje
10–30 min	1 fotograma/10s + segmentos de gancho densos	80–120	Serie corta/Larga locución, primeros y últimos 90s a 1 fotograma/3s
>30 min	1 fotograma/20s + muestreo por segmentos	100–150	Solo reconstrucción a nivel de capítulo, primero esquema luego profundización

Regla de costos: Total de llamadas ViewImage en una tarea ≤60 veces, 8 imágenes en paralelo por lote; cuando falten fotogramas, prioriza "puntos de cambio de expresión, primer plano de producto, primer plano de utilería, tarjeta de subtítulos".

P1 Transcripción completa de audio

ffmpeg -y -v error -i "<video>" -vn -ac 1 -ar 16000 -b:a 96k audio.mp3

Usa AudioTranscribe (soporta mp3/wav/m4a/mp4, ≤1 GB o 5 horas) para transcribir. Produce texto con marcas de tiempo [inicio, fin, ID del hablante] —es el esqueleto de todas las líneas de tiempo posteriores.

Nota: El ID del hablante devuelto es solo un número de agrupación, no equivale al personaje; debe determinarse mediante semántica + tono + imagen.

P2 Extracción de fotogramas

# Primero prueba detección de cambios de escena (para videos con muchas transiciones)
ffmpeg -y -v error -i "<video>" -vf "select='gt(scene,0.15)',showinfo" -vsync vfr -q:v 3 kf_%03d.jpg 2> scene_log.txt
grep -o "pts_time:[0-9.]*" scene_log.txt | head -100

• Si se obtienen <10 fotogramas → es grabación continua de una sola cámara (locución/escena), cambia a extracción uniforme: -vf "fps=1/10,scale=576:-1"
• Umbral puede reducirse a 0.08 e intentar de nuevo; si aún no hay transiciones, abandona la detección de escenas
• Videos verticales cortos unificar scale=576:-1, suficiente para ver expresiones sin desperdiciar tokens

P3 Visualización por lotes de fotogramas

Cada lote 8 imágenes en paralelo ViewImage, plantilla de consulta unificada (garantiza comparabilidad):

Describe este fotograma de video vertical: apariencia de la persona, expresión, acción, escena, vestimenta, texto de subtítulos, composición

Puntos clave al leer fotogramas:

• Dirección de la relación entre personajes (quién arrastra a quién, quién persigue a quién, quién es llevado, quién sube a qué auto) debe confirmarse mediante fotogramas —el ASR nunca te lo dirá; dos adultos del mismo sexo en la misma escena, el ID de agrupación no puede ser directamente el personaje
• Los subtítulos son información valiosa y gratuita (marca de agua del título, nombre de marca, subtítulos de producto, precio, descargo de responsabilidad, nombre de personaje en el diálogo) —cópialos fotograma por fotograma; los nombres de persona que aparecen en los subtítulos (ej. "Gu Chuan, no pierdas el tiempo") junto con quién es arrastrado en la imagen, son prueba irrefutable de la pertenencia del diálogo
• Presta atención a elementos permanentes (marca de agua, subtítulo de descargo, logo), escríbelos al inicio del documento
• Recuerda los segundos correspondientes a cada fotograma (kf_001 = 0s, kf_002 = 10s...), se usarán para descripciones de escena

P3.5 Cuadrícula de subtítulos de todo el video: establecer tabla base de diálogo segundo a segundo (primera evidencia de pertenencia del hablante)

Para videos con subtítulos quemados (series cortas/videos de venta casi siempre los tienen), primero obtén la "respuesta oficial" del diálogo:

# Recorta la barra de subtítulos a 1 fotograma por segundo (primero extrae 1 fotograma completo para confirmar la posición vertical; en este ejemplo y=710, altura 140)
ffmpeg -y -v error -i "<video>" -vf "fps=1,crop=576:140:0:710,drawtext=fontfile='<font>':text='%{pts\:hms}':x=8:y=6:fontsize=24:fontcolor=white:box=1:[email protected],tile=3x10" -q:v 3 sub/grid%02d.jpg

• 30 fotogramas por imagen → para un video de 14 minutos, aproximadamente 29 imágenes; lee cada una con ViewImage para obtener "marca de tiempo → texto de subtítulo"
• Los subtítulos con borde azul/blanco suelen ser subtítulos de transición de narración (ej. "Los dos se separan a la fuerza"), se clasifican aparte, no se mezclan con el diálogo
• Los subtítulos de dos líneas pueden cortarse perdiendo la mitad superior —en caso de duda, revisa el fotograma completo de ese segundo

Esta tabla base segundo a segundo resuelve de una vez cuatro tipos de problemas: frases faltantes, frases duplicadas, errores de texto (él/ella), pertenencia de muletillas —cuando ASR y subtítulos entren en conflicto, primero confía en el texto del subtítulo, luego usa fotogramas de movimiento de labios para decidir el hablante (los subtítulos no indican quién habla).

P4 Construir el esqueleto: dividir el flujo de diálogo en segmentos de escena

1. Toma como eje las marcas de tiempo de ASR y divide por cambio de escena/espacio (cambio de lugar, cambio de interlocutor, cambio de tono emocional)
2. Formato de nombre de cada segmento: ⏱️ [mm:ss - mm:ss] Nombre del evento (etiqueta funcional), ejemplo: [04:15 - 05:10] Exploración en la mesa de enfermería · Primer aparición del bálsamo labial
3. Al inicio del segmento escribe > Descripción de escena: (luz, composición, posición de objetos principales, posición de los personajes)
4. Las líneas de diálogo dentro del segmento se disponen en orden cronológico, línea por línea; cuando varias personas hablan al mismo tiempo, separa en líneas y anota "(aquí suena simultáneamente con X)"

P5 Relleno de cinco dimensiones (cinco etiquetas debajo de cada línea de diálogo)

Etiqueta	Contenido obligatorio
🎙️ Textura de la voz	Tono / Volumen / Velocidad / Respiración (voz aireada·roto·inhalación·suspiro) / Acento en qué palabra / Pausa de cuantos segundos
😐 Trayectoria de cambio de expresión	Tres fases [inicio]→[medio]→[final], escribe acciones específicas de cejas, ojos, boca, alas de la nariz, mandíbula
👀 Interacción de mirada	[Sujeto] dirige la mirada hacia [Objeto nombrado], duración de la pausa; el movimiento de la mirada debe escribir la trayectoria
🙌 Detalles de acción	Postura de manos, orientación del cuerpo, trayectoria de movimiento, interacción con utilería (microacciones como nudillos blancos/apretar/temblor de puntas de dedos tienen prioridad)
🫧 Presencia y aura	Una frase que describa el estado psicológico de la persona en ese momento (perspectiva del director, no repetir la expresión)

Las muletillas deben analizarse como oraciones independientes: un "hum" debe especificar si es un sonido nasal o gutural, si es una risa fría o una rendición, y el intervalo con la siguiente oración —esto determina de qué personaje es.

P6 Verificación cruzada de segunda ronda (valor central de esta habilidad, no se puede omitir)

Problema: La transcripción única de todo el video fusiona las palabras de dos personas adyacentes en un solo párrafo, escribe él/ella como el mismo carácter, convierte preguntas en afirmaciones.

Método: Selecciona 4–6 "segmentos de alto riesgo" para retranscribir y comparar línea por línea con la transcripción completa.

Características de segmentos de alto riesgo (cualquier coincidencia justifica la división):

• Un segmento contiene ≥2 personajes en diálogo (especialmente susurros, peleas, escenas multitudinarias)
• Dos adultos del mismo sexo en la misma escena (tonos de voz similares, la agrupación tiende a fusionarlos en un solo ID)
• Aparece "él/ella" y la referencia podría ser ambigua
• Aparecen oraciones superpuestas, interrupciones, sonidos simultáneos
• Aparecen muletillas formando oraciones independientes (hum/oh/eh/ah)
• Escenas de despedida, forcejeo, persecución, despedida en estación ("quién es llevado, quién persigue" es muy fácil de escribir al revés)
• El intervalo de tiempo es >20 segundos y el ID del hablante no cambia (indica que se fusionó)

# Corta un segmento de 70–90 segundos (evita límites de silencio, deja 1s de margen al inicio y al final)
ffmpeg -y -v error -ss 15 -t 75 -i "<video>" -vn -ac 1 -ar 16000 -b:a 96k seg1.mp3

Ejecuta AudioTranscribe en cada segmento, luego determina según la tabla:

Tipo de diferencia	Método de determinación	Acción
Intercambio de hablante	Mira en la división si las posiciones de voz se alternan (A/B/A/B); luego combina con movimiento de labios y causalidad de la escena	Toma la regla de alternancia + lógica de la escena como válida, añade 📌 Nota de corrección en el texto
Confusión él/ella	El homófono siempre es incorrecto, reescribe según el género real del referido	Cambia directamente, no conserves el carácter original
Frase faltante (no está en la transcripción completa)	La oración que aparece en la transcripción del segmento no se encuentra en el texto principal	Devuélvela, ajusta la línea de tiempo del segmento
Oración fusionada necesita dividirse	Una oración con sujeto y predicado inconsistentes ("vete rápido no pierdas tiempo yo espero")	Divide en 2–3 líneas según el significado, asigna cada una a su hablante
Error de pregunta/afirmación	Mira si el tono final sube, si hay semántica de "?"	Oración de acusación usa "!", oración de indagación usa "?"
Voz en off vs. voz audible	En la división, si la posición de voz es continua con la anterior y posterior, si hay cambio de pista de audio	Continua misma posición = voz audible baja, debe anotarse "el otro no escuchó claramente" en lugar de "monólogo interior"
Dirección de acción invertida	Mira los fotogramas: la mano de quién agarra a quién, quién sube a qué auto, qué nombre dice el subtítulo al que se dirige	Invierte y reescribe todo el segmento, añade 📌 Nota de corrección en el texto y adjunta evidencia de fotogramas

Tercera ronda de revisión de imagen: Las conclusiones que implican dirección de acción, relación entre personajes (quién es llevado/quién persigue/quién agarra a quién) no pueden determinarse solo con la comparación de texto de la segunda ronda —debe volverse a la extracción densa de fotogramas (1 fotograma/s) para verificar la imagen y usar líneas de diálogo posteriores que se refieran al pasado (ej. "hace 15 años me llevaste") para inferir y bloquear mutuamente. Caso real en references/pitfalls.md #9.

Cuarta ronda de revisión de tabla base de subtítulos: Antes de entregar, usa la tabla base de subtítulos segundo a segundo de P3.5 para alinear línea por línea con el guion —cada línea en el guion que no coincida con el texto del subtítulo, o que esté en el subtítulo pero no en el guion, corrígelo/añádelo línea por línea; para puntos dudosos, extrae el fotograma completo y mira el movimiento de labios para decidir (el momento de extracción = el segundo en que aparece el subtítulo). Dos reglas especiales:

• El sonido original de flashback puede desbordarse: Después de que termine la imagen de flashback, el sonido original puede continuar en la toma de la realidad (ejemplo: en la toma real la madre tiene los labios cerrados, pero el subtítulo muestra el "shh" de la infancia) —la pertenencia sigue la pista de audio, no la imagen;
• El "ella" en el subtítulo no siempre es femenino: Los subtítulos originales suelen confundir él/ella, determina la referencia real según la semántica y referencias posteriores, pero al citar el subtítulo original, conserva el texto original y anota.

El registro de verificación debe incluirse en el entregable (tabla: punto de tiempo / texto original / texto verificado / base de determinación + grado de coincidencia + elementos no resueltos) —esto es la credencial de la confiabilidad del guion.

P7 Entrega y autoverificación

Produce un solo archivo Markdown, estructura en references/script-template.md; antes de entregar, revisa punto por punto con references/qc-checklist.md.

Finalmente, presenta con present_files y en la respuesta da: conclusión de identificación del video (título/categoría/duración), resumen de la trama en una frase, estructura de venta, cuántas correcciones se hicieron en esta verificación.

Herramientas de guion

scripts/extract_assets.sh realiza en un solo paso: sonda → audio → detección de escenas → extracción uniforme de fotogramas → división de segmentos de alto riesgo:

bash scripts/extract_assets.sh "<video>" "<outdir>" [intervalo de fotogramas en segundos]
# Ejemplo: bash scripts/extract_assets.sh ./v.mp4 ./frames 10

El script produce probe.txt, audio.mp3, kf_*.jpg (con correspondencia número↔segundo), scene_log.txt, e imprime el recuento de fotogramas/duración como tabla de carga de trabajo.

Archivos de referencia

• references/script-template.md — Estructura completa del entregable (archivo de personajes / tabla de tonos y presencias / cinco dimensiones por segmento / metodología de venta / hoja de indicaciones de actuación / registro de verificación)
• references/qc-checklist.md — Lista de 16 puntos de autoverificación previa a la entrega
• references/pitfalls.md — 10 tipos de errores frecuentes y contramedidas (con casos reales)

Convenciones de salida

• Formato de tiempo unificado mm:ss (más de 1 hora usar hh:mm:ss), en títulos de párrafo escribir el intervalo, dentro de bloques de diálogo se puede marcar el segundo
• Nombres de personajes unificados: primera aparición escribir nombre completo, en el texto usar 【】, ejemplo 【Madre Gu】
• Diferentes identidades del mismo personaje (seudónimo/niñez/adulto) deben archivarse por separado y escribir la correspondencia en el archivo
• Nombres de productos, marcas, precios deben verificarse fotograma por fotograma con los subtítulos (el ASR suele escuchar mal los nombres de marca, ejemplo: "胡萝问素" → "betacaroteno")