ErklärKit (yem-hjk6th/explainer-kit)

Erklärvideo

Sie erstellen Erklärvideos, die ein bestimmter Zuschauer versteht und die richtig sind. Zwei Dinge bestimmen das Ergebnis: die Regeln in references/STYLE.md (sie stammen aus echtem Reviewer-Feedback) und die Gewohnheit, jede gezeigte Zahl zu berechnen und zu überprüfen. Das Rendern ist der einfache Teil.

Repository-Übersicht: Bibliothek animkit/ (API-Referenz animkit/README.md), Werkzeuge tools/, Beispiele examples/, zwei fertige Folgen episodes_example/ (kopieren Sie deren Storyboard- und Shot-Formate; das CLAIMS-Format finden Sie in references/VERIFY.md), Ihre Arbeit kommt in episodes/<ID>_<topic>/.

0. Vor allem

1. Funktioniert die Umgebung? python -I -B -X utf8 tools/selftest.py muss all OK ausgeben. Wenn config/animkit.json fehlt, führen Sie python -X utf8 tools/setup_config.py aus (die Konfiguration ist pro Checkout: ein neuer Klon oder ein git worktree benötigt sie erneut, oder setzen Sie ANIMKIT_CONFIG). Probleme: SETUP.md.
2. Fragen Sie den Benutzer nur das, was Sie nicht standardmäßig vorgeben können (eine Nachricht, kurz):
   • Thema und das Quellmaterial (Vorlesungsmitschrift, ein Paper, eine Seite); Sie benötigen eine Quelle für jede Behauptung;
   • Zielgruppe und was sie bereits weiß (bestimmt die Tiefe, references/STORYBOARD.md §Zielgruppe);
   • Länge; Übersetzung / Erzählung / Sprachausgabe gewünscht?
   • Dürfen Sie echte Modelle ausführen (GPU, Downloads)? Standard: nein, verwenden Sie eine synthetische Szene mit bekannter Grundwahrheit.
   • Standardwerte, falls unbeantwortet: 1080×1440, 30 fps, nur Untertitel, keine Stimme, eine geplante Review-Runde.
3. Erstellen Sie episodes/<ID>_<topic>/ mit STATUS.md (Phase / nächster Schritt / wartet auf / Zeit von date).

1. Die Pipeline (Details und Befehle: references/PIPELINE.md)

Phase	Sie produzieren	Tor vor der nächsten Phase
A. Studium	Quellenzusammenfassung; optional Referenzvideo-Analyse (references/REFERENCES.md)	Sie können den Mechanismus als Input → Formel → Formen → kleines Zahlenbeispiel → Warum darlegen
B. Storyboard	storyboard.md, CLAIMS_to_verify.md, episode.json (+ elements_needed.md, falls der Bibliothek etwas fehlt)	Benutzer-OK für die Gliederung bei langen Folgen; unabhängige Verifikationsrunde 1 durchgeführt und Korrekturen angewandt (references/VERIFY.md)
C. Shots	shots/sNN_*.py, jeder mit @shot.check	--check-only besteht; Kontaktbogen überprüft; vollständiger Render; check.json-Warnungen gefixt
D. Zusammenbau	render/<ID>.mp4 (tools/concat.py), review/round1/review.html (tools/review_page.py)	Sie haben die Kontaktbögen jedes Shots angesehen; Zahlen auf dem Bildschirm = CLAIMS
E. Review-Runden	review/roundN/feedback.md (Notizen des Benutzers), review/roundN+1/changes.md, erneute Renderdurchläufe	Feedback-Punkte jeweils beantwortet; neue Behauptungen verifiziert (max. 2 Runden pro Punkt)
F. Optional	Übersetzte Version (references/I18N.md), Erzählung (references/NARRATION.md), Sprachausgabe (references/TTS.md)	Jede hat ihre eigene Prüfung

Schreiben Sie Shots direkt in der Sprache des Videos (Englisch in den Beispielen): Untertitel, Titel und Beschriftungen sind einfache Zeichenketten im Skript. --lang ist nur für eine zweite, übersetzte Version.

Minipfad (≤ 60 s, 1–3 Shots). Gleiche Phasen, leichter. Minimale Dateiliste in episodes/<ID>_<topic>/:

1. storyboard.md: eine Tabelle, eine Zeile pro Untertitel (Zeitbereich, Untertitel, was sich auf dem Bildschirm ändert, berechnet oder illustrativ). Vorlage: templates/storyboard_skeleton.md.
2. CLAIMS_to_verify.md: eine Zeile pro Zahl / Fakt auf dem Bildschirm (Behauptung, Quelle, wie zu prüfen, gemessen / berechnet / abgeleitet / Paper).
3. shots/s01_<name>.py aus templates/shot_template.py, mit einem @shot.check, der jede berechnete Zahl als die gezeigte Zeichenkette bestätigt.
4. Verifikation: ein frischer Sub-Agent mit templates/verifier_prompt.md, angewendet auf alle CLAIMS-Zeilen; wenden Sie dessen Korrekturen an (alte Formulierung durchgestrichen).
5. Rendern: --check-only → --sheet-only (sheet.jpg ansehen) → vollständiger Render.
6. episode.json + tools/concat.py nur, wenn es 2+ Shots gibt; tools/review_page.py <EP> --round 1 für die Review-Seite (eine Runde). Überspringen Sie nicht die Behauptungstabelle, den @shot.check oder die Kontaktbogen-Ansicht.

2. Regeln, die niemals optional sind

• Jeder berechenbare visuelle Aspekt wird berechnet (Projektionen, Aufmerksamkeitsgewichte, Reshapes, Rückprojektionen, angepasste Linien) und in @shot.check bestätigt, einschließlich der angezeigten Zeichenkette: ck.eq("Tiefe auf dem Bildschirm", f"{z:.3f}", "1.976"). Formatierung mit voller Genauigkeit; runden Sie einen gedruckten Wert niemals neu. Illustrative visuelle Aspekte erhalten shot.tag("Illustration"); dimensionsreduzierte Zeichnungen weisen darauf hin.
• Jede Zahl hat eine Quelle (Paper § / Tabelle / Gleichung, offizielle Codedatei + Zeile, oder unser eigenes Skript) in CLAIMS_to_verify.md, gekennzeichnet als gemessen / berechnet / abgeleitet / Paper. Vergleiche geben Metrik, Einheit und an, ob niedriger oder höher besser ist; Prozentangaben geben ihren Nenner an.
• Jedes Symbol wird dort definiert, wo es erscheint, jedes Mal; Begriffe, die der Zuschauer möglicherweise nicht kennt, erhalten ein Popup-Seitenfenster (animkit.Popup), das sie kurz erklärt und schließt.
• Ein Untertitel = eine visuelle Änderung, ≤ 12 Wörter und nicht breiter als der Rahmen (der Render warnt; bei 42 px sind das oft ~8 lange Wörter pro Zeile, max. 2 Zeilen), 2–3 s pro Untertitel, nichts Statisches.
• Bild zuerst, dann die Formel, Begriff für Begriff beleuchtet, jeder Begriff farbig oder mit seinem Teil des Bildes verknüpft.
• Unsere eigenen Tests werden als unsere gekennzeichnet (nicht das Experiment des Papers) beim ersten Mal und mit demselben Tag danach.
• Unabhängige Verifikation: Wer eine Behauptung aufstellt, verifiziert sie nicht; eine Korrektur ist eine neue Behauptung; maximal zwei Runden, dann wörtlich anwenden und stichprobenartig prüfen. Alte Formulierung wird durchgestrichen (~~alt~~ → neu), niemals stillschweigend gelöscht.
• Keine erfundenen Fakten in Übersetzung oder Erzählung: sie dürfen nur das sagen, was die verifizierten Untertitel / CLAIMS aussagen.
• Vollständige Checkliste: references/STYLE.md (§A Inhalt, §B Rhythmus, §C visuelle Grammatik, §D vor Auslieferung, §E Reviewer- Feedback, das zu Regeln wurde). Lesen Sie es vor dem Schreiben des Storyboards und erneut vor jeder Review-Runde.

3. Arbeitsweise

• Lesen Sie den API-Abschnitt, den Sie benötigen, in animkit/README.md (er ist lang: greppen Sie nach dem Element, dann lesen Sie diesen Teil). Kopieren Sie Muster aus dem ähnlichsten Shot in episodes_example/, anstatt Layouts zu erfinden. templates/shot_template.py ist ein minimaler vollständiger Shot.
• Iterieren Sie an einem Shot mit --still t1 t2 (PNG-Frames) und --sheet-only (12-Frame-Kontaktbogen); vollständige Render zuletzt. Sehen Sie sich den Kontaktbogen jedes Mal selbst an (Überlappungen, Text außerhalb der Leinwand, Kästchen = fehlende Glyphen, Untertitel über dem Bild). Standbilder werden durch spätere Render nicht aktualisiert: führen Sie --still nach jeder Bearbeitung erneut aus.
• 3D-Szenen: animkit/README.md §3D-Szenen (PinholeCam, OrbitCam az/el-Konvention: az=90, el=0 ist eine Seitenansicht). 2D-Diagramme wie eine Lochkamera-Seitenansicht: §2D-Seitenansicht (Plot2D mit gleichem Maßstab).
• Führen Sie Python als python -I -B -X utf8 aus; bearbeiten Sie niemals Bibliotheksdateien, während eine andere Sitzung rendert (references/PITFALLS.md).
• Halten Sie STATUS.md kurz und aktuell; protokollieren Sie den Aufwand in effort_log.csv (item,size,start,end,render_s,iterations,note).
• Lange Folgen oder viele Shots: Teilen Sie die Arbeit über Sitzungen / Sub-Agenten auf, wie in references/DISPATCH.md beschrieben (Kontextbudget ≈ 300k pro Hauptsitzung, ≤ 150k pro einmaligem Sub-Agenten, Übergabedatei vor dem Wechsel).

4. Ausliefern

Teilen Sie dem Benutzer mit: den Videopfad, den Review-Seitenpfad (review/roundN/review.html, im Browser öffnen; sie hat ein Kommentarfeld pro Shot und einen "Alles kopieren"-Button), was berechnet vs. illustrativ ist, was verifiziert wurde und von wem, offene Fragen. Wenn seine Notizen zurückkommen, speichern Sie sie wörtlich als review/roundN/feedback.md (eine Zeile pro Shot-ID, z. B. E03-02: ...), beantworten Sie jede und wandeln Sie jede allgemeine Präferenz in eine neue Zeile in Ihren lokalen Regeln für die Folge um (anhängen an eine STYLE_local.md in episodes/), damit die nächste Folge damit beginnt.

Referenzindex

Datei	Lesen, wenn
references/PIPELINE.md	Start; Phasenbefehle, Dateiformate, Tore
references/STYLE.md	Storyboard schreiben; vor jeder Review-Runde
references/STORYBOARD.md	Phase B: Zielgruppentiefe, Storyboard- + CLAIMS-Formate, Erzählmuster
references/REFERENCES.md	Referenzvideos / Quellen-Papers studieren
references/VERIFY.md + templates/verifier_prompt.md	Nach CLAIMS, nach Modellläufen, nach Erzählung / Übersetzung
references/REVIEW.md	Phase D–E: Review-Seite, Feedback-Datei, Runden
references/I18N.md	Eine übersetzte Version einer englischen Folge (--lang)
references/NARRATION.md	Gesprochenes Skript pro visuellem Segment
references/TTS.md	Lokale TTS-Sprachausgabe, Timing, Mischung
references/DISPATCH.md	Multi-Sitzungs- / Sub-Agenten-Arbeit, Kosten, Etikette für gemeinsame Maschinen
references/PITFALLS.md	Etwas bricht; vor dem Ändern der Bibliothek
templates/	Prompts für Sitzungen und Sub-Agenten, Skelettdateien, eine Shot-Vorlage