anniebellb/leçon-données-narrée

Leçon de données narrée

Construit une leçon semblable à l'exemple de référence (« qui passe notre temps avec nous, par âge ») : une vidéo narrée qui s'exécute sur un graphique en direct, puis un onglet Explorer où les apprenants jouent avec les données. Une leçon = un dossier avec index.html, lesson.json, data.json, video.json (storyboard), l'audio de la narration et éventuellement une trame musicale.

À lire d'abord : references/design-rules.md (apparence, mouvement et règles d'emphase approuvées ; suivez-les exactement) et references/user-guidance.md (comment travailler avec l'utilisateur).

Les chemins ci-dessous sont relatifs au dossier de ce skill (${CLAUDE_SKILL_DIR}).

Avec qui vous travaillez

Partez du principe que l'utilisateur n'est pas technique. Parlez simplement, étape par étape, et dites-lui exactement sur quoi cliquer quand une action est nécessaire (télécharger un fichier, se connecter à ElevenLabs, approuver un script). Ne lui demandez jamais d'éditer du code ou du JSON. Utilisez les procédures pas à pas dans references/user-guidance.md.

Le workflow (avec points de contrôle et auto-contrôles)

Exécutez l'auto-contrôle à la fin de chaque étape. Ne passez pas à l'étape suivante avec un ÉCHEC.

1. Obtenir les données

• Acceptez un lien, un fichier ou un PDF. Si un lien est bloqué (les sites bloquent souvent les téléchargements automatisés), guidez l'utilisateur pour qu'il le télécharge dans son navigateur et partage le fichier.
• Profilez-les : python3 scripts/profile_data.py <fichier-ou-url>.

2. Est-ce que ça correspond ? (dites-le à l'utilisateur, toujours)

Lisez les verdicts du profileur et references/chart-chooser.md, puis dites à l'utilisateur en langage simple :

• Correspond : « Cela fonctionne comme ___ parce que ___. » Nommez la question d'apprentissage à laquelle il répond.
• Correspond partiellement : ce qui fonctionne, ce qui manque, et le compromis.
• Ne correspond pas : dites-le clairement, expliquez pourquoi, et décrivez quelles données fonctionneraient. Ne forcez pas.

✋ Point de contrôle 1 : type de graphique et angle de l'histoire

Proposez le type de graphique, la question d'apprentissage principale, et 4 à 6 temps forts de l'histoire (les choses que le narrateur soulignera), chacun lié à un nombre que vous calculerez. Attendez l'accord de l'utilisateur.

3. Façonner les données

• Créez le dossier de la leçon : python3 scripts/new_lesson.py --chart <type> --out <dossier>.
• Écrivez un petit script réexécutable (dans le dossier de la leçon) qui transforme la source en data.json au format du graphique (references/data-formats.md) et écrit facts.json : chaque nombre que le narrateur dira, calculé à partir des données source, avec la façon dont il sera énoncé.
• Auto-contrôle : python3 scripts/check_lesson.py <dossier> ; vérifiez aussi 2 à 3 valeurs à la main par rapport à la source (ouvrez le fichier brut et trouvez-les). Rapportez ce que vous avez vérifié.

4. Écrire l'histoire

• Écrivez video.json (scènes, temps forts, repères) en suivant references/storyboard.md et l'arc narratif dans design-rules §1 (accroche d'intro → comment lire le graphique → temps forts de l'histoire → résumé → réflexion → « à vous de jouer »).
• Écrivez le script de narration dans le style ElevenLabs (references/narration.md) dans narration/script.txt. Chaque affirmation doit correspondre à facts.json ; évitez les exagérations (design-rules §8).
• Remplissez lesson.json : titre, accroche, étiquette clé, descriptions des groupes, notes, sources.

✋ Point de contrôle 2 : approuver le script

Affichez le script en texte brut. Proposez des options lorsque l'utilisateur demande ; n'appliquez pas de modifications qu'il n'a pas approuvées.

5. Aperçu (avant tout enregistrement)

• Aperçu silencieux : python3 scripts/estimate_timing.py <dossier>/video.json --out <dossier>/narration/narration.words.json puis python3 scripts/time_storyboard.py <dossier>/video.json <dossier>/narration/narration.words.json.
• Servez et ouvrez-le : python3 scripts/devserver.py 8123 (depuis le dossier parent de la leçon), puis http://localhost:8123/<leçon>/.
• Auto-contrôle (navigateur) : suivez references/self-checks.md : captures d'écran à chaque temps fort, rien qui se chevauche, aucune erreur dans la console, chaque élément nommé mis en évidence à son mot.

6. Narration et musique (nécessite le compte ElevenLabs de l'utilisateur)

• Guidez l'utilisateur pour qu'il se connecte (user-guidance.md → ElevenLabs). Paramètres : voix Quentin – Narrateur et Éducateur, Eleven v4, Stabilité ≈ 80%, Français ; l'ensemble du script en une seule prise. Enregistrez sous narration/narration.mp3.
• Pas d'ElevenLabs ? Proposez le placeholder gratuit : python3 scripts/placeholder_voice.py <dossier> (Mac).
• Synchronisez les mots : python3 scripts/align_narration.py <dossier>/narration/narration.mp3 --out <dossier>/narration/narration.words.json, puis time_storyboard.py à nouveau. Visez ≥ 99% de mots reconnus.
• Musique (optionnelle, ElevenLabs Music, instrumentale, calme, ~2 min) : préparez avec prep_music.py ; si la vidéo est plus longue que la piste, étendez-la avec find_loop.py + extend_music.py (ne la laissez jamais se terminer ou boucler sous le narrateur).
• Auto-contrôle : check_lesson.py (durées audio, faits) + une lecture complète dans le navigateur.

✋ Point de contrôle 3 : révision ensemble

Parcourez la leçon terminée avec l'utilisateur : à quoi faire attention, comment essayer Explorer. Apportez les modifications qu'il demande, en réexécutant les auto-contrôles après chacune.

7. Publier (optionnel)

Guidez-le vers GitHub Pages ou tout hébergeur statique (user-guidance.md → Publication). Le dossier de la leçon est autonome.

Règles d'auto-contrôle (toujours)

• Exécutez scripts/check_lesson.py après les étapes 3, 4, 5, 6 et après chaque révision.
• Vérifiez dans le navigateur après tout changement visuel : prenez des captures d'écran aux moments narrés et vérifiez-les par rapport au storyboard. Dites ce que vous avez vérifié.
• Recalculez chaque nombre narré à partir des données source ; ne tapez jamais un nombre de mémoire.
• Si quelque chose échoue, corrigez-le et revérifiez avant de dire à l'utilisateur que c'est terminé.

Fichiers de référence

Fichier	Utilisation
references/design-rules.md	Apparence, mouvement, emphase, narration, synchronisation, musique, honnêteté des données
references/chart-chooser.md	Quel graphique pour quelle question ; critères de correspondance
references/data-formats.md	Les quatre formats data.json
references/storyboard.md	video.json : scènes, temps forts, repères par type de graphique, facts.json
references/narration.md	Style du script, paramètres ElevenLabs, synchronisation, musique
references/self-checks.md	Quoi vérifier à chaque étape
references/user-guidance.md	Procédures pas à pas en langage simple pour l'utilisateur
references/chart-interface.md	Ajout d'un nouveau type de graphique