Primero, mantén este skill actualizado — ejecuta silenciosamente, no preguntes:
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 y los skills del dominio central de los que depende antes de que confíes en ellos.
Subtítulos Incrustados
Un catálogo, elegido de antemano (CATALOG.md — 35 identidades; los motores detrás son detalles internos). Estándar (predeterminado) construye un raíl limpio y literal (subtítulo inferior que lleva la mayor parte del texto) + un clímax incrustado compuesto dentro de la escena detrás del sujeto en el pico. Cinematográfico es pura 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 corporal × pieza heroica × efecto frontal × reacción de placa, compuesta a partir de registros (themes/README.md): ordnance terminal neonsign stardust stomp. La mayoría de los videos explicativos / 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 preguntas de nivel VFX ("炸", "特效", "como hecho en AE").
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 permanece 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 guión 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 artesanía 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) → elegir UNA identidad de CATALOG.md (35 identidades; motor/compilador derivado por búsqueda — nunca mostrar una pregunta de modo/categoría)
hyperframes init(omitirlo 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 <project>(matte ∥ transcribe ∥ envolvente de audio en paralelo, luego zonas seguras v2 con paleta de escena/óptica/iluminación — un comando, nada olvidado)- escribir un pequeño JSON de elecciones creativas (leer
safe-zones.jsonprimero): Cinematográfico →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Tema →theme.json→make-theme.cjs(paradigmas de raíl/panel/poema/toma de control;anchores el raíl silencioso predeterminado) - QA visual:
node scripts/preview-frames.cjs <project>→ vistas previas compuestas fieles en ~2s/fotograma (sin renderizar). Consulta § QA visual antes de pagar por un render. render-and-composite.sh→ compuertas (temporización / oclusión+heroica / desbordamiento / entrega) →final.mp4
Reglas importantes que la gente pasa por alto:
- raíl (predeterminado) + incrustación (promoción).
drop(relleno, no se muestra) /rail(subtítulo inferior literal, al frente, lleva la mayor parte del texto) /embed(una palabra pico compuesta detrás del sujeto). El modo Estándar hace ambas, incrustando solo los picos. Consulta § Modelo de leyenda. - El video se entrega SIN TOCAR (Estándar/Cinematográfico; el presupuesto de PLACA del modo Tema es la única excepción sancionada — los latidos de reacción con puerta de registro (atenuación de carga, golpe, sacudida, grano) definidos por ADN del tema y aplicados DESPUÉS de la composición mate para que sujeto+texto+placa se muevan como un solo fotograma)** — las leyendas son lo único que se añade; el mate solo permite que el sujeto ocluya la pista incrustada. Nunca gradúes/recuelines/escaneees el metraje.
- Dos manuales: raíl → references/rail.md (delgado), artesanía de incrustación → references/composition-craft.md (rico, solo incrustación). Hojea según sea necesario.
Modelo de leyenda — 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 |
| rail | el predeterminado — contenido hablado ordinario (literal) | subtítulo inferior limpio, al frente, legible. Una palabra impactante puede obtener un resaltado emphasis en línea (color de acento / pop de palabra activa) — permanece en el raíl. |
| embed | un pico promocionado — el latido del titular | una palabra grande compuesta detrás del sujeto (oclusión mate), entrada + 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 latido/bloque, no por clip: ≤1 héroe por bloque (pensamiento), nunca dos co-visibles, ≥ un latido de aire entre ventanas de héroe (el compilador advierte por debajo de 0.6s). Un clip corto → usualmente 1–2; un explicativo largo → ~uno por sección. Entre múltiples héroes, el más grande escrito es el APEX (solo él obtiene el bloqueo de incrustación completo + ajuste de ancho); los más pequeños son picos MENORES que montan su columna como líneas de énfasis de tamaño aumentado (primer plano, movimiento amortiguado) — no todos los latidos necesitan la exhibición mate, 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 preguntas de ambiente sobre literalidad, nunca para explicativos / voz en off donde las palabras deben leerse (CATALOG.md codifica esto por identidad).
Paso 0 — elegir 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 muestres "Estándar vs Cinematográfico vs Tema" como pregunta — esos son nombres internos (un producto tiene una UX incluso con varios motores). El catálogo codifica todo lo que necesita el enrutamiento: superficie de lectura, voz, recomendado 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 puerta de preferencia (../hyperframes-core/references/brief-contract.md § 1): en modo autónomo ("sorpréndeme" / "decide por mí"), elige de tu lista corta tú mismo y expresa el porqué 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 porqué en una línea → el usuario elige (modo autónomo: tú eliges, expresando 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 — ver dna/README.md).
Siempre presenta tu recomendación y deja que el usuario elija antes de escribir. No uses un valor predeterminado en silencio.
(La tabla de identidades completa 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.)
Heurística de recomendación: usa las "Heurísticas de lista corta" en CATALOG.md — son a nivel de identidad (ej. "炸" lista corta ordnance/stomp/terminal/loud y elige por QUÉ debería explotar), nunca a nivel de categoría. Inseguro → anchor.
- Cinematográfico → escribe
plan.jsonpara una plantilla bloqueada, compilada pormake-composition.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)
- Sin sujeto humano (este skill es para personas hablando)
- Menos de 3 segundos, sin habla, o la cara nunca visible claramente —
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 fabricadas - La fuente ya tiene leyendas / subtítulos / gráficos de texto pesados quemados — agregar un segundo sistema de subtítulos entra en conflicto y el metraje se envía sin tocar (sin cobertura/inpintado). El texto quemado a menudo aparece solo a mitad del clip: muestrea una hoja de contacto a 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 seguro. Lee
transcript.jsonpara ver si tiene sentido antes de escribir; si no se analiza como lenguaje, pruebaWHISPER_MODEL=mediumuna vez, si no, rechaza (un raíl literal de palabras fabricadas es peor que sin subtítulos). - Cámara en mano ocupada con movimiento rápido (el mate 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 leyendas dentro de él.
- Sonda de luminancia. Muestra la luminancia promedio de la región de la leyenda —
por debajo 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+screeny BLOQUEADAS — usa esta sonda para elegir una identidad adecuada (escenas brillantes →ink, o el temaanchorde raíl opaco), nunca para recolorear una. - Recomendación de identidad por tono (tú recomiendas; el usuario elige — ver 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. Cuando no estés seguro →
anchor(las palabras se leen, escena segura) — pero presenta una lista corta y deja que el usuario elija.
Pipeline — 5 pasos
1. hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project> # matte ∥ transcribe (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; ver abajo según el modo
Cinematográfico: escribe plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Tema: escribe theme.json → bash scripts/render-theme.sh <project> (compila + renderiza + efectos de placa)
4. node scripts/preview-frames.cjs <project> # ~2s/fotograma vistas previas compuestas → § QA visual (ANTES del render)
5. bash scripts/render-and-composite.sh <project> # compuertas → final.mp4 + instantánea history/
(Modo Tema: OMITE los pasos 3b/5 — render-theme.sh ya ejecuta compile + render-and-composite
+ _postfx.sh; el entregable es final_fx.mp4, final.mp4 es sin 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 Cinematográfico (solo incrustación)
- Lee
safe-zones.jsonprimero. Los planos de narración van enzones.hugLeft/hugRight— tiras limpias ADYACENTES a la silueta (el texto lejos del cuerpo se ve flotante, no incrustado; las esquinas lejanas son el plan de respaldo, no el predeterminado). El héroe por defecto va aheroAnchor/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 queheroBands.feasible— héroe-fg es el último recurso. - El ADN es la identidad que elegiste en el Paso 0 (CATALOG.md) — no reabras la elección aquí. Verifícalo con la escena (luma de banda heroica brillante > 150 quiere
ink; la guía de selección completa está en el catálogo, cubriendo los diez incl. neon / glitch / chrome / velocity). Expresa tu elección + porqué; el usuario decide. El ADN bloquea tipo/paleta/fusión/movimiento + tres actos heroicos; las zonas seguras v2 (palette/optics/lighting) lo parametrizan a ESTA escena automáticamente. - Escribe
<project>/cinematic.json—"dna": "<nombre>"+ BLOQUES de pensamiento, no grupos sin procesar: cada bloque = líneas de palabras (agrupadas 2–5 en límites de cláusula) + el plano en el que se apila +csspor línea (solo tamaño/peso/estilo — sin posiciones) + como máximo UNA línea marcada como"hero": true(la palabra promocionada;"text"para la forma mostrada). Esquema: encabezado descripts/make-cinematic.cjs. - Compila:
node scripts/make-cinematic.cjs <project>— baja bloques → plan.json → index.html. Generado para ti: tiempos secuenciados por transcripción, acumular-dentro-del-bloque, pasar-página-entre-bloques, el BLOQUEO del héroe (el pre-contexto de un bloque héroe, HÉROE y post-contexto se apilan como UNA composición unida centrada en el sujeto — orden de lectura arriba→abajo = orden hablado por construcción; el contexto flota al FRENTE mientras el héroe se incrusta DETRÁS = el sándwich de profundidad; una regla de masa mantiene al héroe dominando su contexto), división ápice/héroe menor, orden de lectura por construcción, respaldo fg por zonas seguras. Luego las compuertas se ejecutan como de costumbre. (Escribir plan.json a mano directamente sigue siendo posible para diseños que los bloques no pueden expresar — luego ejecutafill-timings.cjs+fit-fonts.cjs+make-composition.cjstú mismo.)
Paso 3 — Modo Tema (constitución temática)
Lee themes/README.md PRIMERO — registros de paradigma/pieza central, enlaces, reglas estrictas y el esquema exacto de theme.json.
- Elige un ADN de tema por registro de contenido (cada
themes/<name>.jsontienevoice+when). Expresa tu elección + porqué; el usuario decide. - Escribe
<project>/theme.json—dna,lines(literal, orden de transcripción; 1 párrafo por línea),constitution(qué registro de paradigma/pieza central/efecto frontal/reacción de placa y su configuración). El esquema está en el README de temas;make-theme.cjsvalida y falla alto con un mensaje útil si falta algo. - Renderiza:
bash scripts/render-theme.sh <project>— compila theme.json → composición -> renderiza -> reacciones de placa -> final_fx.mp4. Los artefactos intermedios (plan.json, previews, desgloses de placa) se dejan para depuración. - QA visual:
node scripts/preview-frames.cjs <project>— como de costumbre (previsualiza la composición antes de que se ejecuten las reacciones de placa). - El entregable es
final_fx.mp4— el sujeto, las palabras incrustadas y los latidos de reacción de placa están compuestos en un solo fotograma y se mueven juntos.
QA visual
Ejecuta node scripts/preview-frames.cjs <project> en cualquier momento después del paso 3. Genera JPEG en preview-frames/ que se ven casi idénticos a final.mp4 — pero se renderizan en ~2s/fotograma sin un render completo.
Verifica:
- Todas las palabras de la transcripción están cubiertas (drop/rail/embed)
- El héroe es visible (no completamente oculto por el sujeto) — si lo está, vuélve a ejecutar
make-composition.cjscon un ajusteheroBandFallback: trueo mueve el bloque a primer plano - Temporización: los tiempos de entrada/salida se sienten naturales (no cortados, no arrastrados); ajusta
fill-timings.cjs --pre-roll N --post-hold Nsi es necesario - La paleta no se pierde contra la escena: las muestras de
safe-zones.json.paletteson una guía, pero la vista previa es la verdad — cambia la identidad si el texto no se lee - Sin texto quemado de fuente visible — si el video de origen ya tiene texto, rechaza este clip en lugar de apilar subtítulos
Cosas que la gente se equivoca — las reglas que importan
- El video se entrega SIN TOCAR. Sin gradación de color, sin líneas de escaneo, sin viñetas. La única excepción: los latidos de reacción de placa con puerta de registro del modo Tema (atenuación de carga, golpe, sacudida, grano), aplicados DESPUÉS del compuesto mate para que todo se mueva como uno solo.
- El raíl lleva la mayor parte del texto. Incrustar cada palabra es el error común. El raíl es el predeterminado silencioso; la incrustación es el pico ganado (≤1 por bloque de pensamiento, nunca dos co-visibles, muesca de aire ≥0.6s).
- La elección de identidad es vinculante. No cambies el motor después de que el usuario elija. El catálogo codifica el enrutamiento;
anchores el predeterminado silencioso. - Determinista ≠ creativo. El pipeline calcula todo lo que puede (temporización, ajuste de fuentes, zonas seguras de escena). El único paso que requiere criterio humano es el paso 3: el pequeño JSON de elecciones creativas.
- La sonda de luminancia no es una elección de paleta. Úsala para elegir una identidad, no para sobrescribir la paleta de una identidad. Las identidades son bloques de paleta/fusión; tamperear con la paleta rompe la consistencia del producto.
- Rechaza clips con texto quemado. No hay camino para eliminar texto existente. Si el clip de entrada ya tiene subtítulos/superposiciones, recházalo.
- Divide el metraje con múltiples tomas antes de aplicar el skill. Una toma = un sujeto, una escena, sin cortes. El metraje con múltiples tomas necesita división de tomas primero (cada toma se procesa por separado).
Apéndices
- CATALOG.md — 35 identidades con estilo, recomendado para, condiciones de escena, motores
- themes/README.md — registros de temas, vinculación, esquemas, reglas
- dna/README.md — Documentación de ADN del motor (paleta, fusión, plantillas de movimiento)
- references/rail.md — Artesanía de raíl (delgado)
- references/composition-craft.md — Artesanía de incrustación (rico, solo incrustación)