jjietay/kaleidoscope

Vidéo explicative

Vous créez une vidéo qui aide l'utilisateur à apprendre un concept. Vous avez un grand avantage par rapport à un outil neuf : vous connaissez cette conversation et ce projet. Utilisez ces connaissances.

Le moteur se trouve dans ~/.claude/skills/kaleidoscope/engine/. Dans ce fichier, make signifie :

node ~/.claude/skills/kaleidoscope/engine/make.mjs <commande> <répertoire-du-projet>

Étape 0 : demander d'abord (à chaque démarrage de la compétence)

Que l'utilisateur ait tapé /kaleidoscope ou demandé une vidéo en mots, la première chose à faire est de poser les questions ci-dessous avec AskUserQuestion, avec des options cliquables. Omettez chaque question à laquelle le message de l'utilisateur ou cette conversation répond déjà (par exemple, « sous forme de journal d'actualités » répond au style, et « avec de la musique lo-fi » répond à la musique). Mettez l'option recommandée en premier et marquez-la « (Recommandé) ». Posez les quatre questions en un seul appel (l'outil en accepte au maximum 4). Si le sujet lui-même n'est pas clair et qu'aucune question n'est ignorée, posez d'abord la question sur le sujet, dans son propre appel.

Question	En-tête	Options (première = par défaut)
Quel style la vidéo doit-elle utiliser ?	Style	Pâte à modeler 3D : un aspect doux en pâte à modeler, avec le mascotte silencieuse qui fait le travail · 2D classique, mixte : un style 2D différent pour chaque partie · 2D classique, un style : l'utilisateur le nomme (journal d'actualités, tableau blanc, ...)
À qui s'adresse la vidéo et quelle durée ?	Public	Révision d'examen, standard : la notation du cours, des nombres travaillés, les pièges d'examen, 5 à 6 min · Révision d'examen, approfondie : la même chose, 8 à 9 min, chaque étape de la dérivation · Débutant, court : intuition d'abord, moins de symboles, 2 à 4 min · (Autre : l'utilisateur nomme un public et une durée, par exemple « rappel pour expert, court »)
Quand dois-je vérifier avec vous ?	Point de contrôle	En une seule fois : revenez avec la vidéo terminée · Après le storyboard : montrez le plan et attendez l'approbation · Après le premier rendu : montrez les premières images et attendez
Quelle musique ?	Musique	Calme (current) : nappe douce, sans rythme · Lo-fi (lofi) : rythme léger, plus d'énergie · Aucune

Mettez une option recommandée en premier lorsque la conversation en suggère une (un examen la semaine suivante : Révision d'examen, approfondie). Si le message ne répond qu'à une moitié de la question sur le public (par exemple « pour mon examen »), gardez la question et proposez uniquement les options qui correspondent à cette moitié. Les publics sont : révision d'examen, débutant et rappel pour expert (rapide et dense) ; les durées sont : courte (2 à 4 min), standard (5 à 6 min) et approfondie (8 à 9 min). Écrivez les réponses dans video.json à l'étape 4 : "_look" (clay ou classic), "_brief": { "viewer": ..., "length": ..., "checkpoint": ..., "style": ... } et "_render": { "music": "current" | "lofi" | false }. Chaque étape suivante, et une reconstruction, les lit à cet endroit et ne redemande pas. Si l'utilisateur ignore les questions, utilisez la première option de chacune.

En une seule fois, sauf si l'utilisateur a choisi un point de contrôle

Après l'étape 0, effectuez chaque étape ci-dessous sans vous arrêter, et revenez uniquement avec la vidéo terminée et vérifiée. Ne demandez pas « dois-je continuer ? », ne montrez pas de brouillons, n'attendez pas entre les étapes. Chaque vérification ci-dessous est à vous d'effectuer et d'agir en conséquence. Les seuls arrêts sont le point de contrôle choisi par l'utilisateur : « Après le storyboard » s'arrête après l'étape 7 (montrez le storyboard et le verdict de l'agent de script, puis attendez), et « Après le premier rendu » s'arrête au premier make look de l'étape 9 (montrez ses images, puis attendez).

Le style souhaité par l'utilisateur (à lire avant l'étape 6)

Pâte à modeler pour les choses qui agissent, Manim pour les graphiques, et le mascotte est dans chaque vidéo. Lisez styles/clay.md. L'utilisateur a choisi le style pâte à modeler plutôt que l'ancien mixte pour la cohérence entre les vidéos. Les styles 2D sont un style classique optionnel ; voir la section ci-dessous.

• Ne forcez pas un graphique en pâte à modeler (l'utilisateur l'a demandé). Lorsqu'une image 2D Manim aide le spectateur à comprendre plus que la pâte à modeler (une courbe, une distribution, un contour, une projection ou une autre géométrie dans un plan), faites de cette partie une partie Manim, sur le fond sombre de Manim (styles/math-manim.md). Ne construisez jamais un modèle en pâte à modeler qui copie une courbe mathématique : l'utilisateur les a fait enlever. Les objets qui agissent, et le travail physique du mascotte, restent en pâte à modeler. Une vidéo peut passer d'une partie en pâte à modeler à une partie Manim et revenir, avec la même couleur pour la même chose.

• Un style, plusieurs parties. La vidéo est divisée en parties d'environ 15 à 40 s (accroche, chaque idée, votre cas, conclusion). Chaque partie a son propre fond uni, sa caméra et son décor. Deux parties ne partagent jamais le même fond si elles sont côte à côte.

• Le mascotte fait le travail. Il est silencieux, sans synchronisation labiale, et le narrateur est une voix off. Il marche, tire, pousse, porte et éteint les choses de ses propres mains, donc une force dans le script est quelque chose que le spectateur le voit faire. L'utilisateur l'a demandé après une vidéo où il restait debout et regardait. Il reste impassible par défaut, et make check AVERTIT lorsqu'il reste au même endroit.

• Les choses doivent se connecter. Un ressort atteint son mur, une broche touche sa carte, une main touche ce qu'elle tient. L'utilisateur a trouvé un ressort qui manquait son mur après que chaque vérification avait été passée. make bake mesure chaque jointure dans models.js (JOINS), donc ajoutez de nouvelles jointures là, et recherchez le contact dans les images fixes.

• Uniquement nos propres modèles. Utilisez la trousse dans styles/library/clay. Ne téléchargez jamais de modèle. Si une vidéo a besoin d'un nouvel objet, ajoutez-le à la trousse dans le même style.

• Chaque partie est un seul plan continu. Dans une partie, il n'y a ni coupures ni nouvelles diapositives : les objets arrivent, bougent et se joignent pendant que la voix parle, et la caméra bouge lentement. Une partie se termine dans l'état dans lequel la partie suivante commence, ou par un fondu dans le fond de la partie suivante.

• L'image explique ; le texte ne fait que nommer. Le texte reste plat et net, en HTML par-dessus la 3D. Par image : un chapeau (petites capitales, la partie et une source), un titre d'au plus 8 mots, quelques étiquettes de 1 à 4 mots chacune avec de fines lignes de repère, et au plus une ligne de légende en bas. Jamais une colonne de phrases, jamais une liste à puces, jamais une légende de ce que les couleurs signifient. Au maximum 15 mots à l'écran.

• Les formules jouent la voix (l'utilisateur l'a demandé). Une formule fixe ne vaut pas mieux que la lecture de notes. Construisez chacune avec eqn() : les termes arrivent lorsqu'ils sont prononcés, bougent lorsque la voix les déplace, frappent et explosent lorsqu'elle dit annuler, et rebondissent seulement lorsqu'elle nomme quelque chose d'important. make look donne une erreur pour une formule qui reste immobile, et pour une phrase « annule » sans annulation à l'écran. Voir styles/clay.md.

• Mouvement physique. Les choses bougent comme des objets : un bras s'étire, une balle tombe et rebondit, un bloc tombe et se stabilise, une impulsion se déplace. Pas d'accumulation de boîtes statiques.

• Le même objet garde sa couleur dans chaque vidéo (le robot est toujours orange, la carte toujours jaune).

Si un storyboard enfreint l'une de ces règles, modifiez le storyboard avant d'écrire du code.

Règles strictes

• Faites la réflexion ici, dans la conversation principale. Vous écrivez le script, le storyboard et les scènes vous-même, car le contexte est ici. Ne donnez jamais ces étapes à un sous-agent : un sous-agent commence sans contexte. L'agent de script à l'étape 7 est la seule exception, et il démarre à froid intentionnellement.
• Ne précipitez jamais l'explication principale. L'utilisateur apprend de ces vidéos. Suivez les règles de rythme dans reference/script.md et corrigez chaque AVERTISSEMENT de rythme.
• N'inventez jamais un fait. Chaque nombre, formule et affirmation provient d'une source que vous avez vérifiée : le code de l'utilisateur, une fiche technique, une spécification, un article, la documentation. Listez-les dans storyboard.md. Signalez tout ce que vous n'avez pas pu vérifier.
• « Votre cas » est optionnel. Ajoutez-le uniquement lorsque cette conversation ou ce projet contient vraiment un exemple correspondant (un bogue rencontré par l'utilisateur, une correction, un nombre mesuré). N'en inventez jamais.
• Aucun chevauchement. Aucun visuel ne peut en recouvrir un autre : texte sur texte, texte sur un graphique, ou un graphique qui en cache un autre. Chaque étiquette, formule, flèche et objet obtient son propre espace. check AVERTIT sur les textes qui se chevauchent, et review écrit chaque chevauchement mesuré dans overlaps.md. L'encombrement est le jugement de l'utilisateur, donc recherchez-le dans les images en taille réelle. La passe d'identification aide : make look ajoute une image des écarts les plus serrés, et AVERTIT pour un texte à moins de 12 px d'une autre chose, un texte sur un dessin, un faible contraste de texte et un modèle que d'autres cachent. Corrigez chaque chevauchement avant make final.
• Les sous-titres ont une seule ligne. Chaque réplique fait au plus 42 caractères et deux répliques ne s'affichent jamais en même temps, donc un lecteur ne montre jamais deux lignes. Le moteur fait cela ; verify signale une réplique qui enfreint la règle. Ne modifiez pas SUB_MAX dans make.mjs pour faire tenir une réplique.
• La boucle fermée (l'utilisateur l'a demandée, et le moteur l'applique). Après chaque modification : make look, lisez chaque image qu'il liste, corrigez ce que vous voyez, et regardez à nouveau. Ne construisez qu'ensuite. Ne modifiez et ne construisez jamais à l'aveugle, car une construction est longue et un look prend quelques secondes. Chaque image a un CHIFFRE DE CONTRÔLE en haut à droite, et les portes ne s'ouvrent qu'avec les chiffres de toutes les images, dans l'ordre :

1. Modifier. Si vous avez modifié script.md, exécutez make voice. Si la vidéo a des parties Manim et que vous avez modifié manim_scenes.py ou la voix, exécutez make manim : make look dessine les images Manim, il ne les fabrique pas.
2. make look <répertoire> : il mesure chaque scène modifiée sur chaque image et dessine ses images proches et ses parties mobiles. Lisez-les toutes. Ensuite make look <répertoire> --ok <chiffres>. make build s'arrête sans cela.
3. make build <répertoire>. Il s'arrête sur toute collision.
4. Lisez chaque bande dans build/review/moving.md. Ensuite make look <répertoire> --moving-ok <chiffres>.
5. make final <répertoire>. Il s'arrête si la source a changé après le look ou la construction, ou si une collision ou un chevauchement est ouvert. Exécutez chaque étape comme sa propre commande, arrêtez-vous à la première défaillance et confirmez qu'une modification a été appliquée.

• Chaque lecteur vérifie les images proches et les parties mobiles. Tout agent ou session qui juge une vidéo lit les images proches de chaque partie modifiée, et toutes les images de chaque chose qui bouge : le mascotte et les objets, pendant tout leur mouvement. Un échantillon de la vidéo ne compte pas : une main a traversé une table entre les images échantillonnées.
• Un nouveau défaut obtient une barrière de protection. Lorsque l'utilisateur trouve un défaut, ajoutez-le d'abord à reference/faults.md et à engine/test/selftest.mjs, et confirmez que le test échoue dessus. Ensuite, corrigez la vidéo. Ne corrigez pas seulement la vidéo. Exécutez make selftest après chaque modification d'une vérification.

Ce que l'utilisateur a demandé (conservez-les)

Chacun a été demandé ou choisi à l'oreille. Le moteur fait la plupart d'entre eux automatiquement.

Sujet	Quoi	Automatique ?
Voix	La voix intégrée de Chatterbox, ralentie à environ 160 mots par minute par engine/tts/slow-reference.wav ; chaque paragraphe lu d'un trait pour que le ton porte	oui
Pauses	chaque point final exactement 0,6 s, chaque virgule au plus 0,3 s, définies à partir de la ponctuation du script	oui ; voice AVERTIT si une pause n'a pas pu être placée
Mauvaises prises	une partie dont les mots diffèrent du script (vérification Whisper) est reprise avec une nouvelle graine, jusqu'à 3 fois ; la meilleure prise est conservée	oui ; AVERTIT si toujours faux
Passages rapides	un membre de phrase plus de 1,3 fois le rythme habituel de la vidéo (les mots symboliques comptent double) est repris ; l'utilisateur a trouvé « lambda v est v, multiplié par lambda » trop rapide	oui ; AVERTIT « rapide » : donnez-lui sa propre courte phrase et un [pause]
Nombres négatifs	lisez « négatif », jamais « moins »	voice s'arrête avec une ERREUR
Mots répétés	« un un » reçoit une virgule (« un, un »), ou la voix trébuche	oui
Écriture	paragraphes connectés ; [pause] seulement là où une idée se termine ou une animation se joue. Rejeté : une pause après chaque phrase, des phrases saccadées, une voix rapide, une voix étirée (sourde), Kokoro	vous, voir reference/script.md
Musique	audible, régulière, environ 13 dB en dessous de la voix (musicVolume 0,37 ; l'utilisateur l'a augmentée de 3 dB par rapport à 0,26), ducking doux ; deux pistes approuvées, current (par défaut) et lofi. Rejeté : pompage fort-doux, musique trop douce pour être entendue, 4 autres pistes	oui ; vous choisissez la piste, voir SOUND.md
Effets sonores	la trousse dans engine/sfx.mjs, approuvée à l'oreille ; le whoosh d'entrée 4 dB en dessous des autres accents (l'utilisateur l'a trouvé un peu trop fort). Activé pour les nouvelles vidéos (_render.sfx: true), désactivé pour les anciennes	vous ajoutez s.sfx aux repères ; le moteur les mixe
Audio	48 kHz stéréo	oui ; verify le vérifie
Sous-titres	doux, jamais incrustés ; le mpv de l'utilisateur les montre petits (sub-scale=0.7)	oui
Une ligne de sous-titre	une ligne par réplique, au plus 42 caractères, pas deux répliques en même temps. L'utilisateur a vu deux lignes dans la vidéo 1 de l'ensemble ROS 2	oui ; verify signale une réplique qui enfreint la règle
Pas de chevauchements	aucun texte ou graphique n'en recouvre un autre	check AVERTIT pour les textes, overlaps.md et votre liste de contrôle d'images pour le reste
Style	un aspect 3D pâte à modeler avec le mascotte silencieux, et nos propres modèles ; parties Manim sur fond sombre pour les courbes et graphiques (l'utilisateur a demandé : ne forcez pas un graphique en pâte à modeler). Rejeté : modèles téléchargés, vidéo entièrement sombre, colonnes de texte, légendes de couleurs, diapositives d'accumulation	make check ERREUR pour une scène qui n'est ni pâte à modeler ni Manim, ou une vidéo sans mascotte ; le reste est vous, voir « Le style souhaité par l'utilisateur »
Maths	les cinq étapes de formule (besoin, image, formule, signification, test). Manim pour une courbe, un graphique ou une formule qui change étape par étape : manim() en 2D, ou manim({ threeD: true }) pour une image 3D, pas un canvas dessiné à la main	make check AVERTIT sur une formule seule ; le reste est vous, voir reference/script.md et styles/math-manim.md
Quiz	aucun dans le storyboard	vous
Regarder	mpv <répertoire>/out/<slug>.mp4	mettez-le dans le rapport

Paramètres machine

Exécutez make config avant l'étape 1. Cela affiche les paramètres de cette machine, que l'installeur ou /setup-kaleidoscope a écrits.

La ligne voice nomme la voix : Chatterbox (naturelle, meilleure sur un GPU NVIDIA ou Apple silicon) ou Kokoro (petite et rapide sur un CPU, à environ 150 mots par minute). Un projet peut choisir la sienne dans video.json : "_tts": {"engine": "kokoro"}. Sans GPU, Chrome dessine les images avec SwiftShader et ffmpeg encode avec libx264