RobinSp5/explicateur-de-cours

Explicateur de Cours Vidéo

Objectif : les étudiants doivent pouvoir comprendre un cours sans y assister et le réviser rapidement avant l'examen. La vidéo est donc un outil d'apprentissage, pas une vitrine : fidèle au cours, expliquée simplement, mémorisable, lisible à tout moment.

Trois principes guident chaque décision :

1. N'invente rien. Chaque affirmation, nombre, définition et graphique est basé sur les supports de cours. Simplifier est bienvenu ; ajouter des faits ne l'est pas. Quelqu'un qui rédige l'examen après avoir regardé doit pouvoir être certain que le contenu était dans le cours exactement comme ça.
2. Tout lisible, rien de coupé. Aucun texte à moitié visible, aucun débordement, aucune police minuscule. Une seule phrase tronquée détruit la confiance dans toute la vidéo.
3. Voix fluide, visuels calmes. Le narrateur ne fait pas de longues pauses. Là où il y a beaucoup à voir, l'image s'attarde brièvement avant de passer à autre chose – comme dans une bonne présentation.

Le livrable est la vidéo finie, téléchargeable en un seul MP4 directement dans Claude. L'utilisateur n'exécute jamais de code, de scripts ou de commandes et n'a jamais à coller de clé API – tout ce qui est technique se passe de votre côté, avec les outils que cet environnement offre. Pas de lecteur, pas de fichiers supplémentaires sauf si l'utilisateur les demande explicitement (sous-titres sous forme de fichiers, transcription, tableau du plan).

Parlez à l'utilisateur dans la langue dans laquelle il écrit. La langue de la vidéo est un choix distinct (Phase 1, étape 1).

Il existe deux modes, choisis dès la première question : narré (voix IA via OpenRouter, par défaut) et visuel uniquement (pas de voix – tout est expliqué à l'écran, voir "Mode visuel uniquement" ci-dessous). Partout où ce fichier parle de narration, TTS ou audio, cela s'applique uniquement au mode narré.

Flux de travail

Suivez les phases dans l'ordre. La phase 1 est un arrêt obligatoire : aucun argent n'est dépensé (TTS) tant que l'utilisateur n'a pas confirmé le mode, la langue, le modèle et la durée.

Phase 0 – Lire les supports

0. Regardez ce que cet environnement offre, en silence : le connecteur MCP OpenRouter (pour la voix), une sortie vidéo/animation intégrée avec exportation ou téléchargement MP4 (par exemple dans Claude Design), et/ou l'exécution de code avec ffmpeg + Chromium (pour scripts/render.py). La phase 7 choisit le chemin de sortie à partir de cela. Ne faites jamais installer ou exécuter quoi que ce soit à l'utilisateur.
1. Extrayez le PDF avec scripts/extract_pdf.py :

   python3 scripts/extract_pdf.py <pdf> <workdir> [--images]
   

   Cela produit pages.json (texte, nombre de mots, nombre d'images par page), un aperçu PNG de chaque page et – avec --images – les images intégrées. Si pymupdf est manquant : pip install pymupdf --break-system-packages.
2. Regardez les aperçus des pages (pas seulement le texte) : les diagrammes, tableaux et organigrammes existent souvent uniquement sous forme d'images. Pages scannées (sortie "SCANNED/pas de texte") : relancez avec --ocr (Tesseract, pack de langue des supports, par exemple --ocr-lang deu+eng). Si Tesseract ou le pack de langue est manquant, regardez les images d'aperçu et lisez le texte vous-même. Relisez toujours le texte OCR par rapport à l'image avant d'utiliser des termes techniques ou des nombres dans le script.
3. Déterminez à partir des supports : nom du cours, sujet de cette unité, conférencier/professeur, langue des supports, s'il y a une diapositive de résumé, et quelles diapositives n'ont pas de contenu (titre, ordre du jour, références, "Questions ?"). Tout ce qui n'est pas dans les supports n'est pas deviné – demandez-le dans la phase 1.
4. Questions ouvertes dans les diapositives : pages.json liste, par page, questions – des lignes qui posent une question à l'auditoire ("Qu'en pensez-vous : … ?", "Quels sont les avantages de … ?", "Discussion : …", "Question pour vous", "Why could …?"). Elles sont toutes répondues dans la vidéo (voir "Questions ouvertes" dans la phase 2). Lisez aussi les diapositives vous-même : les questions dans les graphiques ou les bulles de dialogue ne sont pas toujours détectées.
5. Cours ou exercice ? pages.json contient exercise_guess (mots comme "Übung", "Aufgabe", "Übungsblatt", "Exercise", "Task", "Assignment", tâches numérotées avec a), b), c)). Confirmez en lisant : une feuille d'exercices demande à l'apprenant de faire quelque chose. S'il s'agit d'un exercice (ou d'un cours avec des diapositives d'exercices), la vidéo résout les exercices – voir "Mode exercice" ci-dessous. Vérifiez également si une feuille de solutions ou des diapositives de solutions sont fournies.

La phase 0 s'exécute en silence : avant les premières questions (Phase 1, étape 1), vous ne demandez rien d'autre à l'utilisateur et ne résumez pas les supports. L'extraction existe uniquement pour que l'option "identique aux supports" puisse nommer la langue détectée.

Phase 1 – Demander à l'utilisateur (obligatoire, avant toute génération)

Étape 1 – Type de vidéo, narration et langue (toujours le tout premier message)

Le premier message contient exactement ces trois questions et rien d'autre (sous forme de trois questions cliquables si un tel outil est disponible), dans la langue de l'utilisateur, le type de vidéo en premier. Exemple pour un utilisateur germanophone :

1. Quel type de vidéo souhaitez-vous ?

• Résumé court – seulement l'essentiel : concepts clés, relations centrales, ce qui est pertinent pour l'examen ; idéal pour une révision rapide
• Résumé complet – couvre tous les sujets des supports, avec explications et exemples ; remplace le cours

2. La vidéo doit-elle être sonorisée ?

• Oui, avec un narrateur (voix IA) – explique comme dans le cours ; coûte quelques centimes
• Non, visuel uniquement – les explications apparaissent sous forme de texte et de graphisme à l'écran, pas de son, gratuit

3. Dans quelle langue doit être la vidéo ?

• Comme les supports (allemand) ← langue détectée entre parenthèses
• Allemand
• Anglais
• Autre langue (texte libre)

Le type de vidéo vient en premier car il décide de ce qui entre dans la vidéo et des durées qui ont du sens :

• Résumé court : seulement le cœur – termes et définitions clés, les relations centrales, tout ce qui est marqué comme pertinent pour l'examen, plus la diapositive de résumé. Les exemples, dérivations et sujets secondaires sont laissés de côté. Chaque chapitre du cours peut être abordé en une ou deux phrases, mais la profondeur ne va qu'à l'essentiel.
• Résumé complet : chaque sujet des supports est couvert – chaque page de contenu se retrouve dans au moins une scène (vérifié dans la phase 6 avec scripts/coverage.py), dans l'ordre du cours, avec les explications et exemples que le cours donne. Rien n'est sauté, seulement condensé.
• Pour un exercice : court = pour chaque tâche, l'approche en une ou deux phrases plus le résultat ; complet = le chemin de solution complet étape par étape.

La narration vient ensuite car elle change tout ce qui suit : avec "visuel uniquement", il n'y a pas de question de modèle, pas de coût, et la vidéo est construite différemment.

Gardez "identique aux supports" même si la langue détectée est l'allemand ou l'anglais – c'est la valeur par défaut. Pour les supports multilingues, nommez la langue dominante ("identique aux supports (principalement anglais)").

La langue choisie s'applique à tout : narration, texte à l'écran, introduction, résumé, étiquettes comme "regardez", instructions de livraison TTS. Elle détermine également quels modèles TTS sont éligibles et comment le budget de mots et le coût sont calculés – c'est pourquoi elle vient en premier.

Si la langue de la vidéo diffère de la langue des supports, appliquez les règles de traduction dans references/didactics-and-script.md (les termes techniques du cours restent visibles, car l'examen les utilise). Pour "autre langue" en mode narré : vérifiez d'abord brièvement si des modèles TTS la prennent bien en charge ; sinon, dites-le ouvertement et proposez des alternatives (y compris visuel uniquement).

Étape 2 – Durée, modèle, données clés, plan, quiz (un seul message)

Uniquement après les réponses à l'étape 1. En mode visuel uniquement, sautez b) (modèle) et ne citez aucun coût ; il n'y a alors pas d'étape 4 (voix).

Si les supports sont un exercice, dites-le en une ligne en haut de ce message ("C'est une feuille d'exercices avec 4 tâches – je les résous toutes étape par étape dans la vidéo.") – pas de question supplémentaire ; les suggestions de durée comptent alors les tâches, pas les pages (≈ 45–90 s par tâche selon la taille).

a) Durée de la vidéo. Suggérez des durées adaptées au type de vidéo de l'étape 1, dérivées du nombre de pages de contenu (n) – estimate.py lengths --content-pages n --type short|comprehensive :

Type de vidéo	Options (règle empirique)	Exemple, 30 pages
Résumé court	très court n × 4 s · court n × 6 s (par défaut)	~2 / ~3 min
Résumé complet	compact n × 10 s · standard n × 14 s (par défaut) · détaillé n × 18 s	~5 / ~7 / ~9 min

Arrondissez aux demi-minutes. Pour "complet", prévenez en une phrase si l'utilisateur choisit une durée inférieure à n × 8 s : tous les sujets sont toujours couverts, mais très brièvement. L'utilisateur décide ; une durée personnalisée est toujours autorisée.

b) Modèle TTS incl. le prix pour exactement cette vidéo (mode narré uniquement). La procédure et la formule de coût sont dans references/tts-models.md – lisez-le avant de demander. Version courte :

• Récupérez les modèles TTS actuels en direct via OpenRouter MCP (list-models avec output_modalities: "speech", trié par prix). Les prix et les modèles changent – ne répondez jamais de mémoire.
• Filtrez les modèles qui prennent en charge la langue de la vidéo choisie.
• Proposez 3–4 modèles, le meilleur pas cher en premier (de préférence une variante Google Gemini Flash TTS), chacun avec le prix estimé pour la durée choisie – calculez avec scripts/estimate.py.
• Si la durée n'est pas encore décidée : donnez les prix pour les trois options de durée.
• Le choix est contraignant. Lorsque l'utilisateur choisit un modèle OpenRouter, ce modèle exact (même ID de modèle, via OpenRouter MCP) DOIT être utilisé pour chaque fichier audio de cette vidéo – voir "Choix contraignant du modèle" dans la phase 4.

c) Données clés manquantes. Uniquement si non trouvées dans la phase 0 : nom du professeur, nom du cours. Proposez "sans nom" comme option au lieu de deviner.

d) Facultatif : afficher les images/graphiques du PDF directement (par défaut : oui, là où ils expliquent quelque chose).

e) Plan au début de la vidéo ? Oui / Non. Une phrase d'explication : juste après l'introduction, une courte table des matières montre chaque chapitre avec sa plage horaire ("0:18–1:30 Jointure Interne") et les numéros de diapositives, afin que les apprenants puissent voir la structure et sauter à ce dont ils ont besoin. Cela coûte environ 10 secondes. Le MP4 comporte également des marqueurs de chapitre, de sorte que les lecteurs peuvent passer d'un chapitre à l'autre dans les deux cas.

f) Questions d'auto-évaluation à la fin ? Oui / Non. Une phrase d'explication : des questions pour s'auto-évaluer avec une brève pause de réflexion suivie de la réponse – aide la mémoire plus que de revoir la vidéo.

Étape 3 – L'apparence (+ nombre de questions)

Un message avec deux questions sur l'apparence – et, uniquement si les questions d'auto-évaluation ont été choisies à l'étape 2 f), une troisième sur leur nombre (sous forme de questions cliquables si un tel outil est disponible ; les valeurs par défaut sont nommées en premier) :

Clair ou sombre ?

• Clair (Standard) · Sombre

Quel style ?

• Moderne (Standard) – accents colorés, dégradés doux, cartes avec ombres, cartes de titre de chapitre
• Sobre – calme, beaucoup de blanc ou de noir, une seule couleur d'accent
• Comme les diapositives – couleurs des diapositives du cours (par exemple, le bleu de l'université), pour correspondre au cours
• Adapté au thème : … – une proposition concrète dérivée du contenu, par exemple "Look base de données : bleu/turquoise avec une grille de tableau discrète", "Durabilité : tons verts avec motif de feuille", "Finance : bleu foncé/or avec lignes de graphique"

Combien de questions d'auto-évaluation ? (uniquement si choisi)

• 3 · 5 · 8 · nombre personnalisé – chacune avec une durée et un coût supplémentaires (voir ci-dessous)

Écrivez l'option "thème" comme une suggestion concrète pour ce cours, pas comme une étiquette générique. Sautez "Comme les diapositives" si scripts/palette.py ne trouve pas de couleurs distinctives (diapositives noir/blanc uni). Comment chaque réponse est construite : references/visual-rules.md, "Look".

Nombre de questions : options 3 / 5 / 8 / personnalisées. Pour chaque option, donnez la durée supplémentaire et le coût supplémentaire (estimate.py quiz --questions N --prompt … --completion … ; pour le total incluant le plan : estimate.py cost … --quiz N --toc), par exemple "5 questions · +1:45 min · +$0.02". Les questions s'ajoutent en plus de la durée choisie pour la partie explication ; indiquez la nouvelle durée totale une fois. Si les supports contiennent moins de points clés significatifs que le nombre de questions demandées, proposez-en moins et dites-le brièvement.

Étape 4 – La voix (mode narré uniquement)

Après le choix du modèle, posez trois courtes questions en un seul message (trois questions cliquables si un tel outil est disponible) ; les valeurs par défaut sont présélectionnées et nommées en premier :

Comment doit sonner la voix ?

• Féminine (Standard) · Masculine

Quel caractère ?

• Motivant & amical (Standard) · Calme & factuel · Ferme & clair · Décontracté & détendu

À quelle vitesse ?

• Lent · Normal · Rapide (Standard) · Très rapide

Par défaut lorsque l'utilisateur passe ou dit "peu importe" : une bonne voix féminine, vive, motivante pour expliquer. Faites correspondre les réponses à une voix concrète du modèle choisi et aux instructions de livraison/vitesse avec references/tts-models.md ("Choix de la voix") ; nommez la voix que vous avez choisie en une courte ligne ("Voix : Laomedeia – féminine, motivante, rapide"). Le rythme change le budget de mots : transmettez-le à estimate.py --pace. Après le test d'introduction (Phase 4), l'utilisateur peut toujours dire "autre voix" ou "plus lent" – alors refaites seulement l'introduction.

Phase 2 – Script

Lisez references/didactics-and-script.md. Ensuite, écrivez le script sous forme de script.json (schéma là-bas), scène par scène. Structure requise :

1. Introduction (≈ 8–12 s) : "Cette vidéo parle de … du cours … par le Prof. …" + un aperçu de ce qui vient en 3–5 points (organisateur avancé). Plan (uniquement si choisi, ≈ 10 s) : une scène directement après l'introduction avec <ol class="toc" data-toc>. Le fichier de scène remplit automatiquement chaque chapitre avec sa plage horaire et ses diapositives à partir du timing final – ne saisissez jamais les heures à la main, elles changent à chaque régénération audio. La narration nomme les chapitres en une ou deux phrases ("D'abord …, ensuite …, et à la fin un résumé et un auto-test") et ne lit pas les heures. Marquez la scène data-dense avec data-hold ≈ 3 s pour que le plan puisse être lu. Lorsqu'un plan est choisi, l'ordre du jour de l'introduction elle-même peut être plus court (une phrase) pour que rien ne soit dit deux fois.
2. Partie principale : chapitres dans l'ordre du cours. Explication

…

[tronqué pour la traduction]