Communitygithub.com

DrChunChihChen/procedural-cartoon-video

利用 Python Pycairo、Gemini 3.8 Flash TTS 與 FFmpeg 自動化產生高品質的向量卡通導覽與教學解說短影片。

Qu'est-ce que procedural-cartoon-video ?

這是一個專為開發者與 AI 代理使用者設計的技能,可透過純程式碼驅動的流程,自動化生成向量風格的卡通教學與導覽解說短影片。它整合了 Python Pycairo 繪圖引擎進行無失真向量渲染、Google Gemini 3.8 Flash TTS 產生自然語音,並透過智慧標點斷句與自動字數時長對齊,搭配 FFmpeg 完成音畫合成,最終輸出 1280×720 (30 fps) 的高畫質 MP4 檔案。此技能主要支援 macOS 環境,並提供完整的六階段製作 SOP(腳本撰寫、TTS 語音生成與音高檢測、角色繪製、視覺場景編碼、預覽質檢與最終算繪)。其核心優勢在於完全脫離外部素材依賴,所有視覺元素皆由程式碼即時生成,確保零失真且高度可自訂,特別適合需要快速迭代、版本控管的自動化影片生產管線。

Compatible avec~Claude Code~Codex CLI~Cursor✓Antigravity✓Gemini CLI
npx skills add DrChunChihChen/procedural-cartoon-video

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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

  1. Générer le fichier de requête TTS :
    python3 tools/make_payloads.py ep1
    
    Remarque : Les instructions de style (p. ex., "accent taïwanais authentique", "guide jeune et dynamique") doivent être placées dans le champ instructions, jamais dans input sinon elles seront prononcées.
  2. Lancer les requêtes vocales par lots :
    bash tools/tts.sh ep1
    
  3. Contrôle de la hauteur tonale (F0 Pitch Check) :
    python3 tools/f0.py tts_ep1/*.pcm
    
    • La médiane normale pour la voix masculine Puck est 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.
  4. Accélération et formatage de la vitesse :
    bash tools/prep.sh ep1
    
    Accélère les fichiers avec atempo=1.1 et les sort dans ep1/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_host en 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 :
    1. Présence de carrés manquants (problème de police).
    2. Contenu qui dépasse les limites du cadre ou chevauchement de chaînes.
    3. Cartes inférieures qui empiètent sur la zone de sous-titres (ne pas descendre en dessous de y=610).
    4. 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

  1. Rendu officiel du MP4 :
    python3 ep1.py
    
    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.
  2. Vérification sans perte :
    ffmpeg -v error -i nom_fichier_sortie.mp4 -f null -
    
    Aucune erreur dans le terminal signifie que la synchronisation audio-vidéo et le conditionnement sont parfaits.

Aide-mémoire des API Principales

FonctionnalitéSyntaxeDescription
Calcul de progressionprog(u, t0, d=0.5)Passe de 0 à 1 en d secondes à partir de t0 secondes
Zoom rebondissantpop(ctx, cx, cy, p)Apparition avec rebond autour d'un point central (courbe arrière)
Alignement de mots-clésep.kw(sc, "texte", nth=0)Calcule précisément le moment où le mot est prononcé (avec avance automatique de 0,25 s)
Rectangle arrondirrect(ctx, x, y, w, h, r)Définit un chemin rectangulaire arrondi
Remplissage et contourfillstroke(ctx, fill, stroke, lw=5)Remplit et trace un contour foncé simultanément
Texte monolignetext(ctx, s, x, y, size, col, align='c')Dessine du texte, alignement gauche 'l', centré 'c', droite 'r'
Étiquette capsulechip(ctx, "étiquette", x, y, p, col, size=30)Carte graphique capsule pop-up
Panneau contextuelif panel(ctx, x, y, w, h, p): ... ctx.restore()Panneau blanc de contenu (doit être associé à restore)
Personnage en bas à droitecorner(ctx, T, m)Dessine une version miniature du personnage permanent en bas à droite
Carte titre de chapitrestation_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 conclusionoutro_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)

  1. Zone de sécurité des sous-titres :
    • La plage y = 648 ~ 702 en 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 !
  2. Interdiction des symboles spéciaux et Emoji :
    • Pycairo avec la police Noto Sans CJK TC ne 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 fonction arrow() ; pour les étoiles, utilisez la fonction star() ; pour les croix, utilisez le symbole alphanumérique × ou la fonction mark(ctx, x, y, False, p).
  3. Précision des mots-clés :
    • phrase dans ep.kw(sc, phrase) doit être une sous-chaîne exacte du texte de cette scène dans script.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

Skills associés