atharhive/vox-explainer

Pipeline de Vidéo Explicative de Style Vox

Produisez une vidéo explicative complète, narrée, sous-titrée et avec musique à partir d'un seul sujet. Le pipeline s'exécute en six étapes, chacune produisant des artefacts consommés par l'étape suivante. La voix off est générée AVANT l'animation car sa durée détermine toutes les décisions de chronométrage.

SUJET → 1.Script → 2.Voix off → 3.Images clés → 4.Animation → 5.Musique → 6.Assemblage
         (Claude)   (xAI TTS)    (Seedream)    (Omni Flash)  (MiniMax)  (ffmpeg)

Prérequis

• Variable d'environnement ATLASCLOUD_API_KEY définie (obtenez-en une sur atlascloud.ai — crédits gratuits à l'inscription)
• ffmpeg et ffprobe installés (avec libass pour le brûlage de sous-titres)
• Python 3.10+ avec requests
• ~3–8 $ de crédit API par film de 60 secondes (voir le tableau des coûts dans references/atlas-cloud-api.md)

Avant tout appel API, vérifiez les chemins d'endpoint et les ID de modèle actuels sur https://www.atlascloud.ai/docs — les API des modèles média évoluent rapidement. Les modèles dans references/atlas-cloud-api.md ont été vérifiés en juillet 2026.

Structure du projet

Créez cette arborescence pour chaque film et conservez-la — chaque étape la lit et y écrit :

projet/
├── brief.md            # sujet, angle, durée cible, public
├── script.json         # beats avec narration, descriptions de plan, légendes
├── audio/
│   ├── vo/             # beat_01.mp3 ... beat_NN.mp3
│   ├── vo_durations.json
│   └── musique.mp3
├── frames/             # keyframe_01.png ... style_anchor.png
├── clips/              # clip_01.mp4 ... (clips animés silencieux)
├── subs/               # sous-titres.ass
└── final/              # film.mp4

Étape 1 — Script

Vous rédigez vous-même. Pas d'appel API. C'est l'étape qui détermine le plus la qualité — un excellent script avec des visuels moyens bat le contraire.

Lisez references/vox-style-guide.md (section Écriture) avant de rédiger. Règles essentielles :

1. Structurez en beats. Un beat = un paragraphe de narration (1 à 3 phrases, 8 à 14 secondes parlées) + un visuel. Un film de 60 secondes fait 6 à 8 beats ; 3 minutes en font 16 à 22.
2. Arc narratif Vox : accroche d'ouverture à froid (un fait surprenant concret ou une question) → contexte (« pour comprendre X, il faut remonter à... ») → explication croissante avec un fil conducteur clair → complication ou retournement → résolution qui recadre l'accroche.
3. Voix : accueil à la deuxième personne (« vous avez probablement vu... »), présent pour le récit historique, chiffres concrets plutôt qu'abstractions, phrases courtes et déclaratives. Pas de circonvolutions, pas de « dans cette vidéo nous allons ».
4. Une idée par beat. Si une phrase introduit un second concept, divisez le beat.

Écrivez script.json :

{
  "title": "Âge d'or Tang",
  "topic": "Comment la Chine des Tang a bâti la plus grande ville du monde",
  "style_seed": "collage de papiers mixtes, montagnes chinoises à l'encre de Chine, palette rouge vermillon et crème vieillie",
  "accent_color": "#C0392B",
  "beats": [
    {
      "id": 1,
      "narration": "Au septième siècle, la Chine des Tang a construit Chang'an — la plus grande et la plus riche ville sur Terre. Le monde entier venait à ses portes.",
      "visual": "Empereur Taizong intronisé au centre en découpe papier, figures de cour sur les côtés, pagodes et montagnes à l'encre en arrière-plan, sceau rouge en haut à droite lisant 盛唐",
      "caption_text": null,
      "motion": "zoom avant lent sur l'empereur, nuages qui dérivent à gauche, parallaxe subtile entre les couches de découpe"
    }
  ]
}

caption_text est réservé aux moments de typographie cinétique à l'écran (une statistique ou un terme clé) — la plupart des beats le laissent à null ; les sous-titres de narration sont gérés lors de l'assemblage. motion devient l'invite d'animation à l'Étape 4.

Étape 2 — Voix off (xAI TTS v1)

Générez un fichier audio par beat, puis mesurez les durées. Ces durées sont l'horloge maîtresse de tout le film.

Appelez l'endpoint audio Atlas Cloud par beat (modèle : xAI TTS v1 — voir references/atlas-cloud-api.md pour la forme exacte de la requête et les conseils de sélection de voix). Choisissez UNE voix pour tout le film. Registre Vox : posée, chaleureuse, légèrement ironique — évitez les voix de « bande-annonce de film ».

Après génération, sondez chaque fichier et écrivez 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}

Vérifiez la durée totale par rapport au brief. Si un beat est trop long, resserrez la narration et régénérez ce beat uniquement.

Étape 3 — Images clés (Seedream 5.0 Pro)

Une image clé par beat, toutes dans un style visuel cohérent. La cohérence est le problème difficile ; résolvez-le avec le motif d'ancrage stylistique :

1. Générez l'ancre. Utilisez bytedance/seedream-v5.0-pro/text-to-image pour le beat 1 (généralement l'image titre/accroche). Construisez l'invite à partir du bloc de style dans references/vox-style-guide.md (section Grammaire visuelle) + le visual du beat + le style_seed et accent_color du film. Demandez 16:9, 2K.
2. Examinez l'ancre avant de continuer. Régénérez jusqu'à ce que le style convienne — toutes les autres images en héritent.
3. Générez les images restantes avec le modèle d'édition. Utilisez bytedance/seedream-v5.0-pro/edit avec l'ancre comme image de référence (jusqu'à 10 références supportées ; ancre + éventuellement l'image précédente). Invite : « Gardez exactement le style artistique, la palette, le traitement en collage de papier et le cadre de la référence. Nouvelle scène : {beat.visual} »

Cela verrouille la palette, la texture et le cadre sur tout le film comme le ferait un directeur artistique humain.

Chaque invite doit se terminer par le suffixe de style (voir le guide de style), qui encode le look Vox : découpes de papier avec bordures blanches, points de trame, bandes adhésives, accents géométriques plats et gras, marges généreuses, une seule couleur d'accent.

Images avec caption_text défini : demandez à Seedream de rendre le texte dans un sans-serif condensé gras, car le rendu typographique de Seedream 5.0 Pro est solide. Limitez à moins de 5 mots par image.

Étape 4 — Animation (Gemini Omni Flash)

Animez chaque image clé en un clip via image-vers-vidéo. Durée cible du clip = durée de la VO de ce beat + 0,5 s de marge (arrondissez aux incréments supportés par le modèle).

Les invites de mouvement pour l'esthétique collage doivent être SUBTILES — c'est le mode de défaillance le plus courant. Le look Vox est « motion design », pas « prise de vue réelle ». Bon vocabulaire de mouvement :

• zoom avant / arrière lent (caméra 2D, pas travelling 3D)
• dérive de parallaxe entre les couches de découpe
• nuages / fumée qui dérivent latéralement
• éléments en papier glissant depuis le bord du cadre et se fixant
• points de trame ou texture qui scintillent doucement
• un seul élément qui s'anime (drapeau qui flotte, eau qui ondule) tandis que tout le reste reste fixe

Interdisez explicitement dans chaque invite : « pas de tremblement de caméra, pas de rotation 3D, pas de morphing des visages ou du texte, pas de dérive de style, les éléments restent des découpes de papier plates. »

Interrogez chaque tâche de génération jusqu'à son achèvement et téléchargez dans clips/clip_NN.mp4. Les générations échouent ou dérivent parfois — examinez chaque clip ; régénérez ceux où le texte se déforme ou le style se casse. Prévoyez ~15 % de régénération.

Étape 5 — Musique (MiniMax Music 2.6)

Un seul fond instrumental pour tout le film. Demandez is_instrumental: true — les voix luttent contre la narration.

Formule d'invite : {ambiance} {texture de genre adjacent}, {tempo}, {instrumentation}, {arc}. Exemple pour un sujet historique : « soulignement cinématographique contemplatif, piano feutré et cordes douces avec une pulsation légère de percussions, 90 bpm, construit progressivement de clairsemé à plein, style documentaire ». Adaptez l'instrumentation au sujet (textures de guzheng/dizi pour le morceau Tang ; pulsation de synthé analogique pour un sujet tech).

Music 2.6 génère des chansons de longueur fixe ; si le morceau est plus court que le film, bouclez-le à l'assemblage avec un fondu enchaîné ; s'il est plus long, rognez-le avec un fondu de sortie. Ne laissez jamais l'arc musical contredire l'arc du film — un drop en milieu de piste tombant sur un beat calme est déstabilisant, alors écoutez le résultat par rapport à la forme du film.

Étape 6 — Assemblage (ffmpeg, local)

Lisez references/ffmpeg-assembly.md pour les recettes complètes. La séquence :

1. Conformez chaque clip à la durée de la VO de son beat (rognez ou tenez la dernière image), normalisez en 1920x1080 30 ips.
2. Concaténez les clips dans l'ordre.
3. Construisez la piste VO en concaténant l'audio des beats avec des pauses de 0,5 s correspondant au timing vidéo.
4. Générez subs/sous-titres.ass à partir du script — sous-titres incrustés de style Vox : sans-serif gras, blanc avec contour noir épais, centré en bas, max 2 lignes, divisez la narration aux limites de proposition et chronométrez chaque segment dans la fenêtre de son beat.
5. Mixez l'audio : VO au niveau plein, musique abaissée de -12 à -15 dB sous la narration (compression sidechain ou une simple automatisation de volume — recettes dans la référence).
6. Gravez les sous-titres + l'attribution (« Réalisé avec ... » en petit en bas à droite si souhaité) et encodez : H.264, CRF 18, AAC 192k, -movflags +faststart.

Passez un dernier contrôle qualité avant de livrer : vérifiez (a) la synchronisation sous-titres/VO, (b) la musique qui ne couvre pas la narration, (c) un clip dont le mouvement boucle visiblement, (d) une dérive de style entre les images. Corrigez à l'étape où le problème est né, pas avec des bidouilles d'assemblage.

Notes d'orchestration

• Exécutez les étapes strictement dans l'ordre la première fois ; ensuite, toute étape peut être relancée isolément car tout l'état réside dans les fichiers du projet.
• La génération API est lente (clips vidéo : 1 à 4 min chacun). Soumettez toutes les tâches d'animation simultanément, puis interrogez — ne sérialisez pas.
• Conservez chaque invite envoyée dans un fichier prompts.log — la reproductibilité compte et les utilisateurs voudront ajuster et régénérer des beats individuels.
• Le coût évolue linéairement avec le nombre de beats. Donnez un coût approximatif à l'utilisateur avant l'Étape 3 (la première étape lourde en paiement) : beats × (0,10 $ image + ~1,20 $ par clip de 10 s) + ~0,50 $ audio.

Références

• references/vox-style-guide.md — lisez avant l'Étape 1 et l'Étape 3. La grammaire visuelle, la voix d'écriture et les modèles d'invite.
• references/atlas-cloud-api.md — lisez avant l'Étape 2. Endpoints, ID de modèles, motif de tâche asynchrone, code d'interrogation, coûts.
• references/ffmpeg-assembly.md — lisez avant l'Étape 6. Conformage, concaténation, sous-titres, réduction de volume et encodage.