Under the Hood (Sous le capot)

Sous le capot

Transforme un sujet (ou le code de l'utilisateur) en une vidéo explicative animée et narrée. Le rendu visuel est chaleureux et dessiné à la main :

• fond « papier » crème à points quadrillés et traits à l'encre
• bleu pour les requêtes, orange pour les réponses, vert pour le chiffré ou le succès
• un compteur d'étapes en haut et de grands sous-titres en bas
• des paquets qui volent entre les boîtes, et des panoramiques entre les « mondes »

Le résultat de référence se trouve dans ${CLAUDE_SKILL_DIR}/assets/example-cookie/, qui montre ce qui se passe quand on tape « cookie » dans Google. Ouvrez son fichier scenes.js chaque fois que vous avez besoin d'un modèle pour quelque chose de complexe.

Tout est piloté par le code. Une page canvas rend les images de façon déterministe, les clips de narration définissent la durée de chaque scène, et la musique et les effets sonores sont synthétisés à partir de la même timeline. Un changement de script resynchronise tout, et une vidéo de 60 secondes est rendue en environ 30 secondes.

Sujet demandé : $ARGUMENTS

Où se trouve quoi

• Scripts : ${CLAUDE_SKILL_DIR}/scripts/ (appelez-le SCRIPTS).
• Environnement d'exécution : UTH_HOME (par défaut ~/.local/share/under-the-hood) contient le module node, l'environnement virtuel TTS et les voix sauvegardées. doctor.sh affiche les chemins exacts, y compris PY (le Python TTS).
• Projets : ./explainers/<slug>/ dans le répertoire de travail courant, sauf si l'utilisateur indique un autre emplacement. Si le répertoire de travail est le dossier personnel, demandez où le placer pour ne pas encombrer ~.

Un dossier de projet ressemble à ceci :

index.html  engine.js  scenes.js  script.json  timeline.js
narration/  (clips vocaux : <id>.wav, <id>_take2.wav, plus fichiers de prévisualisation)
audio/      (pistes et mix.wav)
.shots/     (captures d'écran, un nouveau dossier par exécution)
<slug>.mp4

Flux de travail

0. Vérifier la configuration (une ligne quand prêt)

bash ${CLAUDE_SKILL_DIR}/scripts/doctor.sh          # ajoutez --no-tts si la vidéo n'a pas de narration

S'il affiche READY, notez PY et VOICES et passez à la suite. S'il affiche des lignes MISSING, chargez le skill under-the-hood-setup et suivez-le, puis relancez doctor.

1. Entretien court

Si $ARGUMENTS est vide, demandez le sujet. Ensuite, ne demandez que ce que vous ne pouvez pas décider raisonnablement, en un seul message, avec des valeurs par défaut sensées :

• Angle, uniquement si le sujet est large. « Comment fonctionne internet » a besoin d'un focus, « ce qui se passe quand on fait git push » non.

• Voix : proposez-la toujours, car les utilisateurs ne savent pas que leur propre voix est une option. Présentez-la ainsi :

  1. voix intégrée (par défaut, fonctionne immédiatement)
  2. une voix sauvegardée, si VOICES en liste une
  3. votre propre voix : enregistrez environ 20 à 30 secondes sur votre téléphone et envoyez le fichier. Votre voix reste sur votre machine.
  4. pas de narration (musique et effets sonores uniquement)

  S'ils choisissent leur propre voix, lisez ${CLAUDE_SKILL_DIR}/references/voice.md et donnez-leur ses conseils d'enregistrement et son paragraphe d'exemple avant toute autre chose. Ils peuvent enregistrer pendant que vous écrivez le storyboard.

• Durée : par défaut 30 à 60 secondes, 16:9.

Ne transformez pas cela en questionnaire. Deux ou trois questions courtes au maximum.

2. Comprendre le sujet et obtenir les faits corrects

Si l'utilisateur a donné du code, lisez-le et tracez le flux réel. Les spectateurs techniques repéreront les erreurs. Donc :

• Obtenez l'ordre des événements correct. Exemple : sur une page déjà chargée, le DNS et la poignée de main TLS ont déjà eu lieu, placez-les donc au premier contact ou étiquetez-les « première visite ».
• Préférez ce que les systèmes modernes font réellement. Exemple : Chrome parle à Google via QUIC et TLS 1.3, pas une poignée de main TCP à trois voies de manuel.
• Dites « simplifié » dans un sous-titre lorsque vous simplifiez.
• Utilisez des valeurs illustratives (adresses IP d'exemple, domaines .example, scores inventés) et évitez la précision factice comme des comptes de millisecondes exactes.
• Ne recréez pas les logos ni les interfaces utilisateur pixel par pixel des produits réels. Les substituts au trait conviennent mieux au style.

3. Storyboard et script, puis approbation avant de construire

Prévoyez 4 à 8 étapes numérotées, environ 30 à 60 secondes, plus une scène title au début et une scène end à la fin. Pour chaque scène, écrivez :

• Narration (script.json) : {"id", "text", "gap"}. gap est la pause après la ligne, 0,25 à 0,45 secondes.
• Sous-titre (cap) : 8 mots ou moins, lisible en mode muet. Sous-titre secondaire (sub) : une ligne courte.
• Beat visuel : ce qui apparaît et bouge, et quel est chaque son.

Lisez ${CLAUDE_SKILL_DIR}/references/narration.md avant d'écrire la narration. Une narration de type article ressemble à une IA lisant un article. Écrivez comme une personne qui explique à un ami.

Montrez à l'utilisateur le script et le storyboard sous forme de tableau court et attendez son feu vert. Modifier les mots maintenant est gratuit. Après la génération vocale, cela coûte une nouvelle exécution.

Pas de tirets cadratins ni de points-virgules dans la narration ou le texte à l'écran. Le TTS les lit bizarrement, et les phrases courtes sonnent de toute façon plus naturelles.

4. Échafaudage

bash SCRIPTS/new_project.sh ./explainers/<slug> "<Titre de la page>"

Ceci copie engine.js, un scenes.js de démarrage (un petit exemple fonctionnel « appuyer sur envoyer ») et script.json. Il refuse d'écraser un dossier non vide. Remplacez le contenu de démarrage par le vrai storyboard.

5. Construire scenes.js

Lisez d'abord ${CLAUDE_SKILL_DIR}/references/engine-api.md. Il couvre le modèle temporel, chaque helper, les zones de disposition, les noms de sons et la configuration de démarrage. Idées clés :

• defineScenes([...]) avec des durées de conception. Animez en temps de conception avec prog(t, S.id + a, S.id + b). Le moteur étire chaque scène pour s'adapter à son clip vocal, donc ne réglez jamais manuellement les longueurs de clip.
• Gardez le monde dans y 150 à 800. Le compteur se trouve au-dessus et les sous-titres en dessous.
• Les éléments qui doivent persister (un navigateur, un serveur) apparaissent dans une scène et restent dessinés après.
• Pour un deuxième « lieu », comme à l'intérieur d'un centre de données, dessinez à x + 1920 et panoramiquez avec camera(t). Commencez à révéler son contenu pendant le panoramique afin que l'écran ne soit jamais vide en cours de déplacement.
• Chaque événement visible reçoit un son avec sfx(add). Les clés obtiennent key, les paquets volants obtiennent whoosh*, les arrivées obtiennent thunk ou pop, le succès obtient chime ou success. C'est une grande partie de ce qui donne l'impression que c'est fini.

6. Prévisualisation sans voix, vérifier les images

node SCRIPTS/shots.js <projet>            # milieu de chaque scène, sauvegardé dans un nouveau dossier .shots/<time>/

Regardez chaque capture d'écran. Réduisez avant de lire (sips -Z 960 sur macOS, ffmpeg -i in.png -vf scale=960:-1 out.png ailleurs). Vérifiez :

• le texte qui se chevauche ou dépasse des bords
• les images vides pendant les panoramiques
• les éléments dessinés par-dessus des choses derrière lesquelles ils devraient se trouver

Corrigez et refaites les captures. Si la page ne démarre pas, le script affiche les erreurs de la page.

7. Voix

Voix intégrée (sans --voice) :

$PY SCRIPTS/narrate.py --script <projet>/script.json --out <projet>/narration --takes 2

Une voix sauvegardée : ajoutez --voice <UTH_HOME>/voices/<nom>.wav.

Une nouvelle voix à partir d'un enregistrement : suivez ${CLAUDE_SKILL_DIR}/references/voice.md. Il couvre prep_voice.sh, une ligne de test rapide et le consentement. Ne clonez que la voix de l'utilisateur, ou une voix dont il confirme avoir le consentement d'utilisation.

Ensuite, demandez à l'utilisateur d'écouter : <projet>/narration/narration-preview_take1.wav (utilisez open sur macOS, xdg-open sur Linux).

• La première exécution télécharge environ 1 Go de poids de modèle. Ensuite, elle tourne environ en temps réel sur Apple Silicon ou GPU, plus lentement sur CPU.
• Vous ne pouvez pas entendre l'audio. Dites-le à l'utilisateur et demandez-lui de juger les prises à l'oreille. Il peut mélanger les prises ligne par ligne. Refaites une seule ligne avec --only <id>.
• Turbo prend en charge les balises comme [chuckle], [laugh], [sigh], [gasp] et [surprised]. Utilisez au maximum une ou deux par vidéo.

Pas de narration : sautez cette étape et build_timeline.py. Les scènes conservent leurs durées de conception, et la vidéo n'obtient que musique et effets sonores.

8. Timeline, rendu, vérification

python3 SCRIPTS/build_timeline.py <projet> [--pick dns=2,enter=2]
node SCRIPTS/render.js <projet> [--music-db -12] [--sfx-db 1] [--silent] [--audio-only]

render.js construit les pistes vocale, musicale et d'effets sonores et les mixe, en abaissant la musique sous la voix et en normalisant à -16 LUFS. Il rend vers <slug>.partial.mp4 et ne renomme en <slug>.mp4 qu'après confirmation par ffprobe de la durée totale.

Avant de dire à l'utilisateur que c'est terminé, vérifiez le fichier réel :

• ffprobe montre la durée attendue plus les flux vidéo et audio
• ffmpeg -ss <temps tardif> -frames:v 1 montre la bonne scène
• la loudness est d'environ -16 LUFS

Ouvrez ensuite le MP4 et la prévisualisation index.html. La prévisualisation joue le mix en synchronisation, avec des chapitres et le défilement.

Rapportez simplement ce qui a été vérifié, ce que vous n'avez pas pu vérifier (comment sonne l'audio) et quelles parties sont simplifiées.

Règles de travail

• Pas de suppressions globales. N'exécutez pas rm avec des wildcards ou rm -rf sur les dossiers de projet. Les nouvelles sorties vont dans de nouveaux dossiers, et les fichiers sont écrasés par nom.
• Une commande arrêtée peut avoir partiellement fonctionné. Si l'utilisateur arrête une commande en plusieurs étapes, vérifiez ce qui a changé sur le disque avant de continuer et informez-le des effets partiels. Un ensemble de clips à moitié échangé peut laisser une courte vidéo partielle qui semble terminée.
• Ne basculez pas automatiquement sur des indices de préférence. Si l'utilisateur dit « j'aime la prise 2 » tout en décidant encore, confirmez avant de re-rendre.
• Proposez, ne construisez pas : une version verticale 9:16, un rognage à 30 secondes ou plus de polish. Mentionnez-les en une ligne chacun.

Dépannage

• 'NoneType' object is not callable à PerthImplicitWatermarker : exécutez uv pip install --python $PY "setuptools<81". La bibliothèque de watermark de Chatterbox a besoin de pkg_resources.
• La première exécution TTS est lente : c'est le warmup et le téléchargement du modèle. Les exécutions suivantes sont plus rapides.
• Musique trop forte ou trop faible : --music-db (par défaut -12). Effets : --sfx-db (par défaut 1). Utilisez --audio-only pour itérer rapidement sur le mix.
• Chrome non trouvé : définissez CHROME_PATH, ou chargez le skill under-the-hood-setup.
• L'audio hors ligne de Chrome n'est pas bit-identique d'une exécution à l'autre, donc les pistes diffèrent légèrement entre les rendus. Le timing est exact et les images sont pixel-identiques.