KKcorps/lesson-film

Films pédagogiques

Un film pédagogique enseigne un mécanisme suffisamment bien pour qu'un novice puisse le réexpliquer après un seul visionnage. Chaque image est dessinée par code, la voix du narrateur sert de chronomètre, et la musique joue dans les silences laissés par la voix. Il repose sur code-film : cette compétence gère l'apparence visuelle, la galerie, le goût et les vérifications de défauts. La présente compétence gère l'enseignement, les mots, la voix, le rythme, la fin et le volet YouTube.

L'exemple concret est examples/parcel42-lesson/, une leçon de 130 s sur la façon dont Apache Pinot masque les anciennes lignes. Kartik, l'auteur de la compétence, l'a qualifiée de « parfaite » après huit versions, et toutes les notes en cours de route se trouvent dans le fichier de référence qui les contient. Lisez son README pour la méthode, jamais pour l'apparence.

Le cœur : suivre le spectateur

Un film pédagogique est une moitié d'une conversation, et le spectateur fournit l'autre moitié en silence. À chaque seconde, il a trois choses :

• Ce qu'il sait. Seulement ce que le film a montré et dit jusqu'à présent, plus les connaissances courantes. Pas le code source, et pas ce que vous avez lu pour le réaliser.
• Ce qu'il se demande. Chaque image et chaque affirmation soulèvent la question suivante : « alors qu'arrive-t-il à l'ancien ? », « et s'il arrive en retard ? », « cela ne gaspille-t-il pas de l'espace ? »
• Ce qu'il croit. Un modèle du mécanisme construit uniquement à partir du film. Un seul mot erroné installe un modèle erroné. « Pinot ne démolit jamais la vieille maison » a appris que rien n'est jamais supprimé, puis le film a montré le compactage le supprimant.

Réaliser le film, c'est exécuter ce modèle seconde par seconde, à travers la voix et l'image ensemble :

1. Répondre à la question là où elle se pose. La lettre en retard vient juste après la règle, et « Et les maisons sombres ? » juste après la requête.
2. Les laisser arriver avant d'annoncer. L'image montre la preuve un temps avant que la voix ne la nomme. Un titre, une étiquette ou un nom de chapitre ne donne jamais la réponse avant que la question ne soit posée.
3. Ne jamais couper le fil. Une ligne qui promet quelque chose possède l'image suivante. Après « deux interrupteurs basculent », la chose suivante à l'écran, ce sont les interrupteurs.
4. Donner chaque mot avant de l'utiliser. Chaque terme à l'écran est prononcé à voix haute une fois, là où l'image le montre, et aucun n'atteint la première ligne. La chose dans le monde vient en premier, et le terme est nommé après elle. En dehors de cette ligne de nomination, une phrase reste dans un seul monde : une fleur a cessé de pousser, elle n'est jamais « fermée ». Un film entier a montré « segment 7 » sur des panneaux de signalisation sans jamais dire segment.
5. Enseigner le mécanisme, pas le code. Montrer un nom réel uniquement lorsque le spectateur le rechercherait (validDocIds), jamais un nom de fonction qui n'est qu'une étiquette de machinerie.

Chaque règle dans les références est l'une de ces cinq appliquées. Lorsqu'une règle semble en conflit avec une autre, ou que rien ne couvre un cas, exécutez le modèle du spectateur et il décide.

Une note ne porte jamais sur un seul cas. Lorsque la personne pour qui vous faites le film pointe un moment précis, elle pointe un endroit où le modèle s'est brisé. Trouvez tous les autres endroits où il s'est brisé de la même manière, corrigez-les tous, et rapportez le nombre. Le « temps pénible » de Kartik concernait les remplissages mais aussi les tintements et les clics. Ses lettres manquantes concernaient tout événement chronométré à partir d'une image fixe, c'est pourquoi shiftcheck.py existe. Sa « mauvaise phrase » concernait chaque mot absolu, c'est pourquoi scriptcheck.py les liste.

Configuration

Cette compétence nécessite que code-film soit installé à côté d'elle, dans le même dossier de compétences. Sa construction, sa passerelle, sa capture, ses vérifications de couture et de son, ainsi que son écriture manuscrite proviennent toutes de là, et chaque script le trouve là ou dans $CODE_FILM.

Exécutez bash assets/setup.sh une fois. Il vérifie le diagnostic de code-film, puis construit un environnement virtuel Python 3.12 dans ~/.cache/lesson-film/venv avec Kokoro, soundfile, faster-whisper et le modèle spaCy anglais, et vérifie que ffmpeg dispose de loudnorm.

À quoi ressemble un bon film

• Un novice peut le raconter. Ses deux phrases correspondent à la ligne de conclusion sur la fiche d'intention, avec les vrais termes aux bons endroits.
• On dirait qu'une personne vous explique. Chaque phrase mène à la suivante, et chaque changement de scène porte la question vivante. Lisez le script à voix haute sans les images. S'il ressemble à une liste d'étiquettes, ce n'est pas fini (reference/words.md).
• Il respire. Le spectateur a le temps de voir chaque changement avant le suivant. Kartik a trouvé qu'un montage de 64 s à 0,36 coupes par seconde était « trop rapide ». Le montage approuvé dure 130 s à 0,16 coupes par seconde, avec une voix à vitesse normale et des respirations réelles (reference/pace-and-ending.md).
• Chaque affirmation est vraie et vérifiée. Écrivez les affirmations dans facts.md par rapport à la source avant tout dessin. L'image montre exactement cet état.
• L'image change sur le mot. Chaque chose apparaît au moment où la voix la nomme. Le mouvement et la couleur ne se situent que sur la partie expliquée (reference/teaching.md).
• Il commence en douceur et se termine lentement. Une première ligne que tout le monde peut comprendre, avec l'image et la mélodie déjà en cours, une ouverture à froid qui se termine sur la question, puis un générique d'environ cinq secondes, comme le fait Kurzgesagt. « Le début semble brusque » était la note de Kartik sur un film qui s'ouvrait sur un personnage que le spectateur n'avait pas rencontré (reference/pace-and-ending.md).
• Il se termine, il ne s'arrête pas. Un récapitulatif, une récompense, une phrase de clôture qui répond à l'ouverture, l'accord final, puis l'image et le son s'estompent ensemble pendant plusieurs secondes. « La fin est brusque » est la note à ne plus jamais recevoir.
• Les défauts sont nuls. Pas de flash, pas de pop, pas d'écrêtage, une sonie à -14 LUFS, chaque mot entendu.

Ce sont des jugements, pas des règles. Enfreignez-en une lorsque la fiche dit pourquoi.

Flux de travail

Copiez ceci dans vos notes et rapportez chaque ligne au fur et à mesure que vous la terminez. Une ligne ne peut pas être cochée sans dire comment.

[ ] 0 référence   uniquement s'ils en ont partagé une. Un clip, une image fixe ou une page HTML. Rapportez quelle forme, ce qu'elle fait, quels écarts sont comblables, et ce que vous prenez et laissez.
[ ] 1 faits       faits.md rédigé par rapport à la source. Rapportez les affirmations et où chacune a été vérifiée.
[ ] 2 intention   assets/intent.md copié vers <piece>.intent.md, conclusion, sentiment, question, supposition. Rapportez-les.
[ ] 3 galerie     reference/gallery.md de code-film, les deux ou trois films les plus proches. Rapportez ce que vous prenez et ce que vous ne copierez pas.
[ ] 4 croquis     trois nouvelles histoires, chacune une image fixe d'aspect final dessinée avec le kit (sketch.py), dont un monde dans lequel vous pourriez vivre, aucune tirée de l'exemple ou d'une référence partagée. sketchcheck.py propre de tout BLOC, puis jugé par rapport à la grille. Montrez-les. Rapportez la ligne de chaque histoire, les trois réponses du jugement et le choix.
[ ] 5 mots        le script entier comme un paragraphe dans <piece>.chain.txt, puis coupé en lignes avec ses « termes », « choses » et « tech ». Avant le paragraphe, écrivez la chose de chaque terme et le verbe du monde pour chaque état réel qu'il a. scriptcheck.py propre de tout BLOC. Rapportez cette carte, le script lu à voix haute une fois, chaque charnière, et une décision sur chaque RÉVISION.
[ ] 6 voix        <piece>.lines.json -> voice.py -> heard.py --write. Rapportez la durée, et chaque mot entendu ou pourquoi pas.
[ ] 7 plan        scènes, chacune liée aux mots qui la changent, et l'état du monde qu'elles partagent. Rapportez le plan, avec la chose dans le monde qui montre chaque terme et le verbe du monde pour chaque état réel.
[ ] 8 construction page à partir de assets/template/. Scènes vérifiées seules d'abord en version préliminaire. Rapportez ce que vous avez redessiné après avoir regardé.
[ ] 9 son         <piece>.score.py à partir de assets/score_template.py. Rapportez les accords, la mélodie dans les silences, et les sons du monde.
[ ] 10 rendu      assets/build.sh. DRAFT=1 d'abord. Rapportez les chiffres.
[ ] 11 vérification les trois couches ci-dessous. Rapportez chaque.
[ ] 12 livraison  un nouveau fichier à chaque construction, ne jamais écraser. Le master pour YouTube, un petit aperçu de moins de 30 Mo à envoyer.

Les étapes 1 à 5 sont celles où les leçons sont gagnées. L'étape 5 en particulier : écrivez d'abord le script en prose, puis coupez-le en lignes. Couper d'abord, c'est ainsi qu'un script devient une pile de sous-titres.

Vérification

Rapportez les trois couches séparément dans la note de livraison.

• Bloc des défauts. build.sh exécute scriptcheck.py (chaque terme dit, aucun dans la première ligne, liens qui existent) et check.py et seamcheck.py de code-film, master à -14 LUFS intégré avec un pic vrai à -1.5 dBTP, et encode selon les spécifications YouTube (reference/youtube.md).
• La leçon est mesurée. verify.py vérifie la durée, le rythme et le son de la fiche. heard.py transcrit la voix et indique quels mots n'ont pas été entendus et à quel point le son est en retard sur les temps de repère. wordsync.py vérifie que le mouvement augmente sur chaque mot auquel l'image est liée. shiftcheck.py rend le film avec la voix décalée de deux secondes plus tard et échoue toute scène qui change, ce qui est ainsi qu'un événement chronométré à partir d'une image fixe apparaît. captions.py écrit un SRT exact à partir des mêmes repères.
• Le test de visionnage vous appartient, puis à la personne. Racontez-le en tant que novice. Nommez chaque vignette de la planche contact. Regardez-le sans le son. Lisez le script à voix haute sans les images. Jugez les dix dernières secondes seules. Dites ensuite clairement ce que vous n'avez pas vérifié, comme la voix à l'oreille.

Quand lire quoi

Lisez chaque fichier en entier, avec un appel par fichier, et relisez un fichier seul si la lecture indique que les jetons ont été tronqués. « Quand lire quoi » de code-film indique ce qu'une lecture groupée coûte.

• Lorsqu'ils partagent une référence, lisez reference/references.md de code-film. Il couvre les trois formes. Un clip et une image fixe sont disséqués avec ffmpeg. Une page HTML, la nôtre ou la leur, passe par assets/refpage.mjs de code-film, qui surveille le dessin de la page et rapporte sa palette, ses marques, ses couches et son kit audio, et écrit un MP4 afin que les vérifications de clip s'exécutent également dessus.
• Avant les faits et la fiche d'intention, lisez reference/teaching.md.
• Avant les croquis, lisez reference/sketches.md de cette compétence et la section Histoire de ses propres reference/traps.md. Lisez ensuite reference/story.md de code-film pour « Choisissez d'abord une forme » et « Ce qui persiste », et reference/traps-story.md de code-film.
• Avant d'écrire une seule ligne du script, lisez reference/words.md.
• Lorsque vous planifiez l'ouverture ou la fin, et lorsque vous réglez la vitesse de la voix, les respirations et les poses, lisez reference/pace-and-ending.md.
• Lorsque vous créez ou corrigez la voix, lisez reference/voice.md.
• Lorsque vous planifiez les scènes, les répartissez entre les assistants, ou construisez la page, lisez reference/film.md, et reference/moves.md de code-film, qui possède les mouvements entre deux images.
• Lorsque vous créez le son, lisez reference/sound.md, et reference/sound.md de code-film pour les instruments et ses reference/traps-sound.md.
• Avant le premier rendu et après toute note sur un rendu, lisez reference/traps.md.
• Avant de publier, lisez reference/youtube.md.
• Lorsqu'une règle a besoin de sa source, ou que quelqu'un demande pourquoi la compétence fait quelque chose, lisez reference/research.md : les preuves, les tailles d'effet et les liens.
• Pour l'apparence, le goût et la finition d'impression, lisez gallery.md, taste.md et press.md de code-film, et ses traps-print.md avant d'affiner la finition.

Les fichiers

fichier	ce que c'est
assets/setup.sh	configuration unique : l'environnement virtuel pour la voix et l'audition, et les vérifications
assets/intent.md	la fiche d'intention de la leçon, la fiche de code-film plus les lignes d'enseignement
assets/voice.py	prononce <piece>.lines.json avec Kokoro, place les lignes sur une grille de pulsations, écrit la voix et les repères
assets/heard.py	transcrit la voix avec Whisper, rapporte les mots manquants et le décalage, --write stocke le décalage dans les repères
assets/saytest.py	essaie les réécritures d'un mot que Kokoro prononce mal, et indique lequel Whisper entend correctement
assets/captions.py, assets/wordsync.py	le SRT à partir des repères, et la vérification que le mouvement augmente sur chaque mot lié
assets/shiftcheck.py	la vérification que chaque scène est chronométrée à partir de la voix, et non d'images fixes
assets/scriptcheck.py	la vérification du script : termes dits, aucun dans la première ligne, la chose de chaque terme dite avant le terme, liens qui existent, et une liste de mots absolus, de mots non dits à l'écran et de phrases qui mélangent le monde avec le système réel à lire
assets/sketchcheck.py, assets/barsheet.py	la vérification des croquis de code-film, exécutée avec les images approuvées de cette compétence, la ville de l'exemple et le modèle de base. Et le script qui reconstruit la grille de jugement
assets/score_template.py	un lit par ligne, la mélodie dans les silences, les sons du monde lors des changements d'état, une atténuation de 16 dB sous la parole, l'outro en fondu
assets/build.sh	page, passerelle, capture parallèle, coutures, partition, master -14 LUFS, encodage, sous-titres, planche contact, toutes les vérifications
assets/template/	la page à copier : assemble.py, film/kit.js (le savoir-faire sans monde dedans : encre, points, bords, lumière, écriture manuscrite, la finition d'impression), film/core.js (horloge vocale, calques, caméra, mouvements de plongée et d'iris), film/main.js, film/SCENES.md, une scène exemple qui construit un objet de remplacement, et sketch.py avec sketches/sketch.js pour les trois images d'histoire
reference/stills/	images de la leçon approuvée, sous-titrées, pour les deux règles que la prose seule ne fait pas comprendre : les temps d'ouverture et de fin, et une image changeant sur son mot. Également la grille de jugement des croquis sketch-bar.jpg, ouverte seulement après vos trois propres croquis, et sent-back.jpg
examples/parcel42-lesson/	l'ensemble des sources de la leçon approuvée, sa piste vocale, un lien vers un aperçu du film à regarder, son README, sa planche contact et ses miniatures

La capture parallèle vit dans code-film (assets/capture-range.mjs, assets/capture-par.sh), car tout film long en a besoin.

Modifier cette compétence

Indiquez l'intention et le jugement, et vérifiez le résultat par rapport à l'intention. Une nouvelle leçon approuvée par quelqu'un devient un deuxième exemple, avec une ligne dans ce fichier sur pourquoi elle fonctionne. Une leçon apprise va dans le fichier de référence unique qui la possède, et tous les autres fichiers y pointent avec une ligne.