Communitygithub.com

video-explicativo-del-producto

Convierte cualquier proyecto de software (repositorio de GitHub, carpeta local, scraper, automatización, bot, sitio web, CLI, API o un portafolio completo) en un video explicativo animado y personalizado con locución por IA, subtítulos y música.

¿Qué es video-explicativo-del-producto?

Este skill permite transformar cualquier proyecto de software en un video explicativo animado profesional, con locución generada por IA, subtítulos en formato SRT y un reproductor HTML incrustable. Soporta múltiples fuentes: repositorios de GitHub, carpetas locales, sitios web activos o simplemente una descripción textual. El proceso comienza analizando el proyecto para extraer datos reales (funciones, comandos, rutas, estadísticas), luego genera un guion gráfico personalizado con escenas tanto genéricas como a medida (por ejemplo, un bot conversacional, un scraper que extrae datos de una página, un dashboard con números en vivo). Tras un paso de validación visual (hoja de contacto) que detecta errores de maquetación o colisión de subtítulos, se renderiza el video final en formato MP4 (apaisado 16:9 o vertical 9:16). La locución se obtiene automáticamente desde el motor disponible: ElevenLabs (con clave API), OpenAI TTS, Edge TTS (gratuito, necesita internet), Piper (offline), macOS 'say' o espeak-ng. Si no hay motor de voz disponible, el video se genera sin audio y se entrega el guion escrito. Además, se pueden generar variantes para redes sociales (Reels/Shorts/TikTok/LinkedIn/X) o videos detallados por producto a partir de un portafolio. El skill está diseñado para funcionar con agentes como Claude Code, Cursor o Codex sin depender de una plantilla fija: cada video obtiene su propia metáfora visual y animaciones únicas.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/cheransanketh070-afk/claude-explainer-skill/tree/HEAD/product-explainer-video

Preguntar en tu IA favorita

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

Documentación

Video explicativo del producto

El usuario señala algo que construyó; tú le entregas un video explicativo animado y pulido con locución que un extraño entiende en menos de un minuto. El video debe estar diseñado para este proyecto: su propia metáfora visual, sus propias animaciones a medida. Nunca produzcas un video de plantilla genérico con los nombres cambiados.

analizar (datos) → resumen de diseño → guion gráfico.json (escenas predefinidas + personalizadas) → validar → hoja de contacto QA → corregir → renderizar (+voz, +música) → entregar

Los scripts viven en scripts/ junto a este archivo. $SK = la carpeta de este skill (donde está este SKILL.md).

0. Verificación de configuración (10 segundos)

python3 -c "import playwright, PIL, numpy" && which ffmpeg && python3 $SK/scripts/voiceover.py --list

Componentes faltantes: pip install playwright pillow numpy edge-tts --break-system-packages && playwright install chromium. Si no hay ffmpeg, indícaselo al usuario (necesario para MP4; --html-only aún entrega el reproductor HTML). voiceover --list muestra qué motores de voz funcionan en este momento.

1. Comprender qué explicar

Deduce primero, pregunta rara vez: asunto (un producto, o un portafolio), audiencia/propósito (desarrolladores en GitHub, clientes, redes sociales), fuente (ruta local, zip subido, URL de GitHub, sitio en vivo, o solo una descripción). Valores predeterminados: 16:9, 45–75 s, desarrolladores más espectadores no técnicos curiosos, locución activada. Pregunta una pregunta corta solo si es realmente ambiguo (p. ej. 15 repos, sin pista de cuál). De lo contrario, indica la suposición en una línea y continúa. No entrevistes al usuario.

2. Recopilar datos (nunca te saltes este paso: mantiene el video honesto)

python3 $SK/scripts/analyze_project.py /ruta/o/git-url [más...] -o datos.json
python3 $SK/scripts/capture_site.py https://su-sitio.com -o captura-del-sitio     # sitios en vivo: capturas de pantalla + datos de la página

El analizador imprime la descripción, los lenguajes, las capacidades, los README commands reales, las banderas de CLI, las rutas, los dominios contactados, las salidas, las variables de entorno, CI/cron y ESTADÍSTICAS REALES seguras de mostrar. Léelo, luego lee el README y 1–3 archivos fuente clave tú mismo cuando los datos sean escasos (¿cuál es el bucle principal? ¿qué ejecuta realmente un usuario? ¿cómo se ve la salida?). Si falla la clonación o no hay red, pide un zip o el README. Si la captura del sitio está bloqueada, pide capturas de pantalla o dibuja una interfaz con escenas personalizadas.

3. Resumen de diseño, luego el guion gráfico

Lee references/narrative-playbook.md (arco narrativo, reglas de veracidad), references/storyboard-schema.md (todos los tipos y campos de escena) y references/custom-scenes.md (cómo escribir escenas a medida). Los guiones gráficos de referencia en assets/examples/ muestran cómo se ve un buen trabajo; son inspiración, no plantillas: no reutilices su contenido, estructura ni redacción.

Primero decide (escríbelo brevemente):

  1. La promesa en una frase.
  2. Qué hace físicamente el producto (cosas que se mueven entre lugares) y la metáfora visual única que lo muestra.
  3. La escena del momento "ajá".
  4. Tema, color de acento (el color de la marca del usuario si se conoce), estilo de bg, ritmo: acorde con la personalidad del producto.
  5. Cuáles 2–4 escenas serán personalizadas (dibujadas para este producto) y cuáles ritmos genéricos usan componentes predefinidos (título, problema, pasos, CTA...).

Luego escribe storyboard.json:

  • Arco narrativo: gancho → problema → cómo funciona → prueba de que es simple → resultado tangible → por qué es bueno → CTA; 7–10 escenas, 45–75 s.
  • Nivel de calidad: al menos una escena es personalizada a menos que el producto sea realmente una CLI simple; la escena ajá siempre es personalizada o una predefinida cuidadosamente elegida. Un bot muestra una conversación; un scraper muestra una página que se convierte en filas; una API muestra una solicitud y respuesta; un dashboard muestra números en vivo.
  • narration en cada escena: estilo hablado, 15–35 palabras. Se convierte en la locución, los subtítulos y el SRT.
  • Solo verdad: los comandos, banderas, funciones, rutas y números provienen de los datos o del usuario. La salida del terminal y las filas de la tabla pueden ser ilustrativas pero genéricas; nunca inventes benchmarks, cantidades de clientes o capacidades. Las escenas de estadísticas usan solo ESTADÍSTICAS REALES/números del README/usuario.
  • Pon meta.url en el repo/sitio y termina con un CTA claro.

4. Validar, luego revisar antes de renderizar

python3 $SK/scripts/storyboard.py explainer/storyboard.json
python3 $SK/scripts/render_video.py explainer/storyboard.json --contact-sheet

La hoja de contacto (~20 s) ejecuta la auditoría de maquetación (texto fuera del escenario, recortado, truncado, que choca con los subtítulos, y errores JS de escenas personalizadas) y escribe explainer-output/contact-sheet.png. Revísala y comprueba: nada apretado o cortado, texto legible, escenas visiblemente diferentes entre sí, escenas personalizadas con aspecto intencionado. Una hoja de contacto muestra un fotograma tardío por escena, así que para cada escena personalizada inspecciona también un fotograma temprano y uno intermedio: --still 3.2,6.5. Corrige y repite hasta que esté limpio.

5. Renderizar con locución

cd explainer
setsid nohup python3 $SK/scripts/render_video.py storyboard.json --quality final --gif \
  > render.log 2>&1 < /dev/null &
sleep 100; tail -c 300 render.log

Sigue consultando (sleep 100; tail -c 300 render.log) hasta que aparezca DONE. En entornos aislados (claude.ai) el trabajo en segundo plano avanza solo mientras se ejecuta una llamada a herramienta, así que la consulta con sleep impulsa el renderizado; no termines tu turno mientras se ejecuta. Ajustes predefinidos: draft (960×540, 15 fps), standard (1280×720, 30 fps, predeterminado), final (1920×1080, 30 fps). Más núcleos de CPU → más rápido (--workers N). Vertical: meta.aspect: "9:16" o --vertical. Máquina lenta: --fps 24.

La locución es automática (--voice auto, predeterminado). El renderizador genera un archivo de audio por escena, estira las escenas para que la narración nunca se corte, baja la música bajo la voz y almacena en caché el audio para que las re-renderizaciones sean gratuitas. Prioridad del motor: ElevenLabs (ELEVENLABS_API_KEY) → OpenAI TTS (OPENAI_API_KEY) → Edge neural voices (pip install edge-tts, gratuito, sin clave, necesita internet) → Piper (neural offline) → macOS say → espeak-ng. Opciones: --voice-name en-US-AndrewNeural (nombre de voz de cualquier motor), --voice-rate +8% (Edge), --voice none solo música, --voice-dir carpeta/ para usar archivos scene-01.mp3… propios del usuario, meta.voice para almacenar la elección en el guion gráfico.

Si el renderizado imprime WARNING voiceover: no speech engine available, el video se renderizó igual (solo música) y voiceover.txt contiene el guion. Indícaselo claramente al usuario, con la solución en una línea: habilita internet y pip install edge-tts (gratuito), o configura una clave API, o instala espeak-ng; luego vuelve a ejecutar el mismo comando (solo se rehacen la voz y la codificación; el reproductor y el guion gráfico no cambian). En claude.ai la zona de pruebas normalmente no tiene internet, así que espera esto: indícalo, entrega el video sin voz y con música, más el guion, y explica que pueden añadir voz ejecutando el pipeline localmente en Claude Code o con una clave API. Nunca afirmes que el video tiene locución a menos que el registro diga voiceover: usando '<motor>'.

Música: fondo libre de regalías generado (--mood calm|upbeat|tech o meta.music_mood); --music none o --music archivo.mp3.

6. Entregar

Salidas en explainer-output/: <nombre>.mp4, <nombre>-poster.png, player.html (reproductor interactivo autocontenido; incrustar con <iframe src="player.html?embed">; tiene movimiento y subtítulos pero sin audio), captions.srt, voiceover.txt, storyboard.resolved.json, voice/, .gif opcional.

Verifica: ffprobe -v error -show_entries stream=codec_type -of csv=p=0 <nombre>.mp4 muestra una pista de audio; la duración coincide; revisa el póster. Copia los archivos entregables a /mnt/user-data/outputs/ y present_files con el MP4 primero, luego póster, subtítulos, player.html y storyboard.json (para que puedan editar y re-renderizar). Mantén el mensaje corto: una línea por escena, qué se asumió, qué motor de voz se usó, cómo ajustar. Ofrece variantes solo cuando sea útil: un clip social en 9:16 (~30 s), otra voz o color de marca, un video para otro repo.

Edición y re-renderizado

Edita storyboard.json (texto, orden, colores, código de escenas personalizadas), vuelve a ejecutar la hoja de contacto y luego renderiza. Los cambios en la narración vuelven a sintetizar solo las escenas modificadas. Ajusta la duration de una escena para alargarla; nunca se acorta por debajo de lo que necesitan la animación y la narración.

Portafolio / "todas mis herramientas"

Analiza todos los repos en una sola llamada, elige 3–4 productos estrella que muestren variedad, dale a cada uno una escena personalizada o la más adecuada con su propia metáfora visual, cierra con una cuadrícula de features del resto y un CTA al perfil. Ofrece videos en profundidad por producto después.

Solución de problemas

  • Playwright is not installed → comando del paso 0.
  • Fotogramas en blanco/negros o líneas de scene error → el JS de una escena personalizada lanzó una excepción; la auditoría imprime el error. Corrige el código.
  • Texto recortado/truncado → acorta, elimina elementos o crea un diseño personalizado.
  • Voz robótica → es espeak; usa Edge/OpenAI/ElevenLabs/Piper en su lugar.
  • La voz no coincide con el tiempo de la escena → el tiempo es automático (las escenas se estiran al audio); si los subtítulos se sienten adelantados, acorta la narración.
  • El registro no avanza / el renderizado se terminó → se ejecutó en primer plano o nadie lo consultó; relánzalo en segundo plano y consulta.
  • Salida demasiado larga → elimina las escenas más débiles; el validador advierte por encima de ~90 s.

Límites honestos

Gráficos animados (diagramas, terminales, código, maquetas de interfaz, animaciones a medida), no grabaciones de pantalla ni metraje fotorrealista. Para una interfaz real, pasa capturas de pantalla o dibuja la interfaz. La calidad de la voz depende del motor disponible.

Skills relacionados