CK42BB/vox-explainer-skill

Pipeline vidéo explicative à la Vox

Produisez une vidéo explicative complète, narrée, sous-titrée et musicale à partir d'un seul sujet. Le pipeline se déroule en six étapes, chacune produisant des artéfacts consommés par l'étape suivante. La voix off est générée AVANT l'animation car la durée de la voix off détermine toutes les décisions de synchronisation.

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-la sur atlascloud.ai — crédits gratuits à l'inscription)
• ffmpeg et ffprobe installés (avec libass pour l'incrustation des sous-titres)
• Python 3.10+ avec requests
• ~3 à 8 $ de crédits API par vidéo de 60 secondes (voir le tableau des coûts dans references/atlas-cloud-api.md)

Avant tout appel API, vérifiez les chemins d'accès aux endpoints actuels et les identifiants de modèles sur https://www.atlascloud.ai/docs — les API de 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 lit et écrit dedans :

projet/
├── brief.md            # sujet, angle, durée cible, public
├── script.json         # séquences avec narration, descriptions visuelles, légendes
├── 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 animés silencieux)
├── subs/               # captions.ass
└── final/              # film.mp4

Étape 1 — Script

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

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

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

Écrivez script.json :

{
  "title": "L'â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 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 ville la plus grande et la plus riche de la Terre. Le monde entier venait à ses portes.",
      "visual": "Empereur Taizong trônant au centre en découpage papier, figures de cour encadrant, pagodes et montagnes à l'encre derrière, sceau rouge en haut à droite lisant 盛唐",
      "caption_text": null,
      "motion": "zoom avant lent sur l'empereur, nuages dérivant à gauche, parallaxe subtile entre les couches de découpages"
    }
  ]
}

caption_text est réservé aux moments de typographie cinétique à l'écran (une statistique clé ou un terme) — la plupart des séquences le laissent à null ; les sous-titres de narration sont gérés à 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 séquence, puis mesurez les durées. Ces durées sont l'horloge maîtresse pour tout le film.

Appelez le endpoint audio d'Atlas Cloud par séquence (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 vocale). Choisissez UNE voix pour tout le film. Registre Vox : mesurée, chaleureuse, légèrement ironique — évitez les voix de « bande-annonce ».

Après la 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 longueur totale par rapport au brief. Si une séquence est trop longue, resserrez la narration et régénérez uniquement cette séquence.

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

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

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

Cela verrouille la palette, la texture et le cadrage 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écoupages papier avec bordures blanches, points de trame, bandes adhésives, accents géométriques plats et audacieux, marges généreuses, couleur d'accent unique.

Cadres avec caption_text défini : demandez à Seedream de rendre le texte dans un gras condensé audacieux, car le rendu typographique de Seedream 5.0 Pro est solide. Limitez à 5 mots par cadre.

Étape 4 — Animation (Gemini Omni Flash)

Animez chaque image-clé en clip via image-vers-vidéo. Durée cible du clip = durée VO de cette séquence + 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 d'échec le plus courant. Le look Vox est « graphisme animé », pas « séquence filmée ». Bon vocabulaire de mouvement :

• zoom avant / arrière lent (caméra 2D, pas chariot 3D)
• dérive en parallaxe entre les couches de découpages
• nuages/fumée dérivant latéralement
• éléments papier glissant depuis le bord du cadre et se posant
• points de trame ou texture scintillant doucement
• un seul élément animé (drapeau flottant, eau ondulant) tandis que tout le reste reste immobile

Interdisez explicitement dans chaque invite : « pas de secousse 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écoupages papier plats. »

Sondez chaque tâche de génération jusqu'à la fin et téléchargez-la dans clips/clip_NN.mp4. Les générations échouent ou dérivent parfois — examinez chaque clip ; régénérez tout clip où le texte se déforme ou le style change. Prévoyez environ 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 se battent avec la narration.

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

Music 2.6 génère des morceaux de longueur fixe ; si le morceau est plus court que le film, bouclez-le à l'assemblage avec un fondu enchaîné ; si plus long, rognez avec fondu sortant. Ne laissez jamais l'arc musical contredire l'arc du film — une chute en milieu de morceau tombant sur une séquence calme est brutale, donc auditionnez 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 VO de sa séquence (rognez ou maintenez la dernière image), normalisez en 1920x1080 30ips.
2. Concaténez les clips dans l'ordre.
3. Construisez la piste VO en concaténant l'audio des séquences avec des espaces de 0,5 s correspondant au timing vidéo.
4. Générez subs/captions.ass à partir du script — sous-titres brûlés style Vox : gras sans empattement, blanc avec contour noir épais, centré en bas, max 2 lignes, divisez la narration aux limites de clauses et chronométrez chaque segment dans la fenêtre de sa séquence.
5. Mixez l'audio : VO au niveau plein, musique réduite de -12 à -15 dB sous la narration (compression sidechain ou une simple automation de volume — recettes dans la référence).
6. Brûlez les sous-titres + attribution (« Créé avec ... » petit en bas à droite si désiré) et encodez : H.264, CRF 18, AAC 192k, -movflags +faststart.

Contrôle qualité final avant livraison : vérifiez (a) la dérive de synchro sous-titres/VO, (b) la musique couvrant la narration, (c) un clip dont le mouvement boucle visiblement, (d) la dérive de style entre les cadres. Corrigez à l'étape où le problème est apparu, pas avec des bricolages d'assemblage.

Notes d'orchestration

• Exécutez les étapes strictement dans l'ordre la première fois ; ensuite, toute étape peut être rejouée individuellement 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 en parallèle, puis sondez — ne sérialisez pas.
• Conservez chaque invite que vous envoyez dans un fichier prompts.log — la reproductibilité compte et les utilisateurs voudront modifier et régénérer des séquences individuelles.
• Le coût évolue linéairement avec le nombre de séquences. Estimez un coût approximatif à l'utilisateur avant l'étape 3 (la première étape lourde en paiement) : séquences × (0,10 $ image + ~1,20 $ par clip de 10 s) + ~0,50 $ audio.

Références

• references/vox-style-guide.md — à lire avant l'étape 1 et l'étape 3. La grammaire visuelle, la voix d'écriture et les modèles d'invites.
• references/atlas-cloud-api.md — à lire avant l'étape 2. Endpoints, identifiants de modèles, modèle de tâche asynchrone, code de sondage, coûts.
• references/ffmpeg-assembly.md — à lire avant l'étape 6. Recettes de conformation, concaténation, sous-titres, réduction et encodage.