Yari-tuber/math-rap-video

Vidéo Explicative avec Formule Mnémotechnique (Rap Mathématiques)

Transforme un concept en une vidéo explicative d'environ 1 minute. Elle est facile à retenir car trois couches se superposent et suivent toutes le même fichier audio :

• Oreille : rythme régulier, une phrase par mesure, une seule rime jusqu'à la fin, donc agréable à écouter
• Langage : formule mnémotechnique de 8–10 mots, répétée 2–3 fois, affichée en permanence en haut de l'écran
• Œil : au fur et à mesure que les paroles sont chantées, le graphique avance étape par étape, l'élève voit « pourquoi c'est juste »

La narration suit une structure fixe : poser le problème → piège (la méthode maladroite échoue) → donner la formule → démonstration → expliquer le principe → conclusion.

Répartition : qui fournit quoi

Partie	Qui la fait	Description
Formule, paroles, storyboard	Toi (IA) les écris, l'utilisateur valide	Voir les règles dans references/lyrics.md
Audio (voix + musique)	L'utilisateur ou le client les fournit lui-même	Quel modèle, quelle voix : c'est leur décision. Donne-leur la section « Exigences à envoyer au client » de references/audio.md. Ce skill ne choisit pas de plateforme à la place de l'utilisateur et ne génère pas de musique par défaut avec de l'argent
Sous-titres temporels	Calculés par les scripts	Tout SRT exporté par un outil de reconnaissance vocale fonctionne, même avec des coquilles
Images d'arrière-plan	Sélection automatique depuis la bibliothèque	assets/backgrounds/, étiquetées par usage ; on peut en ajouter
Graphiques, formule, sous-titres	Dessinés image par image par les scripts	Tu écris seulement le storyboard.json et le graphics.py de ce sujet

Environnement

Avant la première utilisation, exécute l'auto-vérification ; elle t'indiquera ce qui manque et comment l'installer :

python $SKILL/scripts/check_env.py

Il faut : Python 3.10+ (avec pip install pillow numpy librosa pypinyin), ffmpeg / ffprobe, une police chinoise en gras (les polices système courantes sont détectées automatiquement), et une bibliothèque d'arrière-plans. La bibliothèque est cherchée dans cet ordre : variable d'environnement MATH_RAP_LIBRARY → assets/backgrounds/ de ce skill → emplacement partagé ~/.math-rap-video/backgrounds/. S'il manque, exécute python $SKILL/scripts/install.py --library <archive_zip_de_la_bibliotheque.zip>.

Ci-dessous, $SKILL désigne le répertoire de ce skill (le dossier contenant ce fichier SKILL.md). Ce n'est pas une variable d'environnement préexistante : remplace-la par le chemin réel quand tu exécutes une commande, ou définis-la une fois (bash : export SKILL="/chemin/math-rap-video" ; PowerShell : $SKILL="C:\chemin\math-rap-video"). Mets le chemin entre guillemets s'il contient des espaces ou des caractères chinois. Tous les scripts sont des programmes CLI standards (ils supportent tous --help) ; tout IA ou humain capable de lancer des commandes peut les utiliser, sans dépendre d'un outil spécifique.

Flux de travail

1 Écrire les paroles et le storyboard ──→ 2 L'utilisateur fournit l'audio ──→ 3 prepare_audio calcule les temps et valide
                                        │
4 Écrire storyboard.json + graphics.py ←────┘
        │
5 Vérification + aperçu (valider visuellement) ──→ 6 build_video génère la vidéo ──→ 7 Vérifier et livrer

Après chaque étape, informe brièvement l'utilisateur du résultat. Les étapes 1 et 5 nécessitent une validation de l'utilisateur avant de continuer.

Quand l'utilisateur arrive avec des paroles et un audio déjà prêts (paroles finalisées, audio enregistré dessus) : ne change pas un mot des paroles, sinon l'image ne correspondra pas au chant. À l'étape 1, fais seulement trois choses : créer le projet, mettre les paroles telles quelles dans lyrics.md, et ajouter le tableau de storyboard à la fin ; ne modifie pas les paroles d'après check_lyrics.py. Puis continue directement à l'étape 3.

1. Créer le projet, écrire la formule, les paroles et le tableau de storyboard

python $SKILL/scripts/new_project.py <répertoire_du_projet>          # Copie l'exemple (compter les segments) comme point de départ
python $SKILL/scripts/new_project.py <répertoire_du_projet> --blank  # Ou démarre avec un modèle vierge

Suis references/lyrics.md pour écrire lyrics.md : une phrase = une mesure, chaque phrase 11–15 mots (section principe 9–11 mots), une seule rime jusqu'à la fin ; structure : Couplet 1 (14 phrases) + Refrain (2 phrases, la formule dite seule) + Couplet 2 (8 phrases).

Le tableau de storyboard va dans la section ## Tableau de storyboard à la fin de lyrics.md (un tableau : numéro de phrase, action visuelle, mot déclencheur). Il sert à la validation par l'utilisateur et est la base pour écrire le code à l'étape 4 ; les scripts ne le lisent pas.

Après avoir écrit, lance la vérification des paroles, corrige tout ce qui est « à corriger absolument » et examine les « suggestions » une par une :

python $SKILL/scripts/check_lyrics.py <répertoire_du_projet>     # Structure, nombre de mots par phrase, rime, formulations sujettes à erreur

Vérifie chaque nombre dans les exemples toi-même (les scripts ne peuvent pas vérifier les maths). Ensuite, soumets la formule, les paroles et le tableau de storyboard à l'utilisateur pour validation.

2. L'utilisateur fournit l'audio

Transmets à l'utilisateur les paroles validées ainsi que la section « Exigences à envoyer au client » de references/audio.md. Ils peuvent utiliser n'importe quel moyen pour créer l'audio : plateforme IA musicale, rap humain, TTS ou voix off avec accompagnement. Ce qu'ils renvoient :

• Un ou plusieurs fichiers audio (mp3 / wav) avec la voix. Pour l'audio généré par IA, recommande 2–3 versions pour pouvoir choisir
• Idéalement, un fichier de sous-titres (SRT). Sinon, utilise un outil de reconnaissance vocale sur l'audio pour en générer un

Si l'utilisateur demande explicitement que tu génères la chanson à sa place, et qu'il fournit une clé API ElevenLabs, tu peux utiliser scripts/gen_music.py (voir references/audio.md pour l'utilisation). C'est optionnel ; chaque version consomme du crédit de l'utilisateur, préviens-le avant de générer.

3. Traiter l'audio : calculer les temps et décider si cette version est utilisable

python $SKILL/scripts/prepare_audio.py <répertoire_du_projet> --audio chanson.mp3 --srt reconnaissance.srt --bpm 90 --intro-bars 2

Il aligne le résultat de la reconnaissance sur les paroles (coquilles, découpage différent : pas grave), détecte la vitesse et le tempo, écrit timing.json, et copie l'audio dans le répertoire du projet (la vidéo le lira depuis là, donc le répertoire contiendra des fichiers audio supplémentaires, c'est normal). La dernière ligne donne la conclusion :

• Utilisable : continue. Si certaines phrases ont un « taux de correspondance faible », note-les pour le dire à l'utilisateur lors de la livraison
• Il vaut mieux en essayer une autre (code de sortie 3) : la raison est listée ; les causes fréquentes sont une phrase manquée, une entrée vocale trop tardive, un écrasement global. Change de version audio, ne force pas

Quand il y a plusieurs versions audio, écris chacune dans un fichier différent avant de comparer, puis copie celle choisie en timing.json :

python $SKILL/scripts/prepare_audio.py <répertoire> --audio gen_01.mp3 --srt 01.srt --bpm 90 --intro-bars 2 --out timing_01.json
python $SKILL/scripts/prepare_audio.py <répertoire> --audio gen_02.mp3 --srt 02.srt --bpm 90 --intro-bars 2 --out timing_02.json
cp <répertoire>/timing_02.json <répertoire>/timing.json

Comment choisir : voir section 3 de references/audio.md. En bref : élimine d'abord les versions « à essayer autre », puis choisis celle où les deux phrases de formule ont le meilleur taux de correspondance, enfin la régularité rythmique. En cas de conflit, la clarté de la formule prime sur la régularité rythmique : le public retient la formule.

Autres cas : voix off explicative, audio sans tempo → ajoute --no-beat ; solution de repli sans SRT → --grid --entry <seconde_entrée_voix> pour déduire les temps phrase par phrase ; --intro-bars indique le nombre de mesures d'intro convenu avec le client (2 dans l'exemple ci-dessus est notre valeur par défaut demandée au client), ne mets rien si pas convenu. Sous Windows PowerShell, cp fonctionne aussi ; dans cmd, remplace par copy.

Pour changer d'audio, il suffit de relancer cette étape ; le storyboard n'a pas besoin d'être modifié.

4. Écrire le storyboard et les graphiques du sujet

Lis references/visuals.md, puis modifie les deux fichiers dans le répertoire du projet :

• storyboard.json : bannière de formule, formules, lettres animées, flèches, changements d'arrière-plan
• graphics.py : graphiques spécifiques au sujet, implémente setup(ctx) et draw(canvas, t, ctx)

La règle la plus importante : les temps s'écrivent toujours comme des expressions relatives aux paroles, jamais en secondes fixes.

Écriture	Signification
L(6) / E(6)	Début / fin de la phrase 6
W(9,'四') / W(9,'四',2)	Instant où le mot « 四 » (2e occurrence) est chanté dans la phrase 9
B / L(6)+2*B	Un temps ; 2 temps après le début de la phrase 6

Ainsi l'image est vraiment synchronisée avec les paroles, et si le client change d'audio, il suffit de relancer l'étape 3 pour générer la vidéo directement.

Les graphiques sont l'étape la plus chronophage. Le moteur fournit déjà les éléments courants (points, lignes, arcs, angles droits, symboles de quadrillages, lignes de liaison, formules multicolores sur une ligne, rotations/translations complètes, déplacement le long d'un chemin, espacement régulier). Cherche d'abord dans la section 4 de references/visuals.md les solutions existantes, ne pars pas de zéro. Sors une image après chaque petite partie écrite (voir étape suivante), n'attends pas d'avoir tout fini.

Les deux défauts les plus fréquents dans la pratique, à éviter dès l'écriture :

• Graphiques trop petits ou trop fins. C'est pour un affichage mobile : le graphique principal doit occuper au moins la moitié de la largeur de l'écran (largeur ≥ 800 ou hauteur ≥ 400), utilise ctx.spread(n) pour remplir la largeur avec une rangée d'éléments, épaisseur de ligne ≥ 9, taille de police ≥ 44. Voir section 1 de references/visuals.md pour les dimensions de référence
• Chaque phrase doit avoir une image. Graphiques, lettres animées ou formules : au moins un élément doit être au centre de l'écran, ne laisse aucune phrase avec seulement l'arrière-plan et les sous-titres

5. Vérification et aperçu

python $SKILL/scripts/overlay_engine.py <répertoire_du_projet> check          # Obligatoire : 0 problème de storyboard, 0 erreur de rendu ; vérifie chaque « alerte de mise en page »
python $SKILL/scripts/overlay_engine.py <répertoire_du_projet> sheet          # aperçu_storyboard.jpg : vue d'ensemble phrase par phrase
python $SKILL/scripts/overlay_engine.py <répertoire_du_projet> sheet --pages  # En plus, aperçu_storyboard_p1.jpg… : pages de grande image pour voir si le texte touche les bords (la vue d'ensemble est aussi mise à jour)
python $SKILL/scripts/overlay_engine.py <répertoire_du_projet> frames "L(18)" "L(19)" 0.2   # storyboard_image_par_image.jpg : décompose une animation image par image

Ouvre les images toi-même et vérifie image par image contre le tableau de storyboard :

• Vue d'ensemble : est-ce que tout ce qui doit apparaître à chaque phrase est présent, y a-t-il une case vide ?
• Pages de grande image : les textes se chevauchent-ils ? Touchent-ils la bannière de formule ou les sous-titres ? Les graphiques sont-ils assez épais et assez grands ?
• Pour les mouvements, rotations, entrées : utilise frames pour vérifier s'ils entrent en collision avec d'autres éléments en cours de route
• Les « alertes de mise en page » de check indiquent des instants à vérifier un par un (il signale : toucher la bannière, écraser les sous-titres, chevauchement avec la formule, toucher un bord, graphique trop petit, espace vide au centre, texte qui se chevauche)
• Ce que check ne détecte pas : texte illisible sur une ligne ou une zone colorée, nombre d'éléments graphiques erroné, couleurs pas assez vives. Seule une inspection visuelle des grandes images peut les révéler

En cas de problème, corrige à l'étape 4 et revérifie. Une fois tout bon, envoie la vue d'ensemble à l'utilisateur pour validation, puis passe au montage.

6. Montage

python $SKILL/scripts/build_video.py <répertoire_du_projet> bg            # Choisit et assemble les arrière-plans, imprime quel segment utilise quel fichier
python $SKILL/scripts/build_video.py <répertoire_du_projet> final 20 30   # Optionnel : d'abord un extrait de 10 secondes pour voir le rendu
python $SKILL/scripts/build_video.py <répertoire_du_projet> final         # Vidéo complète, environ 6–12 minutes (selon la puissance de l'ordinateur), lance en arrière-plan
python $SKILL/scripts/build_video.py <répertoire_du_projet> sheet         # vidéo_finale_vue_ensemble.jpg
python $SKILL/scripts/make_vertical.py <répertoire_du_projet> --title "Titre"   # Optionnel : version verticale (TikTok, Kuaishou, WeChat Video)

bg détecte automatiquement si chaque segment contient des graphiques ; si oui, il ne choisit que des segments « calmes » (pas de gros plan de visage lumineux), et l'indique dans la liste imprimée. Après avoir vu les aperçus, tu peux aussi lancer build_video.py <répertoire_du_projet> all qui enchaîne check + bg + final + vue d'ensemble en une seule commande. La version verticale place la vidéo paysage au centre d'un cadre 1080×1920, ajoute un titre en haut et du petit texte en bas, remplit l'arrière-plan avec un agrandissement flou de la vidéo ; elle ne réorganise pas les graphiques en version verticale. Si --title n'est pas fourni, le titre est lu depuis storyboard.json → vertical.title ; sinon, utilise le titre du fichier de paroles.

7. Vérifier et livrer

Regarde vidéo_finale_vue_ensemble.jpg : l'arrière-plan est-il assez sombre ? Les graphiques et le texte sont-ils clairs ? Y a-t-il un visage lumineux en arrière-plan qui se trouve juste derrière les lettres animées ou le texte explicatif ? (Si oui, ajoute :quiet ou spécifie un segment dans le plan d'arrière-plan pour cette phrase, puis relance bg et final.) Ensuite, livre vidéo_finale.mp4 à l'utilisateur en précisant :

• Les images et les temps ont été vérifiés par les scripts, mais le son doit être écouté par une personne : demande-leur de vérifier en particulier que l'affichage de la formule et l'apparition des résultats numériques coïncident bien avec le chant
• Pour les phrases où le taux de correspondance était faible à l'étape 3, demande-leur de les écouter attentivement

Fichiers de référence

Fichier	Quand le lire
references/lyrics.md	Avant d'écrire la formule, les paroles et le tableau de storyboard
references/audio.md	Quand l'utilisateur demande « quel outil pour la musique/la voix ? » ; pour envoyer les exigences audio au client ; pour valider et choisir l'audio
references/visuals.md	Avant d'écrire storyboard.json et graphics.py (mise en page, champs, outils de dessin, schémas de sujets courants)
references/library.md	Pour ajouter un segment à la bibliothèque, générer un nouvel arrière-plan, ou si l'arrière-plan choisi ne convient pas
references/troubleshooting.md	En cas d'erreur ou de résultat inattendu à n'importe quelle étape
references/teaching.md	Quand l'utilisateur veut comprendre le fonctionnement, apprendre à d'autres, ou ne veut pas coder (méthode avec CapCut)
references/compatibility.md	Quand l'utilisateur demande « une autre IA / un autre modèle peut-il le faire ? » ; quand tu transmets le skill à quelqu'un d'autre
examples/shuxianduan/	Exemple complet : paroles, storyboard, graphiques. À lire avant d'écrire un nouveau sujet

Liste des scripts

Script	Rôle
check_env.py	Auto-vérification de l'environnement
new_project.py	Crée un nouveau répertoire de projet
check_lyrics.py	Vérifie les paroles
prepare_audio.py	Audio + sous-titres → timing.json, et donne une conclusion (utilisable / à essayer autre)
overlay_engine.py	Vérification, aperçu, rendu de la couche de superposition
build_video.py	Choix de l'arrière-plan, montage de la vidéo finale, génération de la vue d'ensemble
make_vertical.py	Vidéo paysage → version verticale
library_tool.py	Gère la bibliothèque d'arrière-plans (ajouter, supprimer, modifier les étiquettes, vue d'ensemble)
gen_music.py	Optionnel : génère une chanson avec ElevenLabs
install.py	Installe ce skill dans d'autres outils IA (Codex, Gemini CLI, opencode, etc.), place la bibliothèque
chat_pack.py	Génère un pack d'instructions pour les IA qui ne peuvent que discuter (écrire des paroles / écrire des visuels / corriger d'après les résultats de vérification)