embedded-captions — capa mute-feed

Instalación del complemento: Antes de los comandos de configuración o actualización, sigue las reglas de ejecución del complemento cuando esta habilidad esté dentro de un complemento 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 que confíes en ellas.

Subtítulos incrustados

Un catálogo, elegido al inicio (CATALOG.md — 35 identidades; los motores detrás son detalles del backend). Estándar (por defecto) construye un riel limpio y textual (subtítulo en la parte 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 puramente incrustado — sin riel, cada subtítulo se compone detrás del sujeto (tipografía principal, acumulación, oclusión como efecto). Temático es una constitución temática completa — paradigma del cuerpo × pieza principal × 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 / con voz en off son 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 ("炸", "特效", "像 AE 做的").

---

Requisitos previos de ejecución

Las instalaciones de complementos utilizan la CLI empaquetada y fijada por manifiesto para enmascaramiento, transcripción y renderizado; no se requiere una copia del código fuente. El asistente de vista previa local y medición de subtítulos también necesita Sharp, Puppeteer (con su navegador Chromium) y GSAP. Instálalos en el proyecto de subtítulos, no dentro del complemento 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 exitosamente 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 de compilación explícito o HYPERFRAMES_ROOT selecciona la CLI del colaborador en lugar del pin del complemento. Cancela un renderizado atascado normalmente a través de la CLI/terminal; el asistente de subtítulos no mata forzosamente 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 selección de identidad como una pregunta diferida — la lista corta necesita el clip sondeado, 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 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 proceso a continuación es largo; el pipeline en sí es corto — y todo lo determinista se calcula o compila, nunca se escribe a mano:

1. Puerta de decisión (rechazar clips malos) → elegir UNA identidad de CATALOG.md (35 identidades; motor/compilador derivado por búsqueda — nunca preguntar por un modo/categoría)
2. hyperframes init (saltarlo 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)
3. redactar un pequeño JSON de opciones creativas (leer safe-zones.json primero): Cinematográfico → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs; Temático → theme.json → make-theme.cjs (paradigmas de riel/panel/poema/toma de control; anchor es el valor predeterminado del riel silencioso)
4. QA visual: node scripts/preview-frames.cjs <proyecto> → vistas previas fieles compuestas en ~2s/fotograma (sin renderizado). Consulta § QA visual antes de pagar por un renderizado.
5. render-and-composite.sh → compuertas (sincronización / oclusión+principal / desbordamiento / entrega) → final.mp4

Reglas importantes que la gente pasa por alto:

• riel (predeterminado) + incrustación (promoción). drop (relleno, no se muestra) / rail (subtítulo textual en la parte inferior, al frente, lleva la mayor parte del texto) / embed (una palabra clave compuesta detrás del sujeto). El modo estándar hace ambas cosas, incrustando solo el(los) pico(s). 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 — ritmos de reacción registrados (carga-disminución, golpe, sacudida, grano) definidos por ADN temático y aplicados DESPUÉS de la composición del enmascaramiento para que sujeto+texto+placa se muevan como un solo fotograma) — los subtítulos son lo único que se agrega; el enmascaramiento solo permite que el sujeto ocluya la pista incrustada. Nunca graduar/recolorear/líneas de escaneo del metraje.
• Dos libros de reglas: riel → references/rail.md (delgado), arte de incrustación → references/composition-craft.md (rico, solo incrustación). Consulta según necesidad.

---

Modelo de subtítulos — riel + incrustación

Cada frase hablada es una de tres cosas:

	Qué es	Cómo se muestra
drop	relleno — um/eh, tartamudeos, autocorrecciones	no se muestra
rail	el predeterminado — contenido hablado ordinario (textual)	subtítulo limpio en la parte inferior, al frente, legible. Una palabra destacada puede obtener un resaltado de énfasis en línea (color de acento / pop de palabra activa) — permanece en el riel.
embed	un pico promocionado — el latido principal	una palabra grande compuesta detrás del sujeto (oclusión de máscara), entrada y salida diseñadas

El riel 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 principal por bloque (pensamiento), nunca dos visibles simultáneamente, ≥ un ritmo de aire entre ventanas principales (el compilador advierte por debajo de 0.6s). Un clip corto → usualmente 1–2; un video explicativo largo → ~uno por sección. Entre varios principales, el más grande redactado es el APEX (solo él obtiene el bloqueo completo de incrustación + elevación de ancho); los más pequeños son picos MENORES que viajan en su columna como líneas de énfasis sobredimensionadas (primer plano, movimiento amortiguado) — no todos los ritmos necesitan la exhibición de 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 riel construyen exactamente esto (riel = rail.html, incrustación = el clímax en index.html). Las identidades de flujo de columna eliminan el riel y hacen todo al estilo de incrustación — recomiéndalas solo para solicitudes de ambiente sobre texto, nunca para videos explicativos / con 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 redacción se derivan por búsqueda a partir de la fila del catálogo. Nunca preguntes "Estándar vs Cinematográfico vs Temático" — esos son nombres del backend (un producto tiene una UX aunque tenga 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 expresa el porqué en una línea en lugar de preguntar.

Procedimiento: sondear el clip → lista corta de 2–3 identidades del catálogo → recomendar UNA con un porqué en una línea → el usuario elige (modo autónomo: tú eliges, expresando 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 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 redacción de cada backend.)

CATALOG.md es todo el espacio de respuesta 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 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 — los bloques caption-* incluidos — no tiene dónde montarse. Un bloque del registro estiliza texto sobre 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 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 (por ejemplo, "炸" lista corta ordnance/stomp/terminal/loud y elige por QUÉ debería explotar), nunca a nivel de categoría. En caso de duda → anchor.

• Cinematográfico → escribir plan.json para una plantilla bloqueada, compilada por make-composition.cjs.
• Temático → leer themes/README.md, redactar theme.json, ejecutar scripts/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%

Lee las muestras. Rechazar si:

• Varios hablantes / cortes duros (dividir y renderizar cada toma, o rechazar)
• Sin sujeto humano (esta habilidad es para primer plano parlante)
• 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 "Thank you." sobre silencio); presta atención y rechaza en lugar de subtitular palabras fabricadas
• La fuente ya tiene subtítulos / texto gráfico pesado quemados — agregar un segundo sistema de subtítulos entra en conflicto y el metraje se entrega sin tocar (sin cubrir/inpaint). El texto quemado a menudo aparece solo a mitad del clip: muestra 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 con acento no nativo/pesado puede transcribirse en galimatías confiado. Lee transcript.json antes de redactar; si no se analiza como lenguaje, prueba WHISPER_MODEL=medium una vez, de lo contrario rechaza (un riel textual de palabras fabricadas es peor que sin subtítulos).
• Mano ocupada con movimiento rápido (la máscara parpadea)

Comprobaciones previas al vuelo (no cuestan nada, evitan los peores fallos)

1. Comprobación de corte de toma. Muestrea fotogramas al 20%, 50%, 80%. Si aparece un sujeto/escena diferente, recorta el clip antes del corte.
2. Comprobación de letterbox / pillarbox. ¿Barras negras en el primer fotograma? Calcula el rectángulo de contenido seguro y restringe la ubicación de los subtítulos dentro de él.
3. Comprobación de luminancia. Muestrea la luminancia promedio de la región de subtítulos — por debajo de 60 → el texto claro se lee tal cual, 60-180 → agrega la cortina de glifos, 180+ → texto opaco + cortina (nunca texto claro desnudo). Las plantillas cinematográficas son crema+screen y BLOQUEADAS — usa esta comprobación para elegir una identidad adecuada (escenas brillantes → ink, o el tema anchor de riel opaco), nunca para recolorear una.
4. Recomendación de identidad por tono (tú recomiendas; el usuario elige — consulta Paso 0 + CATALOG.md). Explicativo / entrevista / palabras deben leerse → identidades de superficie de riel/panel; poético / social / "cinematográfico" → identidades de flujo de columna por registro; "炸 / 特效 / VFX" / mundos nombrados → identidades temáticas. Cuando tengas dudas → anchor (las palabras se leen, la 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] redactar un pequeño JSON; ver abajo según el modo
   Cinematográfico: redactar plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Temático:     redactar theme.json → bash scripts/render-theme.sh <proyecto>   (compila + renderiza + efectos de placa)
4. node scripts/preview-frames.cjs <proyecto>   # vistas previas compuestas de ~2s/fotograma → § QA visual (ANTES del renderizado)
5. bash scripts/render-and-composite.sh <proyecto>  # compuertas → final.mp4 + instantánea history/
   (Modo Temático: SALTAR pasos 3b/5 — render-theme.sh ya ejecuta compilación + renderizado y composición
    + _postfx.sh; el entregable es final_fx.mp4, final.mp4 es anterior a la reacción de placa)

El paso 1 init verifica las habilidades instaladas contra las más recientes 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)

1. Lee safe-zones.json primero. Los planos de narración van en zones.hugLeft/hugRight — tiras limpias COLINDANDO con 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 principal por defecto va a heroAnchor/heroBands.best (centrado EN el sujeto, ~30–55% ocluido). recommendation:"fg" mueve la NARRACIÓN al frente para legibilidad; el principal permanece incrustado siempre que heroBands.feasible — principal-fg es el último recurso.
2. **El ADN es la identidad que