plan-to-video

Plan a video

Convierte un plan escrito en un video explicativo narrado (entre 60 y 90 segundos para una publicación social, de 2 a 2.5 minutos para un plan real con varias decisiones): el gancho, el problema, la propuesta, el mecanismo, luego un fotograma por decisión abierta (pregunta más 2 a 4 opciones) y un cierre con llamado a la acción.

Este skill no reimplementa HyperFrames. Decide el brief, la forma de la historia y la configuración, luego ejecuta el workflow /faceless-explainer instalado paso a paso, añadiendo correcciones en los puntos donde la canalización predeterminada tiende a fallar. Lee /hyperframes y /faceless-explainer según indican; este archivo te dice qué responder y qué parchear.

Primera ejecución en una máquina: lee references/setup.md y ejecuta su preflight. Instala los skills de HyperFrames y una voz local si faltan.

Configuración

Resuelve estos valores una vez al inicio y reutilízalos en cada comando. Pregunta al usuario solo si no se puede encontrar un valor.

Nombre	Cómo resolver	Valor predeterminado
VIDEOS_DIR	$PLAN_TO_VIDEO_DIR si está definido	./videos en el directorio de trabajo actual (convención de faceless-explainer)
FE_DIR	la carpeta que contiene faceless-explainer/SKILL.md instalado	consulta references/setup.md para la búsqueda
MEDIA_DIR	la carpeta que contiene media-use/SKILL.md instalado	misma búsqueda
HYPERFRAMES_PYTHON	variable de entorno si está definida, sino el venv de references/setup.md	~/.hyperframes-venv/bin/python
VOICE	lo que pida el usuario, sino la voz recordada, sino	Kokoro am_michael (sin conexión)

1. Brief (confirmar brevemente, no interrogar)

Lee primero la fuente (el documento del plan, la nota de investigación, el chat). Luego propón estos valores predeterminados en un mensaje corto y pregunta solo lo que la fuente no pueda responder. Un 'sí' rápido es mejor que un cuestionario.

Campo	Valor predeterminado	Por qué
angle	listicle (uno de los valores de la ruta: concept, how-to, listicle, narrative)	un plan es 'por qué importa, cómo funciona, N decisiones'
storyboard arc	concept-explainer with listicle	texto libre en STORYBOARD.md, no un enumerado del brief
aspect	1920x1080	se ve en un portátil o en una llamada; las tarjetas de opciones necesitan ancho
length	2 a 2.5 min para un plan real con varias decisiones; unos 60 a 90 s para una publicación social. Límite máximo 180 s	el punto óptimo de faceless-explainer es de 30 a 90 s; un plan con muchas decisiones dura más. Unos 10 s por decisión más intro y cierre
language / voice	el idioma de la fuente; Kokoro am_michael para inglés	local y gratuito. Las voces de Kokoro en otros idiomas necesitan espeak-ng
flow / storyboard	automation / no (autónomo)	ofrecer la revisión del storyboard cuando el plan es de alto riesgo
look	la propia marca del proyecto cuando el video trata sobre un repo, sino un preset adecuado	el video debe parecerse a lo que explica
music	none	MusicGen local necesita torch; la música de HeyGen requiere inicio de sesión
project	$VIDEOS_DIR/<kebab-topic>/	una carpeta por video

Pregunta, como máximo: quién lo verá (determina qué tan técnico es el texto), y si se debe marcar una opción recomendada en cada decisión (el borde de acento 'lean').

Regla de opción recomendada: marca la opción que recomienda la fuente. Cuando ninguna opción gana, no marques nada; cuando la decisión es 'soportar varias', marca cada opción que forma parte de esa respuesta. Cuando la fuente no lo dice, recomienda los valores predeterminados de este skill (los valores de la tabla anterior) en lugar de inventar una preferencia.

BRIEF.md se escribe en el Paso 0, después de npx hyperframes init (init rechaza una carpeta no vacía), en la forma que describe /hyperframes references/brief-format.md, manteniendo separado lo que dijo el usuario de lo que inferiste.

2. Forma de la historia

Arco predeterminado, adaptado a la fuente:

1. Gancho con un número real de la fuente ('N de M elementos son X'). Cada cifra debe remitirse a una línea de la fuente; nunca inventes estadísticas, precios o recuentos. Si la fuente no tiene número, abre con el dolor concreto.
2. El problema en 2 o 3 causas nombradas, con ejemplos reales de la fuente.
3. La tesis o propuesta para el fotograma 3 (valor antes que evidencia).
4. El mecanismo en un fotograma de diagrama.
5. Una señal ('Cinco decisiones antes de construirlo') como un breve respiro.
6. Un fotograma por pregunta o paso abierto, todos en el mismo escenario de preguntas (references/question-stage.md). Cada fotograma muestra la pregunta y sus 2 a 4 opciones; las opciones aparecen mientras la voz las nombra.
7. Un cierre con llamado a la acción que retoma la señal ('Responde estas cinco y el primer paso se envía esta semana').

Escribe la voz en off como frases cortas clave (de 6 a 25 palabras por fotograma) para que cada opción tenga una palabra que revelar. Si una decisión ya está respondida en la fuente, muestra la respuesta elegida en el acento en lugar de preguntar.

3. Ejecutar el workflow, con estos parches

Sigue los Pasos 0 a 6 de /faceless-explainer en orden. En cada paso aplica el parche correspondiente de references/gotchas.md. Los que causan problemas si se omiten:

• Paso 0: inicia dentro del padre de $VIDEOS_DIR para que el proyecto termine en $VIDEOS_DIR/<topic>, luego escribe BRIEF.md. Estar desconectado de HeyGen está bien: la voz se ejecuta con Kokoro localmente.
• Paso 2 diseño: para un repo, pon sus colores y fuentes en capture/extracted/tokens.json y coloca los archivos .woff2 reales en assets/fonts/ antes de build-frame.mjs (entonces escribe el bloque @font-face por sí mismo). Obtén las fuentes de los archivos del sitio de la marca, de una descarga de Google Fonts o de un paquete de fuentes en node_modules. Si la marca es oscura y el preset es claro, invierte los roles en frame.md, reemplaza los glifos de preset que la fuente incrustada pueda no tener, y cambia un acento de preset que pertenezca a otra marca por el del usuario (references/gotchas.md, Paso 2).
• Paso 3.1 audio: pasa HYPERFRAMES_PYTHON en cada comando de audio a menos que el python3 predeterminado ya importe kokoro_onnx.
• Temporización: deja que el audio termine y ejecuta audio.mjs sync-durations antes de escribir las ventanas de Escena del Paso 4, luego ajusta cada revelación según las temporizaciones reales de palabras en audio_meta.json. (faceless-explainer ejecuta sync-durations en el Paso 5; moverlo antes es intencional.)
• Espacio de respiro: sync-durations establece cada fotograma a su duración exacta de voz, por lo que el último fotograma y la señal terminan abruptamente. Justo después de sync, edita - duration: en STORYBOARD.md: fotograma final +2 a 3 s, señal y otros fotogramas de respiro +1 s. Hazlo antes de construir los paquetes para que los workers animen contra las ventanas acolchadas.
• Palabras de subtítulos: los subtítulos provienen de una transcripción del audio, no de SCRIPT.md, por lo que los nombres de productos se malinterpretan. Antes de construir los subtítulos, compara la lista de palabras en audio_meta.json (voices[].words[].text) con SCRIPT.md y corrige las palabras malinterpretadas en su lugar, manteniendo sus temporizaciones.
• Antes del despacho del Paso 5: dale a cada worker los nombres exactos de archivos de fuentes colocados en el Paso 2. Los paquetes omiten el bloque ## Video direction del storyboard y las temporizaciones completas de palabras, así que pega ambos en el contexto de despacho de cada worker. Dale a los fotogramas del escenario de preguntas la especificación compartida textualmente. Prohíbe emoji.
• Paso 5: un worker por fotograma, en paralelo si tu agente admite subagentes (un modelo más rápido está bien para los workers), cada uno con _role.md, su paquete y el contexto de despacho.
• Después de los workers: normaliza las rutas de activos, corrige las advertencias de lint que son errores reales de búsqueda, ejecuta check, toma una instantánea, mira la hoja de contacto.

4. Puertas de calidad (todas antes del renderizado)

• npx hyperframes lint con 0 errores. Las advertencias studio_missing_editable_id son cosméticas; gsap_repeated_fromto_without_baseline es un error real, arréglalo (references/gotchas.md, Paso 6).
• npx hyperframes check pasa.
• npx hyperframes snapshot --at <punto medio de cada fotograma> y mira realmente la hoja de contacto: texto oscuro sobre fondo oscuro, fuentes faltantes (respaldo serif), tarjetas recortadas y emoji tofu aparecen allí.
• Si el usuario tiene un estilo propio (por ejemplo 'sin guiones largos'), revisa cada cadena: las líneas - voiceover:, las líneas de SCRIPT.md, el texto en compositions/frames/*.html, y también los encabezados. Escribe los encabezados con dos puntos (## Frame 1: Hook, ## Line 1: Hook (Frame 1)); el analizador del storyboard y del guión lo acepta, por lo que nunca se necesita un guión.

5. Revisión, renderizado, entrega

El Paso 6 de faceless-explainer mantiene una pregunta incluso en modo autónomo: abre npx hyperframes preview --background y pregunta '¿renderizar ahora o qué cambios?'. Omite esa pregunta cuando el usuario pidió un renderizado de una sola vez. Luego:

npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4 (--skill solo etiqueta la telemetría de renderizado anónimo; high es un alias de delivery)

Abre el MP4 solo si el usuario lo desea (open en macOS, xdg-open en Linux, start en Windows). Informa: la ruta del MP4, su duración real (ffprobe -v error -show_entries format=duration -of csv=p=0 renders/video.mp4), la lista de fotogramas con ids (compositions/frames/NN-*.html) para que se puedan revisar fotogramas individuales, la ruta de la hoja de contacto, y cualquier cosa omitida (sin música, una palabra mal pronunciada, un hecho omitido porque la fuente no lo tenía).

Archivos de referencia

• references/setup.md: instalación en máquina nueva y preflight (skills de HyperFrames, venv de Kokoro, ffmpeg, Chrome).
• references/question-stage.md: la especificación de diseño compartida para los fotogramas de decisión y paso. Pégala en el contexto de despacho de cada uno de esos workers.
• references/gotchas.md: correcciones de entorno y canalización, por paso del workflow, con comandos.