toon-reel

Toon Reel

Du inszenierst und baust eine kurze animierte Geschichte mit der toon-reel-engine. Alles ist Python: Figuren, Sets, Lichter und Kameras sind Code, und jeder Frame ist eine reine Funktion der Zeit T. Es gibt keinen Timeline-Editor und keine Keyframe-Oberfläche. Du schreibst Daten (Keys, Shot-Tabellen) und dann betrachtest du die Frames.

Aufbau der Engine (behalte ihn bei: die relativen Importe hängen davon ab):

tools/toon/            die Engine: toon.py (Renderer), rig.py (Figuren), anim.py (Timing), cast/ props/ sets/ (Bausatz)
tools/                 sound.py (Stems aus Cues), mix_check.py (Sprachverständlichkeit), finish.py (‑14 LUFS Export),
                       thumb.py (Cover), find_phrases.py (Satzzeiten in einer Erzählaufnahme)
episodes/starter/toon  DIE VORLAGE: „Die Lampe", 12,5 s, vier Shots, ein Raum, eine Person. Kopiere dies, um zu beginnen.
episodes/window/toon   DAS VOLLSTÄNDIGE BEISPIEL: „Der Mann am Fenster", 50 s, 13 Shots, zwei Welten und eine Wendung.
episodes/jeff, episodes/smilingman   Hilfsmodule, die das vollständige Beispiel und der Bausatz importieren (keine ausführbaren Episoden)

Befehle. python unten bedeutet den Interpreter, der requirements.txt installiert hat (py unter Windows). Die eigenen Skripte einer Episode (reel.py, build_tl.py, finalize.py) werden aus dem Episodenordner episodes/<name>/toon ausgeführt. Die Werkzeuge werden vom Projektstamm ausgeführt: python tools/sound.py episodes/<name>/toon.

Zuerst: Engine finden oder einrichten

Arbeite im eigenen Projektordner der Person, niemals im Installationsordner des Plugins (er wird bei Updates ersetzt).

1. Wenn der Arbeitsordner bereits tools/toon/toon.py enthält, verwende ihn.
2. Ansonsten wird die Engine mit dieser Fähigkeit geliefert. Ihr Stamm befindet sich zwei Ordner über dem Basisverzeichnis dieser Fähigkeit (<skill dir>/../..: er enthält tools/, episodes/, requirements.txt und .gitignore). Kopiere diese vier in den Arbeitsordner, behalte die Struktur bei und teile der Person mit, dass du es getan hast. Wenn dieser Ordner kein tools/ hat (die Fähigkeit wurde eigenständig kopiert), klone stattdessen https://github.com/wlr2/toon-reel-engine.
3. pip install -r requirements.txt, und überprüfe, ob ffmpeg -version funktioniert (5.1 oder neuer). Untertitel benötigen Arial Black oder TOON_FONT, gesetzt auf eine fette serifenlose .ttf.
4. Beweise die Einrichtung vor dem Bau von irgendetwas, von episodes/starter/toon: python build_tl.py, dann python reel.py --frame 5.0 muss review/_f5.00.png schreiben.

Die Reihenfolge ist festgelegt

Skript -> Timeline -> Cast-Blätter + Set-Frame -> Blocking -> Prüfungen (2 Runden) -> Vorschau -> Master -> Ton -> Fertigstellung -> Nachbereitung.

Ein Master-Rendering beginnt nie, bevor die Prüfungen bestanden und protokolliert wurden. Zeige der Person das Figurenblatt und einen Set-Frame vor der Animation und ein beschriftetes Key-Frame-Blatt vor der hochauflösenden Vorschau. Frage, bevor du für irgendetwas Geld ausgibst (Bezahlte TTS, bezahlte SFX, Cloud-Renderings).

1. Skript (references/script.md)

Die Zehn-Schritt-Methode: Öffne mit dem spezifischsten Widerspruch, einer Hauptfrage, einer Kette von Konsequenzen, einer Änderung alle paar Sekunden, geschrieben für Sprache und Animation, einer bewegten Mitte, einem verdienten Ende mit dem Erkennungssatz zuletzt, ehrlicher Rahmung („EINE INTERNET-HORRORGESCHICHTE" für Creepypasta), einer getimten Shot-Tabelle, dann einer Bindungskürzung. Wenn dir die Person ein Skript oder ein Beat-Blatt gibt, haben ihre Worte und ihre Vorgabe Vorrang vor jeder Hausregel hier: schreibe nie ihre Zeilen um, schlage Änderungen vor und zitiere, was du ändern würdest.

Ergebnis: SCRIPT.md (drei Hooks + der Pick, vollständige Erzählung, getimte Shot-Tabelle, Wortanzahl) und script.py.

2. Die Timeline, dann die Stimme

• script.py enthält PHRASES (wo jede Zeile platziert ist, ihr Text, ihre Untertitel-Blöcke mit [word] für das rote Schlüsselwort) und MARKS (die Story-Beats in Sekunden, die zu den Shot-Grenzen werden).
• python build_tl.py schreibt timeline.json (total, marks, lines). Das Reel liest nur timeline.json. In der Vorlage funktioniert es, bevor Audio existiert: die Phrasenlängen werden aus Wortanzahlen geschätzt, sodass du zuerst das Bild blocken kannst.
• Die Stimme ist eine Aufnahme pro Sprecher, 48 kHz mono, von beliebiger TTS oder einem Mikrofon (dieses Repo liefert keine; ElevenLabs ist kostenpflichtig, Kokoro ist kostenlos und lokal). Beschleunige niemals eine Aufnahme, um sie passend zu machen: schneide stattdessen einen Beat ab. Schreibe Zahlen als Wörter im Text, den du an eine TTS sendest.
• python tools/find_phrases.py take.wav gibt die (start, end) jeder Phrase in der Aufnahme aus. Füge sie in PHRASES ein und führe build_tl.py erneut aus: es schneidet die Phrasen aus, platziert sie und schreibt audio/narration.wav. Dann überprüfe jeden Shot erneut: echte Phrasenlängen unterscheiden sich von den Schätzungen.
• Die mitgelieferten build_tl.py-Dateien handhaben einen Erzähler. Bei mehreren Sprechern behalte eine Aufnahme pro Sprecher und füge den Sprecher zu jeder Phrase hinzu (eine kleine Änderung an build_tl.py).
• Flüche für TikTok: piep sie in einem separaten Stem aus und ersetze sie in den Untertiteln mit Sternchen (f***ing).

3. Die Episodendateien (references/engine.md)

Datei	Aufgabe
script.py	Zeilen, Untertitel-Blöcke, Markierungen
build_tl.py	timeline.json (+ audio/narration.wav)
looks.py	die Besetzung: jeder Look ist ein Dict in rig.LOOK
scenes.py	die Welt: Set-Geometrie, Lichter, wer wo zur Zeit T ist, die Schauspiel-Spuren
reel.py	SHOTS, Untertitel, render(T), die Prüfungen und die Render-Befehle
cues.py	Sound-Ereignisse für tools/sound.py
finalize.py	Mix der Stems, Mux auf das Rendering, Ausführung von tools/finish.py

Beginne eine neue Episode, indem du episodes/starter/toon nach episodes/<name>/toon kopierst. Seine reel.py, build_tl.py und finalize.py sind generisch und können so bleiben, wie sie sind; du ersetzt script.py, looks.py, scenes.py, die SHOTS-Tabelle und cues.py. Beginne nicht mit episodes/window/toon: seine reel.py, cues.py und Prüfungen sind auf diese Geschichte zugeschnitten (zwei gespiegelte Welten, benannte Markierungen, eine benutzerdefinierte Twist-Kamera). Lese es für Techniken: Texturen, Tiefenschärfe, ein weltenspezifischer Gesichtsschlüssel, Hände auf Glas, ein Überblendung zwischen Welten. Größere Episoden verschieben das Schauspiel aus scenes.py in ein acting.py.

Eine Welt benötigt zwei Methoden: draw(fr, cam, T), die alles zeichnet und {pid: rig.draw Ergebnis} zurückgibt, und cast(T), die [(pid, look, pose)] zurückgibt. pid ist die ID einer Person in dieser Episode („nora"). Eine Welt und eine Timeline pro Ort; Shots wählen nur Kameras.

4. Look (references/look.md)

Runde einfache Formen, leicht große Köpfe, große ausdrucksstarke Augen, matte Materialien mit weicher 3-Stufen-Schattierung und einer dunkleren Kontur in der Grundfarbe. Jede Figur erhält ihre eigene Silhouette, ihr Gesicht und ihre Palette, die aus dem Skript entworfen werden (nie ein Reskin einer anderen Figur aus einem anderen Reel); wiederkehrende Figuren bleiben im Modell. Erstelle ein Modellblatt vor dem Animieren, von tools/toon: python -m cast.sheet ../../episodes/<name>/toon/looks.py <look> (es schreibt assets/kit/cast/<look>.png im Projektstamm oder den Pfad, den du als drittes Argument angibst).

5. Beleuchtung (references/lighting.md)

Drei Ebenen in jedem Ort: eine kühle Umgebung (blau-violette Nacht behält Details), ein weiches Key-Licht auf jedem Gesicht (von oben-vorne, motiviert durch eine Lampe oder ein Fenster), und warme praktische Lichtquellen in mehreren Entfernungen, die das beleuchten, was in ihrer Nähe ist. Gesichter sind das klarste im Bild; der Hintergrund ist etwas dunkler und hat einen geringeren Kontrast um sie herum. Kontaktschatten unter Füßen, Möbeln und sich berührenden Händen. Eine Lichtkonfiguration pro Ort: die Richtung, Farbe und Belichtung bleiben über Schnitte hinweg gleich. Kein Bloom, keine leuchtenden Konturen, keine ausgefressenen Schwarztöne. Wetter (Regen, Schnee, Wind) animiert in ruhigen Momenten, wenn die Geschichte Wetter hat.

6. Kamera (references/camera.md)

• Ein Schnitt alle 2-3 s. Jeder Shot dient einer Handlung, einem Ausdruck oder einer Enthüllung.
• Der Hook (0-3 s) ist der schönste bewegte Shot des Reels: Kamera und Figur bewegen sich ab Frame 1.
• Zuerst eine Zwei-Personen-Einstellung, dann passende Nahaufnahmen. Nahaufnahmen bleiben innerhalb von ~35 Grad der Blicklinie.
• track(a, b, ease) macht eine saubere Bewegung zwischen zwei Keys (Position, Ziel, Brennweite px, Horizont). Die Kamera dreht sich, um das Ziel anzusehen, kann aber nicht neigen: die Höhe des Ziels wird ignoriert. Rahme nach oben oder unten mit der Kamerahöhe und dem Horizont (ein kleinerer Wert setzt die Augenhöhe höher im Bild, was wie ein Herunterschauen wirkt).
• Halte Kameras >= 0,45 m von jeder sichtbaren Person entfernt: rig.draw zeichnet niemanden, der näher ist.
• Untertitel (Arial Black 66 px, weiß, schwarze Kontur, Schlüsselwort #FF4D4D) liegen nie auf einem Gesicht oder einer Hand. Verschiebe sie pro Shot mit cap=(y, size).

7. Schauspiel und Inszenierung (references/acting-staging.md)

Jede Aktion ist eine Kette mit Versätzen: Augen -> Kopf -> Schultern -> Körper -> Hände, als Vorbereitung -> Bewegung -> Beruhigung. Reaktionen easing out/snap, Beruhigungen easing back. Griffe erreichen, bevor sie schließen. Eine Person, die nur den Kopf und die Schultern dreht, kann auf den Standardfüßen stehen; eine Person, die geht oder den Körper dreht, benötigt Füße, die in der Welt platziert sind (ankle_R/ankle_L von rig.replant oder rig.gait), die Schritt für Schritt gesetzt werden. Lese die Inszenierungs-Lektionen, bevor du etwas blockst: jede ist ein bereits aufgetretener Fehler.

8. Prüfungen: das Tor vor jedem Master (references/checks.md)

1. python reel.py --check -> lies die gesamte review/reel_checks.txt. In der Vorlage ist jedes Problem eine ANOMALIE-Zeile: Reichweite, einsinkende Füße, übermäßig gebeugte Ellbogen, Ellbogen- und Knie-Umkippungen, Sprünge, Personen zu nah an der Linse, Untertitel über einem Gesicht oder einer Hand.
2. python reel.py --stills -> erster/mittlerer/letzter Frame jedes Shots (Runde 1).
3. python reel.py --sheet <SHOTS> -> jeder Frame von Kontakt-Shots, Gehen, Drehungen und Verdeckungswechseln auf lückenhaften Blättern (Runde 2). Suche nach Spaltungen, durchschlagenden Gliedmaßen, Köpfen, die durch Dinge gehen, Dingen, die verschwinden.
4. Behebe in den Daten, führe erneut aus und protokolliere jede Anomalie in review/LOG.md (nur anhängen): Zeit, Shot, Ursache, Behebung, wie verifiziert; plus akzeptierte Flaggen mit Grund und was du nicht überprüfen konntest.
5. Behaupete nie „keine Anomalien" nur vom Code. Der Code prüft Gelenke, nicht Bilder: er sieht keine Personen, die durch Möbel oder einander gehen, Props, die eine Hand vermissen, eine falsche Zeichenreihenfolge oder einen 0,8 m seitlichen Schritt, der wie ein Spagat aussieht. Diese findest du auf den Blättern.

9. Rendern (vom Episodenordner)

• python reel.py --preview --full -> review/reel_preview.mp4 (1080×1920, stumm). python finalize.py preview fügt den Mix hinzu -> review/preview.mp4. Zeige es, erhalte eine Freigabe.
• python reel.py --master-par 12 -> video/reel_silent.mp4: der Master auf 12 Prozessen (verwende deine Kernanzahl).

10. Ton, Mix, Fertigstellung, Nachbereitung (references/sound-finish.md)

• cues.py, dann vom Projektstamm python tools/sound.py episodes/<name>/toon -> Musik-, SFX- und Ambient- Stems. Echte Aufnahmen für echte Dinge (bringe CC0 oder lizenzierte Samples in assets/sfx/); Synthese nur für abstrakte Dröhner, Steigerungen und Booms. Die Cues der Vorlage sind alle synthetisiert, damit die Kette läuft: ersetze sie.
• python tools/mix_check.py episodes/<name>/toon: Die Stimme muss >= 10 dB über den Begleitspuren bei jeder Zeile sein (jede Zeile schlägt fehl, bis es eine echte Erzählaufnahme gibt).
• python finalize.py final (Episodenordner) -> tools/finish.py -> -14 LUFS, <= -2 dBTP, H.264 High, +faststart.
• Cover, vom Projektstamm: python tools/thumb.py frame.png cover.jpg --line "TITEL:#F2EFE6:120".
• POST.md: Untertitel pro Plattform, Hashtags und eine Erinnerung, den HD-Upload in der App zu aktivieren.

Hier verwendete Begriffe

• Markierung: ein benannter Story-Beat in Sekunden (MARKS), verwendet als Shot-Grenze und zum Timing von Aktionen.
• Station: ein Ort, an dem eine Figur steht (x, z, Blickrichtung) und die Zeit, zu der sie ihn betritt.
• Fixierter Fuß: ein Knöchel, der an einer Weltposition fixiert ist (ankle_R/ankle_L), sodass der Fuß nicht rutscht.
• Clip-Zone: ein Bildschirmausschnitt im Bildraum, der einen Körperteil hinter etwas verbirgt (Hecke, Wandkante).
• Wandflaches Objekt: flache Set-Dekoration an einer Wand (Vorhänge, Poster); sortiere es so weit hinten wie seine Wand.
• Praktikale Lichtquelle: eine Lichtquelle, die im Set sichtbar ist (Lampe, beleuchtetes Fenster).

Gewohnheiten

• Schau, bevor du behauptest. Rendere den Frame, lies das Blatt, dann sag, was du gesehen hast.
• Eine Änderung, ein erneutes Rendern der betroffenen Shots, eine erneute Prüfung, mit Blättern.
• Wenn eine Inszenierung immer wieder scheitert, vereinfache sie oder wähle einen klareren Winkel. Verstecke niemals Anatomie mit Unschärfe, Dunkelheit, Schnitten oder Untertiteln.
• Schreibe jede Korrektur, die die Person dir gibt, in das review/LOG.md der Episode und, wenn sie allgemein ist, in eine STAGING_NOTES.md im Projektstamm (lies sie zu Beginn jeder Episode). Schreibe niemals in den Plugin-eigenen Ordner.