JustinChenzeting/Lecture-notes-to-videos

Notes de cours → vidéo de cours narrée

Vous écrivez un seul fichier : un beamer lecture.tex contenant les diapositives, les diagrammes et la narration. Les scripts intégrés font tout le reste (installation, LaTeX → pages PNG → synthèse vocale → ffmpeg → MP4), de sorte que le coût est d'environ une longue réponse par cours, et les modifications ultérieures ne resynthétisent que les lignes qui ont changé.

Démarrage rapide : tout le pipeline

Chaque étape est une commande : python3 <dossier-compétence>/scripts/lv.py <commande>, où <dossier-compétence> est le chemin absolu du dossier contenant ce fichier (sous Windows, utilisez py -3 au lieu de python3). Ci-dessous, lv est un raccourci pour cette commande entière ; écrivez-la en entier à chaque fois, car les variables shell ne persistent généralement pas entre vos commandes.

lv setup                           # 0. installation unique ; accordez-lui un délai d'attente de 10 minutes ou exécutez-la en arrière-plan
lv init PHYS101-L05                # 1. affiche le dossier de travail (WORK) et copie le modèle dedans
lv ingest notes.pdf --out WORK     #    tout mélange de .pdf .png .jpg .heic .md .txt ; plusieurs fichiers sont acceptés
#                                       lisez les notes (§1), planifiez (§2), écrivez WORK/lecture.tex (§3-4)
lv check WORK/lecture.tex          # 2. compilation + planches contact numérotées + avertissements de mise en page, pas d'audio
lv render WORK/lecture.tex         # 3. -> WORK/PHYS101-L05.mp4 (ou donnez un chemin de sortie)

• L'étape 0 installe tout (uv, un Python 3.12 privé, TinyTeX uniquement lorsqu'aucun LaTeX fonctionnel n'existe, ffmpeg, voix Kokoro) dans un cache par utilisateur : environ 3 minutes sur une connexion rapide, jusqu'à 10 sur une connexion lente, sans nécessiter de droits administrateur. Elle est idempotente : une fois terminée, elle se termine en quelques secondes, et si elle est interrompue, la relancer reprend là où elle s'était arrêtée. Dites à l'utilisateur qu'il s'agit d'une installation unique. Elle se termine par une ligne commençant par [setup] READY ; toute autre fin est une erreur avec un correctif dans le message ou dans references/troubleshooting.md. lv doctor montre ce qui est installé sans rien modifier. Les autres commandes exécutent également l'installation si elle est manquante.
• Exécutez le pipeline de bout en bout sans demander de confirmation à chaque étape. Arrêtez-vous uniquement pour les obstacles réels : notes que vous ne pouvez pas ouvrir ou lire, étape d'installation nécessitant un mot de passe administrateur, ou demande ambiguë d'une manière qui modifie la vidéo.
• WORK est par défaut ./lecture-videos/<nom> (ou le work_root configuré par l'utilisateur). Placez le MP4 là où l'utilisateur l'a demandé ; sinon, la valeur par défaut dans WORK est suffisante. Conservez WORK : le .tex, la transcription et le cache audio rendent les modifications ultérieures peu coûteuses.

1. Lisez d'abord les notes vous-même

ingest écrit WORK/source.txt (pages avec une couche de texte), WORK/manifest.tsv (comment chaque page a été lue), des images en taille réelle des pages qui nécessitent un examen visuel (WORK/pages/), et des feuilles de survol (WORK/glance-*.jpg, six pages chacune).

• Regardez chaque feuille de survol. Elles capturent les annotations en marge, les passages surlignés et les figures que l'extraction de texte manque, pour environ le coût en tokens d'une page pleine par feuille. Si une feuille montre de l'écriture manuscrite ou des annotations sur une page tapée, relancez avec --visual 3,7-9 pour obtenir ces pages en taille réelle.
• Pages manuscrites ou scannées ([manuscrit/scanné], [image]) doivent être lues en taille réelle : ouvrez chaque image et écrivez WORK/transcript.md avec le contenu dans l'ordre, les équations en LaTeX, et une description d'une ligne de chaque figure (axes, étiquettes, nombres clés). Marquez tout ce qui est illisible comme [illisible] plutôt que de l'inventer. Les notes manuscrites sont souvent les notes personnelles de cours de l'utilisateur, traitez-les donc comme la source principale. Si vous ne pouvez pas visualiser les images, dites-le et demandez une version tapée au lieu de deviner.
• Pages tapées avec figures ([a figure]) : ouvrez l'image en taille réelle uniquement lorsque vous avez besoin d'une valeur ou d'une étiquette que vous ne pouvez pas lire sur la feuille de survol.
• À partir de là, planifiez uniquement à partir de source.txt + transcript.md ; ne relisez pas les images.
• Notes en .docx, .pptx ou .key : exportez-les d'abord en PDF (par exemple avec LibreOffice soffice --headless --convert-to pdf), puis ingérez le PDF.

Pendant la lecture, notez les erreurs ou incohérences dans les notes (fautes de frappe dans les nombres, étiquettes inversées). Utilisez la valeur correcte dans la vidéo et listez chaque correction dans votre rapport final.

1b. Comblez les lacunes à partir de sources fiables

Les notes sont souvent laconiques : une étape de dérivation sautée, un terme utilisé avant d'être défini, une figure sans explication. Lorsque quelque chose pourrait confondre un étudiant, et que vous avez accès au web, recherchez brièvement (2 à 5 requêtes ciblées, pas une revue de littérature) une explication claire au niveau approprié : notes de cours universitaires et OCW, LibreTexts, manuels standard, articles de synthèse pour les points de niveau graduate. Préférez les sources qui correspondent à la notation des notes ; en cas de conflit, suivez les notes et mentionnez la différence. Gardez les ajouts courts et au service du contenu des notes, ciblez d'abord les undergraduates avec une éventuelle remarque de niveau graduate, et listez les sources utilisées dans le rapport final. N'ajoutez pas de sujets que le cours ne couvre pas.

2. Planifiez avant d'écrire (dans votre tête ou en quelques lignes)

• Durée : visez environ 10 minutes (9-11) sauf si l'utilisateur donne une autre durée. La profondeur prime sur la couverture : si les notes contiennent plus que ce que 10 minutes peuvent expliquer sans sauter d'étapes, couvrez le cœur en profondeur, puis dites à l'utilisateur ce qui a été omis et proposez une partie 2. Budget de narration à ≈ 155 mots par minute de durée cible, moins 15 secondes par point de contrôle (la voix par défaut parle à ~165 mots par minute ; les pauses entre les lignes utilisent le reste). Une vidéo de 10 minutes ≈ 1 350 mots + 4 points de contrôle (mesuré : 1 481 mots + 4 points de contrôle = 9,9 min).
• Arc : titre → motivation → concepts dans l'ordre des notes → exemple(s) travaillé(s) → résumé. Une idée par diapositive, 1 à 5 étapes de superposition par diapositive, ~40 à 70 pages au total.
• Chaîne logique : listez la chaîne de raisonnement sous forme d'étapes numérotées (ce qui est supposé, ce qui s'ensuit, et pourquoi). Chaque dérivation va du principe de départ au résultat sans étape sautée : chaque mouvement algébrique obtient sa propre ligne, chaque hypothèse est énoncée là où elle est utilisée, et chaque nouveau symbole est défini avant d'apparaître. Si les notes font un saut ("on peut montrer que…"), comblez le vide (§1b). Un étudiant ne devrait jamais avoir à demander "d'où ça vient ?"
• Les visuels portent le cours : planifiez l'image avant les mots. Chaque diapositive conceptuelle a besoin d'un visuel : un diagramme, un graphique, ou un modèle physique (atomes, réseau, image réservoir-tuyau d'un bilan massique, un levier pour la règle du levier). Montrez ce que les symboles représentent physiquement, pas seulement les équations. Redessinez chaque figure en TikZ/pgfplots original (ne collez jamais les images du polycopié). Construisez les diagrammes étape par étape avec des superpositions, et utilisez 3 à 6 courtes animations là où le mouvement est le point clé (un chemin de refroidissement, une ligne de conjugaison qui balaye, une dislocation qui glisse). Modèles : references/visual-cookbook.md.

Comment expliquer (c'est ce qui rend la vidéo digne d'être regardée)

• Parlez comme un bon tuteur, pas comme un manuel. Langage courant ("donc en gros", "voici l'astuce", "imaginez-le comme…"), phrases courtes, et pourquoi avant quoi. Anticipez la confusion ("ça semble inversé au début, et voici pourquoi ce ne l'est pas").
• Expliquez chaque équation importante deux fois :
  1. Mathématiquement : d'où elle vient, étape par étape, et ce que chaque terme signifie.
  2. Physiquement / intuitivement : ce qu'elle signifie dans le système réel, avec une analogie ou un cas limite ("si c est exactement à c′, l'alliage est tout liquide, et la formule donne exactement ça"). Mettez les deux à l'écran : les lignes mathématiques, puis une note d'une ligne "physiquement :" ou une image.
• Après chaque dérivation, effectuez une rapide vérification de cohérence à voix haute : unités, cas limite, ou un nombre tiré du diagramme.
• Points de contrôle : 3 à 5 pour 10 minutes, placés juste après le concept qu'ils testent (§4).

3. Écrivez WORK/lecture.tex

init a déjà copié assets/template.tex dans WORK/lecture.tex ; il montre toutes les constructions. Remplacez ses diapositives d'exemple par le cours. Règles importantes :

• \usepackage{lecturevideo} charge le thème (papier ivoire, encre foncée, un accent rouge, ou la marque personnelle de l'utilisateur si configurée), la palette (accent, ink, mute, blu, grn, gold), les styles de figures (pd axis, dot, lab, note, tie, atom, atomA, atomB) et les commandes de narration. Ne restylez pas le thème à l'intérieur du cours.
• Narration : \say<n>{...}, une par page de superposition n, placée en haut de la diapositive. \say<2-13>{...} narre une plage d'animation. \wait<n>{2} maintient une page en silence. Chaque page en a besoin ; le rendu nomme toute page manquante.
• Le texte parlé est en anglais simple : nombres et symboles en toutes lettres ("forty six percent", "T three", "seven hundred seventy nine degrees", "alpha plus beta"). Pas de LaTeX et pas de %, &, #, $ à l'intérieur de \say. Dites quoi regarder ("regardez le point", "remarquez la ligne de conjugaison"), puis pourquoi c'est important. Développez le texte de la diapositive plutôt que de le lire mot à mot.
• Les diapositives portent une véritable explication. Un spectateur qui met en pause, revient en arrière ou révise à partir du PDF devrait pouvoir suivre avec les seules diapositives. À côté de chaque visuel, mettez 3 à 5 puces d'environ 15 mots chacune (fait clé, condition, conséquence, signification physique). Pour les dérivations, montrez chaque étape sur sa propre ligne avec une courte raison à côté ("bilan massique sur B", "diviser par W"), révélée au fur et à mesure que la narration l'atteint, en terminant par une ligne "physiquement :" dans la couleur d'accent. Si une dérivation nécessite plus de ~6 lignes, continuez sur la diapositive suivante (répétez la dernière ligne en haut) plutôt que de tasser.
• Mise en page : visuel d'un côté (environ 55 %), texte de l'autre (columns), ou le visuel au-dessus et 2-3 lignes en dessous. Académique et épuré : une idée par diapositive, la couleur d'accent uniquement pour l'emphase, les résultats et les marqueurs d'état.
• Les macros de figure qui prennent #1 vont dans le préambule (un # dans le corps d'une diapositive casse beamer).
• Tout package LaTeX dont le cours a besoin (siunitx, chemfig, …) peut être utilisé ; lorsque le TinyTeX privé est utilisé, les packages manquants sont installés automatiquement lors de la première compilation.

4. Points de contrôle de type examen

\examq[5]{Checkpoint: lever rule}
  {slide question}{spoken question}{slide answer}{spoken answer}

Ceci crée 1 page de question (narrée, puis "Vous avez 5 secondes."), 5 pages silencieuses d'une seconde avec un anneau qui rétrécit, et 1 page de réponse narrée.

Écrivez les questions comme un véritable examen sur ce cours : nombres donnés concrets, une tâche claire, répondable en ~30 s par quelqu'un qui a suivi la vidéo, avec une réponse courte travaillée. Mélangez les types :

• Calculer : "Un alliage à 35 % en poids de B à T₃ avec c′ = 20, c″ = 85 : quelle fraction est liquide ?"
• Lire le diagramme : "Un alliage à 20 % en poids d'Ag est à 900 °C. Quelles phases, et approximativement quelles compositions ?"
• Prédire : "Un alliage à 5 % en poids d'Ag est refroidi lentement de 800 °C à 500 °C. Qu'est-ce qui se forme, et où ?"
• Identifier / classer : "Liquide → α + β à une température : quelle est cette réaction invariante ?"
• Repérer l'erreur : "Un étudiant utilise c″ − c sur la ligne de conjugaison pour la fraction solide. Qu'est-ce qui n'a pas fonctionné ?"

Évitez les invites vagues ("qu'est-ce qu'une phase ?"), les questions triviales non enseignées dans les notes, et les questions à plusieurs parties. La réponse doit montrer le raisonnement étape par étape, pas seulement le résultat. Prenez les nombres du diagramme ou de l'équation que la vidéo vient de montrer, afin que la question, la figure et la réponse concordent. Les questions construites sur une idée fausse courante fonctionnent bien ("diviser l'espacement des broches par deux double la contrainte de la source : vrai ou faux ?"). Gardez le compte à rebours de 5 secondes (la diapositive dit "pausez si vous avez besoin de plus de temps") ; utilisez \examq[8] uniquement si l'utilisateur demande des pauses plus longues.

5. Vérifiez, puis rendez

lv check WORK/lecture.tex

Il compile, affiche les pages, les mots narrés, une durée estimée et des avertissements layout: (contenu trop haut ou lignes trop larges, avec les numéros de ligne source), et écrit des planches contact numérotées WORK/lecture_build/sheet-*.png. Regardez les planches pour détecter les collisions, les étiquettes tronquées, les marqueurs hors courbe ou les diapositives vides ; corrigez-les et relancez (peu coûteux). Si vous ne pouvez pas visualiser les images, corrigez chaque avertissement layout: et gardez les figures simples. Si l'estimation manque la durée cible de plus de ~10 %, réduisez ou étendez la narration maintenant (pas les points de contrôle). Ensuite :

lv render WORK/lecture.tex ["OUT/Lecture title.mp4"]

Narrateur : voix neurale Microsoft Edge en-GB-SoniaNeural (gratuite, nécessite internet) à +10%, 720p. Hors ligne ou si Edge échoue, il revient automatiquement à la voix Kokoro intégrée bf_emma. Options : --tts edge|kokoro|say, --voice <id ou profil>, --rate, --height. Lorsque l'utilisateur nomme une voix ou souhaite la sienne (y compris une voix clonée), lisez references/voices.md.

Les sous-titres sont gratuits. Chaque rendu écrit également OUT.srt et OUT.vtt à côté du MP4 et intègre une piste de sous-titres sélectionnable, construite à partir du texte \say et synchronisée à partir de l'audio synthétisé, donc ils ne coûtent aucun token et restent synchronisés après les modifications. Ne transcrivez jamais la vidéo et n'écrivez jamais les sous-titres à la main. Ils montrent la narration telle qu'écrite (avant les ré-orthographes de lexicon.tsv). --no-subs les désactive.

Les corrections de prononciation vont dans WORK/lexicon.tsv (écrit<TAB>parlé), appliquées uniquement à l'audio. Un nouveau rendu après une modification prend quelques secondes, car les lignes inchangées proviennent du cache audio.

6. Rapportez

Donnez le chemin de la vidéo (et ses sous-titres .srt/.vtt), la durée, le nombre de pages et de points de contrôle, les éventuelles corrections apportées aux notes, les sources utilisées pour combler les lacunes, les figures qui sont des redessins schématiques, et ce qui a été omis (proposez une partie 2). Conservez WORK pour les modifications.

Paramètres personnels

La marque (logo, couleurs, thème beamer d'une institution), la voix par défaut, les dossiers de travail et de sortie se trouvent en dehors de la compétence, dans le dossier de configuration de l'utilisateur, afin que la compétence reste portable : references/customization.md. Ne modifiez jamais les propres ressources de la compétence pour les préférences d'un utilisateur.

Pourquoi est-ce construit ainsi

• Un seul fichier source maintient les diapositives et la narration alignées ; LaTeX écrit la carte de narration précise par page (.narr) lui-même.

…

[tronqué pour la traduction]