srt-whiteboard-animation

# Skill de animación de pizarra con SRT Skill para convertir subtítulos SRT en videos de pizarra dibujados a mano según el orden narrativo. Combina **organización de máscaras por zonas** con **dibujo de trazos en flujo continuo**: cada elemento aparece siguiendo los subtítulos, la punta del lápiz traza de forma continua dentro de la zona, luego se agrega color gradualmente y finalmente se exporta a MP4. Es adecuado para convertir explicaciones de conocimiento, narraciones orales, subtítulos de cursos o guiones de videos cortos en animaciones dibujadas a mano sobre fondo de papel beige cálido. ## Ejemplo de efecto **Escena: La montaña de los monos y el robo de plátanos** — Siguiendo el orden narrativo de los subtítulos, se dibujan sucesivamente la montaña artificial y el monito, el mono grande que roba el plátano y los niños que observan alrededor.  Boceto original: [ver PNG](examples/scene-01-monkey-mountain.png). ## Capacidades principales - Analiza subtítulos SRT y divide escenas según la duración sugerida de 25–35 segundos - Primero genera el guion gráfico y la estrategia de ilustración, asegurando que cada escena exprese solo una idea central - Establece un orden de dibujo semántico para los elementos según los eventos de subtítulos, no según las coordenadas de la imagen - Usa `annotation.json` para gestionar zonas, tiempos, asociación con subtítulos y áreas protegidas contra superposición - Cada zona adopta trazos continuos en flujo: primero `ink` para el boceto lineal, luego `color` para añadir color - Admite una mesa de previsualización en el navegador para ajustar zonas, orden, tiempo y asociación con subtítulos - Admite renderizado por escenas y combinación de múltiples escenas, generando un MP4 completo ## Modo de trabajo La clave de este Skill es "impulsado por subtítulos, confirmación paso a paso". Después de completar cada paso se espera la confirmación, para evitar desperdiciar costos de renderizado cuando el guion gráfico, el boceto o las anotaciones aún no están finalizados: 1. Analiza el SRT y genera el guion gráfico y la estrategia de ilustración. 2. Tras la confirmación, genera bocetos lineales con estilo unificado. 3. Tras confirmar el boceto, crea anotaciones combinando subtítulos e imagen original, y cárgalas en la mesa de previsualización. 4. Tras confirmar las anotaciones, genera la imagen de verificación de zonas y direcciones. 5. En la mesa de previsualización ajusta zonas, orden narrativo, tiempos y asociación con subtítulos, y guarda. 6. Tras confirmar las anotaciones finales, renderiza MP4 escena por escena. 7. Los proyectos de múltiples escenas se combinan después de confirmar el resultado de cada escena. ## Especificaciones visuales - Fondo de papel beige cálido: se recomienda `#F5EBD7` - Líneas de boceto en gris oscuro; rojo, naranja y azul solo como pequeños acentos conceptuales - Dibujo a mano minimalista, fondo limpio y suficiente espacio en blanco - No usar texto en escena, etiquetas, aspecto fotográfico, efectos 3D ni texturas complejas ## Instalación y entorno El Skill incluye un script independiente de preparación de entorno virtual de Python. En la primera ejecución: ```bash python scripts/prepare_env.py --check python scripts/prepare_env.py ``` Si tiene éxito, el primer comando mostrará `ENV_PY=<ruta>`; para renderizados posteriores use ese intérprete para garantizar el aislamiento de dependencias. ## Estructura de materiales del proyecto ```text assets/whiteboard/<nombre-del-proyecto>/ ├── scene-01-<nombre>.png ├── scene-01-<nombre>.annotation.json ├── scene-01-<nombre>-whiteboard.mp4 └── scene-01-<nombre>-preview.mp4 ``` La imagen y la anotación deben tener el mismo nombre, por ejemplo `scene-01-demo.png` corresponde a `scene-01-demo.annotation.json`. ## Formato de anotación Cada elemento usa coordenadas de píxeles enteros de la imagen original y se asocia con eventos de subtítulos mediante `sequence`, `subtitle` y `narrativeRole`. Las zonas deben ordenarse según "preparación de la escena → personajes/objetos clave → acción o cambio → reacción/resultado". ```json { "sceneId": "scene-01", "canvas": { "width": 1672, "height": 941 }, "storyBasis": "El monito está en la montaña de los monos con un plátano, el mono grande le quita el plátano y los niños observan al lado.", "sceneDurationMs": 9000, "elements": [ { "id": "rockery", "label": "Escena de la montaña de los monos", "sequence": 1, "narrativeRole": "Preparación de la escena de la historia", "subtitle": "El monito está sentado en la cima de la montaña de los monos, con un plátano en la mano.", "type": "structure", "region": { "x": 20, "y": 120, "width": 540, "height": 780 }, "reveal": { "direction": "top_to_bottom", "startMs": 300, "durationMs": 2600, "maskPaddingPx": 22, "protectedRegions": [] }, "handPath": { "start": [290, 130], "end": [290, 890], "easing": "easeInOut" } } ] } ``` `direction` y `handPath` se usan para el proxy rectangular en la mesa de previsualización; el trazo real del video final es generado automáticamente por el renderizador de flujo. Para objetos que se superponen, marque en `protectedRegions` del elemento anterior las zonas que deben mostrarse más tarde, para evitar que el contenido posterior aparezca antes de tiempo. ## Comandos comunes Analizar subtítulos y generar guion gráfico sugerido: ```bash python scripts/parse_srt.py <subtitulos.srt> --target-sec 30 --min-sec 25 --max-sec 35 ``` Generar imagen de verificación de zonas: ```bash python scripts/render_annotation_preview.py <ruta-de-imagen> <ruta-de-anotacion> <ruta-de-salida-de-vista-previa> ``` Abra `assets/preview.html`, use "Abrir carpeta" para cargar el directorio de la escena y podrá editar zonas, orden, tiempo y asociación con subtítulos. Renderizar una escena: ```bash <ENV_PY> scripts/render_stream_whiteboard.py <ruta-de-imagen> <ruta-de-anotacion> <salida.mp4> assets/drawing-hand.png \ --ink-path grid --color-fill contour-wipe ``` Combinar múltiples escenas: ```bash <ENV_PY> scripts/merge_scenes.py --inputs escena1.mp4 escena2.mp4 escena3.mp4 --output final.mp4 ``` ## Control de calidad - El primer fotograma es un fondo limpio de papel beige cálido, sin líneas que aparezcan antes de tiempo - `canvas` coincide con el tamaño de la imagen original, y todas las zonas son coordenadas de píxeles enteros dentro del lienzo - `sequence`, `startMs` y el orden narrativo de los subtítulos son coherentes - En los fotogramas intermedios, las zonas no iniciadas y las áreas protegidas no aparecen antes de tiempo - La punta del lápiz se mantiene cerca del trazo fluido actual; cuando el boceto lineal es claro se puede elegir `--ink-path skeleton` - Después de terminar cada escena, mantener al menos 0.5 segundos de imagen completa; el orden de combinación de múltiples escenas coincide con el guion gráfico de subtítulos ## Contenido del repositorio ```text srt-whiteboard-animation/ ├── SKILL.md # Flujo de trabajo completo y restricciones ├── assets/ │ ├── drawing-hand.png # Material de mano │ ├── preview.html # Mesa de previsualización y edición local ├── examples/ # Materiales de ejemplo del README ├── scripts/ │ ├── parse_srt.py # Análisis de subtítulos y sugerencia de guion gráfico │ ├── render_annotation_preview.py # Imagen de verificación de anotaciones │ ├── render_stream_whiteboard.py # Renderizador de MP4 con trazos en flujo │ ├── merge_scenes.py # Combinación de múltiples escenas │ └── prepare_env.py # Preparación del entorno de dependencias └── agents/openai.yaml # Metadatos de Codex ``` ## Contribuciones Se aceptan Issues o Pull Requests. Cualquier cambio relacionado con la lógica de dibujo debe usar subtítulos, anotaciones y videos finales reales para verificar la protección de máscaras, los tiempos y la imagen final. ## Licencia Este proyecto es de código abierto bajo la licencia MIT. Consulte [LICENSE](LICENSE). ## Sobre el autor Un veterano aficionado a criar peces / AI Builder / construye una empresa unipersonal con un equipo de IA. Douyin, Bilibili, cuenta oficial: 江哥是老登啊