Kit de Création de Vidéos Vectorielles Animées Procédurales (Procedural Cartoon Video Kit)
Cette compétence fournit un pipeline entièrement piloté par le code, sans dépendance à des actifs externes (vecteurs purs sans perte) pour la création de courtes vidéos éducatives et de visites guidées animées. En combinant le moteur de dessin Python Pycairo, la synthèse vocale Google Gemini 3.8 Flash TTS, l'alignement automatique de la durée du texte, le sous-titrage intelligent par ponctuation et le compositing audio-vidéo FFmpeg, elle peut automatiquement générer des vidéos MP4 haute définition en 1280×720 (30 fps) en quelques minutes.
Prérequis Système (Prerequisites)
L'environnement d'exécution standard est macOS :
# 1. Dépendances système et polices (obligatoire : Noto Sans CJK TC en gras)
brew install ffmpeg cairo pkg-config
brew install --cask font-noto-sans-cjk-tc
# 2. Bibliothèques Python
pip3 install pycairo numpy pillow
# 3. Clé API OpenRouter (pour la synthèse vocale Gemini 3.8 Flash TTS)
# Écrire la clé API dans ~/.openrouter_key, sans retour à la ligne
echo "VOTRE_CLE_API_OPENROUTER" > ~/.openrouter_key
chmod 600 ~/.openrouter_key
Vérification de l'environnement : exécutez python3 example_ds2.py auto. Si le fichier example_ds2/grid.png est généré correctement, l'environnement est prêt.
Structure Standard du Répertoire du Projet
my_video_project/
├── engine.py # Moteur principal : fond de toile, génération de sous-titres, composition BGM, classe Episode, pipeline FFmpeg
├── dc.py # Bibliothèque de modèles visuels partagés (ouverture, feuille de route, Q&A, résumé...)
├── atian.py (ou xd.py / aj.py) # Définition du personnage principal (remplace dc.doctor pour un changement global)
├── ep1.py # Code de la scène de l'épisode (fonctions de dessin s0, s1, s2...)
├── ep1/ # Répertoire des actifs de l'épisode
│ ├── script.json # Script narratif (tableau de chaînes)
│ ├── c1.pcm ~ cN.pcm # Fichiers audio de chaque segment après accélération 1.1x (PCM 24kHz s16le)
│ └── grid.png # Aperçu miniature automatique de la vidéo entière (2 images par scène)
└── tools/
├── make_payloads.py # script.json -> Requête JSON OpenRouter TTS
├── tts.sh # Appel à OpenRouter pour générer par lots la synthèse vocale PCM 24kHz
├── f0.py # Script de contrôle de la hauteur tonale (médiane en Hz, détecte et relance les segments décalés)
└── prep.sh # Accélération audio 1.1x et renommage en c1.pcm ~ cN.pcm
Processus de Production Standard en Six Étapes (SOP)
Pour chaque nouvel épisode, suivez rigoureusement les six étapes suivantes :
Étape 1 : Rédaction du Script et Division en Scènes (script.json)
- Créez un tableau JSON dans
ep1/script.json. Chaque chaîne correspond à une scène indépendante (Scene). - Le nombre de caractères par segment narratif doit idéalement être compris entre 30 et 80 (lecture d'environ 6 à 15 secondes) pour un rythme optimal.
- Utilisez la ponctuation pleine largeur standard (
,,。,!,?,:,;). Le moteur coupera automatiquement les sous-titres en fonction de la ponctuation.
Étape 2 : Synthèse Vocale TTS, Contrôle de la Hauteur Tonale et Optimisation de la Vitesse 1.1x
- Générer le fichier de requête TTS :
Remarque : Les instructions de style (p. ex., "accent taïwanais authentique", "guide jeune et dynamique") doivent être placées dans le champpython3 tools/make_payloads.py ep1instructions, jamais dansinputsinon elles seront prononcées. - Lancer les requêtes vocales par lots :
bash tools/tts.sh ep1 - Contrôle de la hauteur tonale (F0 Pitch Check) :
python3 tools/f0.py tts_ep1/*.pcm- La médiane normale pour la voix masculine
Puckest de 120 Hz à 160 Hz. - Règle stricte de hauteur : si un segment dépasse 165 Hz (indiquant un glissement de la voix vers une tonalité féminine par Gemini), ce segment doit être redemandé individuellement jusqu'à ce que la hauteur soit normale. Voir audio-tts-pipeline.md pour plus de détails.
- La médiane normale pour la voix masculine
- Accélération et formatage de la vitesse :
Accélère les fichiers avecbash tools/prep.sh ep1atempo=1.1et les sort dansep1/c1.pcmàep1/cN.pcm.
Étape 3 : Liaison du Personnage Principal et Dessin Personnalisé
- Le module du personnage doit respecter l'interface de fonction standard :
def my_host(ctx, x, y, s, t, mouth=0.0, wave=False, point=False, sweat=False, happy=True, look=0.0): - En exécutant
dc.doctor = my_hosten bas du module, tous les modèles de personnages sont remplacés globalement en un clic. - Consultez character-design.md et character_template.py pour les techniques de dessin complètes (calcul du clignement des yeux, bras en tube, ouverture de la bouche pilotée par le volume RMS).
Étape 4 : Écriture du Code Visuel des Scènes avec Pycairo (ep1.py)
- Pour chaque scène, écrivez la fonction correspondante
def s0(ep, ctx, u, T, m):u: secondes écoulées dans cette scène.T: secondes absolues depuis le début de la vidéo.m: amplitude audio en temps réel (0.0 ~ 1.0).
- Utilisez
ep.kw(sc, "mot-clé précis")pour obtenir le moment exact où le mot-clé est prononcé, afin de déclencher l'apparition des cartes graphiques. - L'API des fonctions et de la disposition clés est détaillée dans engine-api.md.
Étape 5 : Aperçu Rapide des Miniatures et Contrôle Visuel (Preview & QA)
python3 ep1.py auto
- Le moteur échantillonne rapidement 2 images par scène en 2 secondes et les assemble dans
ep1/grid.png. - Points de vérification importants :
- Présence de carrés manquants (problème de police).
- Contenu qui dépasse les limites du cadre ou chevauchement de chaînes.
- Cartes inférieures qui empiètent sur la zone de sous-titres (ne pas descendre en dessous de y=610).
- Chevauchement entre les cartes de droite et le personnage permanent en bas à droite.
Étape 6 : Rendu Complet de la Vidéo et Vérification du Décodage FFmpeg
- Rendu officiel du MP4 :
Le moteur compose automatiquement la vidéo H.264 en 1280×720, intègre les sous-titres, mixe la BGM (avec réduction automatique du volume) et encapsule l'audio AAC.python3 ep1.py - Vérification sans perte :
Aucune erreur dans le terminal signifie que la synchronisation audio-vidéo et le conditionnement sont parfaits.ffmpeg -v error -i nom_fichier_sortie.mp4 -f null -
Aide-mémoire des API Principales
| Fonctionnalité | Syntaxe | Description |
|---|---|---|
| Calcul de progression | prog(u, t0, d=0.5) | Passe de 0 à 1 en d secondes à partir de t0 secondes |
| Zoom rebondissant | pop(ctx, cx, cy, p) | Apparition avec rebond autour d'un point central (courbe arrière) |
| Alignement de mots-clés | ep.kw(sc, "texte", nth=0) | Calcule précisément le moment où le mot est prononcé (avec avance automatique de 0,25 s) |
| Rectangle arrondi | rrect(ctx, x, y, w, h, r) | Définit un chemin rectangulaire arrondi |
| Remplissage et contour | fillstroke(ctx, fill, stroke, lw=5) | Remplit et trace un contour foncé simultanément |
| Texte monoligne | text(ctx, s, x, y, size, col, align='c') | Dessine du texte, alignement gauche 'l', centré 'c', droite 'r' |
| Étiquette capsule | chip(ctx, "étiquette", x, y, p, col, size=30) | Carte graphique capsule pop-up |
| Panneau contextuel | if panel(ctx, x, y, w, h, p): ... ctx.restore() | Panneau blanc de contenu (doit être associé à restore) |
| Personnage en bas à droite | corner(ctx, T, m) | Dessine une version miniature du personnage permanent en bas à droite |
| Carte titre de chapitre | station_card(ctx, u, numéro_station, "nom_station") | Carte titre centrale apparaissant au début d'un chapitre (premières 1,9 secondes) |
| Résumé et conclusion | outro_doc(ep, ctx, u, T, m, sc, titre, sous-titre, rows) | Scène de conclusion avec confettis, points clés et teaser du prochain épisode |
Trois Règles d'Or pour Éviter les Pièges (Crucial Guardrails)
- Zone de sécurité des sous-titres :
- La plage
y = 648 ~ 702en bas est réservée aux sous-titres automatiques. - Tous les panneaux d'information, fiches de données et boutons ne doivent en aucun cas dépasser y = 610 !
- La plage
- Interdiction des symboles spéciaux et Emoji :
- Pycairo avec la police
Noto Sans CJK TCne peut pas rendre les Emoji (comme ✨, 📜, 🌱) ni les flèches Unicode spéciales (➔, ➜), qui deviendront des carrés inesthétiques. - Solutions de remplacement : utilisez
->pour les flèches ou appelez la fonctionarrow(); pour les étoiles, utilisez la fonctionstar(); pour les croix, utilisez le symbole alphanumérique×ou la fonctionmark(ctx, x, y, False, p).
- Pycairo avec la police
- Précision des mots-clés :
phrasedansep.kw(sc, phrase)doit être une sous-chaîne exacte du texte de cette scène dansscript.json. Il ne doit pas y avoir de caractères supplémentaires, manquants ou de ponctuation ajoutée, sinon le programme sera interrompu.
Documents de Référence et Exemples de Ressources
- Architecture du moteur et tous les composants géométriques intégrés : references/engine-api.md
- Conception des personnages vectoriels et implémentation de la respiration/clignement des yeux/forme de la bouche : references/character-design.md
- Spécifications des requêtes TTS, algorithme de hauteur F0 et traitement audio : references/audio-tts-pipeline.md
- Zones de sécurité du canevas, prévention des caractères manquants et liste des pièges : references/layout-and-pitfalls.md
- Code modèle du personnage : examples/character_template.py
- Modèle minimal d'épisode complet : examples/minimal_episode.py