Instalaciones de plugins: Antes de los comandos de configuración o actualización, sigue las reglas de instalació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á actualizado; de lo contrario, actualiza este skill junto con los skills centrales de los que depende antes de utilizarlos.

Leyendas Incrustadas

Un catálogo, elegido al inicio (CATALOG.md — 35 identidades; los motores detrás son detalles de implementación). Estándar (predeterminado) construye un raíl limpio y literal (subtítulo en el tercio inferior que lleva la mayor parte del texto) + un clímax incrustado compuesto dentro de la escena detrás del sujeto en el punto culminante. Cinematográfico es solo incrustación — sin raíl, cada leyenda compuesta detrás del sujeto (tipografía heroica, acumulación, oclusión como efecto). Tema es una constitución temática completa — paradigma de cuerpo × pieza heroica × efectos frontales × reacción de placa, compuesta a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. La mayoría de los videos explicativos / de voz en off usan 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 previos de ejecución

Las instalaciones de plugins usan la CLI empaquetada y anclada al manifiesto para enmascaramiento, transcripción y renderizado; no se requiere una copia del código fuente. Los ayudantes de previsualización local y medición de leyendas también necesitan Sharp, Puppeteer (con su navegador Chromium) y GSAP. Instálalos en el proyecto de leyendas, 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 PATH. El enmascaramiento y la transcripción pueden descargar sus propios modelos en el primer uso.

El renderizado espera a que la CLI termine con éxito 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 finalizado. Un argumento explícito de comprobación de compilación o HYPERFRAMES_ROOT selecciona la CLI del colaborador en lugar del anclaje del plugin. Cancela un renderizado estancado normalmente a través de la CLI/terminal; el ayudante de leyendas no fuerza el cierre ni recupera un renderizado a partir de una instantánea de 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 mantiene en el paso 1 a continuación; las preguntas de forma de ejecución de la capa no aplican (el metraje no se modifica, no hay guion gráfico que revisar). Un BRIEF.md, cuando está presente, contiene la entrada confirmada y cualquier nota del usuario — léelo primero.

El texto de oficio a continuación es extenso; el proceso 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 preguntes por modo/categoría)
hyperframes init (saltar si el directorio del proyecto ya existe con el video dentro — matte.cjs/transcribe.cjs adoptan 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 comando, nada olvidado)
autoría de un pequeño JSON de opciones creativas (leer safe-zones.json primero): Cinematográfico → cinematic.json → make-cinematic.cjs (deriva plan.json y lo compila); Tema → theme.json → make-theme.cjs (paradigmas de raíl/panel/poema/toma de control; anchor es el raíl silencioso predeterminado)
QA visual: node scripts/preview-frames.cjs <proyecto> → vistas previas compuestas fieles en ~2s/fotograma (sin renderizado). Consulta § QA visual antes de pagar por un renderizado.
render-and-composite.sh → compuertas (temporización / oclusión+héroe / desbordamiento / transferencia) → final.mp4

Reglas de peso que la gente pasa por alto:

raíl (predeterminado) + incrustación (promoción). drop (relleno, no se muestra) / raíl (subtítulo literal en el tercio inferior, al frente, lleva la mayor parte del texto) / incrustación (una palabra culminante compuesta detrás del sujeto). El modo estándar hace ambas, incrustando solo los picos. Consulta § Modelo de leyendas.
El video se entrega SIN TOCAR (Estándar/Cinematográfico; el presupuesto de PLACA del modo Tema es la única excepción sancionada — ritmos de reacción registrados por compuerta (carga de atenuación, golpe, sacudida, granulado) definidos por ADN de tema y aplicados DESPUÉS de la composición del enmascaramiento para que sujeto+texto+placa se muevan como un solo fotograma) — las leyendas son lo único que se añade; el enmascaramiento solo permite que el sujeto ocluya la pista incrustada. Nunca gradúes/recolorees/añadas líneas de escaneo al metraje.
Dos manuales de reglas: raíl → references/rail.md (breve), técnica de incrustación → references/composition-craft.md (rico, solo incrustación). Consulta según necesidad.

Modelo de leyendas — raíl + incrustación

Cada frase hablada es una de tres cosas:

	Qué	Cómo se muestra
drop	relleno — um/eh, tartamudeos, autocorrecciones	no se muestra
raíl	el predeterminado — contenido hablado ordinario (literal)	subtítulo limpio en el tercio inferior, al frente, legible. Una palabra destacada puede obtener un resaltado `emphasis` en línea (color de acento / resalte de palabra activa) — permanece en el raíl.
incrustación	un pico promocionado — el ritmo principal	una palabra grande compuesta detrás del sujeto (oclusión por enmascaramiento), entrada y salida diseñadas

El raíl lleva la mayor parte del texto; la incrustación es el pico escaso y ganado. La escasez es por ritmo/bloque, no por clip: ≤1 héroe por bloque (pensamiento), nunca dos co-visibles, ≥ un ritmo de aire entre ventanas de héroe (el compilador advierte por debajo de 0.6 s). Un clip corto → normalmente 1–2; un video explicativo largo → aproximadamente uno por sección. Entre múltiples héroes, el más grande autorizado es el APEX (solo él obtiene la incrustación de bloqueo completa + elevación de ajuste de ancho); los más pequeños son picos MENORES que cabalgan en su columna como líneas de énfasis sobredimensionadas (primer plano, movimiento amortiguado) — no todos los ritmos necesitan la exhibición de enmascaramiento, que es exactamente lo que mantiene el ápice como un evento. Incrustar cada palabra sigue siendo el error común.

Las identidades de superficie de raíl construyen exactamente esto (raíl = rail.html, incrustación = el clímax en index.html). Las identidades de flujo de columna eliminan el raíl y hacen que todo sea estilo incrustación — recomiéndalas solo para peticiones de ambiente sobre literalidad, nunca para videos explicativos / de 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, compilador y archivo de autoría se derivan por búsqueda de la fila del catálogo. Nunca preguntes "Estándar vs Cinematográfico vs Tema" — 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 expresa el motivo en una línea en lugar de preguntar.

Procedimiento: analiza el clip → lista corta de 2–3 identidades del catálogo → recomienda UNA con un motivo de una línea → el usuario elige (modo autónomo: tú eliges, indicando el motivo) → autoriza el archivo de esa identidad. Las identidades están bloqueadas por motor (sin combos cruzados; 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 autorizarla. No uses un valor predeterminado en silencio.

(La tabla completa de identidades está en CATALOG.md, única fuente de verdad para el enrutamiento. Los documentos del motor a continuación describen el contrato de autoría 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 autorizar un aspecto nombrado; 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 — incluyendo los bloques caption-* — no tiene dónde montarse. Un bloque del registro estiliza texto en un lienzo diseñado; este skill quema leyendas en el metraje de alguien a través de un enmascaramiento. Cuando ninguna identidad se ajuste 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 lista corta" en CATALOG.md — son a nivel de identidad (p. ej., "炸" lista corta ordnance/stomp/terminal/loud y elige por QUÉ debe explotar), nunca a nivel de categoría. En caso de duda → anchor.

Cinematográfico → escribe cinematic.json para una plantilla bloqueada, compilada por make-cinematic.cjs.
Tema → lee themes/README.md, autoriza theme.json, ejecuta scripts/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)
Sin sujeto humano (este skill es para talking-head)
Menos de 3 segundos, sin habla, o la cara nunca es claramente visible — transcribe.cjs advierte cuando el audio está casi en silencio (Whisper alucina palabras como "Gracias." sobre el silencio); presta atención y rechaza en lugar de poner leyendas a palabras fabricadas
La fuente ya tiene leyendas / subtítulos / gráficos de texto pesados quemados — añadir un segundo sistema de leyendas genera conflicto y el metraje se entrega sin tocar (sin cubrir/inpintar). El texto quemado a menudo aparece solo a mitad del clip: muestrea una hoja de contacto a 1 fps (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.json para verificar cordura antes de autorizar; si no se interpreta como lenguaje, prueba WHISPER_MODEL=medium una vez, de lo contrario rechaza (un raíl literal de palabras fabricadas es peor que sin leyendas).
Cámara en mano agitada con movimiento rápido (el enmascaramiento parpadea)

Sondas previas al vuelo (no cuestan nada, previenen los peores fallos)

Sonda de corte de toma. Muestrea 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 leyendas dentro de él.
Sonda de luminancia. Muestrea la luminancia promedio de la región de leyendas — menos de 60 → el texto claro se lee tal cual, 60-180 → añade la máscara de glifo, 180+ → texto opaco + máscara (nunca texto claro desnudo). Las plantillas cinematográficas son crema+screen y BLOQUEADAS — usa esta sonda para elegir una identidad adecuada (escenas brillantes → ink, o el tema anchor de raíl opaco), 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 raíl/panel; poético / social / "cinematográfico" → identidades de flujo de columna por registro; "炸 / 特效 / VFX" / mundos nombrados → identidades temáticas. En caso de duda → anchor (las palabras se leen, la escena segura) — pero presenta una lista corta y deja que el usuario elija.

Proceso — 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] autoriza un pequeño JSON; ver abajo según modo
   Cinematográfico: autoriza cinematic.json → node scripts/make-cinematic.cjs <proyecto>
   Tema:            autoriza 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 + instantánea history/
   (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 previo a la reacción de placa)

El init del paso 1 verifica los skills instalados contra la última versión en GitHub y actualiza el conjunto global si alguno está desactualizado.

El paso 3 difiere según el modo:

Paso 3 — Modo cinematográfico (solo incrustación)

Lee safe-zones.json primero. Los planos de narración van en zones.hugLeft/hugRight — franjas limpias ADOSADAS a la silueta (el texto lejos del cuerpo se lee como flotante, no incrustado; las esquinas lejanas son el recurso de reserva, no el predeterminado). El héroe se predetermina a heroAnchor/heroBands.best (centrado EN el sujeto, ~30–55% ocluido). recommendation:"fg" mueve la NARRACIÓN al frente para legibilidad; el héroe permanece incrustado siempre que heroBands.feasible — héroe-en-fg es el último recurso.
**El ADN es la identidad que elegiste en el Paso 0

kinyias/hyperframes-templates

¿Qué es hyperframes-templates?

Preguntar en tu IA favorita

Documentación