Instalación de plugins: Antes de los comandos de configuración o actualización, sigue las reglas de ejecución de plugins cuando esta habilidad esté dentro de un plugin de HyperFrames. Las instalaciones independientes mantienen las instrucciones de actualización a continuación.
Primero, mantén esta habilidad actualizada — 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 esta habilidad junto con las habilidades del dominio central de las que depende antes de confiar en ellas.
Subtítulos Incrustados
Un catálogo, elegido de antemano (CATALOG.md — 35 identidades; los motores detrás son detalles de backend). Estándar (predeterminado) construye una vía (rail) limpia y literal (subtítulo inferior que lleva la mayor parte del texto) + un clímax incrustado (embed) compuesto dentro de la escena detrás del sujeto en el punto álgido. Cinematográfico es solo incrustación — sin vía, cada subtítulo compuesto detrás del sujeto (tipografía heroica, acumulación, oclusión como efecto). Temático es una constitución temática completa — paradigma corporal × pieza central 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 / de voz en off usan Estándar; la incrustación es el pico escaso y ganado — incrustar cada palabra es el error común; Temático es para solicitudes de nivel VFX ("炸", "特效", "como hecho en AE").
Prerrequisitos de ejecución
Las instalaciones de plugins usan la CLI empaquetada y con versiones fijas para máscara, transcripción y renderizado; no se requiere una copia local del repositorio. 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 <project> --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. La máscara 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 terminación ni recupera un renderizado a partir 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 sondeado, 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 está editado, 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 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 plantear una pregunta de modo/categoría)
hyperframes init(omitir 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>(máscara ∥ transcripción ∥ envolvente de audio en paralelo, luego zonas seguras v2 con paleta de escena/óptica/iluminación — un solo comando, nada olvidado)- redactar un pequeño JSON de elecciones creativas (leer
safe-zones.jsonprimero): Cinematográfico →cinematic.json→make-cinematic.cjs(derivaplan.jsony lo compila); Temático →theme.json→make-theme.cjs(paradigmas de vía/panel/poema/toma de control;anchores la vía tranquila predeterminada) - QA Visual:
node scripts/preview-frames.cjs <project>→ vistas previas de composición fieles en ~2s/fotograma (sin renderizado). Consulta § QA Visual antes de pagar por un renderizado. render-and-composite.sh→ compuertas (tiempo / oclusión+heroico / desbordamiento / traspaso) →final.mp4
Reglas importantes que la gente pasa por alto:
- vía (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 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/Cinematográfico; el presupuesto de PLACA del modo Temático es la única excepción sancionada — los beats de reacción registrados y controlados por puerta (carga-oscurecimiento, golpe, sacudida, grano) definidos por ADN de tema y aplicados DESPUÉS de la composición de la máscara para que sujeto+texto+placa se muevan como un solo fotograma) — los subtítulos son lo único que se añade; la máscara solo permite que el sujeto ocluya la pista incrustada. Nunca etiquetar/recolorear/líneas de escaneo el metraje.
- Dos libros de reglas: vía → references/rail.md (delgado), artesanía de incrustación → references/composition-craft.md (rico, solo incrustación). Hojea según sea necesario.
Modelo de subtítulos — vía + incrustación
Cada frase hablada es una de tres cosas:
| Qué | Cómo se muestra | |
|---|---|---|
| drop | relleno — em/eh, tartamudeos, autocorrecciones | no se muestra |
| rail | el valor predeterminado — contenido hablado ordinario (literal) | subtítulo inferior limpio, al frente, legible. Una palabra impactante puede tener un resalte emphasis en línea (color de acento / palabra activa) — permanece en la vía. |
| embed | un pico promocionado — el beat del titular | una palabra grande compuesta detrás del sujeto (oclusión de máscara), entrada + salida diseñadas |
La vía lleva la mayor parte del texto; la incrustación es el pico escaso y ganado. La escasez es por beat/bloque, no por clip: ≤1 heroico por bloque (pensamiento), nunca dos co-visibles, ≥ un beat de aire entre ventanas heroicas (el compilador advierte por debajo de 0.6s). Un clip corto → generalmente 1–2; un video explicativo largo → ~uno por sección. Entre múltiples heroicos, el más grande creado es el APEX (solo él recibe la incrustación de bloqueo completa + elevación de ajuste de ancho); los más pequeños son picos MENORES que montan su columna como líneas de énfasis sobredimensionadas (fg, movimiento amortiguado) — no todos los beats necesitan el escaparate de la máscara, 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 vía construyen exactamente esto (vía = rail.html, incrustación = el clímax en index.html). Las identidades de flujo de columna eliminan la vía y hacen todo al estilo de incrustación — recomiéndalas solo para solicitudes de ambiente sobre literal, nunca para videos explicativos / voz en off donde las palabras deben leerse (CATALOG.md lo codifica 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, el compilador y el archivo de autoría se derivan por búsqueda de la fila del catálogo. Nunca plantear "Estándar vs Cinematográfico vs Temático" 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 puerta 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 indica el porqué en una línea en lugar de preguntar.
Procedimiento: sondear el clip → preseleccionar 2–3 identidades del catálogo → recomendar UNA con un porqué en una línea → el usuario elige (modo autónomo: tú eliges, indicando el porqué) → redactar 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 redactar. No uses 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 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 redactar 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 — los bloques caption-* incluidos — no tiene nada en qué montarse. Un bloque de registro estiliza texto en un lienzo diseñado; esta habilidad quema subtítulos en el metraje de alguien a través de una máscara. Cuando ninguna identidad se ajusta a la solicitud, dilo y elige la más cercana, en lugar de salir del catálogo.
Heurística de recomendación: usa las "Heurísticas de preselección" en CATALOG.md — son a nivel de identidad (por ejemplo, "炸" preselecciona ordnance/stomp/terminal/loud y elige según QUÉ debe explotar), nunca a nivel de categoría. No estoy seguro → anchor.
- Cinematográfico → escribir
cinematic.jsonpara una plantilla bloqueada, compilada pormake-cinematic.cjs. - Temático → leer themes/README.md, redactar
theme.json, ejecutarscripts/render-theme.sh(compila + renderiza + reacción de placa → final_fx.mp4).
Puerta de decisión — EJECUTAR PRIMERO
Sondear el video y clasificar la escena antes de cualquier modo.
ffprobe <video.mp4> # especificaciones
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png # al 20/50/80%
Leer las muestras. Rechazar si:
- Múltiples hablantes / cortes bruscos (dividir y renderizar cada toma, o rechazar)
- Sin sujeto humano (esta habilidad 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); presta atención y rechaza en lugar de subtitular palabras inventadas - La fuente ya tiene subtítulos / leyendas / gráficos de texto pesados quemados — añadir un segundo sistema de subtítulos genera conflicto y el metraje se envía sin tocar (sin cubrir/rellenar). El texto quemado a menudo aparece solo a mitad del clip: muestrea una hoja de contactos 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 se puede transcribir como galimatías seguro. Lee
transcript.jsoncon criterio antes de redactar; si no se interpreta como lenguaje, pruebaWHISPER_MODEL=mediumuna vez, de lo contrario rechaza (una vía literal de palabras inventadas es peor que ningún subtítulo). - Cámara en mano movida con movimiento rápido (la máscara parpadea)
Sondas previas al vuelo (no cuestan nada, evitan los peores fallos)
- Sonda de corte de toma. Muestrear fotogramas al 20%, 50%, 80%. Si aparece un sujeto/escena diferente, recortar el clip antes del corte.
- Sonda de letterbox / pillarbox. ¿Barras negras en el primer fotograma? Calcular el rectángulo de contenido seguro y restringir la colocación de los subtítulos dentro de él.
- Sonda de luminancia. Muestrear la luminancia promedio de la región de subtítulos —
inferior a 60→ el texto claro se lee tal cual,60-180→ añadir la pantalla de glifo,180+→ texto opaco + pantalla (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 vía opaca), 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 vía/panel; poético / social / "cinematográfico" → identidades de flujo de columna por registro; "炸 / 特效 / VFX" / mundos con nombre → 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> # máscara ∥ transcripción (paralelo) → zonas seguras. Un solo comando.
# → frames_fg/ transcript.json safe-zones.json
3. [PASO DEL AGENTE — el único paso creativo] redactar un pequeño JSON; ver a continuación según el modo
Cinematográfico: redactar cinematic.json → node scripts/make-cinematic.cjs <project>
Temático: redactar theme.json → bash scripts/render-theme.sh <project> (compila + renderiza + efectos de placa)
4. node scripts/preview-frames.cjs <project> # ~2s/fotograma vistas previas de composición → § QA Visual (ANTES del renderizado)
5. bash scripts/render-and-composite.sh <project> # compuertas → final.mp4 + instantánea history/
(Modo Temático: OMITIR 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 las habilidades instaladas contra lo último en GitHub y actualiza el conjunto global si alguna está desactualizada.
El paso 3 difiere según el modo:
Paso 3 — Modo Cinematográfico (solo incrustación)
- Leer
safe-zones.jsonprimero. Los planos de narración van enzones.hugLeft/hugRight— franjas limpias QUE COLINDAN con la silueta (el texto lejos del cuerpo se lee como flotante, no incrustado; las esquinas lejanas son la alternativa, no el valor predeterminado). El heroico predetermina aheroAnchor/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