Fldicoahkiin/demo-video-skill

Demo Video Studio

Convierte una aplicación web en funcionamiento en un video demo pulido: interacción real grabada (no diapositivas, no simulaciones) + narración local por TTS + subtítulos sincronizados con palabras + una pista musical de fondo discreta, compuesta de forma determinista con HyperFrames.

Cuándo usar

Al hacer cualquier video demo / tutorial / producto / lanzamiento / hackathon de una aplicación web, especialmente cuando se deba mostrar el producto real funcionando con narración y subtítulos. Graba una URL desplegada o un servidor de desarrollo local.

Pipeline

① grabar    uno de tres motores (abajo)                    → out/*.mp4|webm
② narrar    escribir VO por escena → Kokoro TTS (local)    → narración/*.wav
③ transcribir Whisper marcas de tiempo a nivel de palabra  → *.transcript.json
④ subtitular agrupar en frases + corregir nombres de marca → subtítulos.js
⑤ música    ffmpeg cama ambiental (mezclada baja bajo la voz) → música/cama.wav
⑥ componer  HyperFrames HTML una línea de tiempo: clips+voz+subtítulos+música → MP4

① tiene tres motores — elige según el objetivo (references/screen-studio-look.md):

Objetivo	Motor	Aspecto
App web/escritorio, macOS	Cap CLI — scripts/record-cap.mjs	Screen Studio nativo: auto-zoom desde clics reales, cursor elástico + desenfoque de movimiento, fondo de pantalla / redondeo / sombra, renderizado por GPU
Herramienta CLI	VHS cinta → mp4	terminal estilizado (relleno, margen, borde redondeado, barra de ventana), determinista
Headless / CI / Linux	Playwright — scripts/record.mjs	cursor sintético + ondas; escribe <scene>.events.json (marcas de tiempo + coordenadas) para cualquier composición posterior de zoom

Sea cual sea el motor de grabación, su salida es solo el clip que alimenta ②–⑥ — la grabación y la composición permanecen independientes: vuelve a grabar una escena, o vuelve a ejecutar la narración, sin rehacer la otra. Una pista GIF generada por código (escenas HTML renderizadas directamente a MP4, sin grabación) es una ruta opcional para páginas de documentación.

Flujo de trabajo

0. Elige el motor CON el usuario — nunca en silencio. Mira el proyecto real (¿app web? ¿CLI? ¿escritorio? ¿esta máquina tiene sesión GUI? ¿necesita ejecutarse en CI?), luego presenta las opciones de motor con pros/contras para este proyecto específico y deja que el usuario elija. Por ejemplo, para una app web en Mac: "Cap CLI da el aspecto de Screen Studio de forma nativa pero necesita permiso de grabación de pantalla y una calibración inicial; Playwright funciona en cualquier lugar y regraba escenas individuales rápido pero no tiene auto-zoom; VHS no aplica aquí." Detalles del motor: references/screen-studio-look.md.
1. Entiende el producto primero. Lee su README / docs demo. Escribe un Flujo de Demo antes de tocar las herramientas: problema → recorrido del producto → evidencia → conclusión. Elige la ruta de clics recomendada y el resultado visible que cada escena debe alcanzar. Consulta references/templates.md.
2. Graba. Copia scripts/record.mjs, configura APP y SIZE, reemplaza scenes con tu coreografía (deslizar → pausar → actuar → mantener). Graba a escala de dispositivo 1:1. node scripts/record.mjs [scene]. Motor + ejemplo práctico: references/recording.md.
3. Narrar → subtitular. Escribe un assets/narration/NN-*.txt por escena con voz de narrador (le hablas a un espectador, no lees un README — esto es un arte diferente al copy de marketing; el skill de marketing proporciona el tema/gancho/storyboard, este skill escribe las palabras habladas). Luego: bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs. Edita PHRASE_FIX en build-captions.mjs para tus nombres de marca. La voz es intercambiable por contrato: la narración es un wav por escena (narration/NN-*.wav) — reemplaza cualquier wav con una toma humana, un doblaje de 剪映, u otro TTS, vuelve a ejecutar transcripción+subtítulos, recomponer; nada más cambia. Kokoro (local, Apache-2.0) es el predeterminado y tiene voces en mandarín; edge-tts es una alternativa gratuita en línea. Guía: references/narration-and-captions.md.
4. Componer & renderizar. Empieza desde references/composition-skeleton.html (un clip + pista de subtítulos + audio), amplía la línea de tiempo, luego npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high. Renderiza 1:1 (1080p creado → 1080p de salida) — nunca aumentes a 4K, suaviza la interfaz. references/composition.md.
5. Control de calidad antes de enviar. ffprobe la duración/audio, muestrea 1–2 fotogramas (no negros, no vacíos), subtítulos dentro del fotograma, narración sin cortes, la página de resultado clave realmente visible. Corrige el flujo/temporización, luego vuelve a renderizar.

Inicio rápido

# dependencias del sistema
brew install node ffmpeg
npx playwright install chromium

# entorno virtual de Python para TTS local + transcripción (una vez)
python3 -m venv .ttsvenv && .ttsvenv/bin/pip install kokoro-onnx soundfile
export PATH="$(pwd)/.ttsvenv/bin:$PATH"

# 1) grabar  2) narrar  3) subtitular  4) componer+renderizar
node scripts/record.mjs
bash scripts/tts.sh && bash scripts/transcribe.sh && node scripts/build-captions.mjs
npx hyperframes render . --resolution landscape --fps 30 --crf 17 --quality high --output out/demo.mp4

La primera ejecución de TTS descarga ~340 MB (Kokoro), la primera transcripción ~466 MB (Whisper small.en); ambos se almacenan en caché en ~/.cache/hyperframes/.

Reglas ganadas con esfuerzo

• La interacción real supera a las diapositivas — graba el producto realmente ejecutándose.
• 1:1, nunca escalado 2× — grabar a 2× DPR y renderizar a 4K suaviza cada clip de interfaz. Crea y renderiza a 1080p.
• Composición determinista — nada de Date.now(), Math.random() o red en el HTML; HyperFrames busca fotogramas, por lo que el movimiento debe ser reproducible.
• Cursor visible + mantener en resultados — desliza deliberadamente, pausa en el punto culminante.
• VO, no documentos — la narración sigue la imagen; no es el README leído en voz alta.
• Video ≥ narración — alarga el tiempo del clip para que los visuales nunca terminen antes que la voz.

Dependencias

Node 22+, FFmpeg, Playwright (Chromium), y el CLI de HyperFrames (npx hyperframes, instala sus skills con npx skills add heygen-com/hyperframes). El TTS/Whisper local necesita Python + kokoro-onnx. Por motor (opcional): la ruta Cap necesita cap (curl -fsSL https://cap.so/install-cli.sh | sh) + clicclick (brew install cliclick) + permiso de grabación de pantalla; la ruta de terminal necesita vhs (brew install vhs). Todo gratuito — tabla de licencias en references/screen-studio-look.md. Consulta references/composition.md para la configuración de HyperFrames.

Referencias

• references/pipeline.md — las seis etapas y el flujo de datos
• references/screen-studio-look.md — los tres motores de grabación; ciclo de vida de Cap CLI, agrupación de zoom, cintas VHS, qué no construir
• references/recording.md — motor Director + ejemplo práctico + errores comunes de grabación
• references/narration-and-captions.md — escritura de VO, TTS, Whisper, correcciones de subtítulos
• references/composition.md — línea de tiempo de HyperFrames, fundidos cruzados, 1080p, renderizado
• references/composition-skeleton.html — composición mínima renderizable para copiar como index.html
• references/templates.md — estructuras de hackathon + demo de producto y esqueletos de VO
• references/troubleshooting.md — subtítulos, pantalla blanca, audio, fuentes