¿Qué hace Narrador de Demos?
Pipeline: fotogramas → entender → borrador de guion → ⛔ PUERTA DE APROBACIÓN DEL USUARIO → SFX + TTS → renderizar → verificar.
Salida: output_final.mp4 (H.264/AAC, −16 LUFS, subtítulos quemados) + subtitles.srt.
SKILL="<ruta absoluta del directorio que contiene este SKILL.md>" # p.ej. ~/.claude/skills/demo-narrator o ./.claude/skills/demo-narrator
PY="$SKILL/.venv/bin/python"
Resuelve SKILL una vez al inicio (depende de dónde se instaló la habilidad) y usa rutas absolutas a partir de entonces.
0. Requisitos previos
- Si
$PYno existe, informa al usuario que la instalación requiere ffmpeg + espeak-ng (Homebrew/apt), un entorno virtual Python 3.12, PyTorch y ~400 MB de pesos de modelo gratuitos; si acepta, ejecutabash "$SKILL/setup.sh"(tarda unos minutos; ejecútalo en segundo plano). - Elige un directorio de trabajo junto al video:
WORK="<directorio del video>/demo-narrator-work/<nombre del video>". Nunca escribas dentro del directorio de la habilidad. - Pregunta (un solo mensaje, solo lo que se desconoce): nombre del producto + qué hace, audiencia, tono (por defecto: amigable, seguro, conciso), preferencia de voz (por defecto
af_heart), y cualquier cosa que deba decirse (CTA, URL). No te detengas si el usuario ya dijo "solo hazlo" — infiere de los fotogramas.
1. Extraer fotogramas + verificar duración
"$PY" "$SKILL/scripts/extract_frames.py" "<video>" --out "$WORK"
- Muestra duración/resolución, muestrea 1 fotograma / 2 s, detecta cambios de escena, construye mosaicos de contactos de 3×3.
- Rechaza videos de < 3 s o > 15 min (
--force/--max-durationpara anular; usa--interval 4para videos largos). - Revisa
$WORK/sheets/*.jpgprimero (cada una etiquetada con marcas de tiempo). Abre fotogramas individuales$WORK/frames/*.jpgsolo donde necesites detalle (texto UI pequeño, momento exacto de un clic). $WORK/frames.json→duration,scene_changes(mejores lugares para whooshes), lista de fotogramas.
Construye una lista de tiempos: qué hay en pantalla en cada momento, qué acciones ocurren (clic, escribir, cambio de página, estado de éxito), y qué debe llevarse el espectador.
2. Redactar $WORK/script.json
{
"video": "/ruta/absoluta/a/demo.mp4",
"voice": "af_heart",
"speed": 1.0,
"approved": false,
"segments": [
{"id": 1, "start": 0.4, "end": 4.6, "text": "Conoce Relay, la forma más rápida de convertir llamadas de clientes en tickets."},
{"id": 2, "start": 5.0, "end": 10.8, "text": "Suelta una grabación, y Relay extrae cada error, solicitud y seguimiento por ti."}
],
"sfx": [
{"name": "whoosh", "at": 4.8},
{"name": "pop", "at": 7.2, "gain_db": -12},
{"name": "ding", "at": 10.4}
]
}
Reglas de tiempo
- Presupuesto de palabras por segmento ≈
(end − start) × 2.5palabras (Kokoro ≈ 150 ppm a velocidad 1.0). Mantente por debajo. - Deja ≥ 0.3 s entre segmentos; comienza la primera línea a ~0.3–0.8 s; deja que el video respire después de momentos importantes.
- Ancla
startal momento en que lo que se describe aparece, no antes. La narración puede adelantarse a una acción por ~0.3 s. - Los segmentos no deben exceder el video; el segmento final debe terminar ≥ 1 s antes de que termine el video.
Escribir para el oído
- Conversacional, segunda persona ("tú"), contracciones, verbos activos. Una idea por segmento.
- Describe el beneficio de lo que sucede, no los píxeles. Nunca "Aquí vemos…" / "Como puedes ver…".
- Escribe las palabras como deben pronunciarse: "el doble de rápido", "A-P-I" solo si debe deletrearse, "punto com". Evita símbolos, emojis, URLs con barras y paréntesis.
- Oraciones cortas. Termina con una CTA clara si el usuario la proporcionó.
SFX (whoosh, whoosh_soft, pop, click, ding) — at es el tiempo absoluto del video.
whooshen transiciones de página/pantalla (usascene_changes),whoosh_softpara paneles/modales deslizándose,poppara elementos/toasts que aparecen,clickpara pulsaciones de botones clave,dingpara éxito/completado.- Moderación: ~1 señal cada 4–6 s como máximo. No apiles señales en menos de 0.3 s. Nivel por defecto −9 dB bajo la voz; usa
gain_db(p. ej. −14) para las sutiles.
Voces (Kokoro): af_heart (mujer estadounidense cálida, por defecto), af_bella, am_michael / am_fenrir (hombre estadounidense), bf_emma (mujer británica), bm_george (hombre británico). Otras voces se descargan una vez al primer uso.
3. ⛔ PUERTA DE APROBACIÓN DEL GUIÓN — obligatoria
No generes ningún audio hasta que el usuario apruebe explícitamente el guion.
-
Presenta el guion como una tabla y detente:
# Tiempo Palabras / presupuesto Narración SFX 1 0:00.4–0:04.6 11 / 10 ⚠ Conoce Relay, … — Marca los segmentos que superan el presupuesto con ⚠. Menciona la voz + duración total de la narración. Termina con: "Aprueba este guion, o dime qué cambiar."
-
Termina tu turno y espera. El silencio, "¿se ve bien?", o la aprobación de un borrador anterior no es aprobación de este.
-
Con ediciones: actualiza
script.json, vuelve a presentar las filas cambiadas, espera de nuevo. -
Solo después de un sí explícito ("aprobar", "sí", "adelante", "dale") para el texto actual, márcalo:
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json" --approveLa marca es un resumen del texto de la narración.
generate_tts.pyyrender_video.pyse niegan a ejecutarse en un guion sin marcar o si algún texto cambió después de marcar; debes volver a pasar por esta puerta. Nunca establezcasapproved/approved_digestmanualmente. Las ediciones de tiempo (start/end) ysfxno necesitan re-aprobación.
4. Generar SFX + locución
"$PY" "$SKILL/scripts/generate_sfx.py" --out "$WORK/sfx"
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json"
- TTS escribe
$WORK/audio/seg_###.wav+tts.json. Motor: Kokoro, con respaldo automático a Piper (--engine piperpara forzar). - Cada clip se ajusta a su ranura (hasta el inicio del siguiente segmento); los desbordamientos se resintetizan más rápido hasta
--max-speed 1.25. - Si la tabla aún muestra
OVER, prefiere moverstart/endo segmentos posteriores (no necesita re-aprobación). Si el texto debe acortarse, eso es un cambio de texto → vuelta a la puerta. - Rehacer segmentos individuales:
--only 3 5. Variación diferente de SFX:--seed 7.
5. Renderizar
"$PY" "$SKILL/scripts/render_video.py" "$WORK/script.json"
- Coloca los clips en su
start, nunca superpuestos; los pequeños desbordamientos obtienen un ajusteatempoque preserva el tono (≤ 1.12×), el resto desplaza clips posteriores (se imprime como deriva). Mantiene el último fotograma si la narración supera la duración del video. - Mezcla voz + SFX, normaliza el volumen a −16 LUFS, quema subtítulos (tarjetas renderizadas con Pillow + superposición FFmpeg, por lo que no se necesita libass), escribe
$WORK/output_final.mp4ysubtitles.srt. - Música de fondo opcional (original, sintetizada localmente, sin licencia):
"$PY" "$SKILL/scripts/generate_bgm.py" --duration <segundos de video> --out "$WORK/bgm.wav"(estilos:positive(por defecto) = guitarra acústica con punteo en semicorcheas y cuerdas al aire sonando, acorde cálido en cada pulso, bombo a cuatro por cuatro, rimas/claps sincopados, bajo fuera del compás, lead suave punteado, 111 BPM, pausa en medio de la pista, modelado sobre una referencia de demo B2B;demo-bright/demo-dorian= ritmo de demo SaaS modelado en pistas de demostración de productos comerciales: 110 BPM, acordes cálidos que pulsan en corcheas y bombean con un bombo suave, claps en tiempos 2 y 4, hi-hats en corcheas, bajo en las fundamentales de los acordes, una línea melódica sostenida, una melodía punteada ligera, introducción → ritmo → pausa de 8 compases en medio de la pista → ritmo → final limpio;uke,marimba,pluck,kalimba= bases brillantes para demos de software, un motivo punteado/de martillo sobre un ritmo simple de bombo suave + snap/clap + shaker y un poco de bajo, 100–112 BPM, tonalidad mayor;lofi(por defecto) = ritmo relajado con swing y batería;keys= piano eléctrico;upbeat= cuatro por cuatro + arpegio;ambient= solo pad.--bpm,--key(estilos brillantes),--mood(otros),--seed Npara una variación). Haz previsualizaciones de 30–40 s con--duration 40y deja que el usuario elija de oído antes de renderizar todo, luego renderiza con--bgm "$WORK/bgm.wav".--bgmtambién acepta una pista proporcionada por el usuario (mp3/m4a/wav): se nivela automáticamente a la misma referencia, se repite con un crossfade de 2.5 s si es más corta que el video, y se desvanece al final. Pide al usuario que confirme que tiene los derechos de cualquier pista que proporcione. La música se atenúa automáticamente bajo la voz; ajusta con--bgm-db(por defecto −2.5) y--duck-db(por defecto −5). - Banderas útiles:
--out <ruta>,--orig-volume 0.15(mantener el audio original en silencio),--sfx-gain-db -12,--no-subs(aún escribesubtitles.srt; úsalo cuando el video ya tenga subtítulos en pantalla cerca de la parte inferior),--font <ttf>,--font-scale 0.05,--crf 20.
6. Verificar antes de informar
- Revisa el resumen del renderizado: columna de deriva ~0, sin advertencia de fotograma sostenido (o explícala).
- Verifica subtítulos:
ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg"en 2–3 puntos medios de segmentos, luego visualiza las imágenes: subtítulos legibles, que no cubren la interfaz clave. Si cubren algo importante, considera--font-scaleo informa al usuario. - Informa: ruta de salida, duración, motor/voz utilizados, segmentos que se aceleraron o desplazaron, y cómo ajustar (editar
script.json→ volver a ejecutar los pasos 4–5; las ediciones de texto pasan nuevamente por la puerta).
Solución de problemas
| Síntoma | Solución |
|---|---|
kokoro no disponible … probando respaldo | Vuelve a ejecutar setup.sh; verifica que Python sea 3.10–3.12 en .venv. La salida de Piper es buena pero menos natural. |
| Palabra/nombre mal pronunciado | Vuelve a escribir fonéticamente en text (p. ej. "Kubernetes" → "ku-ber-ne-tis"), obtén aprobación, regenera ese segmento con --only. |
| Voz se siente apresurada | Reduce speed a 0.95, amplía las ventanas de segmento o recorta palabras. |
| Subtítulos demasiado pequeños/grandes | --font-scale 0.035–0.06. |
| Colores incorrectos / tartamudeo VFR | Añade --fps 30. |
| El video tiene música que quieres conservar | --orig-volume 0.12–0.2. |
Todo se ejecuta sin conexión después de la descarga única del modelo. Licencias: Kokoro-82M Apache-2.0, Piper GPL-3.0 (piper-tts ≥1.3), voces según la tarjeta del modelo, FFmpeg LGPL/GPL.