Communitygithub.com

DrChunChihChen/procedural-cartoon-video

Automatiza la creación de videos cortos de dibujos animados vectoriales de alta calidad para tutoriales y guías utilizando Python Pycairo, Gemini 3.8 Flash TTS y FFmpeg.

¿Qué es procedural-cartoon-video?

Este skill ofrece un pipeline completo, impulsado puramente por código y sin dependencias externas de activos (vectores sin pérdida), para producir videos cortos de dibujos animados para tutoriales y explicaciones guiadas. Combina el motor de dibujo Python Pycairo para gráficos vectoriales, la síntesis de voz Google Gemini 3.8 Flash TTS, alineación automática de duración de texto, subtítulos inteligentes basados en signos de puntuación y composición de audio y video con FFmpeg. Está diseñado para generar videos MP4 de alta definición (1280×720 a 30 fps) en minutos, y es ideal para usuarios que mencionan "hacer videos", "animación", "dibujos animados", "video educativo" o necesitan el pipeline completo desde el guion hasta la salida MP4 final. Soporta macOS como entorno de ejecución estándar y utiliza una estructura de proyecto modular con roles de presentador personalizables y una biblioteca de plantillas visuales.

Compatible con~Claude Code~Codex CLI~Cursor✓Antigravity✓Gemini CLI
npx skills add DrChunChihChen/procedural-cartoon-video

Preguntar en tu IA favorita

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

Documentación

Kit de Producción de Vídeo Vectorial Procedimental (Procedural Cartoon Video Kit)

Esta skill proporciona un pipeline de producción de videos cortos de dibujos animados para tutoriales y guías explicativas, completamente impulsado por código y sin dependencias de activos externos (vectores puros sin pérdida). Combina el motor de dibujo Python Pycairo, la síntesis de voz Google Gemini 3.8 Flash TTS, la alineación automática de duración de texto, los subtítulos inteligentes basados en signos de puntuación y la composición de audio y video con FFmpeg, permitiendo renderizar automáticamente videos MP4 de alta definición (1280×720 a 30 fps) en cuestión de minutos.


Requisitos del Entorno del Sistema (Prerequisites)

Con macOS como entorno de ejecución estándar:

# 1. Dependencias del sistema y fuentes (obligatorio: Noto Sans CJK TC, negrita china tradicional)
brew install ffmpeg cairo pkg-config
brew install --cask font-noto-sans-cjk-tc

# 2. Bibliotecas Python dependientes
pip3 install pycairo numpy pillow

# 3. Clave API de OpenRouter (para la generación de voz Gemini 3.8 Flash TTS)
# Escribir la clave API en ~/.openrouter_key, asegurándose de que no contenga saltos de línea
echo "TU_CLAVE_API_OPENROUTER" > ~/.openrouter_key
chmod 600 ~/.openrouter_key

Verificar el entorno: Ejecutar python3 example_ds2.py auto. Si se genera correctamente example_ds2/grid.png, la configuración del entorno está completa.


Estructura Estándar del Directorio del Proyecto

my_video_project/
├── engine.py                  # Motor central: capa base del lienzo, generación de subtítulos, composición BGM, clase Episode, pipeline FFmpeg
├── dc.py                      # Biblioteca de plantillas visuales compartidas (apertura, hoja de ruta, preguntas y respuestas, resumen de puntos clave...)
├── atian.py (o xd.py / aj.py) # Definición del rol de presentador (sobrescribe dc.doctor para cambiar el rol globalmente)
├── ep1.py                     # Código de escenas del episodio actual (funciones de dibujo s0, s1, s2...)
├── ep1/                       # Directorio de activos del episodio actual
│   ├── script.json            # Guion de narración (array de cadenas)
│   ├── c1.pcm ~ cN.pcm        # Archivos de voz de cada segmento después del procesamiento de aceleración 1.1x (PCM 24kHz s16le)
│   └── grid.png               # Vista previa de miniaturas de todo el video generada automáticamente (2 fotogramas por escena)
└── tools/
    ├── make_payloads.py       # script.json -> Solicitudes JSON TTS de OpenRouter
    ├── tts.sh                 # Llama a OpenRouter para generar voz PCM a 24kHz por lotes
    ├── f0.py                  # Script de control de calidad de tono (mediana Hz, detecta y vuelve a muestrear segmentos con deriva de tono)
    └── prep.sh                # Acelera la voz 1.1x y renombra a c1.pcm ~ cN.pcm

Proceso de Producción Estándar en Seis Fases (SOP)

Para producir cualquier nuevo episodio, seguir estrictamente las siguientes seis fases:

Fase 1: Redacción del Guion y División de Escenas (script.json)

  • Crear un array JSON de cadenas en ep1/script.json, cada cadena corresponde a una escena independiente (Scene).
  • Se recomienda que cada segmento de narración tenga entre 30 y 80 caracteres (aproximadamente 6 a 15 segundos de lectura) para un ritmo más cómodo.
  • Utilizar signos de puntuación de ancho completo estándar (,, 。, !, ?, :, ;). El motor dividirá inteligentemente los subtítulos según los signos de puntuación.

Fase 2: Generación de Voz TTS, Control de Calidad de Tono y Optimización de Velocidad 1.1x

  1. Generar archivo de solicitud TTS:
    python3 tools/make_payloads.py ep1
    
    Nota: Las indicaciones de estilo (como "acento taiwanés auténtico", "guía juvenil vivaz") deben colocarse en el campo instructions, está terminantemente prohibido colocarlas en input o serán leídas.
  2. Solicitar voz por lotes:
    bash tools/tts.sh ep1
    
  3. Control de calidad de tono (F0 Pitch Check):
    python3 tools/f0.py tts_ep1/*.pcm
    
    • La mediana normal para la voz masculina Puck es de 120 Hz a 160 Hz.
    • Regla estricta de tono: Si se detecta que algún segmento supera los 165 Hz (lo que indica que Gemini se ha desviado a una voz femenina), se debe volver a solicitar ese segmento individualmente hasta que el tono sea normal. Ver detalles en audio-tts-pipeline.md.
  4. Aceleración y formateo de la velocidad del habla:
    bash tools/prep.sh ep1
    
    Acelera los archivos con atempo=1.1 y los envía a ep1/c1.pcm ~ ep1/cN.pcm.

Fase 3: Vinculación del Rol de Presentador y Dibujo de Características

  • El módulo de personaje debe cumplir con la interfaz de función estándar: def my_host(ctx, x, y, s, t, mouth=0.0, wave=False, point=False, sweat=False, happy=True, look=0.0):
  • Ejecutando dc.doctor = my_host en la parte inferior del módulo, se reemplaza globalmente el presentador de todas las plantillas con un solo clic.
  • Para técnicas de dibujo completas (cálculo de parpadeo, brazos de goma, apertura de boca impulsada por RMS de volumen), consultar character-design.md y character_template.py.

Fase 4: Escritura de Código de Escenas Visuales Pycairo (ep1.py)

  • Escribir la función correspondiente para cada escena: def s0(ep, ctx, u, T, m):
    • u: Segundos transcurridos dentro de esta escena.
    • T: Segundos absolutos de todo el video.
    • m: Amplitud de voz en tiempo real (0.0 ~ 1.0).
  • Usar ep.kw(sc, "palabra clave exacta") para obtener el segundo exacto en que se pronuncia esa palabra clave e impulsar la aparición de la tarjeta gráfica.
  • Para detalles de funciones clave y API de diseño, consultar engine-api.md.

Fase 5: Vista Previa Rápida de Miniaturas y Control de Calidad Visual (Preview & QA)

python3 ep1.py auto
  • El motor muestrea rápidamente 2 fotogramas por escena en 2 segundos y los combina en ep1/grid.png.
  • Puntos clave a verificar:
    1. Si el texto tiene cuadrados de tofu (falta de glifos).
    2. Si el contenido se sale de los límites del lienzo o las cadenas se superponen.
    3. Si las tarjetas inferiores invaden el área de subtítulos (no deben estar por debajo de y=610).
    4. Si las tarjetas del lado derecho chocan con el presentador permanente.

Fase 6: Renderizado Completo del Video y Verificación de Decodificación FFmpeg

  1. Renderizado formal a MP4:
    python3 ep1.py
    
    El motor sintetiza automáticamente video H.264 1280×720, comprime subtítulos, mezcla BGM (reduce automáticamente el volumen) y encapsula audio AAC.
  2. Verificación de integridad sin pérdidas:
    ffmpeg -v error -i nombre_archivo_salida.mp4 -f null -
    
    Si el terminal no muestra ningún error, significa que el audio y el video están sincronizados y el encapsulado es perfecto.

Tabla de Referencia Rápida de la API Principal

FunciónSintaxisDescripción
Cálculo de progresoprog(u, t0, d=0.5)Desde el segundo t0, cambia de 0 a 1 en d segundos
Escala con rebotepop(ctx, cx, cy, p)Aparece alrededor del centro con un rebote (curva de retroceso)
Alineación con palabra claveep.kw(sc, "texto", nth=0)Calcula con precisión el momento en que se pronuncia la palabra (ajustado 0.25 segundos antes automáticamente)
Rectángulo redondeadorrect(ctx, x, y, w, h, r)Define una ruta de rectángulo redondeado
Relleno y trazofillstroke(ctx, fill, stroke, lw=5)Rellena y traza con un color oscuro simultáneamente
Texto de una líneatext(ctx, s, x, y, size, col, align='c')Dibuja texto, opciones de alineación: izquierda 'l', centro 'c', derecha 'r'
Etiqueta cápsulachip(ctx, "etiqueta", x, y, p, col, size=30)Tarjeta gráfica de cápsula emergente
Panel emergenteif panel(ctx, x, y, w, h, p): ... ctx.restore()Panel de fondo blanco (debe ir junto con restore)
Presentador inferior derechocorner(ctx, T, m)Dibuja una versión miniaturizada del presentador permanente en la esquina inferior derecha
Tarjeta de título de capítulostation_card(ctx, u, número_estación, "nombre_estación")Tarjeta grande de título que aparece centrada al inicio del capítulo (primeros 1.9 segundos)
Cierre de resumen de puntos claveoutro_doc(ep, ctx, u, T, m, sc, título, subtítulo, rows)Confeti de flores, lista de puntos clave y escena final de avance del próximo episodio

Tres Reglas de Oro para Evitar Problemas (Crucial Guardrails)

  1. Límites de seguridad de subtítulos:
    • El área y = 648 ~ 702 en la parte inferior está dedicada exclusivamente a los subtítulos automáticos.
    • Todos los paneles de información, tarjetas de datos y bordes inferiores de botones están estrictamente prohibidos por debajo de y = 610.
  2. Prohibición de símbolos especiales y Emoji:
    • Pycairo no puede renderizar Emojis (como ✨, 📜, 🌱) ni flechas Unicode especiales (➔, ➜) con la fuente Noto Sans CJK TC, apareciendo como cuadrados de tofu.
    • Alternativas: Usar -> para flechas o llamar a la función arrow(); usar star() para estrellas; usar el símbolo alfanumérico puro × o la función mark(ctx, x, y, False, p) para tachar.
  3. Precisión de palabras clave:
    • La phrase en ep.kw(sc, phrase) debe ser una subcadena exacta del texto de ese segmento en script.json. No se permiten caracteres adicionales, faltantes ni signos de puntuación, de lo contrario provocará una interrupción del programa.

Documentación de Referencia y Recursos de Ejemplo

Skills relacionados