atharhive/vox-explainer

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 produce artefactos que la siguiente etapa consume. La locución se genera ANTES de la animación porque la duración de la VO determina todas las decisiones de sincronización.

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

Prerrequisitos

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

Antes de realizar cualquier llamada a la API, verifica las rutas de endpoint actuales y los IDs de modelo en https://www.atlascloud.ai/docs — las APIs de modelos multimedia evolucionan rápidamente. Los patrones en references/atlas-cloud-api.md se verificaron en Julio 2026.

Estructura del proyecto

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

proyecto/
├── brief.md            # tema, ángulo, duración objetivo, audiencia
├── script.json         # beats con narración, descripciones de plano, 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/               # subtitulos.ass
└── final/              # video.mp4

Etapa 1 — Guion

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

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

1. Estructura en beats. Un beat = un párrafo de narración (1–3 oraciones, 8–14 segundos hablados) + un visual. Un video de 60 segundos tiene 6–8 beats; 3 minutos tiene 16–22 beats.
2. Arco narrativo Vox: gancho de apertura en frío (un hecho sorprendente concreto o una pregunta) → contexto ("para entender X, hay que remontarse a...") → explicación ascendente con un hilo conductor claro → complicación o giro → resolución que replantea el gancho.
3. Voz: segunda persona acogedora ("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 vamos a".
4. Una idea por beat. Si una oración introduce un segundo concepto, divide el beat.

Escribe script.json:

{
  "title": "La 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 mixto, montañas chinas con tinta y lavado, 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 de tinta y lavado al fondo, sello rojo en la esquina superior derecha que dice 盛唐",
      "caption_text": null,
      "motion": "acercamiento lento al emperador, nubes se desplazan a la izquierda, paralaje sutil entre capas de recortes"
    }
  ]
}

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

Etapa 2 — Locución (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 orientación sobre selección de voz). Elige UNA voz para todo el video. Registro Vox: mesurado, cálido, ligeramente irónico — evita voces de "tráiler de película".

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 sea coherente con el brief. Si un beat se alarga, aprieta la narración y regenera solo ese beat.

Etapa 3 — Fotogramas clave (Seedream 5.0 Pro)

Un fotograma clave por beat, todos en 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 del 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 marco del 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 (consulta la guía de estilo), que codifica el aspecto 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 configurado: indica a Seedream que renderice el texto en una sans condensada y negrita, ya que la representación tipográfica de Seedream 5.0 Pro es sólida. Mantenlo por debajo de 5 palabras por fotograma.

Etapa 4 — Animación (Gemini Omni Flash)

Anima cada fotograma clave en un clip mediante imagen a video. La duración objetivo del clip = duración de la VO de ese beat + 0.5s de margen (redondea a los incrementos compatibles del 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 aspecto Vox es "gráficos en movimiento", no "metraje". Buen vocabulario de movimiento:

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

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

Monitorea cada tarea de generación hasta su finalización y descárgala a clips/clip_NN.mp4. Las generaciones fallan o se desvían a veces — revisa cada clip; regenera aquellos donde el texto se deforme o el estilo se rompa. Presupuesta ~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: {estado de ánimo} {textura de género adyacente}, {tempo}, {instrumentación}, {arco}. Ejemplo para una pieza histórica: "subrayado cinematográfico contemplativo, piano con fieltro y cuerdas suaves con pulso ligero de percusión, 90bpm, construye gradualmente de escaso a completo, estilo documental". Adapta la instrumentación al 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, haz un bucle en el ensamblaje con un crossfade; si es más larga, recorta con fade-out. Nunca permitas que el arco de la música compita con el arco del video — una caída a mitad de pista que aterriza en un beat tranquilo es discordante, así que prueba el resultado contra la forma del video.

Etapa 6 — Ensamblaje (ffmpeg, local)

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

1. Conforma cada clip a la duración de la VO 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 VO concatenando el audio de los beats con espacios de 0.5s que coincidan con la sincronización del video.
4. Genera subs/subtitulos.ass a partir del guion — subtítulos quemados estilo Vox: sans negrita, blanco con contorno negro intenso, centrado en la parte inferior, máximo 2 líneas, divide la narración en los límites de las cláusulas y cronometra cada fragmento dentro de la ventana de su beat.
5. Mezcla el audio: VO al nivel completo, música atenuada -12 a -15dB bajo la narración (compresión sidechain o una automatización de volumen simple — recetas en la referencia).
6. Quemar subtítulos + atribución ("Hecho con..." pequeño abajo a la 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 en la sincronización subtítulos/VO, (b) música que domina la narración, (c) un clip cuyo movimiento se note que es un bucle, (d) desviación de estilo entre fotogramas. Arregla en la etapa donde se originó el problema, no con trucos de ensamblaje.

Notas de orquestación

• Ejecuta las etapas estrictamente en orden la primera vez; después, cualquier etapa puede reejecutarse de forma aislada porque todo el estado vive 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 consulta — no serialices.
• Guarda cada prompt que envíes en un archivo prompts.log — la reproducibilidad es importante 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 costos 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 prompt.
• references/atlas-cloud-api.md — lee antes de la Etapa 2. Endpoints, IDs de modelo, patrón de tareas asíncronas, código de consulta, costos.
• references/ffmpeg-assembly.md — lee antes de la Etapa 6. Recetas para conformar, concatenar, subtitular, atenuar y codificar.