CK42BB/vox-explainer-skill

Pipeline de Video Explicativo Estilo Vox

Produce un video explicativo completo, narrado, subtitulado y musicalizado a partir de un solo tema. El pipeline se ejecuta en seis etapas, cada una generando artefactos que la siguiente consume. La voz en off se genera ANTES de la animación porque la duración de la voz impulsa todas las decisiones de sincronización.

TEMA → 1.Guion → 2.Voz en off → 3.Fotogramas clave → 4.Animación → 5.Música → 6.Ensamblado
         (Claude)   (xAI TTS)    (Seedream)       (Omni Flash)  (MiniMax)  (ffmpeg)

Requisitos previos

• Variable de entorno ATLASCLOUD_API_KEY configurada (consíguela en atlascloud.ai — créditos gratuitos al registrarse)
• ffmpeg y ffprobe instalados (con libass para quemar subtítulos)
• Python 3.10+ con requests
• ~$3–8 en créditos de API por cada 60 segundos de video (ver tabla de costos en references/atlas-cloud-api.md)

Antes de hacer cualquier llamada a la API, verifica las rutas de los endpoints y los IDs de modelo actuales en https://www.atlascloud.ai/docs — las APIs de modelos multimedia evolucionan rápido. Los patrones en references/atlas-cloud-api.md fueron verificados en julio de 2026.

Estructura del proyecto

Crea esta estructura para cada video y mantenla — cada etapa lee y escribe desde ella:

proyecto/
├── brief.md            # tema, enfoque, duración objetivo, audiencia
├── script.json         # beats con narración, descripciones visuales, subtítulos
├── audio/
│   ├── vo/             # beat_01.mp3 ... beat_NN.mp3
│   ├── vo_durations.json
│   └── music.mp3
├── frames/             # keyframe_01.png ... style_anchor.png
├── clips/              # clip_01.mp4 ... (clips animados sin sonido)
├── subs/               # captions.ass
└── final/              # film.mp4

Etapa 1 — Guion

Lo escribes tú mismo. Sin llamada a la API. Esta es la etapa que más determina la calidad — un gran guion con imágenes promedio supera a lo contrario.

Lee references/vox-style-guide.md (sección Escritura) antes de redactar. Reglas principales:

1. Estructura como beats. Un beat = un párrafo de narración (1–3 oraciones, 8–14 segundos hablados) + una imagen. Un video de 60 segundos tiene 6–8 beats; uno de 3 minutos tiene 16–22 beats.
2. Arco narrativo de Vox: gancho de apertura en frío (un hecho concreto sorprendente o una pregunta) → contexto ("para entender X, hay que remontarse a…") → explicación creciente con un hilo conductor claro → complicación o giro → resolución que replantea el gancho.
3. Voz: segunda persona de bienvenida ("probablemente has visto…"), tiempo presente para narrativa histórica, números concretos en lugar de abstracciones, oraciones declarativas cortas. Sin rodeos, sin "en este video veremos".
4. Una idea por beat. Si una oración introduce un segundo concepto, divide el beat.

Escribe script.json:

{
  "title": "Edad de Oro Tang",
  "topic": "Cómo la China de la Dinastía Tang construyó la ciudad más grande del mundo",
  "style_seed": "collage de papel de técnica mixta, montañas chinas a tinta lavada, paleta rojo bermellón y crema envejecida",
  "accent_color": "#C0392B",
  "beats": [
    {
      "id": 1,
      "narration": "En el siglo VII, la China Tang construyó Chang'an — la ciudad más grande y rica de la Tierra. El mundo entero llegó a sus puertas.",
      "visual": "Emperador Taizong entronizado al centro como recorte de papel, figuras cortesanas flanqueando, pagodas y montañas a tinta lavada detrás, sello rojo en la parte superior derecha que dice 盛唐",
      "caption_text": null,
      "motion": "lento acercamiento al emperador, nubes se desplazan a la izquierda, sutil paralaje entre capas de recortes"
    }
  ]
}

caption_text es para momentos de tipografía cinética en pantalla (una estadística clave o término) — la mayoría de los beats lo dejan nulo; los subtítulos de narración se manejan en el ensamblado. motion se convierte en el prompt de animación en la Etapa 4.

Etapa 2 — Voz en off (xAI TTS v1)

Genera un archivo de audio por beat, luego mide las duraciones. Estas duraciones son el reloj maestro de todo el video.

Llama al endpoint de audio de Atlas Cloud por beat (modelo: xAI TTS v1 — consulta references/atlas-cloud-api.md para la forma exacta de la solicitud y la guía de selección de voz). Elige UNA voz para todo el video. Registro Vox: mesurada, cálida, ligeramente irónica — evita voces de "tráiler de cine".

Después de la generación, analiza cada archivo y escribe audio/vo_durations.json:

ffprobe -v error -show_entries format=duration -of csv=p=0 audio/vo/beat_01.mp3

{"beats": [{"id": 1, "file": "audio/vo/beat_01.mp3", "duration": 9.83}], "total": 61.2}

Verifica que la longitud total coincida con el brief. Si un beat es demasiado largo, acorta la narración y regenera solo ese beat.

Etapa 3 — Fotogramas clave (Seedream 5.0 Pro)

Un fotograma clave por beat, todos con un estilo visual consistente. La consistencia es el problema difícil; resuélvelo con el patrón de ancla de estilo:

1. Genera el ancla. Usa bytedance/seedream-v5.0-pro/text-to-image para el beat 1 (generalmente el fotograma de título/gancho). Construye el prompt a partir del bloque de estilo en references/vox-style-guide.md (sección Gramática Visual) + el visual del beat + el style_seed y accent_color del video. Solicita 16:9, 2K.
2. Revisa el ancla antes de continuar. Regenera hasta que el estilo sea correcto — todos los demás fotogramas lo heredan.
3. Genera los fotogramas restantes con el modelo de edición. Usa bytedance/seedream-v5.0-pro/edit con el ancla como imagen de referencia (hasta 10 referencias compatibles; ancla + opcionalmente el fotograma anterior). Prompt: "Mantén exactamente el estilo artístico, la paleta, el tratamiento de collage de papel y el encuadre con borde de la referencia. Nueva escena: {beat.visual}"

Esto fija la paleta, la textura y el encuadre en todo el video, como lo haría un director de arte humano.

Cada prompt debe terminar con el sufijo de estilo (ver guía de estilo), que codifica el look Vox: recortes de papel con bordes blancos, puntos de semitono, tiras de cinta, acentos geométricos planos y audaces, márgenes generosos, un solo color de acento.

Fotogramas con caption_text establecido: instruye a Seedream para que renderice el texto en una sans-serif condensada y negrita, ya que la representación tipográfica de Seedream 5.0 Pro es sólida. Mantén menos de 5 palabras por fotograma.

Etapa 4 — Animación (Gemini Omni Flash)

Anima cada fotograma clave en un clip mediante imagen a video. Duración objetivo del clip = duración de la voz de ese beat + 0.5 s de margen (redondear al incremento compatible con el modelo).

Los prompts de movimiento para la estética de collage deben ser SUTILES — este es el modo de fallo más común. El look Vox es "gráficos en movimiento", no "metraje". Buen vocabulario de movimiento:

• lento acercamiento / alejamiento (cámara 2D, no dolly 3D)
• desplazamiento de paralaje entre capas de recortes
• nubes/humo desplazándose lateralmente
• elementos de papel deslizándose desde el borde del encuadre y asentándose
• puntos de semitono o textura brillando suavemente
• un solo elemento animándose (bandera ondeando, agua ondulándose) mientras todo lo demás se mantiene

Prohíbe explícitamente en cada prompt: "sin sacudidas de cámara, sin rotación 3D, sin transformación de rostros o texto, sin desviación de estilo, los elementos permanecen como recortes de papel planos"

Supervisa cada tarea de generación hasta completarla y descarga los archivos en clips/clip_NN.mp4. Las generaciones a veces fallan o se desvían — revisa cada clip; regenera cualquier clip donde el texto se deforme o el estilo se rompa. Presupuesta aproximadamente un 15% de regeneración.

Etapa 5 — Música (MiniMax Music 2.6)

Una pista instrumental para todo el video. Solicita is_instrumental: true — las voces compiten con la narración.

Fórmula del prompt: {ambiente} {textura cercana al género}, {tempo}, {instrumentación}, {arco}. Ejemplo para una pieza histórica: "fondo cinematográfico contemplativo, piano sentido y cuerdas suaves con pulso de percusión ligera, 90bpm, crece gradualmente de disperso a completo, estilo documental". Empareja la instrumentación con el tema (texturas de guzheng/dizi para la pieza Tang; pulso de sintetizador analógico para un tema tecnológico).

Music 2.6 genera canciones de longitud fija; si la pista es más corta que el video, repítela en el ensamblado con un crossfade; si es más larga, recórtala con fade-out. Nunca dejes que el arco musical luche contra el arco del video — un drop en medio de la pista que cae en un beat tranquilo es discordante, así que prueba el resultado contra la forma del video.

Etapa 6 — Ensamblado (ffmpeg, local)

Lee references/ffmpeg-assembly.md para las recetas completas. La secuencia:

1. Conforma cada clip a la duración de la voz de su beat (recorta o mantén el último fotograma), normaliza a 1920x1080 30fps.
2. Concatena los clips en orden.
3. Construye la pista de voz concatenando el audio de los beats con espacios de 0.5s que coincidan con la sincronización del video.
4. Genera subs/captions.ass a partir del guion — subtítulos quemados estilo Vox: sans-serif negrita, blanco con contorno negro grueso, centrado en la parte inferior, máximo 2 líneas, divide la narración en los límites de cláusulas y temporiza cada fragmento dentro de la ventana de su beat.
5. Mezcla el audio: voz al nivel completo, música atenuada de -12 a -15dB bajo la narración (compresión sidechain o una automatización de volumen simple — recetas en la referencia).
6. Quema subtítulos + atribución ("Hecho con ..." pequeño en la parte inferior derecha si se desea) y codifica: H.264, CRF 18, AAC 192k, -movflags +faststart.

Pasa el control de calidad final antes de entregar: verifica (a) desviación de sincronización entre subtítulos y voz, (b) música que domina la narración, (c) un clip cuyo movimiento se nota en bucle, (d) desviación de estilo entre fotogramas. Corrige en la etapa donde se originó el problema, no con parches en el ensamblado.

Notas de orquestación

• Ejecuta las etapas estrictamente en orden la primera vez; después, cualquier etapa se puede volver a ejecutar de forma aislada porque todo el estado reside en los archivos del proyecto.
• La generación por API es lenta (clips de video: 1–4 min cada uno). Envía todas las tareas de animación de forma concurrente, luego supervisa — no serialices.
• Guarda cada prompt que envíes en un archivo prompts.log — la reproducibilidad importa y los usuarios querrán ajustar y regenerar beats individuales.
• El costo escala linealmente con los beats. Cotiza al usuario un costo aproximado antes de la Etapa 3 (la primera etapa con pagos significativos): beats × ($0.10 imagen + ~$1.20 por clip de 10s) + ~$0.50 audio.

Referencias

• references/vox-style-guide.md — lee antes de la Etapa 1 y la Etapa 3. La gramática visual, la voz de escritura y las plantillas de prompts.
• references/atlas-cloud-api.md — lee antes de la Etapa 2. Endpoints, IDs de modelo, patrón de tareas asíncronas, código de supervisión, costos.
• references/ffmpeg-assembly.md — lee antes de la Etapa 6. Recetas de conformación, concatenación, subtítulos, atenuación y codificación.