soil-motion-deck

SOIL Animierte Lehrpräsentation: Einmal erstellen, zwei Ergebnisse

Ergebnis	Inhalt	Verwendung
A Präsentation (.pptx)	SOIL-Sechs-Motoren-Lehrpräsentation. 2–4 🎬 Animationsseiten enthalten stumme, untertitellose Animationsausschnitte, die die Lehrkraft während des Vortrags erläutert	Vorlesungsprojektion
B Video (MP4)	Vollständiger Erklärfilm zum gleichen Stoff: Sprachausgabe, Untertitel, Dreifarben-Thema	Vorkurs, Nachbereitung, Upload

Beide Ergebnisse teilen sich dieselben Animationen: Zuerst wird B erstellt, dann werden aus der stummen Zwillingsversion die 🎬-Seiten-Clips ausgeschnitten und in A eingebettet. So wird die Animation nur einmal erstellt und die Längen in beiden Formaten sind exakt identisch.

Dieses Skill ist nur für die Verknüpfung zuständig. Die Ausführung richtet sich nach zwei übergeordneten Skills:

• soil-teaching-deck (mathruffian-dot/soil-teaching-deck): Sechs Motoren, Seitenrollen, visuelle Layouts, Sandwich-Struktur, F-0-Schriftarten-Installation.
• motion-explainer (mathruffian-dot/claude-motion-explainer) sowie die damit verbundenen Skills motion-design, review-loop und die offiziellen HyperFrames-Skills: Drehbuch, Erzählerstimme, Einzelbild-Erstellung, Untertitel, Dreifarben-Thema, Qualitätssicherung, Ausgabe.

0. Umgebung und Pfade

Dieses Dokument verwendet drei Platzhalter, deren tatsächliche Pfade vor Beginn ermittelt werden müssen:

Platzhalter	Beschreibung	Typischer Pfad
<smd>	Ordner dieses Skills	~/.claude/skills/soil-motion-deck (Claude Code), ~/.agents/skills/soil-motion-deck (Codex)
<me>	Ordner des motion-explainer-Skills	Wie oben, Ordnername motion-explainer
<soil>	Ordner des SOIL-Skills	Wie oben, Ordnername soil-teaching-deck

ls -d ~/.claude/skills/{soil-motion-deck,motion-explainer,soil-teaching-deck,review-loop} ~/.agents/skills/{soil-motion-deck,motion-explainer,soil-teaching-deck,review-loop} 2>/dev/null

PowerShell (falls kein bash auf Windows vorhanden):

Get-ChildItem "$HOME\.claude\skills","$HOME\.agents\skills" -Directory -ErrorAction SilentlyContinue | Select-Object FullName

Andere Agenten (z. B. Gemini CLI): Im entsprechenden Skills-Ordner des Agents nach gleichnamigen Ordnern suchen.

Fehlt einer, bittet man den Benutzer, die Installation gemäß der README des entsprechenden Repos durchzuführen (jedes Repo kopiert die Ordner aus skills/ oder skill/ in den Skills-Ordner des Agents). Das SOIL-install.py installiert nur in den ersten gefundenen Ordner und wartet auf die Eingabetaste. Bei manueller Installation durch den Agenten: cp -r soil-teaching-deck/skill <skills-Ordner>/soil-teaching-deck.

Weitere Anforderungen:

• Abhängigkeiten der beiden übergeordneten Skills: Node.js 22+, ffmpeg, Python 3, HyperFrames und ein TTS: edge-tts (Standard) (keine GPU nötig, Standard für die meisten Benutzer); oder Breeze TTS 2 (fortgeschritten, benötigt NVIDIA GPU, nur für Forschung und nicht-kommerzielle Nutzung, Installation nur auf Wunsch des Benutzers gemäß motion-explainer/references/tts-setup.md).
• Präsentation: PptxGenJS 3.12.0 (Installation über die templates/package.json dieses Skills, siehe §5), Schriftarten GenSekiGothic2 H / B / M (gemäß SOILs F-0-Installation).
• Vorschaubilder: Windows mit PowerPoint ist am besten (das Skript thumbs.py verwendet PowerPoint direkt zur Ausgabe, Schriftarten und Videocover sind identisch zur Projektion). Ohne PowerPoint kann LibreOffice + poppler verwendet werden – damit kann man das Layout prüfen, sieht aber nicht unbedingt die Videocover.
• Getestete Versionen: HyperFrames 0.8.168, PptxGenJS 3.12.0.

Agenten ohne Sub-Agenten (z. B. manche Codex-, Gemini-Konfigurationen): Dort, wo motion-explainer „pro Einzelbild einen Sub-Agenten parallel arbeiten lassen“ sagt, arbeitet man die Einzelbilder nacheinander ab; die gelesenen Dateien und die Reihenfolge bleiben gleich.

1. Einleitendes Interview (einmal alles abfragen)

1. Fach, Einheit/Skript, Zielgruppe, Unterrichtsdauer (Nachfrage des SOIL-Skills).
2. Welche Ergebnisse gewünscht: A+B (Standard), nur A, nur B. Auch bei nur A wird zuerst B erstellt: Die Erzählerstimme bestimmt den Rhythmus jedes Einzelbildes, damit die Animation natürlich wirkt. B wird nur nicht ausgeliefert, die Erzählerstimme muss nicht vom Benutzer probegehört werden.
3. Farbgebung. Standard ist „Video-Dreifarben + SOIL-Sandwich“:
   • Video (und das Animationsfenster in der Präsentation) verwendet die Dreifarben von motion-explainer, Standardmäßig schwarzer Hintergrund #121212, weiße Schrift #F2F0EA, orangefarbener Akzent #FF7A1A.
   • Die Titelseite, Aktionsseite und Schlussfolgerung der Präsentation sind dunkle Seiten und verwenden die Videofarben; Inhaltsseiten sind helle Seiten, die Animation befindet sich in einem dunklen „Fenster“.
4. Erzählerstimme: Gemäß den Regeln von motion-explainer.

Das eigene einleitende Interview von motion-explainer (Plattform, Länge, Stimme, Dreifarben) wurde hier bereits durchgeführt, nicht erneut nachfragen. Die Videolänge ist auch nicht durch die „60–90 Sekunden“-Empfehlung von motion-explainer eingeschränkt: Die Länge entspricht der Länge der Erzählerstimme, normalerweise 15–25 Sekunden pro 🎬-Seite, zuzüglich einiger Bilder am Anfang und Ende.

2. SOIL-Motoren eins bis drei, 🎬 Animationsseiten markieren

Führe die Motoren eins (Konzept-Ortung), zwei (Kontext-Ortung) und drei (Seitenstruktur) gemäß soil-teaching-deck aus. Nach jedem Motor dem Benutzer zur Bestätigung vorlegen. Füge in der Seitenrollentabelle von Motor drei bei den zu animierenden Seiten ein animate-Feld ein. Markiere mit 🎬, nicht mit ★ (SOILs ★ steht für „Schlüsselseite“ und hat eine andere Bedeutung):

Seite 6: Warum gilt es immer? Flächenpuzzle 🎬
- Seitenrolle: Prozessseite
- Einziger Hauptpunkt: Großquadrat und Dreiecke ändern sich nicht, also sind die freien Flächen gleich groß
- animate: { frame: 04-proof, poster: last }

frame ist der Dateiname des Einzelbildes im Video (ohne .html), der in §3 beim Storyboard festgelegt wird: Wenn die src in STORYBOARD.md des Einzelbildes compositions/frames/04-proof.html ist, dann schreibt man hier 04-proof. Die Länge jedes Abschnitts wird durch die Erzählerstimme bestimmt, nicht hier angegeben.

Welche Seiten eine Animation lohnen (insgesamt 2–4 Seiten, jede 15–25 Sekunden): Seiten, bei denen „sich etwas im Laufe der Zeit ändert“ selbst der Kern ist.

Geeignet	Beispiele
Herleitungen, Beweise, Prozesse	Puzzle-Beweis, Reaktionsverlauf, Lichtweg
Mengenakkumulation oder -vergleich	Zählen von Kästchen 9 + 16 = 25, Balkenwachstum
Umkehrung von Fehlvorstellungen	Falsche Aussage → X → korrekte Aussage
Räumliche Beziehungen	Drehung, Verschiebung, Abwicklung, schräg gelegtes Quadrat

Nicht geeignet: Definitionen, Tabellen, Übungsaufgaben, Zusammenfassungen – diese Seiten werden mit SOILs visuellen Layouts erstellt.

3. Vom Präsentationsablauf zum Videodrehbuch (Übergabe)

Die Einzelbilder des Videos folgen dem Ablauf der Präsentation. Schreibe zuerst eine Zuordnungstabelle in BRIEF.md des Videoprojekts. Die Dateinamen werden hier endgültig festgelegt:

Präsentationsseite	Videobild (Dateiname)	Erzählerstimme	Verwendung
2 Problem-Einführung	01-ladder	Kontextproblem von Motor eins	Nur im Video
🎬 3	02-squares	Einziger Hauptpunkt dieser Seite	Ausgeschnitten als p03
4–5 Konzepte	03-names	Gesamtkonzept + Begriffe	Nur im Video
🎬 6	04-proof	Einziger Hauptpunkt dieser Seite	Ausgeschnitten als p06
…	…	…	…
13 Zusammenfassung	07-takeaway	„Ein Satz zum Mitnehmen“ von Motor eins	Nur im Video

Die Namen der ausgeschnittenen Segmente verwenden p + zweistellige Seitenzahl (p03, p06) und stimmen mit den Namen in video(s, "p06", …) in build_deck.js überein.

Schreibe dann gemäß dem Format von motion-explainer SCRIPT.md (pro Zeile ein ## Line N) und STORYBOARD.md (die src jedes Bildes verwendet den Dateinamen aus der obigen Tabelle). Das Material für die Erzählerstimme wird direkt aus SOILs Ergebnissen übernommen:

• „Drei häufige Fehlvorstellungen“ von Motor eins → Die drei Erzählerpassagen für das Einzelbild zur Fehlvorstellungsumkehrung.
• „Ein Satz zum Mitnehmen“ von Motor eins → Die Erzählerstimme des letzten Bildes, unverändert; die Zusammenfassungsseite der Präsentation verwendet denselben Satz.
• Der „einzige Hauptpunkt“ jeder 🎬-Seite → Der letzte Satz der Erzählerstimme in diesem Bild.
• Längenschätzung: 4–4,5 chinesische Zeichen pro Sekunde. Die Erzählerstimme eines 🎬-Bildes ist etwa 70–100 Zeichen (15–25 Sekunden) lang.

Wenn ein 🎬-Bild an einen Worker übergeben wird, muss _dispatch_context.md diese vier zusätzlichen Angaben enthalten (sie werden separat für die Wiedergabe ohne Ton und Untertitel benötigt):

1. Auch ohne Ton verständlich: Wichtige Zahlen, Beschriftungen und Schlussfolgerungen müssen auf dem Bild sein, nicht nur in der Erzählerstimme.
2. Von leer beginnend, endend mit Schlussfolgerung: Der letzte Zustand muss vollständig und mindestens 1 Sekunde still sein, da er das Cover auf der Folie ist.
3. Wichtiger Inhalt nicht im Untertitelbereich (y > 896 px): Videountertitel würden ihn überdecken; in der Präsentation gibt es zwar keine Untertitel, aber dasselbe Bild muss in beiden Formaten funktionieren.
4. Die Übergänge zwischen den Bildern (gleiche Leiter, gleiches Dreieck) werden normal erstellt; beim Schnitt werden die überlappenden Bereiche automatisch entfernt.

Ab hier wird der Prozess von motion-explainer vollständig befolgt: Erzählerstimme → Kameraeinstellungen → jedes Einzelbild (parallel mit Sub-Agenten, sonst nacheinander) → Zusammenbau, Untertitel, Farbgebung → Entwurfsprüfung → Ausgabe B.

4. Stumme Zwillingsversion → 🎬-Segmente ausschneiden

Verwendung absoluter Pfade oder Ausführung aus demselben Ordner. $FILM steht für den vollständigen Pfad des Videoprojekts:

python <smd>/scripts/make_silent.py --project "$FILM"            # Erstellt $FILM-silent: entfernt alle Audiospuren und Untertitel
(cd "$FILM-silent" && npx hyperframes render --quality high --output renders/silent.mp4)
python <smd>/scripts/cut_clips.py --project "$FILM" --video "$FILM-silent/renders/silent.mp4" \
    --map p03=02-squares p06=04-proof p09=06-myths@first --out "$FILM/deck/media"

• cut_clips.py liest den Beginn und die Dauer jedes Bildes aus index.html und schneidet vom Ende der Überlappung mit dem vorherigen Bild bis zum Beginn der Überlappung mit dem nächsten Bild. Unabhängig davon, ob der Übergang ein Crossfade, Push-Slide oder Zoom-Through ist, werden keine Teile des vorherigen oder nächsten Bildes mit hineingemischt. Das Skript gibt die Länge jedes Segments aus und schreibt sie in die Sprechernotizen.
• Das Titelbild ist standardmäßig das letzte Bild (endet mit der Schlussfolgerung). Um dies segmentweise zu überschreiben, wird @first oder @Sekunden an das Mapping angehängt (z. B. [email protected]). Bei Fehlvorstellungsseiten, bei denen die Antwort nicht vorweggenommen werden soll, wird @first verwendet.
• Jede Änderung am Video (Einzelbild, Farbgebung, Länge): make_silent.py erneut ausführen, rendern, cut_clips.py erneut ausführen. Die Zwillingsversion ist eine Momentaufnahme und wird nicht automatisch aktualisiert.

5. Präsentation erstellen (SOIL-Motoren vier bis sechs)

1. Motor vier (kognitive Bearbeitung) und Motor fünf (Stil) gemäß den SOIL-Regeln ausführen. Motor fünf verwendet das in Schritt 1 gewählte Farbschema.
2. Präsentationsordner erstellen. Zwingend die package.json dieses Skills verwenden: Die package.json im Stammverzeichnis des HyperFrames-Projekts hat "type": "module", ohne eine eigene package.json schlägt require fehl.

mkdir -p "$FILM/deck" && cp <smd>/templates/package.json <smd>/templates/deck_helpers.js "$FILM/deck/"
cp <smd>/templates/example_pythagoras.js "$FILM/deck/build_deck.js"     # Ausgehend vom Beispiel anpassen
(cd "$FILM/deck" && npm install)

3. build_deck.js anpassen. Der Anfang ist fix wie folgt. Alle Layouts verwenden LAYOUT_WIDE (13,333 × 7,5 Zoll): Das SOIL-PptxGenJS-Spickzettel verwendet LAYOUT_16x9 (10 Zoll breit) und Microsoft JhengHei, dies hier nicht übernehmen; die Koordinaten in deck_helpers.js sind alle für 13,333 Zoll Breite ausgelegt. Die Schriftarten folgen den SOIL-Regeln: Titel GenSekiGothic2 TW H, Fließtext GenSekiGothic2 TW M.

const path = require("path");
const pptxgen = require("pptxgenjs");
const { makeDeck } = require("./deck_helpers");
const pptx = new pptxgen();
pptx.layout = "LAYOUT_WIDE";
const D = makeDeck(pptx, { theme: { bg: "121212", fg: "F2F0EA", accent: "FF7A1A" }, mediaDir: path.join(__dirname, "media") });
const s = D.lightSlide("Prozess・Animation");
D.title(s, "Warum gilt es immer? Flächenpuzzle");
D.video(s, "p06", 0.6, 2.0, 8.0);   // Links: 8 Zoll breites Videofenster (16:9), darunter Hinweis "Zum Abspielen klicken"
// Rechts: x = 9.0, Breite 3.9 Zoll: Schritt-für-Schritt-Zusammenfassung oder Kernaussage der Animation, damit die Seite auch ohne Abspielen verständlich ist
pptx.writeFile({ fileName: path.join(__dirname, "Einheitsname.pptx") });

4. Layout der 🎬-Seiten: Links die Animation (8.0 × 4.5 Zoll), rechts 2–3 Schritte oder die Schlussfolgerung. Die Sprechernotizen enthalten: Videolänge, Stellen, an denen die Schüler unterbrochen werden sollen, und die erwarteten Antworten.
5. Alle anderen Seiten gemäß den SOIL-Seitenrollen und visuellen Layouts erstellen. Die Antworten auf Übungsaufgaben in die Sprechernotizen schreiben, nicht auf die Folie.
6. node build_deck.js ausführen. Solange die Segmente noch nicht geschnitten sind, zeigt video() zunächst einen Platzhalterrahmen an; das Layout kann dennoch erstellt werden.

Der Benutzer hat bereits eine SOIL-Präsentation: PptxGenJS kann keine vorhandene .pptx-Datei ändern. Gemäß dem SOIL-Modus „Diagnose und Änderung“ den Inhalt jeder Seite auslesen (python -m markitdown <Datei>.pptx, falls markitdown nicht verfügbar, bittet man den Benutzer um den Text), die zu behaltenden Seiten unverändert in build_deck.js übernehmen, die ausgewählten Seiten in das 🎬-Layout umwandeln und die gesamte Präsentation neu erstellen. Bei der Übergabe erläutern, dass es sich um eine neu erstellte Datei handelt, die Originaldatei nicht verändert wurde.

6. Qualitätssicherung

python <smd>/scripts/thumbs.py "$FILM/deck/<Präsentation>.pptx" --out "$FILM/deck/thumbs"   # Pro Seite ein PNG + Übersichtsbild deck-*.png

Das in der SOIL-Dokumentation erwähnte thumbnail.py (pptx-Skill) muss nicht extra gesucht werden; dieses thumbs.py ist ausreichend. Die Übersichtsbilder seitenweise durchgehen und mit der folgenden Checkliste abgleichen:

• Das Cover der 🎬-Seiten ist das entsprechende Einzelbild der Animation, kein schwarzer Rahmen oder Platzhaltertext.
• Das Animationsfenster wird von keinem anderen Text oder Grafikelement überdeckt; der Abspielhinweis darunter ist sichtbar.
• Jede Seite hat nur einen Hauptpunkt; Sandwich-Struktur (dunkle Deck-, Aktions-, Schlussfolgerungsseiten, helle Inhaltsseiten).
• Die Akzentfarbe in Präsentation und Video stammt aus demselben Farbschema (auf hellen Seiten kann eine dunklere Abstufung derselben Farbe verwendet werden, z. B. #E8601A zum Video-#FF7A1A); Zahlen und Begriffe sind in beiden Formaten identisch.
• Sprechernotizen enthalten die Videolänge, Stellen für Fragen und die Antworten.
• Die Antworten auf die Übungsaufgaben wurden selbst einmal durchgerechnet.
• Die Qualitätssicherung für Video B erfolgt gemäß review-loop (jeder Untertitelabschnitt als Einzelbild, Bild für Bild prüfen).

7. Übergabe

Übergib die Pfade zur .pptx und zum MP4 mit folgender Erläuterung:

• Welche Seiten die 🎬-Seiten sind, deren jeweilige Länge (in Sekunden) und welches Einzelbild für das Cover verwendet wurde.
• Der Präsentationscomputer muss die Schriftarten GenSekiGothic2 installiert haben (die .pptx bettet Schriftarten nicht ein; bei fehlenden Schriftarten wird auf Systemschriftarten zurückgegriffen).
• Das Video ist in die .pptx eingebettet und kann sowohl in PowerPoint als auch in Keynote direkt abgespielt werden. Der Import in Google Präsentationen behält eingebettete Videos möglicherweise nicht bei; für Google Präsentationen die media/*.mp4-Dateien in die Cloud hochladen und dann als Video einfügen.
• Der Benutzer sollte die Aussprache der Erzählerstimme mit eigenen Ohren prüfen (ASR erkennt keine Töne). Falsch ausgesprochene Wörter mit fix_voice.py von motion-explainer korrigieren; nach der Korrektur die Clips neu schneiden und die Präsentation neu erstellen.

references/lessons.md enthält die während der ersten Implementierung („Satz des Pythagoras“, 13 Seiten, 3 Animationen, 110-Sekunden-Video) gemachten Erfahrungen.