Communitygithub.com

Narrador de Demos

Convierte una demo silenciosa o grabación de pantalla en un video narrado con voz humana natural, efectos de sonido limpios, música de fondo opcional y subtítulos (quemados o .srt). Incluye un paso de aprobación del guion antes de generar cualquier audio. 100% local y gratuito.

¿Qué es Narrador de Demos?

Demo Narrator es una habilidad de agente de IA que automatiza la producción de videos narrados a partir de demos de productos o grabaciones de pantalla, proporcionando una solución completamente local, gratuita y que preserva la privacidad del usuario. La habilidad estructura el proceso en un pipeline claro: extracción de fotogramas, comprensión del contenido, redacción de un guion narrativo, y una puerta de aprobación obligatoria donde el usuario revisa y aprueba el guion antes de que se genere cualquier audio. Soporta voces TTS Kokoro-82M con respaldo a Piper, efectos de sonido UI (whooshes, pops, clicks, dings), música de fondo generada sintéticamente (con varios estilos como positivo, lofi, ambient) o música proporcionada por el usuario, y subtítulos quemados o un archivo .srt. Diseñado para ser utilizado con Claude Code, Cursor, Codex o cualquier agente de IA que ejecute comandos de shell, la habilidad se implementa mediante scripts Python que utilizan FFmpeg, numpy/scipy y modelos de aprendizaje automático, todo ejecutándose sin necesidad de API keys o servicios de pago. El resultado final es un video con calidad profesional, normalización de sonido a -16 LUFS, y la flexibilidad de ajustar cada aspecto del guion o la producción.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GarvitSolanki/audio-generator/tree/main/skills/demo-narrator

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿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

  1. Si $PY no 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, ejecuta bash "$SKILL/setup.sh" (tarda unos minutos; ejecútalo en segundo plano).
  2. 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.
  3. 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-duration para anular; usa --interval 4 para videos largos).
  • Revisa $WORK/sheets/*.jpg primero (cada una etiquetada con marcas de tiempo). Abre fotogramas individuales $WORK/frames/*.jpg solo 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.5 palabras (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 start al 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.

  • whoosh en transiciones de página/pantalla (usa scene_changes), whoosh_soft para paneles/modales deslizándose, pop para elementos/toasts que aparecen, click para pulsaciones de botones clave, ding para é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.

  1. Presenta el guion como una tabla y detente:

    #TiempoPalabras / presupuestoNarraciónSFX
    10:00.4–0:04.611 / 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."

  2. Termina tu turno y espera. El silencio, "¿se ve bien?", o la aprobación de un borrador anterior no es aprobación de este.

  3. Con ediciones: actualiza script.json, vuelve a presentar las filas cambiadas, espera de nuevo.

  4. 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" --approve
    

    La marca es un resumen del texto de la narración. generate_tts.py y render_video.py se 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 establezcas approved/approved_digest manualmente. Las ediciones de tiempo (start/end) y sfx no 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 piper para 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 mover start/end o 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 ajuste atempo que 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.mp4 y subtitles.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 N para una variación). Haz previsualizaciones de 30–40 s con --duration 40 y deja que el usuario elija de oído antes de renderizar todo, luego renderiza con --bgm "$WORK/bgm.wav". --bgm tambié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 escribe subtitles.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

  1. Revisa el resumen del renderizado: columna de deriva ~0, sin advertencia de fotograma sostenido (o explícala).
  2. 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-scale o informa al usuario.
  3. 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íntomaSolución
kokoro no disponible … probando respaldoVuelve 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 pronunciadoVuelve 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 apresuradaReduce 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 VFRAñ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.

Skills relacionados