Pedrovbm1/explicador

Explicador animado (Motion Graphics 3D per Code)

Alles ist Code: Jeder Teil des Videos ist eine 3D-Welt (escena/partes/<teil>.js), die eine reine Funktion der Zeit ist, motor.js entscheidet, welcher Teil aktuell angezeigt wird und zeichnet die Karaoke-Untertitel, und render.mjs fordert von Chrome ohne Fenster jedes Einzelbild an. Nichts wird von Hand bearbeitet: Wenn etwas schiefgeht, wird der Code korrigiert und neu gerendert.

Wo alles ist: HOME3D = $EXPLICADORES_3D oder, falls nicht vorhanden, ~/.explicadores-3d (wird vom Installer erstellt). Dort befinden sich biblioteca/ (3D-Modelle, vendor/ mit three.js, Schriftarten) und eine Kopie dieser Skill. SKILL_DIR = der Ordner dieser SKILL.md.

Datei	Zweck
nuevo.py <ordner>	Erstellt das Projekt mit der Vorlage (Motor, Stil, lib2d, three.js, Fredoka-Schriftart, Skripte für Sprache/Zeiten/Audio, ein Beispielteil, leeres CONTRATO.md und DECISIONES.md)
render.mjs	--hoja, --probe a,b,c, --rango a,b, --mitad, --sub N, --rapido, --sin-gpu
entregar.py <projekt> <NAME> --ronda N [--escritorio]	Video + Audio, mobile Version < 29 MB, Prüfblätter alle 0,5 s und datos.txt (Dauer, LUFS, Spitzenpegel)
revisar_hoja.py <projekt> [--tramo a,b | --ronda N | --cuadros …]	Automatische Prüfung in ~5 s ohne Token: doppelter Text in Überblendungen, Halos, Zwillinge (sehen aus wie Augen), weiße Überstrahlung, Flecken, außerhalb des Bereichs, Helligkeitssprünge
ENCARGO_CONSTRUCTOR.md	Vorlage für den kurzen Konstruktionsauftrag (ein Teil pro Agent)
ENCARGO_REVISORES.md	Prüfer A (Kohärenz), B (Daten), D (Bild) über das Blatt und das Video

Voraussetzungen: Node 18+, npm install playwright-core im Projekt, Chrome (oder CHROME_PATH, oder npx playwright install chromium), Python 3.10+ mit numpy und faster-whisper, und ffmpeg.

Hausregeln

• Keine erfundenen Daten: Jede Zahl mit ihrer Quelle im CONTRATO bevor konstruiert wird.
• Keine Haustiere oder Objekte mit Augen, und keine Formen, die wie Augen gelesen werden (siehe "Typische Fehler").
• Standard-Stil: Ein sauberes Objekt auf dunklem Hintergrund mit warmem Halo, Makrokamera in ständiger sanfter Bewegung, Schlüsselwort in Gold, Karaoke-Untertitel für die gesamte Erzählung, Loop zum ersten Bild.
• Rhythmus: 3,0–3,2 Wörter/s, ein Bildwechsel alle ~3 s, nichts länger als 5 s unbewegt, Hook vor 4,5 s.
• Dauer: 15–30 s, wenn einzeln; mehr als 60 s nur als Teil einer Serie mit Name und Nummer.

Der Ablauf

1. python SKILL_DIR/nuevo.py <thema>-JJJJ-MM (erstellt den Ordner im aktuellen Verzeichnis). Öffne und prüfe, ob es angezeigt wird: npx http-server escena -p 8080 (oder python -m http.server innerhalb von escena/) und gehe zu localhost:8080.
2. Skript mit der Skill guion: Recherche mit Quellen, MAP, Runde 0 (A ≥ 9, C ≥ 9, max. 2 Runden) und Stopp GUION LISTO. Fahre nicht ohne das OK des Benutzers fort.
3. Sprache (verbraucht Guthaben oder CPU-Zeit, daher nach dem OK):
   • ElevenLabs: export ELEVENLABS_API_KEY=... (vom Benutzer gesetzt; niemals selbst in eine Datei schreiben) und python scripts/voz_eleven.py [--voz <id>] → voz/tomas_eleven/. Kostenloser Plan = keine kommerzielle Nutzung mit Guthaben.
   • Kostenlos und lokal: pip install kokoro soundfile (+ espeak-ng systemweit) und python scripts/voz_local.py [--voz em_alex] → voz/tomas_local/.
   • python scripts/verificar_voz.py (Whisper large-v3, einmal und im Hintergrund) markiert schlecht ausgesprochene Wörter.
   • python scripts/tiempos.py --tomas tomas_eleven (oder tomas_local) → voz/voz_completa.wav, escena/beats.js (Sekunde jedes Schlüsselworts, gemäß voz/claves.json) und escena/palabras.js (Karaoke).
4. CONTRATO vollständig (escena/CONTRATO.md): Teile mit ihren Abschnitten B.*, was in jedem Schlüssel zu sehen ist, genaue Schriftzüge, Daten mit Quelle, Sicherheitszone, Rhythmus. Es ist das Einzige, was die Konstrukteure lesen: Was nicht drin steht, raten sie. Ändere in motor.js das PLAN (Reihenfolge der Teile und Übergänge) und CLAVE (goldene Wörter des Karaoke).
5. 3D-Modelle: Vor dem Modellieren in der Bibliothek suchen (Skill biblioteca, HOME3D/biblioteca/CATALOGO.md) und kopieren, was passt, nach escena/modelos/. Was fehlt, wird von einem einzigen Agenten erstellt (gemeinsames Modell, Aufwand medium, Limit 150 k) und mit modelos/LISTO_<objekt>.txt gemeldet.
6. Konstrukteure mit ENCARGO_CONSTRUCTOR.md:
   • ein Teil pro Agent (eine Szene ≤ 15 s), im Hintergrund, maximal 3 gleichzeitig;
   • kurzer Auftrag: nur sein Abschnitt, seine Modelle mit der API in einer Zeile und die Regeln; der Konstrukteur liest weder den Motor noch das gesamte CONTRATO;
   • mit dem Block "Typische Fehler" und dem "Limit des Konstrukteurs" wörtlich angehängt;
   • ein frischer Konstrukteur pro Reparaturrunde, niemals mit einem weiterdiskutieren, der bereits 40 Züge überschritten hat;
   • niemals warten lassen auf einen anderen Agenten: zuerst das gemeinsame Modell, dann die Teile.
7. Blatt vor dem Rendern: node render.mjs --hoja (ein Bild pro Beat: das visuelle Skript) und python SKILL_DIR/revisar_hoja.py .. ROT = mit einem frischen low-Agenten reparieren, bevor es weiter geht. Dann Prüfer A, B und D über das Blatt (ENCARGO_REVISORES.md, Runde 1), mit der Ausgabe von revisar_hoja.py im Auftrag von D.
8. python scripts/audio.py → audio/mezcla.wav mit -14 LUFS (synthetisierte Musik und Effekte; bearbeite EFECTOS und CAMBIOS oben in der Datei).
9. Rendern für Iteration: node render.mjs --rapido --sub 1. Danach python SKILL_DIR/entregar.py . NAME --ronda 1 und python SKILL_DIR/revisar_hoja.py . --ronda 1 bevor A und D prüfen (1 Runde über das Video).
10. Finales Rendern, nur einmal: node render.mjs --sub 6. Niemals zwei Renderläufe gleichzeitig.
11. python SKILL_DIR/entregar.py . NAME --ronda N --escritorio und Auslieferung der mobilen Version.
12. Beitrag zur Bibliothek (standardmäßig aktiviert): Folge dem Vorgehen "Neue Modelle beisteuern" der Skill biblioteca (nuevos.py → vorbereiten → Soll ich sie in die Bibliothek hochladen? (S/n)). Wenn der Benutzer bereits bei diesem Projekt Nein gesagt hat, nicht noch einmal fragen.

Aufwand und Modell pro Rolle

Siehe vollständige Tabelle pro Ausführungsumgebung in AGENTS.md des Repos. Zusammenfassung (Namen von Claude Code; bei anderen Ausführungsumgebungen das Äquivalent "schnell/mittel/tief" verwenden):

Rolle	Modell	Aufwand
Sitzung, die das Video koordiniert	das verwendete	medium
Datenrechercheur und Prüfer B	mittel (Sonnet)	high
Gemeinsames 3D-Modell	mittel	medium, Limit 150 k
Szenenkonstrukteure	mittel	medium, Limit 40 Züge / 120 k
Prüfer A, C, D	mittel	medium (kleine Modelle wie Haiku widersprechen Regeln: nein)
Kleine Reparaturen an einer Szene	mittel	low
max	niemals	dauert extrem lange und denkt zu viel

Token-Budget und Sitzungen

Die Kosten sind Züge × Länge des Gesprächs, nicht das Geschriebene. Regeln:

• Eine frische Sitzung pro Video. Staffelübergabe bei 150 k Kontext: hinterlasse AVANCE.md (was erledigt ist, was als Nächstes kommt, Entscheidungen) und fahre in einer neuen Sitzung fort, die es liest.
• Benachrichtigungen nur bei Meilensteinen: GUION LISTO, VIDEO RÁPIDO LISTO, TERMINADO oder wenn du blockiert bist. Alles andere wird in TIEMPOS.md notiert, ohne Benachrichtigung.
• Keine Screenshots oder Bilder in der Hauptsitzung: Ein Unteragent sieht sie und antwortet in Text.
• Prüfer mit Budget: Runde 0 über die MAP max. 2 Runden; Runde 1 über das Blatt 1; über das Video 1 Runde nur mit A und D. Zweite Runde nur in dem Bereich, der unter 8,5 geblieben ist.

Limit des Konstrukteurs (wird wörtlich am Ende jedes Auftrags angehängt; für das gemeinsame Modell 150 k):

Budget: maximal 40 Züge und 120 k Token Kontext. Wenn du eines von beiden erreicht hast, schreibe AVANCE.md in deinen Arbeitsordner (was erledigt ist, was fehlt, was du probiert hast und gescheitert ist) und beende mit einer 5-zeiligen Zusammenfassung; ein anderer Agent wird von dort fortfahren. Lies nicht den Motor, das komplette CONTRATO oder fremde Teile: Was du brauchst, steht in diesem Auftrag. Lies niemals eine vollständige Datei mit mehr als 300 Zeilen: verwende Bereiche oder grep. Screenshots nur mit node render.mjs --probe <sek> --mitad und maximal 1 pro 5 Züge. Bevor du einen Screenshot anforderst, führe revisar_hoja.py aus (kostet keine Token). Warte auf niemanden: Wenn etwas fehlt, notiere es in AVANCE.md und beende.

Typische Fehler (werden wörtlich in jeden Konstrukteurauftrag eingefügt; (auto) = wird von revisar_hoja.py erkannt):

1. Doppelter Text in Überblendungen (auto): Entferne das alte Schild vollständig, bevor das neue erscheint (Ausgang < 0,15 s) oder verwende einen harten Schnitt; niemals zwei Schilder gleichzeitig in derselben Zone.
2. Halos und Auren (auto): Ein Orbis, eine Scheibe oder ein Lichtpunkt mit weichem Glanz drumherum wird als Auge oder Sonne gelesen. Flaches Emissiv, ohne radialen Sprite; wenn etwas glänzt, dann länglich und ohne Ring.
3. Zwillinge (auto): Zwei Fenster, Lichtpunkte oder Orben gleicher Größe und Helligkeit nebeneinander werden als Augen gelesen. Unterschiedliche Größen, unterschiedliche Höhen, oder nur eines.
4. Weiße Überstrahlung (auto, Warnung): Nichts in reinem Weiß mit Bloom; Farbe der Palette, matt.
5. Flecken und lose Punkte (auto, Warnung): Einzelne Partikel, Schatten hinter Schildern, zurückgebliebene Kanten.
6. Außerhalb der Zone (auto): Nichts bei y < 215 noch unterhalb von y = 1450 (Karaoke); nichts kreuzt ein Schild.
7. Helligkeitssprünge (auto mit --ronda): Mittlere Helligkeit 60–90, keine Sprünge > 25 zwischen Aufnahmen.
8. Doppelte: Derselbe Text in Schild und Karaoke gleichzeitig; ein Schild pro Idee.
9. Gesichter und Hände: Personen von hinten oder 3/4-Rücken; die Hand kommt von der Seite oder vom Handrücken.
10. Kleine Schilder: Alles >= 42 px (Schilder >= 52 px).

Rendern: Wo die Zeit bleibt (gemessen auf einem Laptop mit 4 Kernen und integrierter GPU)

Schritt	Pro Bild
Bild aus Chrome holen (JPEG, GPU per ANGLE)	~0,07 s
x264 slow CRF 16 (Auslieferung)	+0,11 s
--rapido (Quick Sync unter Windows/Intel; x264 veryfast auf Anderen; CODEC_RAPIDO zur Auswahl)	+0,02–0,05 s
Weichzeichner --sub 6	+0,09 s

Ohne GPU (--sin-gpu) ist es ~40 % langsamer. Kein transmission in Materialien und jeder Teil < 80 ms pro Bild.

Lektionen, die einen Durchlauf kosten, wenn man sie vergisst

• update(t) ist eine reine Funktion von t: Der Renderer fordert einzelne Bilder und Unterbilder an. Kein Math.random (verwende E.azar(seed)) und kein Zustand zwischen Bildern. Schütze t < 0.
• Kamerabewegungen ≥ 0,6 s mit inOutCubic: Mit --sub 6 werden Peitschenhiebe als Geisterbilder ausgegeben.
• Wenn ein Test mit Bruchstücken eines anderen Bildes herauskommt, hat ein anderer Prozess gleichzeitig gerendert: Wiederhole ihn.
• Der 404 "Failed to load resource" am Ende des Renderings ist normal; echte Fehler sind pageerror.
• Mit scene.environment verwendet three r186 scene.environmentIntensity, nicht envMapIntensity des Materials.
• Partikel aus der Bibliothek (three.quarks) sind deterministisch über die Zeit: Verschiebe nicht die Gruppe, verwende ihre pos.
• Einstellungs-Panel mit der Maus: ?ajustes=1 in der URL (siehe biblioteca/base/LEEME.md); der Renderer lädt es nie.
• Echtes Material (Fotos, Archivmaterial): Wikimedia Commons und Internet Archive sind Public Domain und CC BY; notiere die Credits in der Beschreibung.