Instalación de plugins: Antes de los comandos de configuración o actualización, sigue las reglas de ejecución de plugins cuando este skill esté dentro de un plugin de HyperFrames. Las instalaciones independientes mantienen las instrucciones de actualización a continuación.
Primero, mantén este skill actualizado — confirma con el usuario antes de ejecutar:
npx hyperframes skills update embedded-captions. Una operación rápida sin cambios cuando todo está al día; de lo contrario, actualiza este skill junto con los skills centrales de los que depende antes de usarlos.
Subtítulos Incrustados (Embedded Captions)
Un solo catálogo, elegido al inicio (CATALOG.md — 35 identidades; los motores detrás son detalles de implementación). Estándar (por defecto) construye una barra limpia y literal (subtítulo en el tercio inferior que lleva la mayor parte del texto) + un punto culminante compuesto dentro de la escena detrás del sujeto en el momento clave. Cinemático es solo incrustación — sin barra, cada palabra se compone detrás del sujeto (tipografía heroica, acumulación, oclusión como efecto). Tema es una constitución temática completa — paradigma del cuerpo × pieza central heroica × efectos frontales × reacción de la placa, compuesta a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. La mayoría de los videos explicativos o de voz en off son Estándar; la incrustación es el pico escaso y ganado — incrustar cada palabra es el error común; Tema es para peticiones de nivel de efectos visuales ("炸", "特效", "como hecho en AE").
Requisitos de ejecución
Las instalaciones de plugin usan la CLI empaquetada y fijada por manifiesto para el enmascaramiento, la transcripción y el renderizado; no se requiere una copia del código fuente. La vista previa local y las herramientas de medición de subtítulos también necesitan Sharp, Puppeteer (con su navegador Chromium) y GSAP. Instálalos en el proyecto de subtítulos, no dentro del plugin de solo lectura:
npm install --prefix <proyecto> --save-dev --save-exact [email protected] [email protected] [email protected]
Mantén el archivo de bloqueo del proyecto. Si estas dependencias ya existen, usa sus versiones bloqueadas en lugar de sobrescribirlas. Bash y FFmpeg/ffprobe deben estar en el PATH. El enmascaramiento y la transcripción pueden descargar sus propios modelos en el primer uso.
El renderizado espera a que la CLI termine correctamente antes de componer. El antiguo watchdog de shell HF_TIMEOUT_S ya no se usa: un archivo parcial grande no es prueba de que el renderizado haya terminado. Un argumento explícito de compilación verificada o HYPERFRAMES_ROOT selecciona la CLI del colaborador en lugar del pin del plugin. Cancela un renderizado atascado normalmente a través de la CLI/terminal; la herramienta de subtítulos no fuerza la finalización ni recupera un renderizado de una instantánea del proceso.
Flujo operativo (resumen)
Enrutado a través de /hyperframes, la capa de intención confirma solo la entrada (qué clip) y anuncia la elección de identidad como una pregunta diferida — la lista corta necesita el clip analizado, por lo que se queda en el paso 1 a continuación; las preguntas de forma de ejecución de la capa no aplican (el metraje no se toca, no hay guion gráfico que revisar). Cuando hay un BRIEF.md, contiene la entrada confirmada y cualquier nota del usuario — léelo primero.
El texto de procedimiento a continuación es largo; el pipeline en sí es corto — y todo lo determinista se calcula o compila, nunca se escribe a mano:
- Puerta de decisión (rechazar clips malos) → elige UNA identidad de CATALOG.md (35 identidades; motor/compilador derivado por búsqueda — nunca plantees una pregunta de modo/categoría)
hyperframes init(omítelo si el directorio del proyecto ya existe con el video dentro —matte.cjs/transcribe.cjsadoptan cualquier video en el directorio como source.mp4) →bash scripts/prepare.sh <proyecto>(enmascaramiento ∥ transcripción ∥ envolvente de audio en paralelo, luego zonas seguras v2 con paleta de escena/óptica/iluminación — un solo comando, nada olvidado)- escribe un pequeño JSON de opciones creativas (lee
safe-zones.jsonprimero): Cinemático →cinematic.json→make-cinematic.cjs(derivaplan.jsony lo compila); Tema →theme.json→make-theme.cjs(paradigmas de barra/panel/poema/toma de control;anchores la barra silenciosa por defecto) - QA Visual:
node scripts/preview-frames.cjs <proyecto>→ vistas previas de composición fieles en ~2s/fotograma (sin renderizar). Consulta § QA Visual antes de pagar por un renderizado. render-and-composite.sh→ compuertas (timing / oclusión+heroico / desbordamiento / traspaso) →final.mp4
Reglas importantes que la gente pasa por alto:
- barra (por defecto) + incrustación (promoción).
drop(relleno, no se muestra) /barra(subtítulo literal en el tercio inferior, al frente, lleva la mayor parte del texto) /incrustación(una palabra clave compuesta detrás del sujeto). El modo Estándar hace ambas, incrustando solo los picos. Consulta § Modelo de subtítulos. - El video se entrega SIN TOCAR (Estándar/Cinemático; el presupuesto de PLACA del modo Tema es la única excepción sancionada — los beats de reacción definidos por registro y por ADN del tema se aplican DESPUÉS de la composición del enmascaramiento para que el sujeto+texto+placa se muevan como un solo fotograma) — los subtítulos son lo único que se añade; el enmascaramiento solo permite que el sujeto oculte la pista incrustada. Nunca gradúes/recueles/añadas líneas de escaneo al metraje.
- Dos libros de reglas: barra → references/rail.md (delgado), arte de la incrustación → references/composition-craft.md (rico, solo incrustación). Hojea según necesidad.
Modelo de subtítulos — barra + incrustación
Cada frase hablada es una de tres cosas:
| Qué | Cómo se muestra | |
|---|---|---|
| drop | relleno — um/eh, tartamudeos, autocorrecciones | no se muestra |
| barra | el valor por defecto — contenido hablado ordinario (literal) | subtítulo limpio en el tercio inferior, al frente, legible. Una palabra impactante puede obtener un resaltado emphasis en línea (color de acento / pop de palabra activa) — permanece en la barra. |
| incrustación | un pico promocionado — el latido del titular | una palabra grande compuesta detrás del sujeto (oclusión del enmascaramiento), entrada y salida diseñadas |
La barra lleva la mayor parte del texto; la incrustación es el pico escaso y ganado. La escasez es por latido/bloque, no por clip: ≤1 heroico por bloque (pensamiento), nunca dos co-visibles, ≥ un latido de aire entre ventanas heroicas (el compilador advierte por debajo de 0.6s). Un clip corto → normalmente 1–2; un explicativo largo → ~uno por sección. Entre múltiples heroicos, el más grande escrito es el APEX (solo él obtiene la incrustación completa de bloqueo + elevación de ajuste de ancho); los más pequeños son picos MENORES que cabalgan su columna como líneas de énfasis sobredimensionadas (primer plano, movimiento amortiguado) — no cada latido necesita la exhibición del enmascaramiento, que es precisamente lo que mantiene el ápice como un evento. Incrustar cada palabra sigue siendo el error común.
Las identidades de superficie de barra construyen exactamente esto (barra = rail.html, incrustación = el clímax en index.html). Las identidades de flujo de columna eliminan la barra y hacen todo al estilo de incrustación — recomiéndalas solo para peticiones de ambiente sobre lo literal, nunca para explicativos/voz en off donde las palabras deben leerse (CATALOG.md lo codifica por identidad).
Paso 0 — elige UNA identidad del CATÁLOGO
Un front-end, tres motores detrás. El usuario elige una IDENTIDAD de CATALOG.md (35 entradas: 10 clásicas + 25 temáticas); el motor, el compilador y el archivo de escritura se derivan por búsqueda de la fila del catálogo. Nunca plantees "Estándar vs Cinemático vs Tema" como una pregunta — esos son nombres de backend (un producto tiene una UX incluso con varios motores). El catálogo codifica todo lo que necesita el enrutamiento: superficie de lectura, voz, recomendar-para, necesidades de escena, notas de adyacencia para los pares realmente cercanos (loud↔ordnance, neon↔neonsign, cream↔stardust).
La elección de identidad es una compuerta de preferencia (../hyperframes/references/brief-contract.md § 1): en modo autónomo ("sorpréndeme" / "decide por mí"), elige de tu lista corta tú mismo y declara el porqué en una línea en lugar de preguntar.
Procedimiento: analiza el clip → haz una lista corta de 2–3 identidades del catálogo → recomienda UNA con un porqué de una línea → el usuario elige (modo autónomo: tú eliges, declarando el porqué) → escribe el archivo de esa identidad. Las identidades están bloqueadas por motor (sin combinaciones cruzadas; abrir una es un evento de validación — consulta dna/README.md).
Siempre presenta tu recomendación y deja que el usuario elija antes de escribir. No tomes un valor predeterminado en silencio.
(La tabla completa de identidades está en CATALOG.md — fuente única de verdad para el enrutamiento. Los documentos del motor a continuación describen el contrato de escritura de cada backend.)
CATALOG.md es todo el espacio de respuestas aquí: este flujo de trabajo no busca en el registro de componentes de HyperFrames. Los flujos de trabajo de composición ejecutan npx hyperframes catalog antes de escribir un aspecto con nombre; este no debe hacerlo. Sus motores son compiladores bloqueados que consumen cinematic.json / theme.json y emiten la composición ellos mismos, por lo que un elemento del registro — incluidos los bloques caption-* — no tiene dónde montarse. Un bloque de registro estiliza texto en un lienzo diseñado; este skill quema subtítulos en el metraje de alguien a través de un enmascaramiento. Cuando ninguna identidad se ajusta a la petición, dilo y elige la más cercana, en lugar de buscar fuera del catálogo.
Heurística de recomendación: usa las "Heurísticas de preselección" en CATALOG.md — son a nivel de identidad (ej. "炸" preselecciona ordnance/stomp/terminal/loud y elige por QUÉ debería explotar), nunca a nivel de categoría. Inseguro → anchor.
- Cinemático → escribe
cinematic.jsonpara una plantilla bloqueada, compilada pormake-cinematic.cjs. - Tema → lee themes/README.md, escribe
theme.json, ejecutascripts/render-theme.sh(compila + renderiza + reacción de placa → final_fx.mp4).
Puerta de decisión — EJECUTAR PRIMERO
Analiza el video y clasifica la escena antes de cualquier modo.
ffprobe <video.mp4> # especificaciones
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png # al 20/50/80%
Lee las muestras. Rechaza si:
- Múltiples hablantes / cortes bruscos (divide y renderiza cada toma, o rechaza)
- No hay sujeto humano (este skill es para persona hablando)
- Menos de 3 segundos, sin habla, o la cara nunca es claramente visible —
transcribe.cjsadvierte cuando el audio está casi en silencio (Whisper alucina palabras como "Gracias." sobre el silencio); hazle caso y rechaza en lugar de subtitular palabras inventadas - La fuente ya tiene subtítulos quemados / leyendas / gráficos de texto pesados — añadir un segundo sistema de subtítulos entra en conflicto y el metraje se entrega sin tocar (sin cubrir/reparar). El texto quemado a menudo aparece solo a mitad del clip: muestra una hoja de contactos de 1fps (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), no confíes en 3 fotogramas puntuales. - La transcripción es basura — el habla no nativa/con acento fuerte puede transcribirse como galimatías con confianza. Lee
transcript.jsonantes de escribir; si no se interpreta como lenguaje, pruebaWHISPER_MODEL=mediumuna vez, de lo contrario rechaza (una barra literal de palabras inventadas es peor que sin subtítulos). - Cámara en mano ocupada con movimiento rápido (el enmascaramiento parpadea)
Sondas previas al vuelo (no cuestan nada, evitan los peores fallos)
- Sonda de corte de toma. Muestra fotogramas al 20%, 50%, 80%. Si aparece un sujeto/escena diferente, recorta el clip antes del corte.
- Sonda de letterbox / pillarbox. ¿Barras negras en el primer fotograma? Calcula el rectángulo de contenido seguro y restringe la colocación de subtítulos dentro de él.
- Sonda de luminancia. Muestra la luminancia promedio de la región de subtítulos —
menos de 60→ el texto claro se lee tal cual,60-180→ añade la máscara de glifos,180+→ texto opaco + máscara (nunca texto claro desnudo). Las plantillas Cinemáticas son crema+screeny BLOQUEADAS — usa esta sonda para elegir una identidad adecuada (escenas brillantes →ink, o el tema de barra opacaanchor), nunca para recolorear una. - Recomendación de identidad por tono (tú recomiendas; el usuario elige — consulta Paso 0 + CATALOG.md). explicativo / entrevista / palabras que deben leerse → identidades de superficie de barra/panel; poético / social / "cinemático" → identidades de flujo de columna por registro; "炸 / 特效 / VFX" / mundos con nombre → identidades temáticas. Cuando inseguro →
anchor(las palabras se leen, escena segura) — pero presenta una lista corta y deja que el usuario elija.
Pipeline — 5 pasos
1. hyperframes init <proyecto> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <proyecto> # enmascaramiento ∥ transcripción (paralelo) → zonas seguras. Un comando.
# → frames_fg/ transcript.json safe-zones.json
3. [PASO DEL AGENTE — el único paso creativo] escribe un pequeño JSON; consulta a continuación según el modo
Cinemático: escribe cinematic.json → node scripts/make-cinematic.cjs <proyecto>
Tema: escribe theme.json → bash scripts/render-theme.sh <proyecto> (compila + renderiza + efectos de placa)
4. node scripts/preview-frames.cjs <proyecto> # ~2s/fotograma vistas previas compuestas → § QA Visual (ANTES del renderizado)
5. bash scripts/render-and-composite.sh <proyecto> # compuertas → final.mp4 + history/ instantánea
(Modo Tema: OMITE los pasos 3b/5 — render-theme.sh ya ejecuta compilación + render-and-composite
+ _postfx.sh; el entregable es final_fx.mp4, final.mp4 es antes de la reacción de placa)
El paso 1 init verifica los skills instalados contra los últimos en GitHub y actualiza el conjunto global si alguno está desactualizado.
El paso 3 difiere según el modo:
Paso 3 — Modo Cinemático (solo incrustación)
- Lee
safe-zones.jsonprimero. Los planos de narración van enzones.hugLeft/hugRight— tiras limpias PEGADAS a la silueta (el texto lejos del cuerpo se lee como flotante, no incrustado; las esquinas lejanas son el plan de respaldo, no el predeterminado). El heroico por defecto esheroAnchor/heroBands.best(centrado EN el sujeto, ~30–55% ocluido).recommendation:"fg"mueve la NARRACIÓN al frente para la legibilidad; el heroico permanece incrustado siempre queheroBands.feasible— heroico-fg es el último recurso. - El ADN es la identidad que elegiste en el Paso 0