chuonglife/lesson-video-producer-skill

Lesson Video Producer

Verwandle das Foliendeck einer Lektion in ein fertiges Lehrvideo: Eine synthetische Stimme liest die Erzählung, jede Karte, jeder Schritt oder jede Zeile erscheint genau dann, wenn die Stimme sie erreicht, die Übergänge variieren, sanfte Soundeffekte markieren jede Einblendung, ein Klavierbett duckt sich unter die Stimme, ein Countdown läuft, wo Lernende pausieren, Schlüsselelemente erhalten einen handgezeichneten Kreis, Untertitel kommen als separate Dateien, und echte Bildschirmaufnahmen werden in Anleitungslektionen eingefügt. Eine Lektion nach der anderen; ausführen, ansehen, dann übergeben.

Eingabe, aus dem lesson-slide-designer-Skill: slides/<kurs>/<lektion>/slides.json, <dateiname>.pptx und _preview/slide-NN.png. Wenn sie fehlen, baue zuerst das Deck. Decks aus der vietnamesischen Ausgabe (kieu, loi_doc, _kiem/) werden ebenfalls gelesen.

Ausgabe in videos/<kurs>/<lektion>/ (spiegelt den Slide-Pfad wider; sonst <slides-Ordner>/video/):

Datei	Beschreibung
<dateiname>.mp4	Das Video: 1920x1080, 30 fps, H.264, AAC 48 kHz, -16 LUFS
<dateiname>.<sprache>.vtt / .srt	Untertitel als separate Dateien, nie eingebrannt (sie würden Folientext verdecken); lade die .vtt als Untertitel hoch
<dateiname>.narration.txt	Bereinigte Erzählung, ein gesprochener Takt pro Zeile; `
<dateiname>.storyboard.json / .md	Was wann passiert: aus der pptx gemessene Regionen, die Zeile, auf der jede erscheint, Effekte, Übergänge, Kreise, Zooms, Countdowns; die .md dient der Überprüfung per Auge
<dateiname>.voice.mp3 + .timeline.json	Die Erzählung und der genaue Start und Ende jeder Zeile (Zeilen werden in .voice.mp3.cache/ zwischengespeichert)
<dateiname>.events.json, .audio.mp3	Soundereignisse und der Dreischicht-Mix
video.json (optional, du schreibst es)	Pro-Folien-Überschreibungen: Einblendezeilen, Übergang, Halten, Kreis, Zoom, Bildschirmaufnahme
_check/	contact-NN.png (Einzelbilder des fertigen Videos), <dateiname>.report.md (Messungen), voice-review.txt (Whisper), voice-exceptions.txt
_segments/	Ein gerendertes Segment pro Folie, wird wiederverwendet, wenn sich diese Folie nicht geändert hat

Werkzeuge: Python 3.10+ mit python-pptx, numpy, Pillow (opencv-python zum Glätten von Aufnahmen, faster-whisper für die Sprachüberprüfung); Node 18+ mit puppeteer-core (npm install in assets/engine) und Chrome, Chromium oder Edge; ffmpeg/ffprobe. Stimmen: Kokoro (pip install kokoro soundfile) oder VieNeu-TTS, beide Apache 2.0 und lokal. Wenn eine Engine in ihrer eigenen virtuellen Umgebung lebt, setze KOKORO_PYTHON oder VIENEU_PYTHON auf dieses Python. Eine GPU hilft, ist aber optional.

Workflow

Schritt 0. Das Deck lesen und die Aufgabe klären

1. Lese slides.json (Erzählung, Produktionsnotizen, Folientypen) und wirf einen Blick auf _preview/contact-sheet.png. Wenn der Lektionsquelltext existiert, lies ihn, um zu wissen, wo Lernende üben und wo ihnen Fragen gestellt werden.
2. Lese references/video-standards.md (der Standard: ein Thema, Skript, Einleitung-Hauptteil-Schluss, Übergänge, Interaktion) und references/motion-and-sound.md (was jeder Folientyp bekommt und warum sich das Video bewegen muss, ohne hektisch zu werden).
3. Kläre: Sprache und Stimme (language in slides.json; Englisch standardmäßig Kokoro am_michael, af_heart für eine weibliche Stimme, andere Kokoro-Sprachen per Stimmenpräfix, Vietnamesisch VieNeu); ob die Lektion echte Bildschirmaufnahmen benötigt (jede Lektion, die Klicks, Tippen oder Software lehrt: ja, siehe Schritt 2); welche Fragenfolien pausieren und wie lange; was umkreist oder gezoomt werden soll. Die Erzählung wurde im Folienschritt für Text-to-Speech geschrieben. Schreibe den Lehrinhalt hier nicht um; korrigiere nur, wie ein Wort ausgesprochen wird, wenn die Stimme es falsch macht.

Schritt 1. Das Storyboard erstellen und überprüfen

python scripts/storyboard.py slides/<kurs>/<lektion>/slides.json

Lies <dateiname>.storyboard.md: Regionen pro Folie, die Zeile, auf der jede erscheint, Übergänge, Halte, Kreise. Überprüfe es gegen Abschnitt 4 von motion-and-sound.md: Die dritte Karte erscheint, wenn die Stimme die dritte Idee erreicht; Nachbarn teilen nie einen Übergang; Fragenfolien halten; ein Hinweis wie „Kreis Antwort B“ hat einen Kreis erzeugt. Korrigiere mit video.json (siehe templates/video.example.json) und führe es erneut aus. „Keine Regionen gefunden“ bedeutet, dass die Folie als Ganzes erscheint: in Ordnung für image, überprüfe die pptx bei anderen Typen.

Schritt 2. Echte Bildschirmaufnahmen (Anleitungs-, Praxis- und Softwarelektionen)

Wenn die Lektion eine Aktion lehrt, zeige die reale Aktion. Ersetze sie niemals durch einen Screenshot oder eine nachgebaute Seite. Regeln in references/screen-recording.md. Kurz gesagt:

1. Bereite das Fenster vor: ein privates Browserfenster oder ein sauberes Konto, keine Benachrichtigungen, keine echten Namen in Seitenleisten. Unter Windows: python scripts/record_screen.py --list gibt Fenstertitel aus.
2. Nimm auf: python scripts/record_screen.py videos/<kurs>/<lektion>/clips/S07-name.mp4 --window "<titel>" --seconds 40 --size 1280x720 [--crop-top 90] [--scroll "6:200:4"] (Windows; auf anderen Systemen OBS oder ffmpeg verwenden). Steuere die Klicks und das Tippen selbst über Browser-Tools oder lass den Benutzer sie ausführen. Scrolle nur mit --scroll oder einem sanften In-Page-Scroll (window.scrollBy({top: 200, behavior: 'smooth'}) alle 0,6 bis 0,8 s), niemals ruckartig. Halte nach jedem Ergebnis 3 bis 5 s lang still; scrolle lange Ergebnisse langsam (150 bis 250 px/s), damit Lernende sie lesen können.
3. check_motion.py läuft nach jeder Aufnahme. Bleibt ein Sprung übrig: python scripts/smooth_scroll.py <in> <out>, dann erneut messen, bis null erreicht ist. Überprüfe das obere Band des Clips auf Kontonamen und verlorene Tabs.
4. Deklariere es in video.json: "S07": {"clip": {"file": "clips/S07-name.mp4", "mode": "frame", "speed": "auto"}}. Die Folie sollte eine image- oder two-column-Folie mit einem großen Rahmen sein; platziere das erste Bild des Clips darauf (composite_clips.py --first-frame clips/S07-name.mp4 slides/<kurs>/<lektion>/S07-first-frame.png) und baue das Deck neu, sodass der Clip ohne Sprung einblendet.
5. Führe make_video.py ... --extend aus: Es fügt Stille hinzu, wo eine Aufnahme länger läuft als ihre Erzählung. Beschleunige eine Aufnahme niemals über 1,25x.

Schritt 3. Mit einem Befehl rendern

python scripts/make_video.py slides/<kurs>/<lektion>/slides.json [--extend]

Neun Schritte: Storyboard, Erzählung (über gpu_lock.py), Whisper-Überprüfung, Renderplan, Dreischicht-Mix, Bild (Headless Chrome, Folie für Folie), Bildschirmaufnahmen, Untertitel, Endkontrolle. Führe es im Hintergrund aus für Lektionen über 3 Minuten (das Rendern dauert beim ersten Mal etwa ein bis zwei Minuten pro Minute Video, bei einer folienweisen Korrektur nur Sekunden). Wenn es stoppt:

• Sprachüberprüfung (_check/voice-review.txt): Whisper hört sich die gesamte Datei einmal an, dann werden nur die verdächtigen Zeilen neu generiert und erneut überprüft, bis zu 3 Runden. Es filtert Whispers eigene Fehler bei kurzen Wörtern, Phrasen, die es über Musik erfindet, und alles, was ein zweites, vorbereitetes Hören richtig versteht, heraus; es stoppt nur bei langen Wörtern, Begriffen, Namen oder mehreren Wörtern hintereinander. Höre an die Stelle (ffmpeg -ss 1:23 -t 4 -i <voice.mp3> clip.wav). Wenn die Stimme falsch ist, füge eine Umschrift zu PRONUNCIATION in make_voice.py hinzu (Untertitel behalten die echte Schreibweise) oder ändere das Wort in slides.json; wenn Whisper es falsch verstanden hat, füge das Wort zu _check/voice-exceptions.txt hinzu. Dann --from-step 2 (zwischengespeicherte Zeilen werden nicht neu generiert).
• Endkontrolle FEHLGESCHLAGEN (_check/<dateiname>.report.md): Korrigiere die Ursache (Lautstärke mit --music-db, Sprünge durch Glätten der Aufnahme, Länge durch erneutes Rendern) und führe es ab diesem Schritt erneut aus.

Schritt 4. Vor dem Berichten ansehen

1. Sieh dir _check/contact-NN.png an (drei Einzelbilder pro Folie: Ankunft, eingestellt, kurz vor Verlassen) mit der Checkliste in references/quality-checks.md: ein Cover-Fleck, der über Text liegt, durch einen Zoom abgeschnittener Text, zwei gleichzeitig während eines Übergangs sichtbare Folien, ein Countdown über Text, eine Aufnahme außerhalb ihres Rahmens, ein leeres erstes Bild. Um einen Moment genau zu inspizieren: node assets/engine/render.mjs sheet <storyboard.json> <timeline.json> _check/zoom --from 40 --to 46 --every 0.25.
2. Höre an zwei Stellen: die ersten 20 s und einen Übergang (ffmpeg -ss 0 -t 20 -i <mp4> -vn test.mp3). Effekte hörbar, aber deutlich unter der Stimme, Musik leise.
3. Korrigiere mit video.json oder den Skripten, rendere erneut (nur geänderte Folien werden neu gerendert), sieh erneut nach, bis ein vollständiger Durchlauf nichts mehr findet. Melde ein Video nie als fertig, bevor du dir die Kontaktabzüge des letzten Renderdurchlaufs angesehen hast.

Schritt 5. Bericht

Gib dem Benutzer: die mp4- und vtt-Pfade; tatsächliche Dauer; Stimme und Tempo (Wörter pro Sekunde); Folien, Effekte, Pausen; den Prüfbericht (Urteil, LUFS, Sprünge); welche Aufnahmen zusammengesetzt wurden; zur Aussprachetabelle oder den Whisper-Ausnahmen hinzugefügte Wörter; verbleibende Warnungen und warum. Zeige ein Kontaktblatt.

Mehrere Lektionen hintereinander

Behalte Stimme, Musikpegel und Sounds innerhalb eines Kurses bei; Lektionen sollten sich um nicht mehr als 1,5 LU unterscheiden (vergleiche die LUFS-Linie jedes Berichts). Die Aussprachetabelle und die Whisper-Ausnahmen wachsen mit der Zeit; setze sie nicht zurück. Bewahre Aufnahmen in videos/<kurs>/<lektion>/clips/ auf, ein neuer Dateiname pro Take. Ein Deck, das in Themenvideos aufgeteilt ist (V<k>-<name>/slides.json), wird einzeln pro Unterdeck gerendert.

Grundsätze

• Der Standard ist festgelegt (video-standards.md): ein Thema pro Video, ein Skript, Einleitung-Hauptteil-Schluss, gesprochene Übergänge zwischen Teilen, Interaktion. Rhythmus, Bild und Ton sind die Bereiche, in denen du kreativ wirst.
• Bild und Stimme ergänzen sich; die Stimme liest nie die Folie vor. Eine Region erscheint, wenn die Stimme sie erreicht; Text, der gerade vorgelesen wird, bewegt sich nicht.
• Mit dem Bildschirm übereinstimmende Pausen: Eine Erzählung, die sagt „Pausiere das Video“, erhält einen 3-sekündigen Halt und keinen Countdown (der Lernende drückt Pause; ein laufender Timer neben einem „60 Sekunden“-Label würde dem widersprechen). Eine Frage ohne diesen Satz hält für die angegebene Zeit, höchstens 60 s, mit Countdown.
• Aufmerksamkeitskreise: Antworten und Notizen wie „Kreis B“ erhalten einen bewussten Kreis; eine Idee, die mit einem Betonungswort vorgelesen wird, erhält einen automatischen Kreis, der verblasst; Ellipsen für Karten, abgerundete Kästen für Zeilen; höchstens drei pro Folie.
• Cursor standardmäßig aus. Ein gezeichneter Zeiger wirkt auf die meisten Zuschauer wie eine verlorene Maus. Schalte ihn mit {"_all": {"cursor": true}} in video.json für Demo-Videos ein; er bewegt sich auf Kurven, ruht außerhalb von Text und erscheint nie auf Titel-, Abschnitts-, Kernaussagen- oder Abschlussfolien.
• Lebendig, nicht hektisch: Alle 5 bis 10 Sekunden ändert sich etwas, und nichts steht länger als 25 Sekunden still; aber ein Brennpunkt pro Bild, keine Drehungen oder Überschläge, höchstens 16 Soundeffekte pro Minute, Übergangsgeräusche nur bei Folienwechseln, Musik 17 bis 23 dB unter der Stimme.
• Die Stimme ist die Qualität, die man zuerst hört. Dehne kein Modell zeitlich, das gedehnt schlecht klingt (VieNeu); verlangsame es stattdessen mit längeren Pausen. Die Whisper-Überprüfung ist nicht optional: Ein falsch ausgesprochener Begriff ist ein Lehrfehler.
• Untertitel sind separate Dateien, niemals eingebrannt.
• Der Inhalt ändert sich im Videoschritt nicht: keine neuen Ideen, keine erfundenen Zahlen. Ein Erzählungsproblem geht zurück zum Lektions- oder Folienschritt.
• Ausführen, messen, ansehen, bevor du übergibst: Lautstärke, Sprünge, Dauer, Kontaktabzüge.
• Eine Aufnahme ist eine Aufnahme: keine Screenshots, die für Aktionen stehen; Scrollen muss glatt gemessen werden.
• Um einen Übergang, Effekt oder Sound hinzuzufügen: erweitere assets/engine/video.js, die Tabellen in scripts/storyboard.py und references/motion-and-sound.md, rendere einen Test, sieh ihn dir an, verwende ihn dann.

Referenzen

• references/video-standards.md: der didaktische Standard für Audio- und Video-Lernmaterialien, auf Folientypen abgebildet, plus Plattform-Spezifikationen (Udemy und ähnliche).
• references/motion-and-sound.md: wie Regionen und Aktionen abgeleitet werden, die Folientyp-Tabelle, Bewegungszahlen, der Soundtrack, video.json-Syntax, wie Lernende wach gehalten werden.
• references/narration-voice.md: Kokoro und VieNeu, Tempo, Aussprachekorrekturen, die Whisper-Überprüfung.
• references/screen-recording.md: Aufnahme eines Fensters, sanftes Scrollen, Messen und Glätten von Sprüngen, Compositing, Privatsphäre.
• references/quality-checks.md: Schwellenwerte der Endkontrolle und die Checkliste für das Kontaktblatt.
• templates/video.example.json: Pro-Folien-Überschreibungen.