iwyusdaz/chalkreel

chalkreel — objectif en entrée, vidéo explicative accessible en sortie

Vous produisez une vidéo explicative d'apprentissage. Contrairement aux vidéos explicatives optimisées pour l'engagement par IA, une vidéo d'apprentissage part d'un objectif mesurable, gère délibérément la charge cognitive (principes multimédia de Mayer) et fournit des livrables d'accessibilité — sous-titres, transcript, notes d'audiodescription — comme résultats de première classe, et non comme après-pensées. Chaque affirmation factuelle dans la narration est traçable jusqu'à une source.

Tout ce qu'un spectateur entend doit également pouvoir être vu ou lu. Tout ce qui est dit à un apprenant doit être traçable. Rien n'est livré sans validation humaine.

Règles strictes

1. Aucun modèle vidéo génératif. Aucune image d'archives. Aucun générateur d'images pour le contenu des scènes. Les images sont dessinées en code (composants Remotion, SVG, CSS). Cela garantit que chaque image est révisable, différentiable et reproductible.
2. Quatre étapes de validation humaine. Ne jamais passer une étape sans approbation explicite consignée dans le journal de projet : ÉTAPE 1 objectif + carte des séquences, ÉTAPE 2 script de narration, ÉTAPE 3 style visuel, ÉTAPE 4 montage final.
3. Tout ce qui est synthétique doit être étiqueté. Les données d'exemple construites, les timings simulés et les résultats de révision par agent sont étiquetés comme tels dans le fichier lui-même. Ne jamais présenter un artefact sec comme un résultat réel rendu/synthèse vocale.
4. Les affirmations avant le script. Les notes de recherche avec des affirmations sourcées existent avant que la narration ne soit écrite, et aucun nombre n'entre dans le script sans une ligne dans le registre.
5. Synthèse vocale locale par défaut. La voix par défaut est kokoro-82m (locale, gratuite). La possibilité d'apporter sa propre synthèse vocale est prise en charge ; n'appelez jamais une synthèse vocale cloud sans la clé configurée par l'utilisateur. Aucun modèle local autre que la synthèse vocale choisie par l'utilisateur.

Entrées

objectif :    une phrase mesurable (ABCD — l'étape objectif impose cela)
audience :    qui apprend, et leurs connaissances préalables supposées
durée :       cible (par défaut 60–120 s)
langue :      langue de la narration (par défaut en)

Refuser les sujets. "Une vidéo sur la photosynthèse" n'est pas une entrée ; exécutez scripts/objective-gate.mjs et itérez avec l'utilisateur jusqu'à ce que cela passe.

Pipeline

objectif + audience + connaissances préalables + durée + langue
  |
  +-- 1. ÉTAPE OBJECTIF    objective-gate.mjs ; réécrire le sujet -> objectif ABCD ;
  |                        cadre visible par l'apprenant "vous serez capable de..." ;
  |                        carte des séquences segmentée selon le principe de
  |                        segmentation de Mayer (séquences de 10-30 s)
  |                        << ÉTAPE 1 : l'utilisateur approuve l'objectif + la carte
  +-- 2. RECHERCHE          extraire les affirmations, trouver les sources, écrire le
  |                        registre des affirmations (ids style claim-001 ; sources
  |                        avec titre/éditeur/année ; formulation vague préférée aux
  |                        statistiques inventées)
  +-- 3. NARRATION         script par budget de séquence ; passage du vérificateur de
  |                        style rédactionnel IA (scripts/lint-narration.mjs doit
  |                        retourner 0) ; vérification du niveau de lecture vs audience
  |                        << ÉTAPE 2 : l'utilisateur approuve le script
  +-- 4. COMPARAISON DE    rendre la MÊME séquence dans 2-3 variantes de fond/thème
  |     STYLE              avec le modèle ; l'utilisateur choisit visuellement
  |                        << ÉTAPE 3 : l'utilisateur choisit un style
  +-- 5. CONSTRUCTION      un composant Remotion par séquence (template/) ;
  |                        TTS avec horodatages par mot (kokoro-82m par défaut,
  |                        BYO accepté) ; construction JSON de timing
  |                        {segments[].words[{w,start,end}]}
  +-- 6. ACCESSIBILITÉ     make-srt.mjs (SRT aligné mot), make-transcript.mjs
  |                        (HTML de transcript), notes d'audiodescription par
  |                        séquence, puis a11y-lint.mjs DOIT passer
  +-- 7. QC                noter les images rendues + script par rapport aux
  |                        critères ci-dessous ; écrire qc-report.md avec les
  |                        étiquettes de méthode
  |                        << ÉTAPE 4 : l'utilisateur révise le montage final
  +-- livrer : video.mp4 + .srt + transcript.html + instructor-notes.md
      + registre des affirmations + trace complète (objectif, recherche, narration,
      storyboard, timing, rapport qc)

Budgets de séquence

• 10–30 s par séquence (segmentation de Mayer ; plafond strict de 30 s sans dérogation de l'utilisateur).
• ~145 mots par 60 s de narration ; une idée par séquence.
• Texte à l'écran : uniquement des étiquettes et des phrases courtes (2–7 mots), jamais la narration lue textuellement (principe de redondance).
• Chaque séquence définit : narration, un type de scène, texte à l'écran, note d'audiodescription, identifiants d'affirmation.

Paramètres TTS par défaut

• Par défaut : kokoro-82m, local. Voix : af_heart (ou choix de l'utilisateur). Vitesse 1.0.
• Capturer les horodatages par mot depuis le TTS/aligneur dans le JSON de timing. Si le TTS ne peut pas les émettre, aligner avec un aligneur forcé ; ne jamais deviner les timings — un alignement deviné fait dériver les sous-titres, et la vérification en boucle détectera les textes non correspondants mais pas les temps dérivés.
• BYO TTS : tout moteur qui renvoie des horodatages au niveau du mot ; documenter le moteur et la voix dans le journal de projet.

Scripts (tous autonomes, node >=18, aucune dépendance)

Script	Objectif	Sortie 0 signifie
scripts/objective-gate.mjs "<objectif>"	valide l'objectif ABCD	l'objectif est mesurable
scripts/lint-narration.mjs <script.txt>	vérificateur d'écriture IA (exécuter avant TTS)	le script sonne assez humain pour être enregistré
scripts/make-srt.mjs <timing.json> --out x.srt	SRT aligné mot depuis le JSON de timing	SRT écrit
scripts/make-transcript.mjs --timing <timing.json> --storyboard <sb.json> --out t.html	page de transcript accessible	HTML écrit
scripts/a11y-lint.mjs <storyboard.json>	"aucune info uniquement audio" + vérifications des livrables	chaque fait de narration est à l'écran ou dans le transcript/notes AD

Les fixtures négatives se trouvent dans examples/ (bad-narration.txt, bad-storyboard.json) — toujours vérifier une nouvelle installation en exécutant les lints sur celles-ci et en confirmant qu'elles ÉCHOUENT.

Formats de fichiers

timing.json — horodatages par mot (depuis l'alignement TTS) :

{ "video": { "title": "...", "fps": 30 },
  "segments": [ { "id": "seg-01", "text": "...", "start": 0.0,
    "words": [ { "w": "Fermer", "start": 0.1, "end": 0.34 } ] } ] }

storyboard.json — un objet par séquence :

{ "video": { "title": "...", "fps": 30, "width": 1920, "height": 1080,
    "srtEmitted": true, "transcriptEmitted": true, "claimsLedger": "chemin" },
  "segments": [ { "id": "seg-01", "title": "Accroche", "sceneKind": "statement",
    "startSec": 0, "durationSec": 18.2, "narration": "...",
    "visual": { "backdrop": "chalkboard", "description": "...",
                "onScreenText": [ "Relire les battements" ] },
    "audioDescriptionNote": "...", "claims": [] } ] }

sceneKind correspond à un composant modèle : statement, definition, timeline, cycle, list, caption. Ajouter de nouveaux types dans le modèle, pas comme composants uniques dans un projet.

Pack de critères QC (noter la sortie rendue par rapport à CECI, par écrit)

Un agent QC ne "regarde" pas la vidéo et ne donne pas son avis. Il note chaque critère réussi/échoué avec une observation citée. Les vérifications au niveau des images nécessitent des images rendues ; les vérifications au niveau du script s'effectuent sur les artefacts. Écrire le résultat dans qc-report.md et étiqueter la méthode de révision (par ex. "Révision heuristique par agent").

Niveau script (exécuter à chaque fois)

1. Alignement avec l'objectif — chaque séquence fait progresser l'objectif approuvé ; tout ce qui ne le fait pas est supprimé (principe de cohérence appliqué aux objectifs).
2. Traçabilité des affirmations — chaque nombre, date ou résultat nommé dans la narration a une ligne dans le registre des affirmations avec une source. Échec pour tout fait orphelin.
3. Vérification de la narration — lint-narration.mjs sortie 0.
4. Niveau de lecture — les phrases font en moyenne moins de ~17 mots ; aucun terme technique non expliqué ; verbes concrets plutôt que des abstractions.
5. Pack d'accessibilité — a11y-lint.mjs sortie 0 ; SRT et transcript existent ; note AD présente pour chaque séquence.

Niveau image (exécuter sur les images rendues ou captures d'écran par séquence)

6. Signalisation — le terme clé/numéro du moment est visuellement mis en évidence (souligné à la craie, couleur, flèche) exactement pendant sa narration.
7. Cohérence — rien de décoratif à l'écran ; chaque élément correspond à une idée narrée ; pas de musique de fond sauf demande de l'utilisateur.
8. Redondance — le texte à l'écran ne duplique pas la narration textuelle ; ce sont des étiquettes et des phrases courtes.
9. Contiguïté spatiale — les étiquettes sont adjacentes à la chose qu'elles décrivent ; pas de chasse au trésor légende-graphique dans une image.
10. Contiguïté temporelle — la révélation d'un élément est synchronisée avec sa ligne de narration (vérifier avec timing.json), pas montrée avant ou après.
11. Lisibilité — les lignes de craie contrastent avec le fond (>= 4.5:1 pour les équivalents texte à l'écran) ; rien n'est rogné en 1920x1080 ou 1280x720.
12. Budget d'animation — les animations se stabilisent en moins de 1,2 s ; rien ne bouge pendant une phrase qui introduit une idée différente.

Noter chaque RÉUSSI/ÉCHEC avec preuve. Tout ÉCHEC sur 1–5 bloque l'ÉTAPE 4. Tout ÉCHEC sur 6–12 nécessite une correction et un nouveau rendu de cette séquence, ou une acceptation explicite de l'utilisateur.

Styles par défaut (comparaison ÉTAPE 3)

• Fond : chalkboard (ardoise foncée, texture subtile, vignette douce). Alternatives pour la comparaison : paper (blanc cassé chaud, traits d'encre), night (presque noir, une seule couleur d'accent).
• Palette : blanc craie primaire, un accent (ambre #FFC66D) pour les surlignages. Surligner uniquement ce que la signalisation nécessite.
• Typographie : grande (>= 64 px en 1080p), contraste élevé ; sous-titres en bas-centre avec plaque translucide, max 2 lignes / 42 caractères par ligne.
• Respecter le spectateur : pas de flash (> 3 flashs/s interdit), le mouvement se stabilise rapidement, une barre de progression montre la position du chapitre.

Trace (tout valider)

01-objective.md (+ sortie de l'étape)     05-timing.json
02-research-notes.md                      06-subtitles.srt
03-narration.md                           07-claims-ledger.md
04-storyboard.json                        08-qc-report.md

La trace est autant un produit que la vidéo : c'est ce qui rend le pipeline vérifiable par un autre concepteur pédagogique.

Limites honnêtes (les mentionner dans le journal de projet)

• Le QC par agent est une révision heuristique par un modèle, pas une approbation experte.
• Aucune affirmation qu'une sortie est "validée pédagogiquement" — cela nécessite des tests avec des apprenants que cette compétence ne fait pas.
• Les sous-titres alignés mot ne sont aussi bons que l'alignement TTS ; vérifier 10 indices par rapport à l'audio avant l'ÉTAPE 4.
• Licence des voix : les voix kokoro-82m ont leurs propres conditions d'utilisation ; vérifier avant distribution commerciale.

Attribution

Inspiration au niveau de la méthode, aucun code copié : anything2explainer (PolyForm Noncommercial — méthode uniquement, voir ATTRIBUTION.md de ce dépôt), le modèle de flux d'approbation avec étapes de vox-director (MIT), et le concept de liste de vérification des signes d'écriture IA de blader/humanizer et de Wikipedia "Signs of AI writing" (le lint de ce dépôt est une implémentation indépendante).