Orinkle/ideaform

Konstruktivistisches Erklärvideo · Workflow

Eine zentrale Zeitachse, drei nachgelagerte Schritte leiten sich davon ab.

① Manuskript       ② TTS als Zeitachse         ③ BGM-Variation       ④ Fertiges Video
   Text     ──→   Sprachspur (Zeitachse)   ──→   LMMS-Musik (Ebenen) ──→   Remotion-Bild + Tonspur-Integration + Cover
                         │                         ▲
                         └───── Zeitpunkte der Ebenengrenzen ─────┘

• Die Bildanzahl wird durch die natürliche Sprechgeschwindigkeit des TTS bestimmt (nicht umgekehrt)
• Die Variationspunkte der Hintergrundmusik werden an den Ebenenwechselpunkten der Erzählung ausgerichtet
• Das fertige Video wird an der Sprachspur als Basis ausgerichtet, die Hintergrundmusik dient nur als Hintergrund

---

0. Start: Pfadvertrag lesen (Dieser Schritt darf nicht übersprungen werden)

Dieser Skill findet Werkzeuge nicht selbst, alle Pfade stammen aus dem vom Umgebungseinrichtungsskill geschriebenen Vertrag:

$VW_CONTRACT  (Standard: ~/.config/ideaform/toolchain.json)

CONTRACT="${VW_CONTRACT:-$HOME/.config/ideaform/toolchain.json}"
source "$(dirname "$CONTRACT")/env.sh"     # Exportiert VW_NODE / VW_VENV / VW_FFMPEG / …

Vor Arbeitsbeginn müssen drei Dinge überprüft werden:

1. Existiert die Vertragsdatei? Nein → Den Benutzer bitten, zuerst den Skill ideaform-setup auszuführen.
2. Ist die schema_version die von diesem Skill erkannte Version? Nicht passend → Umgebungseinrichtungsskill erneut ausführen lassen.
3. Ist verified_at null? Ja → Benutzer warnen: "Umgebung hat Rauchtest nicht bestanden", zuerst reparieren, dann weitermachen. Zusätzlich muss tools.lmms.stkdir_ok true sein, sonst wird die Hintergrundmusik durchgehend stumm und ohne Fehlermeldung sein.

Schnellübersicht der Schlüsselfelder:

Verwendung	Vertragsfeld
TTS-Skript ausführen (edge-tts in venv)	tools.venv.python
Audio/Video zusammenführen	tools.ffmpeg.path / tools.ffprobe.path
Bild rendern	tools.remotion.project / tools.remotion.browser.resolved
Hintergrundmusik rendern	tools.lmms.apprun
Temporäre Dateien ablegen (muss große Partition sein)	tmpdir

⚠️ tmpdir im Vertrag ist keine Option. Das lokale /tmp hat nur 10 MB, Remotion-Pakete / pip-Installationen schreiben dorthin → ENOSPC. Jeder Remotion-Befehl muss TMPDIR mitführen.

⚠️ Pfade werden nicht aufgelöst (Symlinks). Die verwalteten Toolchain-Pfade enthalten Symlinks. Das Auflösen des venv-Interpreters entfernt den venv-Kontext, alle Pakete können nicht importiert werden. Siehe Projektstamm docs/03-Pfadvertrag.md.

---

1. Vier-Phasen-Übersicht

Phase	Was tun	Eingabe	Ausgabe (alle im Arbeitsbereich)	Referenz
① Manuskript	Benutzereingabe in geschichtetes Erklärskript umwandeln	Benutzereingabe	script.md + Sprach.txt (Ebenen markiert)	references/stage1-script.md
② TTS als Zeitachse	Natürliche Sprechgeschwindigkeit messen → Zeitachse erstellen → Sprachspur ausgeben	Sprach.txt	plan.json / timeline.ts / voice.wav	references/stage2-tts.md
③ BGM-Variation	Ebenengrenzen → Variationsplan → LMMS-Tonspur	plan.json + Ebenenmarkierungen	bgm-plan.json / bgm.wav	references/stage3-bgm.md
④ Fertiges Video	Remotion-Bild + Tonspur-Integration + Rendern + Cover	timeline.ts + Tonspuren + bgm-plan.json	final.mp4 + cover.png	references/stage4-render.md · references/cover.md

Stilistische Einheitlichkeit wird durch references/constructivist-style.md geregelt, Bild und Cover teilen dieselbe Palette / Schriftart / Raster, daher natürliche Konsistenz.

---

2. Phase Eins · Manuskript (Schichtung ist Pflicht)

Der Benutzer gibt eine Eingabe (ein Thema / Material / mündliche Idee). Die Ausgabe ist:

• script.md — vollständiges Manuskript, explizite Markierung der Argumentationsebenen
• Sprach.txt — ein Satz pro Zeile, Sprechtext für TTS

Schichtung dient nicht der Ästhetik, sondern ist die Eingabe für Phase drei. Ohne Ebenenmarkierungen hat die BGM-Variation keinen Ansatzpunkt.

## Ebene 1 · Einleitung
Dies ist die erste Ebene von "Manuskript als Zeitachse".
Die Sprachspur ist die zentrale Zeitachse der gesamten Pipeline.
## Ebene 2 · Entfaltung
Die Bildanzahl wird von ihr bestimmt, nicht umgekehrt.
...

• Ein Satz = eine semantische Einheit, nicht zwei Dinge in einen Satz packen (TTS reiht Sätze zeitlich aneinander, Zusammenpacken verlängert den Slot)
• Einzelsätze empfohlen 8–30 Zeichen; zu lange Sätze aufteilen, zu kurze zusammenfassen
• Satzzeichen mit Punkt/Fragezeichen beenden, hilft TTS bei der Satztrennung

Details siehe references/stage1-script.md.

---

3. Phase Zwei · TTS als Zeitachse (Reihenfolge ist zwingend)

"$VW_VENV/bin/python" skills/ideaform/scripts/make-tts-track.py \
    --lines Sprach.txt --fps 30 --audio \
    --plan-out out/plan.json --ts-out out/timeline.ts

Zuerst Tonspur, dann Zeitachse. Die Zeitachse ergibt sich aus der tatsächlichen Sprechgeschwindigkeit des TTS:

① Text schreiben
② make-tts-track.py --lines Sprach.txt --fps 30 --audio   ← Natürliche Sprechgeschwindigkeit messen, Zeitachse ableiten
③ Die ausgegebenen TOTAL_FRAMES für die Remotion-Komposition verwenden       ← Bildanzahl wird so bestimmt
④ Dann rendern

Kosten des Gegenbeispiels (gemessen): Zuerst 43 Zeitschlüssel nach Storyboard festlegen, TTS natürliche Sprechgeschwindigkeit ergibt 212,90 s, Video jedoch nur 174,80 s → 1,218-fache Kompression erzwungen. Dieser Kompromiss wäre vermeidbar gewesen.

Das gleiche Skript kann auch das Gegenteil tun (wenn SRT bereits vorhanden, Zeitschlüssel festgelegt, zweistufige Geschwindigkeitsanpassung verwenden), aber das ist Notlösung, nicht erste Wahl. Siehe references/stage2-tts.md.

⚠️ Dem Benutzer nicht die Frage stellen: "Wie viele Minuten soll das fertige Video haben?". Die Dauer = Sprechgeschwindigkeit × Textmenge, ist Ausgabe, nicht Eingabe; Zu Beginn der Arbeit sollte man weder danach fragen noch Optionen wie "Standard X Minuten" geben. Nur melden: "Bei diesem Manuskript, gemessen X Minuten Y Sekunden". Der Benutzer wünscht länger/kürzer → Manuskript ändern, nicht die Zeit. (Am 15.10.2026 mit dem Guihua-Clip erlebt, notiert in E16)

Ausgabe: plan.json enthält pro Zeile start/end/dur/frameStart/frameEnd; timeline.ts kann direkt in das Remotion-Projekt als src/timeline.ts kopiert werden.

---

4. Phase Drei · BGM-Variation (Seele dieses Workflows)

Kernpunkt: Jedes Mal, wenn die Erzählung eine neue Ebene betritt, wechselt die Musik ihre Form – aber nicht das Stück.

# ① Ebenen des Manuskripts auf Cue-Nummern abbilden, narrative Funktion jeder Ebene markieren
"$VW_VENV/bin/python" skills/ideaform/scripts/bgm-plan.py \
    --plan out/plan.json \
    --layers "1:present,4:develop,6:resolve" \
    --key "A minor" --out out/bgm-plan.json

# ② Entsprechend bgm-plan.json LMMS-Projekt generieren und rendern (über composer.py aus electronic-music-production)
#    Vertragliches tools.lmms.apprun rendert; bpm und timeline lp1pos müssen gemäß mmp_hints geschrieben werden

Sechs narrative Funktionen (eine pro Ebene auswählen):

Funktion	Bedeutung	Was ändert sich
present	Präsentieren · Einleiten	Nur Motiv zeigen, eine Stimme, Leerräume
develop	Entfalten · Vertiefen	+Bass +Rhythmus, Motivsequenz
intensify	Betonen · Konflikt	Alle Stimmen, Oktavlage erhöhen, entlehnte Akkorde, Lautstärke anheben
contrast	Gegenüberstellung · Wendepunkt	Textur wechseln ohne Lautstärke zu erhöhen: Schichten entfernen, Klangfarbe wechseln, Tonart modulation
resolve	Abschließen · Rückkehr	Reduzieren, zur Grundtonart zurückkehren, Motivwert steigern
sustain	Fortdauer · Übergang	Nichts ändern (Ebene unverändert, nicht variieren, sonst wird Kontrast verwässert)

Eiserne Regeln:

• Identitätselemente dürfen nicht geändert werden – Motivzelle, Tonika, Grundtempo. Ändern bedeutet Liedwechsel, nicht Variation.
• Jeder Abschnitt muss mindestens 1 morphologisches Element ändern; bgm-plan.md listet für jeden Abschnitt die "Variationsbeweise" auf. Wenn zwei benachbarte Abschnitte leere Beweise haben, wurden Ebenenmarkierungen übersehen.
• Variationspunkte müssen auf den Ebenengrenzen der Erzählung liegen (--lead-in kann die Musik leicht vorziehen lassen).

Vollständige Methode und LMMS-seitige Umsetzung siehe references/stage3-bgm.md.

---

5. Phase Vier · Fertiges Video

5.1 Bild: Sprachspur als zentrale Zeitachse

cp out/timeline.ts <Remotion-Projekt>/src/timeline.ts     # Bildanzahl/Szenengrenzen werden von CUES abgeleitet
cd <Remotion-Projekt>
export TMPDIR="$VW_TMPDIR"                             # ★ Zwingend
npx remotion studio                                    # Benutzer zuerst Vorschau geben

Szenengrenzen auf der Bildseite nicht manuell als Frame-Nummern schreiben, sondern von CUES ableiten:

export const SCENES = {
  s1: { from: 0,            dur: CUES[2].start },
  s2: { from: CUES[2].start, dur: CUES[4].start - CUES[2].start },
} as const;

Strukturbilder / Signalwege / Schemazeichnungen → grundsätzlich deterministisch generieren, niemals KI-Bilder verwenden. KI gezeichnete chemische Strukturen halluzinieren zwangsläufig Bindungen und sind nicht erkennbar falsch – solches Material muss reproduzierbar und überprüfbar sein. Verwende scripts/gen-structures.py: SMILES → RDKit deterministische Darstellung → Framegesteuerte Remotion-Komponenten.

python3 scripts/gen-structures.py --tsv structures.tsv --out structures
#   → svg/*.svg  +  components/*.tsx (mit Animation)  +  manifest.json
#   → Offline-Prüfung der Summenformel (RDKit CalcMolFormula), bei Nichtübereinstimmung Exit-Code ungleich Null, kann direkt mit `&&` verkettet werden

• Farbgebung über RDKit offizielle Optionen (useBWAtomPalette / singleColourBonds / setSymbolColour), nicht mit Regex die SVG-Farben nachbearbeiten – das ist das Rad neu erfinden und zerbricht bei RDKit-Updates (siehe Fehlerheft E20).
• Generierte Komponenten nutzen CSS-Variablen --mol-dash / --mol-text für Strichanimationen, äußeres Element muss color setzen.
• Für breiteres Molekül-Visualisierung (Gitternetz / Gerüst-Highlight / 3D-Konformation / Protein-Ligand-Interaktionsdiagramme) zuerst nach vorhandenen Skills suchen (siehe §7), nicht in die Videopipeline einzwängen.

5.2 Tonspur-Integration (zwei Wege, Standard A)

A. Remotion-Integration (empfohlen) – <Audio> in der composition verwenden, gerendertes mp4 enthält Tonspur:

<Audio src={staticFile("voice.wav")} />
<Audio src={staticFile("bgm.wav")} volume={0.1694} />

Die Zahl volume nicht aus dem Bauch heraus, sondern mit gemessenen RMS rückrechnen:

bash scripts/mix-av.sh --plan-only --voice voice.wav --bgm bgm.wav --drop 9
# Erzählung RMS = -23,46 dBFS   BGM RMS = -17,04 dBFS
# → BGM benötigt -15,42 dB  →  volume = 0,1694

B. Nachträgliche Synthese (Video bereits gerendert / erneute Sprachaufnahme):

bash scripts/mix-av.sh --video silent.mp4 --voice voice.wav --bgm bgm.wav --out final.mp4

⚠️ Bei Weg B muss explizit -map 0:v:0 -map 1:a:0 gesetzt werden. Remotion-ausgegebenes mp4 enthält eine eigene stille AAC-Spur. Ohne -map wählt ffmpeg automatisch diese → Ergebnis Exit-Code 0, korrekte Länge, abspielbar, aber stumm. mix-av.sh hat dieses -map bereits eingebaut.

5.3 Rendern und Cover

export TMPDIR="$VW_TMPDIR"
npx remotion render <CompositionId> out/video.mp4 --concurrency=3
npx remotion still Cover out/cover.png --props='{...}'    # Cover: statische composition, keine Animationen verwenden

• Langes Video in Abschnitte rendern: 7-minütiges Video kann aufgrund von Speicherüberlastung beim einmaligen Rendern timeouten. --frames=A-B Abschnitte → concat -c copy verlustfrei zusammenfügen.
• Cover mit statischer composition durationInFrames={1} verwenden, innerhalb der Komponente useCurrentFrame nicht verwenden (bei still konstant 0, Animationsanfangswert macht Elemente unsichtbar).
• Cover-Layout siehe references/cover.md, Stilrichtlinien siehe references/constructivist-style.md.

---

6. Blindabnahme: Jede Phase muss durch den Validator

Das Modell sieht kein Bild, hört keinen Ton. Daher bedeutet "Rendering erfolgreich" ≠ "Bild korrekt, Ton korrekt". Jeder Schritt wird numerisch gemessen, bei Nichtbestehen wird Auslieferung verweigert:

# Audio-Selbstprüfung (TTS-Spur, BGM): Spitzenpegel/RMS/Clipping/Zeitabweichung
# Bild-Selbstprüfung: Pixel-Farbabgleich / Reinheit des Korridors / Zählung von Text-Pixeln
#   --layout muss korrekt gewählt sein: cover=Cover-Layout; scene=Videoszene (Standard).
#   Stichprobenbereich wird durch Layout bestimmt, falsche Wahl führt auch bei korrektem Cover zu Fehlschlag (siehe 05-Fehlerbehebung D2).
python3 scripts/verify-video.py cover out/cover.png --layout cover

# Fertiges Video-Selbstprüfung: Bildanzahl / Dauer / Tonspur-Bitrate (gegen stille Tonspur)
# ffprobe Suchreihenfolge: VW_FFPROBE → Pfadvertrag toolchain.json → System
VW_FFPROBE="$VW_FFPROBE" python3 scripts/verify-video.py video out/final.mp4 --frames 732 --fps 30

Skripte signalisieren Fehler mit Exit-Code ungleich Null, können direkt mit && in die Pipeline eingebunden werden.

Häufige Kriterien schnell nachschlagen:

Objekt	Kriterium	Schwelle
Audio	Nicht stumm	Spitzenpegel > 1000 und RMS > 100
Audio	Kein Clipping	Vollaussteuerungs-Samples < 0,01%
Audio	Zeitliche Ausrichtung	Abweichung vom Plan < 50 ms
Cover	Abmessungen	1920×1080
Cover	Text-Rendering	Textbereich Tintenpixel > 300
Cover	Achsen überschreiben keinen Text	Rote Pixel im Titelbereich < 60
Fertiges Video	Bildanzahl	Genau gleich Planwert
Fertiges Video	Tonspur nicht stumm	Bitrate > 64000 bps
BGM	Hintergrundpegel	8–12 dB leiser als Erzählung

---

7. Weitere Fähigkeiten in Verbindung mit diesem Skill

Was wird benötigt	Welchen verwenden
Umgebungserkennung / Nachinstallation / Vertrag	ideaform-setup (einmalig)
Fertige Skills für neue Open-Source-Werkzeuge (Ernte: GitHub einsammeln → Sicherheitscheck → ablegen)	ideaform-setup's scripts/harvest-skills.py <Werkzeugname>
Deterministische Grafiken für chemische Strukturen / Reaktionswege	Dieses Skills scripts/gen-structures.py (RDKit → SVG → Remotion-Komponenten)
Breitere Molekül-Visualisierung (Gitternetz / Gerüst-Highlight / 3D-Konformation / Protein-Ligand)	Externe fertige Skills: synthetic-sciences/openscience's molecule-visualization (Apache-2.0), ghutchis/chem-skill (MIT)
LMMS-Projektformat, Plugin-Parameter, eldata-Hüllkurven	electronic-music-production + dessen references/05
Kompositionslehre (Harmonie, Motiv, gehörloses Komponieren, Emergenz)	electronic-music-production's references/06–10
Remotion-Syntax und Rendering-Details	remotion-best-practices
Vollständige Methode zur pixelgenauen Blindabnahme	headless-visual-verify
WSL-Umgebungsfallen (/mnt, gh-Fetch, Audio-Pfad)	wsl-pitfalls

---

8. Lieferliste

Nach Fertigstellung eines Videos sollte der Arbeitsbereich enthalten:

<Arbeitsbereich>/
├── script.md            Geschichtetes Manuskript
├── Sprach.txt           Sprechtext
├── out/
│   ├── plan.json        Zentrale Zeitachse (Sekunden/Bilder pro Cue)
│   ├── timeline.ts      Direkt in Remotion importierbare Zeitachse
│   ├── voice.wav        Sprachspur-Master
│   ├── bgm-plan.json    Variationsplan + bgm-plan.md (Variationsbeweise)
│   ├── bgm.wav          BGM-Tonspur
│   ├── video.mp4        Stummes Bild (oder fertiges Video mit integrierter Tonspur)
│   ├── final.mp4        ★ Endgültiges fertiges Video
│   └── cover.png        ★ Cover
└── .tts/                TTS-Cache (behalten, Wiederholung dauert nur wenige Sekunden)

Vor der Auslieferung müssen alle Validierungen aus Abschnitt 6 durchlaufen werden, und es muss wahrheitsgemäß berichtet werden, welche bestanden und welche nicht getestet wurden.

---

9. Selbstevolution: Fallstricke dokumentieren

Dieser Workflow ist ein veränderbarer zusammengesetzter Skill – je mehr er genutzt wird, desto besser sollte er sich an den eigenen Produktionsrhythmus anpassen:

• Einen Fallstrick erlebt, direkt nach der Reparatur → im Projektstamm docs/06-Fehlerheft.md notieren (sechsspaltiges Format, Nummern fortlaufend). ⚠️ Nicht in skills/ideaform/ ein separates docs/ anlegen – das wäre ein zweites Heft und würde mit den Nummern des Haupthefts kollidieren (am 15.10.2026 erlebt, notiert in E19).
• Ein Fallstrick wurde durch Skript/Dokumentation dauerhaft repariert (nicht umgangen) → Status des Eintrags auf Geheilt setzen und Reparaturmethode angeben.
• Derselbe Fallstrick-Typ ein zweites Mal erlebt → Nicht einen dritten Eintrag anlegen, sondern die Absicherung direkt in das Skript einbauen (Validator / Standardwerte / Vertrag).
• Neues Open-Source-Werkzeug einführen → zuerst ernten, dann loslegen: harvest-skills.py <Werkzeugname> um in der Community fertige Skills zu suchen (mit Fork-Schutz, überschreibt nicht lokal geänderte); nur wenn kein passender gefunden wird, selbst schreiben. Wenn geerntete Skills ebenfalls Fallstricke haben, werden sie ebenfalls dokumentiert.
• Vor Sitzungsende kurz prüfen: Gibt es etwas, das "repariert, aber nicht dokumentiert" wurde?

---