video-add-captions

Video Add Captions

Dependencias

/video-understand es un prerrequisito. Ejecútelo primero para que los subtítulos usen la transcripción validada palabra por palabra y la línea de tiempo canónica. Antes de comenzar, verifique que esté instalado. Si no lo está, advierta al usuario que falta este prerrequisito y deténgase antes de procesar el material multimedia.

Requiere ffmpeg/ffprobe en el PATH, Python con Pillow y Node.js >= 22 (para los scripts .mjs y npx hyperframes, descargados bajo demanda). hyperframes render/snapshot utiliza un Chrome sin interfaz gráfica (headless): gestiona su propio chrome-headless-shell y recurre a un Chrome del sistema (configure CHROME para anularlo) cuando el caché no es utilizable. Verifique estos antes de procesar el material multimedia.

Alcance

Esta habilidad se encarga de la agrupación de subtítulos, selección de estilo, revisión y la pista de subtítulos transparente. No transcribe, corta, reajusta tiempos, califica, reencuadra ni elige la política de audio de entrega.

Ejecute los subtítulos antes de las tarjetas de contenido y los gráficos en movimiento cuando cualquiera de ellos esté seleccionado. El diseño de subtítulos aprobado establece una región reservada de subtítulos que ambas operaciones posteriores deben mantener despejada. Este orden relativo también se aplica cuando solo un par está activo.

Use video-understand primero. Si existe un corte, subtitule la línea de tiempo del programa activo; no trate los segundos de la transcripción fuente como segundos del programa.

Entradas del Protocolo

Obligatorias:

• work/project.json
• work/understand/transcript.json, con marcas de tiempo fuente a nivel de palabra
• work/understand/media.json
• work/timeline.json
• el video fuente nombrado por work/project.json

La línea de tiempo es la única asignación de fuente a programa. Todos los rangos son semiabiertos [start_s, end_s). scripts/build_captions.py usa projectlib.map_transcript_to_timeline compartido; las palabras en rangos fuente eliminados desaparecen, las palabras retenidas se mueven al tiempo del programa y las señales siempre se rompen en los límites de los clips.

Salidas Duraderas

work/captions/
|-- captions-plan.json
|-- caption-spatial-context.json (solo para composiciones B-roll elegibles)
`-- caption-interaction.json
work/cache/captions/
|-- preview-project/
|-- preview-snapshots/
|-- overlay-project/
`-- overlay-frames/frame_000001.png ...
review/05-captions/
|-- captions.srt
|-- captions-style-review-<UUID>.html
|-- captions-style-review.html
|-- captions-review.html
|-- preview-early.png
|-- preview-middle.png
|-- preview-late.png
|-- preview-no-caption.png
|-- captions-evidence.json
`-- captions-summary.md

Los HTML generados, archivos de tiempo de ejecución copiados, fotogramas fuente extraídos y fotogramas de superposición son caché. El plan, el contexto espacial opcional, el SRT, el recibo de decisión y la evidencia de revisión son duraderos.

Plan de Subtítulos

work/captions/captions-plan.json es el plan canónico de subtítulos, apunta a overlay y usa tiempo de programa. Registra:

• timeline_id, program_duration_s y la ruta de la transcripción fuente;
• configuraciones de agrupación de señales;
• estilo aprobado, modo de decisión, justificación, elección de galería y estilo resuelto completo;
• evidencia de revisión respaldada por la fuente y actor de aprobación;
• señales con campos de compatibilidad start, end, text, lines y words;
• program_range y source_ranges en cada señal;
• rangos de programa/fuente y clip_id en cada palabra mapeada;
• una receta de renderizador local con FPS racional exacto y activos de tiempo de ejecución con hash.

El generador también acepta el antiguo arreglo de señales de nivel superior. Eso es solo un adaptador de compatibilidad independiente; no puede expresar la procedencia de la línea de tiempo ni regenerar una contribución de protocolo aprobada.

Estándar es el modo de presentación predeterminado. Los planes estándar no necesitan un campo presentation y no deben migrarse solo para agregarlo. Expresivo es un modo de presentación explícito, no un preajuste: solicítelo con --presentation-mode expressive. El paso de construcción luego agrega IDs de señal estables, valores predeterminados de semantic_role de palabra y un esqueleto de planificación presentation de borrador; no adivina variantes de diseño.

Expresivo solo admite bottom-standard y center-emphasis. Lea reference/caption-rules.md antes de llenar el esqueleto. El renderizador existente consume solo presentation.layout_beats completados; no infiere posiciones ni cambia el diseño dentro de un beat.

Las señales expresivas también pueden definir una hero_line contigua a nivel de frase. Use el nivel canónico level: hero; renderiza la frase en dorado en su propia línea a 1.5x. El nivel heredado level: strong sigue siendo aceptado como un alias de entrada y se renderiza de manera idéntica, pero los nuevos planes creados por Agentes no deben emitirlo. Los roles de palabra mantenidos keyword, number y contrast usan 1.22x; normal sigue siendo 1.0x. Estos tratamientos son ortogonales a los preajustes y no crean nuevos IDs de estilo. Lea reference/caption-rules.md para el esquema, la política de desbordamiento y las reglas de Karaoke.

Cuando una operación B-roll activa y aprobada por revisión contiene composiciones de recuadro de orador aprobadas o verificadas, los subtítulos pueden derivar caption-spatial-context.json del plan upstream congelado, la evidencia, las composiciones normalizadas y el display_mode de subplano explícito. Esto no modifica ni vuelve a seleccionar el diseño B-roll. Alinea los límites de las señales antes de la planificación Expresiva y resuelve solo las ubicaciones mantenidas preset-bottom, frame-center, panel-center y panel-bottom solo de límite. panel-bottom solo está permitido para un unsplittable_word_boundary adyacente a un panel enfocado en el centro inferior; centra la señal estable dentro de la franja reservada debajo del rectángulo estructurado del orador. Dicha señal se verifica en cada contexto visual que intersecta, no solo en el contexto que contiene el punto medio de la palabra. Sin este contexto, todo el comportamiento de colocación Estándar y Expresivo existente permanece sin cambios.

Estilos

Los preajustes mantenidos son clean, minimal, social-bold, pill, boxed, stroked y shorts. Los IDs de combinación de galería agregan temas mantenidos, por ejemplo pill-yellow, stroked-blue y shorts-green. Karaoke es una opción, no un preajuste separado.

Elección delegada predeterminada: clean, Karaoke desactivado. Elija un preajuste más expresivo solo cuando el destino o el material lo justifique. Almacene los cambios específicos del trabajo en un JSON de anulaciones; no edite el generador para comentarios de estilo ordinarios.

Expresivo admite tanto semantic-only (Karaoke desactivado) como semantic-plus-karaoke (Karaoke activado). El énfasis semántico persiste durante toda la señal en ambas configuraciones. En modo de coexistencia, el énfasis semántico y la palabra Karaoke activa usan style.wordHighlight.activeColor como su color de primer plano en cada modo de resaltado; un resaltado de fondo sigue siendo un efecto adicional. La escala efectiva es max(escala semántica, escala activa de karaoke), nunca su producto. Expresivo nunca renderiza un subrayado, incluso para el rol semántico compatible contrast.

El contrato de revisión existente continúa usando semántico-solo como la evidencia Expresiva principal y vincula semántico-más-karaoke por separado. El campo de carga útil de compatibilidad permanece nombrado experimental_comparison; no lo renombre sin una migración del protocolo de aprobación.

Lea:

• reference/caption-rules.md antes de cambiar los límites de agrupación;
• reference/caption-style-themes.md para el vocabulario de estilo;
• reference/caption-feedback-mapping.md para el mapeo de anulaciones.

Modos de Decisión

Dos modos honestos comparten la misma máquina de estados vinculada por hash:

• human: pase el resumen de galería copiado exacto a select, muestre toda la evidencia de vista previa real y pase el resumen de aprobación o revisión copiado exacto a confirm o adjust. Los comandos vinculados a la página de revisión no aceptan frases de aprobación simples.
• agent: úselo solo cuando el usuario delegue explícitamente las decisiones de subtítulos. Comience con una nota de delegación no vacía, luego use agent-select y agent-confirm con justificaciones no vacías.

Los comandos humanos fallan en modo agente y los comandos de agente fallan en modo humano. Estándar sin contexto espacial requiere las cuatro imágenes mantenidas respaldadas por la fuente; las revisiones Expresivas y conscientes de la composición usan sus contratos de evidencia dinámicos. Un cambio en la fuente, el plan, la línea de tiempo, el estilo, la anulación, los metadatos del proyecto, la página de revisión o la evidencia invalida la aprobación; el contexto espacial, la revisión B-roll upstream o los cambios de composición vinculada hacen lo mismo. Reconstruya los artefactos afectados y revíselos nuevamente.

Flujo de Trabajo Canónico

Ejecute desde la raíz del repositorio. Establezca las rutas del proyecto:

$RepoRoot = (Resolve-Path ".").Path
$SkillRoot = Join-Path $RepoRoot "skills\video-add-captions"
$ProjectRoot = (Resolve-Path "<project-root>").Path
$Work = Join-Path $ProjectRoot "work"
$SourceVideo = "<absolute path from work/project.json>"
$Plan = Join-Path $Work "captions\captions-plan.json"
$SpatialContext = Join-Path $Work "captions\caption-spatial-context.json"
$SpatialArgs = @()
$SpatialReviewArgs = @()
$Receipt = Join-Path $Work "captions\caption-interaction.json"
$Review = Join-Path $ProjectRoot "review\05-captions"
$Cache = Join-Path $Work "cache\captions"
$PreviewProject = Join-Path $Cache "preview-project"
$ComparisonProject = Join-Path $Cache "preview-project-expressive-karaoke"
$OverlayProject = Join-Path $Cache "overlay-project"
$OverlayFrames = Join-Path $Cache "overlay-frames"
New-Item -ItemType Directory -Force -Path (Split-Path $Plan),$Review,$Cache | Out-Null

Antes de construir el plan de subtítulos, pida al usuario que elija el modo de presentación a menos que la solicitud actual ya seleccione uno explícitamente. Renderice la pregunta en el idioma de conversación actual del usuario, manteniendo sin traducir los identificadores Standard y Expressive. Mantenga el texto fuente en inglés a continuación en este archivo, presente la opción localizada en la sesión actual y luego Presente + STOP:

Elija el modo de presentación de subtítulos:

1. Standard: Usa una colocación convencional estable y es adecuado para la mayoría del contenido.
2. Expressive: Cambia entre colocación inferior y central según el significado y enfatiza palabras clave y números.

Responda con Standard, Expressive o "Usar el predeterminado (Standard)."

No ejecute build_captions.py hasta que el usuario responda. Si el usuario delega explícitamente la elección en cualquier redacción, seleccione Standard. Indique que se seleccionó Standard como el predeterminado que preserva la compatibilidad antes de construir el plan.

Construya señales en tiempo de programa y el SRT de revisión:

python "$SkillRoot\scripts\build_captions.py" `
  "$Work\understand\transcript.json" `
  $Plan `
  "$Review\captions.srt" `
  --timeline "$Work\timeline.json" `
  --source-transcript "understand/transcript.json" `
  --max-chars 42 --max-lines 2 --max-dur 6 --gap 0.6

Después de que el usuario seleccione Standard, el comando anterior produce el plan Standard sin cambios. Después de que el usuario seleccione Expressive, ejecute el mismo comando con:

  --presentation-mode expressive

Después de la generación de señales de borrador, inspeccione la operación B-roll activa y su plan vinculado (solo lectura). Active la colocación consciente de la composición solo cuando la operación esté activa, su estado sea approved o verified, review.status sea approved, los enlaces de análisis/entrada de agente/vista previa/despeje de recuadro de orador estén completos, y al menos un plano verificado o normalizado tenga un diseño de composición mantenido. El constructor espacial usa display_mode: enabled de subplano explícito para la geometría del orador; pure_broll y la evidencia faltante de orador nunca implican un rectángulo de orador.

Cuando sea elegible, alinee las señales de borrador a cada límite visual B-roll antes de llenar cualquier layout_beats o hero_line de Expresivo. La alineación solo divide en espacios entre palabras y escribe atómicamente; un límite dentro de una palabra mantiene la palabra completa y registra evidencia de revisión obligatoria:

python "$SkillRoot\scripts\caption_spatial_context.py" align `
  --project-root $ProjectRoot --plan $Plan --out-plan $Plan

Para un proyecto elegible, prepare los argumentos opcionales utilizados por cada compuerta posterior:

$SpatialArgs = @("--spatial-context", $SpatialContext)
$SpatialReviewArgs = @("--spatial-context", $SpatialContext, "--project-root", $ProjectRoot)

Cuando no exista una composición elegible, omita los cuatro comandos espaciales y deje $SpatialArgs y $SpatialReviewArgs vacíos. No cree ni adjunte un contexto vacío.

Antes de comenzar la selección de estilo o generar una vista previa, el Agente debe planificar todo el programa Expresivo en una sola pasada:

1. Lea la transcripción, los artefactos de comprensión disponibles, la línea de tiempo canónica, las señales de subtítulos generadas y cualquier evidencia de fotograma fuente real necesaria para justificar los cambios de diseño.
2. Llene todos los presentation.layout_beats, anote los valores excepcionales de semantic_role de palabra, agregue como máximo una hero_line contigua con level: hero canónico a una señal cuando esté justificado, escriba una justificación por beat/línea heroica y escriba la presentation.planner.rationale general.
3. Establezca presentation.planning_status en complete solo después de que cada señal esté cubierta exactamente una vez.
4. Valide el plan completado antes de la generación de la vista previa:

python "$SkillRoot\scripts\build_captions.py" --validate-plan $Plan

Para una composición elegible, construya, valide y adjunte el contexto solo después de que los IDs de señal finales y los candidatos Expresivos estén completos. Esto preserva el diseño upstream y vincula su revisión actual y hashes en el plan de subtítulos:

python "$SkillRoot\scripts\caption_spatial_context.py" build `
  --project-root $ProjectRoot --plan $Plan --out $SpatialContext

python "$SkillRoot\scripts\caption_spatial_context.py" validate `
  --project-root $ProjectRoot --plan $Plan --context $SpatialContext

python "$SkillRoot\scripts\caption_spatial_context.py" attach `
  --project-root $ProjectRoot --plan $Plan --context $SpatialContext

No pida al usuario que elija una posición señal por señal. El usuario revisa la evidencia HTML existente y corrige solo un pequeño número de beats anómalos. Comenzar la interacción después de la planificación mantiene el enlace hash del plan de subtítulos existente como autoritario.

Inicie un modo de decisión. Para modo humano, publique la galería mantenida fuera de línea en el directorio de revisión del proyecto sin pedir al usuario que localice un archivo:

$StartOutput = node "$SkillRoot\scripts\caption_interaction.mjs" start `
  --state $Receipt --source $Sou

...

[truncado para traducción]