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
- Generar archivo de solicitud TTS:
Nota: Las indicaciones de estilo (como "acento taiwanés auténtico", "guía juvenil vivaz") deben colocarse en el campopython3 tools/make_payloads.py ep1instructions, está terminantemente prohibido colocarlas eninputo serán leídas. - Solicitar voz por lotes:
bash tools/tts.sh ep1 - Control de calidad de tono (F0 Pitch Check):
python3 tools/f0.py tts_ep1/*.pcm- La mediana normal para la voz masculina
Puckes 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.
- La mediana normal para la voz masculina
- Aceleración y formateo de la velocidad del habla:
Acelera los archivos conbash tools/prep.sh ep1atempo=1.1y los envía aep1/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_hosten 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:
- Si el texto tiene cuadrados de tofu (falta de glifos).
- Si el contenido se sale de los límites del lienzo o las cadenas se superponen.
- Si las tarjetas inferiores invaden el área de subtítulos (no deben estar por debajo de y=610).
- Si las tarjetas del lado derecho chocan con el presentador permanente.
Fase 6: Renderizado Completo del Video y Verificación de Decodificación FFmpeg
- Renderizado formal a MP4:
El motor sintetiza automáticamente video H.264 1280×720, comprime subtítulos, mezcla BGM (reduce automáticamente el volumen) y encapsula audio AAC.python3 ep1.py - Verificación de integridad sin pérdidas:
Si el terminal no muestra ningún error, significa que el audio y el video están sincronizados y el encapsulado es perfecto.ffmpeg -v error -i nombre_archivo_salida.mp4 -f null -
Tabla de Referencia Rápida de la API Principal
| Función | Sintaxis | Descripción |
|---|---|---|
| Cálculo de progreso | prog(u, t0, d=0.5) | Desde el segundo t0, cambia de 0 a 1 en d segundos |
| Escala con rebote | pop(ctx, cx, cy, p) | Aparece alrededor del centro con un rebote (curva de retroceso) |
| Alineación con palabra clave | ep.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 redondeado | rrect(ctx, x, y, w, h, r) | Define una ruta de rectángulo redondeado |
| Relleno y trazo | fillstroke(ctx, fill, stroke, lw=5) | Rellena y traza con un color oscuro simultáneamente |
| Texto de una línea | text(ctx, s, x, y, size, col, align='c') | Dibuja texto, opciones de alineación: izquierda 'l', centro 'c', derecha 'r' |
| Etiqueta cápsula | chip(ctx, "etiqueta", x, y, p, col, size=30) | Tarjeta gráfica de cápsula emergente |
| Panel emergente | if panel(ctx, x, y, w, h, p): ... ctx.restore() | Panel de fondo blanco (debe ir junto con restore) |
| Presentador inferior derecho | corner(ctx, T, m) | Dibuja una versión miniaturizada del presentador permanente en la esquina inferior derecha |
| Tarjeta de título de capítulo | station_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 clave | outro_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)
- Límites de seguridad de subtítulos:
- El área
y = 648 ~ 702en 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.
- El área
- 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ónarrow(); usarstar()para estrellas; usar el símbolo alfanumérico puro×o la funciónmark(ctx, x, y, False, p)para tachar.
- Pycairo no puede renderizar Emojis (como ✨, 📜, 🌱) ni flechas Unicode especiales (➔, ➜) con la fuente
- Precisión de palabras clave:
- La
phraseenep.kw(sc, phrase)debe ser una subcadena exacta del texto de ese segmento enscript.json. No se permiten caracteres adicionales, faltantes ni signos de puntuación, de lo contrario provocará una interrupción del programa.
- La
Documentación de Referencia y Recursos de Ejemplo
- Arquitectura del motor y todos los componentes geométricos integrados: references/engine-api.md
- Implementación de diseño de personajes vectoriales, respiración, parpadeo y sincronización de labios: references/character-design.md
- Especificaciones de solicitud TTS, algoritmo de tono F0 y procesamiento de audio: references/audio-tts-pipeline.md
- Zona segura del lienzo, prevención de falta de glifos y lista de problemas: references/layout-and-pitfalls.md
- Código de plantilla de personaje: examples/character_template.py
- Plantilla mínima de episodio completo: examples/minimal_episode.py