Recomendado: Cargar las mejores prácticas de Remotion
Este skill se beneficia de
remotion-best-practices(no incluido) para la biblioteca completa de patrones de Remotion. Es opcional: las reglas mínimas están a continuación si no está presente.
- Pi: lee el skill cargado en
remotion-best-practices(listado en skills disponibles).- Claude Code: invoca el skill/herramienta
remotion-best-practicesantes de continuar.¿No está instalado? Consíguelo en remotion-dev/skills (docs: remotion.dev/docs/ai/skills).
Si
remotion-best-practicesno está instalado, las reglas mínimas son: chromium debe estar disponible, envolver siempre el contenido 4K en<Scale4K>, usar<TransitionSeries>conlinearTiming, y tratar el audio como el reloj maestro.
Creador de Podcast en Video
Pipeline automatizado para videos de conocimiento horizontales en 4K para Bilibili a partir de un tema. Agente de codificación + backend TTS + Remotion + FFmpeg.
Contenido
- Arranque — requisitos previos (ejecutar antes del Paso 1)
- Modos de ejecución — Automático vs Interactivo → references/workflow-script.md
- Regenerar un video existente — iterar sobre un video terminado
- Flujo de trabajo — el pipeline de 11 pasos + indicadores de fase + paradas obligatorias
- Reglas estrictas — restricciones de producción no negociables
- Reloj maestro de audio y sincronización
- Estructura por video
- Recursos adicionales — cuándo cargar cada archivo de
references/ - Preferencias del usuario
- Solución de problemas
Arranque
Resuelve SKILL_DIR al directorio que contiene este SKILL.md:
- Pi: el agente conoce la ruta del skill desde la lista de skills cargados; establece
SKILL_DIRa ese directorio antes de ejecutar comandos. - Claude Code:
${CLAUDE_SKILL_DIR}se completa automáticamente.
SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"
# Prerrequisitos (CLIs + variables de entorno del backend)
python3 "${SKILL_DIR}/scripts/check_prereqs.py"
Las actualizaciones fluyen a través de la CLI de skills (npx skills update video-podcast-maker -g); las instalaciones directas con git clone usan git pull según el README. Este skill no realiza comprobaciones de actualización.
Fallos de prerrequisitos — consulta README.md para la configuración. La comprobación reconoce el backend (resuelve TTS_BACKEND env → user_prefs.json global.tts.backend → edge por defecto), por lo que solo se validan las variables de entorno requeridas por el backend activo.
¿Primer video en un nuevo proyecto? Es preferible reutilizar un proyecto Remotion existente con node_modules/ ya instalado; crear un proyecto nuevo descarga ~2.2 GB de paquetes npm más un shell headless de Chrome de 90 MB (una vez por proyecto). Si el usuario tiene un proyecto de un video anterior, úsalo. Si es necesario un proyecto nuevo, ejecuta npm install en segundo plano mientras realizas los Pasos 1-4 (investigación del tema y escritura del guion).
Todo el renderizado va a videos/{name}/ — cada output.mp4, final_video.mp4 y thumbnail_*.png se coloca directamente en el directorio del video. Nunca renderices a un directorio out/ o dist/; la convención --public-dir videos/{name}/ mantiene todo autocontenido.
Motor TTS — dos backends locales, sin skill externo:
edge(por defecto) — gratuito, sin clave, mediante edge-tts.azure— necesitaAZURE_SPEECH_KEY+AZURE_SPEECH_REGION(Microsoft Speech SDK).
Cada uno sintetiza internamente (scripts/tts/backends/native.py) — la pronunciación (mostrar → hablar → volver a mostrar para subtítulos) y la aplicación de fonemas están integradas. check_prereqs.py valida las variables de entorno del backend activo.
¿TTS multiplataforma? El antiguo skill componente ttscn que proporcionaba la matriz de 9 backends ya no es una dependencia de este skill. Si deseas esas plataformas, instala Agents365-ai/ttsCN por separado y llámalo directamente; este skill solo incluye edge + azure.
Atajo de aprendizaje de diseño: Si el usuario proporciona un video/imagen de referencia o pide guardar/listar/eliminar perfiles de estilo, consulta references/design-learning.md en lugar de ejecutar el flujo de trabajo a continuación.
Modos de ejecución
Detecta el Modo Automático (por defecto) vs el Modo Interactivo al inicio del flujo de trabajo; la tabla de decisión del modo Automático por defecto y las anulaciones por solicitud están en references/workflow-script.md.
Regenerar un video existente
Si videos/{name}/ ya existe y el usuario está iterando sobre un video terminado o en proceso, reutiliza ese directorio. NO inicies un nuevo proyecto ni un nuevo videos/{newname}/.
Elige la reejecución más pequeña para lo que realmente cambió:
| Cambió | Re-ejecutar | Reutiliza (no rehagas) |
|---|---|---|
Guion de narración (podcast.txt) | Paso 7 (TTS) → vista previa Paso 8 → renderizar + mezclar | investigación del tema + diseño de secciones |
| Solo visuales (componentes, diseño, colores) | Vista previa Paso 8 → renderizar + mezclar | audio (podcast_audio.wav / timing.json) |
| Solo música de fondo | Re-mezclar BGM | output.mp4 (sin rerenderizar) |
| Solo subtítulos | Paso 10.1 finalizar | output.mp4 / video_with_bgm.mp4 |
Cualquier re-ejecución que cambie lo que el espectador ve u oye vuelve a entrar en la puerta del Paso 8: aplica el cambio, deja que Studio recargue en caliente, y espera una nueva confirmación explícita de "renderizar 4K" — la confirmación anterior no se transfiere. Un cambio de guion desplaza cada sello de tiempo posterior, así que siempre regenera timing.json a través de TTS — nunca lo edites a mano. Después de cualquier re-ejecución, vuelve a verificar:
python3 ${SKILL_DIR}/scripts/verify_output.py videos/{name}/
Flujo de trabajo
¿Iterando sobre un video terminado? Si
videos/{name}/ya existe, consulta Regenerar un video existente arriba para la re-ejecución mínima — NO empieces en el Paso 1.
Al inicio del Paso 1, crea una tarea por paso en el rastreador de tu agente. Marca in_progress al comenzar, completed al finalizar. Los archivos en videos/{name}/ son el registro duradero — si se interrumpe, inspecciona el directorio para determinar dónde reanudar.
| # | Paso | Salida | Archivo de fase |
|---|---|---|---|
| 1 | Definir dirección del tema | topic_definition.md | workflow-script.md |
| 2 | Investigar el tema | topic_research.md | workflow-script.md |
| 3 | Diseñar 5-7 secciones | (en memoria) | workflow-script.md |
| 4 | Escribir guion de narración | podcast.txt | workflow-script.md |
| 4.5 | Verificación previa de pronunciación (zh-CN) | phonemes.json | workflow-script.md |
| 5 | Plan de activos y resolución | assets/manifest.json | workflow-assets.md |
| 6 | Generar miniaturas (16:9 + 4:3) | thumbnail_*.png | workflow-production.md |
| 7 | Generar audio TTS | podcast_audio.wav, timing.json | workflow-production.md |
| 8 | Composición Remotion + vista previa Studio | — | workflow-production.md |
| 9 | Renderizar 4K + mezclar BGM | output.mp4, video_with_bgm.mp4 | workflow-production.md |
| 10 | Información de publicación + verificar salida | publish_info.md, final_video.mp4 | workflow-publish.md |
| 11 | Generar cortos verticales (opcional) | shorts/ | workflow-publish.md |
Paradas obligatorias (filas en negrita arriba):
- Paso 8 — Revisión Studio. DEBE iniciar
npx remotion studioy esperar la retroalimentación del usuario antes de renderizar. NUNCA renderices 4K hasta que el usuario confirme explícitamente ("renderizar 4K" / "renderizar final"). Una respuesta que contenga solicitudes de ajuste no es confirmación — aplica los cambios, deja que Studio recargue en caliente y vuelve a preguntar. Cada ronda de ajustes necesita su propia confirmación nueva antes del Paso 9. - Paso 10 —
verify_output.py. DEBE pasar antes de declarar el video como terminado. Salida 0 = verde; salida 2 = advertencias aún publicables. Corrige automáticamente omisiones comunes (creafinal_video.mp4si falta). Valida la información de publicación (título, descripción, etiquetas, capítulos) contra la matriz de plataformas — genérala en los Pasos 5.5 y 10.2. Para salida legible por máquina añade--format json.
Auditoría previa al renderizado (recomendada) — antes del Paso 8:
python3 ${SKILL_DIR}/scripts/audit_beat_sync.py <Video.tsx> <timing.json>
Señala los beats que se desvían > 1.5s de la narración.
Modo Automático: auto-revisión visual. Cuando se ejecuta en Modo Automático (sin usuario viendo Studio), renderiza 3-5 fotogramas clave antes de pedir confirmación de renderizado:
npx remotion still src/remotion/index.ts <CompositionId> videos/{name}/_review_001.png --public-dir videos/{name}/ --frame=<midpoint_frame>
Elige fotogramas en: título principal (~10% de avance), un punto medio de una sección densa y el final. Lee las imágenes fijas como imágenes y ejecuta las listas de verificación de design-guide.md y visual-taste.md contra la salida renderizada real. Detecta desbordamiento, contraste y regresiones de diseño antes del renderizado 4K. Elimina _review_*.png después de la revisión.
Puntos de control de validación
| Después del Paso | Verificación |
|---|---|
| 7 (TTS) | podcast_audio.wav se reproduce · timing.json cubre todas las secciones · SRT es UTF-8 |
| 9 (Renderizado) | output.mp4 es 3840×2160 · sincronización audio-video · sin fotogramas negros |
| 10 (Verificar) | verify_output.py sale 0 (o 2 con advertencias revisadas) |
Reglas estrictas
| Regla | Requisito |
|---|---|
| Proyecto único | Todos los videos bajo videos/{name}/ en el proyecto Remotion del usuario. NUNCA crees un nuevo proyecto por video. |
| Salida 4K | 3840×2160 (o 2160×3840 vertical), usa el envoltorio scale(2) sobre el espacio de diseño de 1920×1080 |
| Sincronización de audio | El audio (podcast_audio.wav + podcast_audio.srt) es el reloj maestro. timing.json DEBE generarse a partir de la salida TTS real, nunca estimada manualmente. Antes de renderizar, la duración del video final debe coincidir con el audio dentro de ±0.5s. Consulta Reloj maestro de audio y sincronización. |
| Miniatura | DEBE generar tanto 16:9 (1920×1080) como 4:3 (1200×900) — consulta design-guide.md |
| Studio antes de renderizar | DEBE iniciar remotion studio para revisión. NUNCA renderices 4K hasta que el usuario confirme explícitamente. La retroalimentación de ajuste ≠ confirmación — aplica, recarga en caliente, vuelve a preguntar. |
--public-dir | Cada comando de Remotion usa --public-dir videos/{name}/. Todos los archivos de salida (output.mp4, final_video.mp4, miniaturas) van directamente a videos/{name}/ — nunca a un directorio out/ o dist/. |
Los mínimos visuales (tamaños de texto, ancho de contenido, zonas seguras, seguridad de animación) están en references/design-guide.md. DEBE cargarse antes del Paso 8.
Reloj maestro de audio y sincronización
Reglas de oro
- El audio es el reloj maestro. Cada inicio de diapositiva, subtítulo, capítulo y beat de animación se deriva de
podcast_audio.wavypodcast_audio.srt. - Genera la sincronización desde TTS, no desde estimaciones de texto. Pipeline:
podcast.txt→generate_tts.py→podcast_audio.wav+podcast_audio.srt+timing.json→ composición → renderizado. - Nunca escribas
timing.jsona mano antes de que exista el audio. Si ya tienes diapositivas seleccionadas, ejecutaalign_timing_from_srt.pypara anclarlas al SRT real. - Compensar la superposición de TransitionSeries.
TransitionSeriesrenderizasum(section.duration_frames) - (N-1) * transitionFramesfotogramas. Escala cada sección proporcionalmente para mantener la longitud renderizada igual atiming.total_frames. No metas todos los fotogramas de superposición en la primera sección. El patrón corregido está entemplates/Video.tsx.
Puntos de control de sincronización obligatorios
| Cuándo | Verificación |
|---|---|
| Después del Paso 7 (TTS) | timing.json.total_duration coincide con podcast_audio.wav dentro de ±0.5s |
| Antes del renderizado | Video.tsx escala todas las secciones para la superposición de transición |
| Después del renderizado | La duración de final_video.mp4 coincide con podcast_audio.wav dentro de ±0.5s |
| Paso 10 (verificar) | verify_output.py sale 0 e informa verde en audio/sincronización |
Si algún punto de control falla, detente. No publiques.
Especificaciones de salida
| Parámetro | Horizontal (16:9) | Vertical (9:16) |
|---|---|---|
| Resolución | 3840×2160 (4K) | 2160×3840 (4K) |
| Fotogramas por segundo | 30 fps | 30 fps |
| Codificación | H.264, 16Mbps | H.264, 16Mbps |
| Audio | AAC, 192kbps | AAC, 192kbps |
| Duración | 1-15 min | 60-90s (destacado) |
Estructura por video
raíz-del-proyecto/ # Raíz del proyecto Remotion
├── src/remotion/ # Código fuente de Remotion (Root.tsx, composiciones, index.ts)
├── videos/{nombre-del-video}/ # Directorio por video
│ ├── topic_definition.md # Paso 1
│ ├── topic_research.md # Paso 2
│ ├── podcast.txt # Paso 4: guion de narración
│ ├── phonemes.json # Paso 4.5: anulaciones de pronunciación zh-CN
│ ├── assets/manifest.json # Paso 5: registro de activos por sección
│ ├── publish_info.md # Paso 10: título/descripción/etiquetas
│ ├── podcast_audio.wav # Paso 7: audio TTS
│ ├── podcast_audio.srt # Paso 7: subtítulos
│ ├── timing.json # Paso 7: línea de tiempo (controla animaciones)
│ ├── thumbnail_*.png # Paso 6
│ ├── output.mp4 # Paso 9: renderizado 4K
│ ├── video_with_bgm.mp4 # Paso 9: con BGM
│ ├── final_video.mp4 # Paso 10: salida final
│ └── bgm.mp3 # Música de fondo
└── remotion.config.ts
--public-dir por video
Cada comando de Remotion usa --public-dir videos/{name}/ — los activos de cada video permanecen en su propio directorio, permitiendo renderizados paralelos:
npx remotion studio src/remotion/index.ts --public-dir videos/{name}/
npx remotion render ... videos/{name}/output.mp4 --public-dir videos/{name}/ --video-bitrate 16000000
Recursos adicionales
| Archivo | Cuándo cargar |
|---|---|
| references/workflow-script.md | Pasos 1-4: definición del tema → guion (guía de modo + directrices de estilo de escritura) |
| references/workflow-assets.md | Paso 5: plan de activos visuales y manifiesto |
| references/workflow-production.md | Pasos 6-9: miniaturas, TTS, composición, renderizado |
| references/workflow-publish.md | Pasos 10-11: información de publicación, verificación, cortos |
| references/design-guide.md | Antes de la composición Remotion (Paso 8): diseño visual, tipografía, animaciones, zonas seguras |
| references/design-learning.md | Cuando el usuario proporciona un video/imagen de referencia o pide guardar/listar/eliminar perfiles de estilo — anula todo el flujo de trabajo de 11 pasos |
| references/visual-taste.md | Paso 8 (revisión): lista de verificación de auto-revisión visual de Modo Automático |
| references/style-guide-examples.md | Opcional: ejemplos de estética visual en los que inspirarse |
Preferencias del usuario
Leer en user_prefs.json:
{
"global": {
"tts": {
"backend": "edge",
"voice": "zh-CN-XiaoxiaoNeural",
"rate": 0.0
},
"layout": {
"style": "modern-minimal",
"font_family": "Noto Sans SC",
"primary_accent": "#1a73e8",
"bg_pattern": "gradient-mesh"
},
"bgm": {
"track_id": "tech-calm",
"volume": -14.0
},
"platforms": ["bilibili", "youtube"]
}
}
Los valores se pueden pasar por video como --pref key=value. Los cambios en user_prefs.json se aplican al siguiente video, no retroactivamente.
Solución de problemas
| Síntoma | Causa probable | Solución |
|---|---|---|
| El renderizado 4K falla o tiene fotogramas negros | Dependencia de Chromium faltante o --public-dir incorrecto | Verifica que chromium esté disponible (npx remotion puppeteer check) y que --public-dir videos/{name}/ esté presente en todos los comandos de Remotion |
timing.json.total_duration no coincide con el audio | Edición manual de sincronización sin regeración de TTS | Elimina timing.json, ejecuta generate_tts.py de nuevo para regenerar desde el audio real. Nunca edites timing.json a mano después de que exista el audio. |
| La duración del video final no coincide con el audio después del renderizado | Desajuste de superposición de TransitionSeries no corregido | Verifica que Video.tsx escale proporcionalmente todas las secciones para (N-1) * transitionFrames. Ejecuta audit_beat_sync.py para diagnosticar. |
verify_output.py sale con 2 (advertencia) | final_video.mp4 faltante o campos de metadatos | Ejecuta de nuevo el script: corrige automáticamente final_video.mp4 si output.mp4 existe. Completa cualquier campo de publish_info.md que falte. |
| El TTS falla con "no backend activo" | Faltan las variables de entorno AZURE_SPEECH_KEY + AZURE_SPEECH_REGION para azure, o edge-tts no está instalado | python3 scripts/check_prereqs.py diagnostica la configuración. Para edge, pip install edge-tts. Para azure, configura las variables de entorno. |
| "Permiso denegado" en scripts | El script no es ejecutable | chmod +x scripts/*.py o ejecuta con python3 scripts/... |
| Los subtítulos SRT no se muestran correctamente | Codificación de caracteres | Verifica UTF-8: file -I podcast_audio.srt debería mostrar charset=utf-8. Reconvierte con iconv -f UTF-8 -t UTF-8 podcast_audio.srt si es necesario. |
| El audio se desincroniza con el video | Velocidad de fotogramas incorrecta en la composición de Remotion | Verifica que el compositor use 30 fps o que las duraciones de timing.json estén en segundos, no en fotogramas. Reconcilia con el SRT. |