zenstory-ai/video-recap

1. Posicionamiento y Flujo de Trabajo

Esta habilidad es una herramienta de producción de resúmenes narrados y edición de video autocontenida que unifica la comprensión del video, la ideación narrativa, la edición visual, la redacción de la narración, la síntesis de locución y la mezcla de audio y video en un flujo de trabajo coherente. Todas las fases comparten un mismo directorio de trabajo work_dir donde se depositan los artefactos JSON y MP4:

understand.py (comprensión de video)─▶ El agente define la historia y el plan audiovisual y escribe clip_plan.json o narration.json ─▶ [cut.py (edición y nuevo resumen)] ─▶ validate.py (validación local) ─▶ voiceover.py (locución TTS) ─▶ assemble.py (mezcla y renderizado de subtítulos)

Para uso diario, se puede llamar directamente al punto de entrada principal scripts/recap.py que encadena automáticamente todo el flujo y se detiene en los puntos de creación. También es posible invocar por separado los puntos de entrada de cada fase ( understand.py, cut.py, validate.py, voiceover.py, assemble.py) bajo scripts/.

La descomposición de un video de muestra terminado en una referencia de producción (production_reference.json) no está en la cadena de producción predeterminada. Cuando el usuario solicite aprender de un video de muestra: primero, ejecute understand.py en el video de muestra (se recomienda configurar ASR_SEGMENT_SECONDS=5), luego use una habilidad de descomposición independiente para ejecutar secuencialmente la medición (measure), el marcado, la verificación (check) y la exportación (export). Copie el archivo production_reference.json exportado en el work_dir de la siguiente ejecución, o regístrelo como una plantilla production_reference en la biblioteca de recursos y vincúlelo a través de --project. El flujo principal no ejecutará automáticamente la descomposición ni comparará mecánicamente el nuevo video terminado con el video de referencia.

Todo el flujo admite la reanudación desde el último punto de control: después de que el agente escriba clip_plan.json o narration.json, simplemente vuelva a ejecutar el mismo comando recap.py para continuar. Al reanudar, el script verificará la ruta del video fuente, el tamaño del archivo, la hora de modificación y los parámetros de ejecución registrados en recap_run_manifest.json. Si el directorio de trabajo proviene de otro video o de una combinación de parámetros diferente, rechazará directamente la reutilización; el caché de comprensión de video solo se utilizará cuando el video fuente y la configuración sean exactamente iguales. El comando de reanudación impreso en la terminal en cada pausa conserva la sintaxis de la llamada original y convierte automáticamente los parámetros de video y ruta en rutas absolutas, completando --work-dir, de modo que se pueda ejecutar directamente pegándolo en cualquier directorio.

El flujo de video --edit-mode full|cut y la estrategia de audio --audio-mode narration|source-mix son independientes: narration utiliza la cadena de locución de resumen estándar, mientras que source-mix no genera locución y mezcla directamente el audio original con música de fondo opcional. El sistema solo admite las cinco rutas legales que se muestran en la siguiente tabla; cualquier otra combinación bloqueará el inicio con un error:

Entrada	--edit-mode	--audio-mode	Punto de pausa del agente	Flujo	Detalles
Video único	full	narration	1 vez: escribir narration.json	Comprensión → Redacción → Validación → Locución → Síntesis	§4
Video único	cut	narration	2 veces: primero escribir clip_plan.json, luego de editar, escribir narration.json para el video resultante	Comprensión → Edición → Nuevo resumen de tiempo de salida → Redacción → Validación → Locución → Síntesis	§4
Múltiples videos	cut	narration	2 veces: igual que arriba, y cada fragmento debe tener source_id	Comprensión por fuente → Edición → Redacción → Validación → Locución → Síntesis	§4.5
Video único	full	source-mix	Sin pausa	Sintetizar directamente el video completo actual (sin comprensión ni TTS)	§4.7
Video único / múltiple	cut	source-mix	1 vez: escribir clip_plan.json	Comprensión → Edición → Síntesis (sin redacción de narración)	§4.7

2. Responsabilidades Creativas

El poder de decisión creativa recae completamente en el agente. Antes de comenzar, el agente debe determinar el modo de control creativo de esta ronda (CREATE creación libre / DIRECTED creación dirigida / REVISION revisión final, independiente de --edit-mode) y, actuando como un único cerebro creativo, realizar cinco juicios clave antes de la locución y el renderizado:

1. Juicio de dirección: Definir qué verá la audiencia, qué punto de vista (POV) se seguirá en todo momento, cuál es el misterio central, cómo fluye la emoción de principio a fin y qué carta se guarda para el final.
2. Edición narrativa: Cada ritmo (beat) debe explicar un "cambio sustancial en la situación", evitando resúmenes de escenas lineales.
3. Edición visual: Seleccionar las acciones más impactantes, las reacciones faciales y los mejores puntos de entrada y salida, eliminando las transiciones lentas.
4. Sonido / Narración: Primero decidir si cada ritmo está dominado por la imagen, el diálogo original, los sonidos de acción, el silencio o la narración, y luego escribir el guion siguiendo el ritmo de "cubrir media frase, dejar media frase, conectar media frase".
5. Revisión del espectador: Ponerse en el lugar del espectador que ve el video por primera vez y realizar tres comprobaciones: ver el video sin narración, escuchar solo el audio con los ojos cerrados, y verificar el cumplimiento de la promesa inicial.

Las responsabilidades de los tres modos de control, las reglas de bloqueo sin retroceso en modo REVISION, las técnicas específicas de edición y escritura, y las especificaciones de formato de recap_story_plan.json, visual_audio_board.json y style_card.json se detallan en references/creative-editing-playbook.md. Estos archivos JSON se utilizan para almacenar decisiones creativas que se pueden revisar, asegurando que la selección de tomas, los silencios del audio original y la narración se mantengan fieles a la misma intención narrativa de principio a fin.

3. Entorno y Notas sobre Llamadas Remotas

# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***

Una sola MIMO_API_KEY es suficiente para impulsar toda la cadena predeterminada. Para garantizar la transparencia del flujo de datos, los detalles de las partes de esta habilidad que implican llamadas de red remotas son los siguientes:

• Comprensión de video (understand.py): Envía las ventanas de audio segmentadas a MiMo ASR (mimo-v2.5-asr) y los fotogramas JPEG extraídos junto con el resumen de background_research.json a MiMo VLM (mimo-v2.5). Si el directorio de trabajo ya contiene el producto de análisis completo, pasar --brief-only o --edited-storyboard-only ejecuta todo localmente sin iniciar ninguna solicitud de red.
• Locución de narración (voiceover.py): Según --tts-provider (por defecto auto prioriza MiMo configurado, luego Fish Audio, nunca selecciona automáticamente index-tts), envía el texto de la narración al servicio TTS correspondiente:
  • mimo-tts: Envía a MiMo TTS (mimo-v2.5-tts); si se pasa explícitamente --voice-ref <audio>, también envía segmentos de ese audio de referencia a mimo-v2.5-tts-voiceclone (asegúrese de tener la autorización de voz antes de usar).
  • fish-audio: Requiere configurar FISH_API_KEY. Envía cada segmento de texto de la narración y FISH_TTS_REFERENCE_ID a FISH_TTS_API_URL (por defecto https://api.fish.audio/v1/tts).
  • index-tts: Solo se activa cuando se especifica explícitamente --tts-provider index-tts. Envía el texto y INDEX_TTS_VOICE al INDEX_TTS_ENDPOINT autoalojado por el usuario (ver references/index-tts.md para más detalles).
• Validación de narración (validate.py), edición de video (cut.py, shot_review.py) y síntesis de audio y video (assemble.py): Lógica determinista local y llamadas a ffmpeg / ffprobe. No inician ninguna solicitud de red.

Las claves de Token Plan que comienzan con tp- se envían por defecto al clúster de China. Se puede cambiar el clúster mediante MIMO_TOKEN_PLAN_CLUSTER. La lista completa de opciones de configuración se encuentra en references/config-playbook.md, y los formatos de todos los artefactos intermedios se describen en references/data-schema.md. En el texto a continuación, scripts/... es relativo al directorio de esta habilidad.

4. Flujo de Trabajo Creativo y de Edición Fluido

4.1 Investigación de Antecedentes y Comprensión de Video

Siempre que se pueda reconocer el nombre de la película, el nombre de la serie o el tema científico a partir del nombre del archivo o las instrucciones del usuario, antes de comenzar, investigue las relaciones y los antecedentes de los personajes según references/research-guide.md y escríbalos en work_dir/background_research.json. De esta manera, al ejecutar el análisis de video posteriormente, se podrá nombrar correctamente a los personajes y comprender el subtexto, evitando referencias genéricas como "hombre de negro" o "mujer joven". Al editar varios videos, también se escribe en el work_dir raíz del proyecto, y el script lo sincronizará automáticamente con los subdirectorios de cada fuente sources/<source_id>/.

Luego, inicie la entrada de comprensión y organización:

python3 scripts/recap.py <video> --work-dir <work_dir> --context "antecedentes"

Después de que el script realice la extracción de audio, la detección de puntos de anclaje de silencio y pausa final de frase (speech_boundary_anchors.json), la segmentación de escenas, el análisis de cuadros VLM y la transcripción ASR, generará un mosaico del storyboard (storyboard/storyboard_*.jpg) y un resumen creativo (agent_narration_brief.md), y se detendrá automáticamente.

4.2 Intención del Director y Plan de Selección de Tomas (Primera Fase del Modo cut)

Después de leer agent_narration_brief.md y revisar directamente las imágenes del storyboard, primero escriba recap_story_plan.json (que enumere al menos 2 planes candidatos y seleccione el POV principal, el gancho inicial, el arco emocional y la carta guardada) y visual_audio_board.json (que especifique para cada ritmo qué momento visual elegir, por qué entrar y salir, y qué elemento sonoro domina).

En la primera fase del modo cut, proceda a escribir el work_dir/clip_plan.json basado en la línea de tiempo del video original (SOURCE) (en este punto aún no se escribe narration.json):

{
  "target_duration": "3m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 | hook | knowledge: unknown→threat | POV=沈曼 | Se encuentra con su prometido abrazando a una heredera hablando de una alianza matrimonial | Punto de entrada=Empuja la puerta y ve la acción de ambos | Punto de salida=Se da la vuelta y aprieta el libro de registro familiar"
    }
  ],
  "required_evidence": {
    "nodes": [
      {"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "Empuja la puerta y se encuentra con ambos abrazándose"}
    ],
    "before": []
  }
}

La selección de tomas y los puntos de corte deben cumplir estrictamente con las siguientes reglas:

• Estructura de siete partes en reason: Escriba secuencialmente beat_id | función narrativa | cambio de estado de la situación (A→B) | POV=personaje | punto destacado sustancial de este segmento | Punto de entrada=acción específica/anclaje de audio original | Punto de salida=reacción específica/punto de aterrizaje, lo que obliga a que cada segmento de imagen sirva para el avance de la historia.
• Evidencia de imagen y audio original obligatoria (required_evidence): Las decisiones finales sobre las acciones destacadas, los momentos de cambio facial o las preguntas y respuestas clave del audio original que se deben conservar se escriben en el required_evidence de nivel superior (nodes registra id/ruta absoluta de source/start/end/track/content, before registra pares de orden que no se pueden invertir); si el ajuste de límites elimina cualquier intervalo de evidencia obligatoria o altera el orden, el script informará directamente un error y bloqueará.
• Entrada tardía y selección de tomas: Por defecto, se sigue un orden cronológico de "entrada tardía" (se empieza directamente desde el estallido del conflicto, una comparación absurda o una acción clave, eliminando las introducciones lentas como empujar una puerta para entrar, saludos, etc.). Solo se permite usar un <= 2.5s de toma de suspenso de inicio en frío si el conflicto en orden cronológico aparece demasiado tarde, y debe cumplir que se pueda entender sin preparación, no repetir la misma toma de cámara que en el video principal, y solo dejar suspenso sin adelantar el resultado del giro final. Cuando la narración baja el volumen del audio original, se deben priorizar las reacciones faciales del oyente, los detalles de acción o las tomas estables, evitando colocar debajo de la narración imágenes de un personaje de frente hablando sin parar cuyo sonido se silencia; no repita el mismo tipo de asentimiento o mirada vacía más de dos veces.
• Puntos de corte seguros al final de la frase y cola de respiración: El punto de corte debe caer al inicio o final del video original, en un punto de anclaje de pausa final de frase o dentro de una ventana de silencio, o pertenecer a una unión sin costura de fragmentos adyacentes de la misma fuente; al ajustarse al final de una frase, se reservará automáticamente un máximo de 0.30s de reacción/respiración dentro de la ventana de pausa sin cruzar nunca el punto de corte duro, y la duración mínima del fragmento no será inferior a 0.8s. El último ritmo del video debe dejar 1.5–2.5s de resonancia emocional después de que la acción final o el diálogo concluyan, y terminar limpiamente antes de pasar a la siguiente escena. Si se pisa el medio de un diálogo original, se activará la comprobación unsafe_clip_sentence_boundary y se proporcionará nearest_safe; si al retroceder el ajuste del corte duro se exponen simultáneamente <= 0.20s de fotogramas parpadeantes y diálogo truncado, se informará directamente shot_speech_conflict y se bloqueará.
• Corte rápido de alta frecuencia e inspección de fragmentos cortos: Después de que cut.py renderice edited_source.mp4, llamará automáticamente a shot_review.py para generar shot_review.json y bloqueará directamente los fragmentos de residuo extremadamente cortos (flash_slivers) con una duración <= 0.20s (aproximadamente 1–5 fotogramas). Ante escenas de acción o cortes de contraplano densos, también se puede ejecutar manualmente ffmpeg -i <video> -vf "select='gt(scene,0.35)',showinfo" -f null - o la herramienta de solo lectura scripts/shot_review.py (uso en references/shot-review.md) para localizar puntos de corte de alta puntuación, pero es necesario distinguir entre los cortes propios del video original y los cortes generados por el montaje actual: si se trata de un corte propio del video original debido a la eliminación completa de una toma corta irrelevante o mover el corte al exterior del clúster de cortes rápidos; si se trata de un corte generado por el montaje actual (por ejemplo, bordes de corte duro que dejan residuos de unos pocos fotogramas de la toma adyacente, contraplanos fragmentados), entonces expanda los puntos de entrada y salida o combine fragmentos adyacentes de la misma fuente, y está estrictamente prohibido usar transiciones para disimular.

Después de escribir clip_plan.json, vuelva a ejecutar recap.py. El script llamará a cut.py para completar tres pasos de ajuste de límites (ajuste a corte duro de cámara → ajuste a silencio final de frase con cola → alineación a cuadrícula de fotogramas), renderizará edited_source.mp4 con una frecuencia de cuadros constante y completará la inspección de fotogramas parpadeantes. Luego, reasignará los anclajes ASR, VLM y finales de frase a la línea de tiempo de salida del video resultante (speech_boundary_anchors_output.json, storyboard/edited_storyboard.*), y se detendrá nuevamente para esperar la escritura del guion de la narración.

4.3 Creación de la Narración y los Silencios del Audio Original (Modo full / Segunda Fase del Modo cut)

Al entrar en la fase de redacción del guion (primera pausa en modo full, segunda pausa después de editar edited_source.mp4 en modo cut), primero revise el storyboard posterior a la edición, complete el tiempo de salida del video resultante en visual_audio_board.json y, si es necesario, escriba style_card.json. Luego, redacte work_dir/narration.json:

[
  {
    "start": 0.2,
    "end": 5.0,
    "narration": "Tras cinco años juntos, Shen Man fue a proponer matrimonio con el libro de registro familiar en la mano. Al abrir la puerta, se encontró con su prometido abrazando a una heredera para hablar de una alianza.",
    "pause_after_ms": 250,
    "overlaps_speech": true
  }
]

Nota: En el modo cut, las marcas de tiempo en narration.json deben ser las del tiempo de SALIDA del video editado (0 .. duración total del video resultante) (al llamar al validador por separado, pase validate.py --mode cut_output). Al escribir, siga las nueve reglas principales de escritura (las reglas detalladas y ejemplos positivos y negativos se encuentran en references/creative-editing-playbook.md):

1. Muestre el gancho o el momento destacado del audio original en los primeros 2.5 segundos, lanzando directamente una acción contrastante concreta o el misterio central. No escriba currículums de personajes, anuncios de fechas o aperturas de cortesía; una apertura en frío de más de 2.5s sin narración ni diálogo original activará la comprobación weak_cold_open_silence.
2. Explique claramente los antecedentes, las relaciones entre personajes y las causas y consecuencias. Controle la densidad de nombres, rechace la "descripción literal de la imagen": Cuando se proporcionen nombres de personajes en background_research.json, está estrictamente prohibido usar términos genéricos como "hombre de negro" o "mujer joven" (de lo contrario, se reportará generic_character_label). En videos de 60 segundos o menos, nombre como máximo 1 o 2 personajes principales (en la primera oración, nombre como máximo a 1 persona y mencione su identidad de paso). Al resto de personajes secundarios, refiérase a ellos por su relación o identidad (por ejemplo, "la exnovia", "su jefe", "el médico imperial"), y avance oración por oración en torno a "situación → acción → consecuencias inmediatas".
3. Sincronización audiovisual de "cubrir media frase, dejar media frase, conectar media frase" y las imágenes fuertes deben ser sincrónicas: Ceda el paso decisivamente antes de un diálogo original destacado, un sonido de bofetada o un cambio facial silencioso. Después de que el audio original termine, conecte con media frase para revelar el subtexto. Cuando aparezcan acciones visuales contundentes como besos, bofetadas, arrodillarse, desmayos o la exhibición de un objeto simbólico, la narración debe estar cerca o el audio original debe permanecer para explicar la causa y el efecto. Está prohibido que imagen y narración cuenten cosas diferentes. En todo el video, no debe haber una ventana de silencio muerto de más de 5.0s consecutivos sin narración ni diálogo original (de lo contrario, se activará la comprobación excessive_dead_air).
4. Respete estrictamente las líneas rojas duales de entrada y recuperación del audio original: Al bajar el volumen del audio original para introducir la narración (overlaps_speech: true), start debe estar cerca del anclaje final de la frase o de la zona de silencio (de lo contrario, se reportará interrupts_source_sentence). Al finalizar la narración y restaurar el audio original, no se debe aumentar el volumen repentinamente en medio de la frase de un personaje (esto se reportará como unsafe_source_release / unsafe_source_handoff durante la validación y la síntesis, respectivamente).
5. Controle estrictamente el presupuesto de palabras por ventana de tiempo, mantenga un ritmo de habla natural y termine las oraciones de forma completa: Cada segmento debe terminar con un signo de puntuación de cierre de oración completa (las oraciones truncadas activarán incomplete_sentence). Adapte la ventana de tiempo mediante la concisión de palabras, no esperando meterlas a alta velocidad. En modo full, superar el presupuesto en 1.25 veces reportará directamente over_budget. El validador nunca eliminará palabras por sí mismo.
6. Elimine el tono editorializante y el tono telegráfico, deje que el final lo muestren las imágenes: Escriba oraciones largas y cortas fluidas y naturales, no oraciones fragmentadas palabra por palabra. Está estrictamente prohibido escribir comentarios de estilo "lectura de comprensión" y generalizaciones como "Esto significa...", "Esta es una lucha sobre...", "Deja que el orgullo y el poder se retiren", "El engranaje del destino" (esto activará la advertencia editorial_commentary_tone). El final de la historia debe ser interpretado por las imágenes y el audio original en el momento. Está estrictamente prohibido añadir una oración final de resumen después de que el final se haya cumplido, ni arrastrar una cola de audio original que repita el mismo resultado después de la narración de cierre.
7. Ancle evidencia visual específica y disciplina de música instrumental: Hable con miradas, accesorios y detalles de acción que se puedan ver. No invente actividades psicológicas fuera de la imagen para los personajes. Si se elige música de fondo externa (BGM_PATH), debe ser exclusivamente instrumental (sin letra vocal). Cuando el video original ya tenga una canción de fondo vocal alta que no se pueda evitar, no se debe superponer música de fondo externa para evitar que múltiples pistas vocales compitan.
8. Apruebe los subtítulos del audio original: Cuando se active la máscara de subtítulos del video original y se conserven segmentos destacados de audio original, escriba simultáneamente los diálogos originales corregidos en work_dir/original_subtitles.json según el tiempo del video resultante, corrigiendo los errores de homófonos del ASR.
9. Después de escribir, realice tres autoinspecciones: Primero, lea todo el texto para ver si la historia tiene sentido y los hechos coinciden con el video original. Luego, verifique las ventanas de tiempo para detectar si hay interrupciones o exceso de palabras. Finalmente, ejecute validate.py (o vuelva a ejecutar recap.py). Si es necesario redactar un título promocional externo, un fotograma de portada y un plan de texto gráfico (packaging_plan.json), debe hacerse después de que la historia principal esté bloqueada, siguiendo references/promotional-copy.md.

4.4 Síntesis de Locución y Mezcla de Audio y Video

Después de escribir narration.json, vuelva a ejecutar el mismo comando recap.py:

1. Validación local determinista (validate.py): Genera narration_lint.json. Realiza comprobaciones de bloqueo estricto para superposiciones de tiempo, desbordamiento, exceso de presupuesto de palabras, oraciones truncadas, apertura en frío, ventanas de silencio muerto de más de 5 segundos, interrupción del diálogo original, restauración del audio original a mitad de frase, etiquetas de personajes genéricos y fuga de marcadores de posición. Si hay algún error, se detiene inmediatamente.
2. Locución TTS (voiceover.py): Sintetiza el habla segmento por segmento y escribe en tts_segments/ y tts_meta.json. El caché se activa exactamente según el texto, el timbre, el modelo y la huella del audio de referencia. Si la duración del audio de un segmento es inferior al límite inferior de velocidad de habla normal (TTS_MIN_SPEECH_RATE), lo que sugiere una posible alucinación del modelo, se reintentará automáticamente y se conservará un archivo *.rejected.wav rechazado fuera del lote.
3. Síntesis de audio y video (assemble.py): Mezcla y renderiza en un MP4 final: las imágenes, la narración segmento por segmento, el audio original reducido y restaurado al final de la frase (ver source_handoff_status en references/data-schema.md), el BGM opcional (BGM_PATH), efectos de sonido de transición opcionales y empaquetado visual de lujo (work_dir/packaging_plan.json: admite encuadre vertical 9:16 de doble línea dorada para escenario/serie, marco de cine 16:9 y tiras de subtítulos con sensación de papel blanco arroz, sobremuestreo @2x de placas de identificación de personajes, tarjetas de datos, texto gráfico caligráfico, y subtítulos de doble capa con luz suave para palabras clave; o packaging_layers.json para imágenes estáticas), y un fundido a negro suave al final (por defecto 350ms). También genera un timeline.json independiente del backend (pase --export-jianying para exportar simultáneamente un borrador de Jianying).

Si cualquier segmento de narración no cabe en la ventana de tiempo disponible incluso dentro del límite de micro-aceleración permitido, el sintetizador reportará directamente no_safe_fit y bloqueará, nunca cortando el final de la narración. Más modos de sonido, enrutamiento de audio y especificaciones de empaquetado visual externo se encuentran en references/audio-modes.md, references/audio-routing.md y references/packaging.md, respectivamente.

4.5 Edición de Múltiples Videos y Biblioteca de Recursos

La entrada de múltiples videos solo es compatible con el modo cut. El resumen a nivel de proyecto enumerará un source_id fijo para cada video. Al escribir clip_plan.json, cada fragmento debe indicar el source_id al que pertenece:

python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep

Si desea almacenar los resultados de comprensión de un solo episodio en un directorio local para reutilizarlos en varios episodios, puede activar una biblioteca de materiales de archivos liviana (--material-library-dir .video-materials --save-materials y --use-materials) y usar directamente grep para buscar archivos JSON/MD. En el mismo directorio raíz de la biblioteca, también se pueden registrar recursos de producción reutilizables (BGM, efectos de sonido, timbres, fuentes, imágenes), plantillas con historial de adopción (subtitle_style, packaging, production_reference) y videos de muestra. Se pueden consultar con scripts/library.py check|list|show y vincular a la ejecución actual con --project recap_project.json. Al final de cada síntesis, se registrarán los recursos realmente utilizados y su estado de autorización en work_dir/resource_lock.json. Para más detalles, ver references/resource-library.md.

Si necesita medir el intervalo vertical de píxeles de los subtítulos duros del video original para habilitar una máscara precisa, puede ejecutar tools/measure_subtitle.py <video> en el repositorio de código fuente completo, o simplemente revisar las imágenes de fotogramas extraídos para medir los bordes superior e inferior, y luego pasar --subtitle-y-top y --subtitle-y-bot.

4.6 Visualización Final y Revisión de Entrega

Ningún indicador de script, puntuación de corte, mosaico de fotogramas o informe de control de calidad automático puede reemplazar la visualización y audición humanas. Antes de cada entrega, es obligatorio abrir directamente el archivo de video final que se entregará al usuario en esta ronda y realizar una revisión de cinco pasos:

1. Ver a velocidad normal una vez: De principio a fin, sin acelerar ni saltar, anotando cualquier punto que llame la atención o tenga problemas de fluidez.
2. Examinar cada punto de corte individualmente: Mire 0.5–1 segundo antes y después de cada punto de corte para detectar fotogramas parpadeantes, disolvencias a medio hacer, saltos de acción y diálogos originales cortados a la mitad.
3. Cerrar los ojos y solo escuchar una vez: Sin mirar las imágenes, solo escuche el audio. Verifique si la narración está fragmentada en un tono telegráfico, si las transiciones de sonido son suaves y si los diálogos originales clave son claros.
4. Aislar tres puntos culminantes: Vuelva a ver por separado el gancho de apertura de los primeros 5 segundos, el punto culminante emocional de la mitad y la última escena del final. Confirme que el momento de entrada, la retención emocional y la resonancia final sean sólidos.
5. Conciliación de revisiones y verificación de especificaciones: En modo REVISION, primero confirme uno por uno que "lo que se pidió cambiar se cambió realmente, y los elementos bloqueados no solicitados permanecen intactos". Finalmente, verifique la integridad de la decodificación, la duración total, el escaneo de fotogramas residuales y las especificaciones de codificación de audio y video en final_qc.json (--require-final-qc está activado por defecto; los elementos de bloqueo determinan directamente el código de salida; solo se puede pasar --no-require-final-qc durante la depuración).

Al entregar el video final, asegúrese de revisar metadata.warnings en final_qc.json: si no está vacío (por ejemplo, si aparece partial_tts por segmentos faltantes después de habilitar la tolerancia a fallos parciales, o si ffmpeg en la máquina local carece de libass lo que provoca una degradación subtitle_burn_degraded a un .srt externo), debe informar al usuario con honestidad, no solo decir "renderizado exitoso".

4.7 Video Final con Audio Original sin Narración

# Mezcla y sintetiza directamente la entrada completa actual; no ejecuta implícitamente comprensión, ASR o TTS
python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
# Genera un plan de edición mediante el flujo cut, edita y sintetiza directamente el video final con audio original, sin esperar más a narration.json
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix

source-mix ejecutará la mezcla completa, el fundido a negro suave final y la recodificación de audio. Al cambiar el modo de audio, se debe usar un directorio de trabajo completamente nuevo. Ver references/audio-routing.md para más detalles.

5. Autocomprobación y Panel de Solo Lectura

python3 scripts/doctor.py
python3 scripts/dashboard_server.py --root <directorio> [--port 0] [--open]

doctor.py verifica ffmpeg / ffprobe local, los filtros de subtítulos y la conectividad de las claves de varios servicios remotos. dashboard_server.py inicia una plataforma de revisión de video estrictamente de solo lectura en 127.0.0.1 (solo responde a GET y HEAD), escanea automáticamente los directorios de trabajo de video resultante y library.json bajo --root, y muestra de forma intuitiva la reproducción del video resultante, la narración en sincronía con las tomas y una vista previa de la biblioteca de materiales.

6. Salida y Parámetros

Artefactos de entrega principales:

• recap_<video>.mp4: Video final narrado o con audio original.
• subtitles.srt / subtitles.ass: Archivos de subtítulos generados.
• work_dir/: Conjunto completo de artefactos intermedios de análisis, planificación y validación. El contrato de campos se encuentra en references/data-schema.md.
• work_dir/recap_story_plan.json y visual_audio_board.json: Decisiones de dirección y storyboard audiovisual tomadas por el agente.

La lista completa de parámetros de línea de comandos se basa en la salida de python3 scripts/recap.py --help y --help de los scripts de cada fase. --style es un requisito de texto libre que se pasa sin cambios al agente de redacción, no es un valor predefinido fijo o un interruptor de enumeración.

7. Límites de Capacidad

• Las comprobaciones de validación local determinista (fotogramas residuales/fragmentados, truncamiento de diálogos, narración que pisa el diálogo, límite máximo duro de palabras por ventana de tiempo, truncamiento de cola larga, pérdida de evidencia obligatoria, fuga de marcadores de posición, especificaciones de decodificación y encapsulación) siempre se ejecutan como bloqueo estricto; el script solo es responsable de la ejecución mecánica y el aseguramiento del mínimo técnico.
• La calidad semántica y narrativa, como el arco argumental, el gancho inicial, la respiración audiovisual y la coherencia de los hechos, no tienen un umbral de puntuación de modelo. El agente es responsable de controlarlas de forma autónoma basándose en la evidencia visual, la línea de tiempo del audio original y references/creative-editing-playbook.md, y de completar la revisión audiovisual antes de la entrega.