explainer

Was macht explainer?

Eine Spezifikationsdatei listet die Szenen auf; die Skripte erfassen das Material, vertonen die Erzählung, bauen eine HyperFrames-Unterkomposition pro Szene und überprüfen alles, bevor es ausgeliefert wird.

1. verstehen     den Code / die Doku / die App lesen, um die es geht
2. erfassen      scripts/capture.py      Screenshots, Elementboxen, Aufnahmen, Schwärzungen
3. spezifikation Sie schreiben explainer.json (Szenen + Erzählung + Behauptungen mit Quellen)
4. fakten prüfen scripts/verify.py fakten (Tor: nichts wird vertont, bis es besteht)
5. bauen         scripts/build_explainer.py (Stimme, Untertitel, Szenen; kein Charakter standardmäßig)
6. überprüfen    scripts/verify.py alles   (Assets, Build, Render, Audio) – wiederholen, bis sauber
7. rendern       scripts/render.py

Pfade sind relativ zum Stammverzeichnis dieses Pakets: dem Ordner, der .claude-plugin/ enthält, zwei Ebenen über dieser Datei (symlinks zuerst auflösen). Erfordert die öffentlichen HyperFrames-Skills (hyperframes, hyperframes-cli; hyperframes-registry und media-use für Extras). Lesen Sie hyperframes einmal, bevor Sie generierte Kompositionen von Hand bearbeiten.

0. Preflight (immer zuerst)

Führen Sie python3 scripts/setup.py doctor aus (fügen Sie --json hinzu, um es zu parsen). Es listet jede Abhängigkeit auf, wofür sie ist und den genauen Installationsbefehl für diese Maschine; es beendet sich mit Exit-Code 1, wenn ein erforderliches Element fehlt.

• Erforderlich fehlend (ffmpeg, Node.js 18+, die HyperFrames-Skills und der ElevenLabs-Key oder say wenn diese Stimme konfiguriert ist): Teilen Sie dem Benutzer in einem Satz mit, wofür jedes ist, und schlagen Sie den angezeigten Befehl vor. Führen Sie ihn erst aus, nachdem der Benutzer zugestimmt hat. Geben Sie niemals selbst einen API-Key ein oder fragen Sie danach: Sagen Sie dem Benutzer, er soll ELEVENLABS_API_KEY in seiner Shell exportieren.
• Optional fehlend: Bieten Sie sie einmal an und sagen Sie, was jedes freischaltet. Playwright ermöglicht Webaufnahmen mit Element-Zoom-Boxen und ganzseitigen Aufnahmen, Tesseract (OCR) ermöglicht den Secrets-Scan auf Screenshots und ASR (mlx-whisper / openai-whisper) ermöglicht die Audio-Überprüfung und genaue Wortzeitmessungen. Überspringen Sie sie, wenn der Benutzer ablehnt; die entsprechenden Prüfungen werden dann zu manuellen review-Schritten.
• HyperFrames-Skills (hyperframes, hyperframes-cli, hyperframes-registry, media-use): Wenn fehlend, empfehlen Sie npx hyperframes skills. Lesen Sie hyperframes (und hyperframes-cli für Render-Probleme), bevor Sie eine Komposition bauen oder bearbeiten.

Setup (erster Start oder wenn der Benutzer etwas ändern möchte)

python3 scripts/setup.py show gibt die aktive Konfiguration aus. Wenn keine vorhanden ist, befragen Sie den Benutzer (eine kurze Frage nach der anderen, bieten Sie den Standard an) und schreiben Sie sie:

Frage	Flag	Optionen
Welche Teile?	--features	explainer allein (keine Charakterdatei nötig) oder character,explainer für einen möglichen Präsentator
Erzählsprache	--language	ISO-Code (en, es, ...): wählt eine klare say-Stimme und teilt der ASR mit, was zu erwarten ist
Erzählstimme	--narration-voice	voice (der konfigurierte Anbieter), say (kostenlos, macOS), none (nur Untertitel)
Sprachanbieter	--voice	elevenlabs (deren ELEVENLABS_API_KEY aus der Umgebung + --voice-id), say, none
Guthaben-Grenzen	--max-chars, --max-seconds, --daily-credit-cap	die Zahlen des Benutzers
Render	--render	local, cloud, preview
Größe	--size	1080x1920 (Standard), 1920x1080, 1080x1080

python3 scripts/setup.py init --features explainer --voice say --render local --yes

init führt zuerst den Doctor aus und bietet dieselben Installationen an. Wenn eine Konfiguration existiert, fragt es vor dem Überschreiben (übergeben Sie --force bei nicht-interaktiver Ausführung). setup.py voices --lang <code> listet macOS-Stimmen für eine Sprache und die ElevenLabs-Stimmen des Benutzers auf; --say-voice "<name>" wählt eine aus. Fragen Sie niemals nach API-Keys, geben Sie sie nicht aus und schreiben Sie sie nicht.

1. Verstehen, dann Skript

• Holen Sie sich zuerst die Fakten aus der Quelle: Lesen Sie den Code, den PR, das Dokument oder die App. Ein falscher Erklärer ist schlimmer als keiner. Zeigen Sie die Form der Sache vor den Details, führen Sie einen echten Fall hindurch (echte Namen, echte Werte) und halten Sie jede Szene auf eine Idee beschränkt.
• Form (≤ styles.explainer.max_seconds): 3–5 Szenen von etwa 6–12 s Dauer und ein Abschlusstitel. TTS liest etwa 2,4 Wörter pro Sekunde: Halten Sie die Erzählung einer Szene unter ~25 Wörtern.

Wählen Sie einen Stil für dieses Video

Das Paket enthält nur neutrale Standardeinstellungen. Wählen Sie einen Stil pro Video basierend auf Thema, Zielgruppe und der Marke oder den Vorlieben des Benutzers, und fragen Sie nach, wenn es wichtig ist (eine Marke, ein öffentlicher Kanal, eine Serie). Wiederholen Sie nicht aus Gewohnheit das Aussehen des vorherigen Videos. Fügen Sie es in den style-Block der Spezifikation ein:

Schlüssel	Werte
palette	background, panel, ink, muted, accent, highlight (CSS-Farben; Textkontrast ≥ 4,5:1 beibehalten)
typography	font, mono (HyperFrames-gebündelte Schriftarten), title_scale (0,6–1,6)
layout	align (left, center), radius (0–60), background_style (solid, gradient)
motion	motion (calm, normal, lively): Dauern und Easing jeder Bewegung
captions	caption_style (box, outline, plain, none), caption_position (bottom, top)

Ein brand-Kit in der Konfiguration (gleiche Schlüssel) überschreibt Ihre Wahl Schlüssel für Schlüssel. Das Set des Präsentators folgt dem Hintergrund des Videos, es sei denn, sein Block hat einen eigenen style (siehe talking-clip).

2. Das Material erfassen

python3 scripts/capture.py url http://localhost:3000/login --name login
python3 scripts/capture.py url http://localhost:3000/login --name login --box "#submit"   # benötigt Playwright
python3 scripts/capture.py screen --name settings --interactive
python3 scripts/capture.py record --name signup --seconds 12          # macOS
python3 scripts/capture.py add --name diagram --file ./docs/arch.png
python3 scripts/capture.py redact --name login --box 820,410,360,48   # or --blur
python3 scripts/capture.py list

• url verwendet Playwright, wenn installiert (erforderlich für --box und --full-page), andernfalls headless Chrome. Ohne Playwright geben Sie Fokusboxen als Pixelrechtecke [x, y, w, h] an, die aus dem PNG gelesen werden (doppelt so viele CSS- Pixel bei Standardskalierung). Wenn Playwright in einer virtualenv lebt, führen Sie die Skripte mit diesem Interpreter aus (.venv/bin/python scripts/capture.py ...). --box zeichnet die Box eines Elements in Bildpixeln auf, sodass eine Szene direkt darauf zoomen kann. Standardmäßig --scale 2 hält Text beim Zoomen scharf.
• Erfassen Sie die kleinste Region, die die Geschichte erzählt; ein voller Desktop, der in einen Telefonrahmen gequetscht wird, ist unlesbar. Verwenden Sie Fokusboxen zum Zoomen.
• Eine ganze Website als Projekt statt einzelner Aufnahmen: npx hyperframes capture <url> (hyperframes-cli).

3. Die Spezifikation schreiben

examples/explainer/explainer.json ist ein vollständiges, funktionierendes Beispiel. Legen Sie die Spezifikation im Stammverzeichnis des Materials ab: Codedateien und Aufnahmen, auf die sie verweist, müssen sich im Ordner der Spezifikation befinden. Szenentypen:

Typ	benötigt	was es zeigt
screen	capture, optional focus: [{"box": "#sel" or [x,y,w,h], "label": "...", "at": s}]	den Screenshot, dann eine Kamerabewegung zu jeder Box mit Hervorhebung und Beschriftung
recording	capture (ein Video), optional focus	die Bildschirmaufnahme, stumm, gleiche Kamera und Beschriftungen
code	file, lines: "a-b" (≤ 24, Zeilen ≤ ~49 Zeichen in vertikaler Richtung), highlight: [{"lines": [a, b], "at": s}]	den Code auf einer Karte, Zeilen erscheinen, Bänder auf den Schlüsselzeilen
diagram	nodes: [{"id","label","sub"?,"highlight"?}], edges: [[a, b]], optional flow: [ids]	Boxen und Pfeile, die aufgebaut werden, ein Token, das entlang flow reist
title	text, optional sub, dur	eine Abschluss- oder Abschnittskarte

Bewegung, in jeder Szene (optional; Farben und Timing kommen aus dem Stil, variieren Sie sie also pro Video wie den Rest des Looks):

Schlüssel	Was
callouts: [{"type": "circle" or "arrow", "box": [x,y,w,h] or "#sel", "at": s, "note": "..."}]	handgezeichneter Kreis oder Pfeil, der sich einzeichnet; Bildpixel auf Bildschirm-/Aufnahmeszenen, Framepixel anderswo
kinetic: [{"text", "at", "dur", "y"?, "from"?}]	Wörter, die zur Betonung einschlagen; sparsam verwenden (ein oder zwei pro Video)
counter: {"to", "from"?, "at", "dur", "prefix"?, "suffix"?, "label"?}	ein Hochzähler, der auf dem genauen Wert landet
Top-Level transition: "wipe" or "fade"	ein Übergang bei jedem Schnitt (Standard none)

Sie folgen den Registry-Elementen count-up, caption-kinetic-slam, hw-callout-circle und hw-arrow (siehe /hyperframes-registry). style.hand_font: "Caveat" lädt diese Handschrift-Schriftart mit npx hyperframes add. Verwenden Sie nicht jedes Feature in jedem Video; wählen Sie, was die Geschichte braucht.

Jede Szene mit narration muss claims enthalten: jede technische Aussage, die sie macht, mit einer source (path:lines relativ zur Spezifikation, capture:<name>, https://..., doc:<name>) und status: "supported", sobald Sie sie anhand dieser Quelle überprüft haben. "claims": [] bedeutet, dass die Erzählung keine technische Behauptung aufstellt. Nicht unterstützte Behauptungen werden korrigiert oder gestrichen, niemals vertont.

Kein Charakter standardmäßig. Ein Erklärvideo ist Erzählung, Untertitel und Bilder. Fügen Sie den Charakter als Präsentator nur hinzu, wenn der Benutzer darum bittet, oder wenn Sie urteilen, dass es einen Mehrwert bringt (eine Serie mit einem Gastgeber, ein freundliches Onboarding) und Sie dies dem Benutzer mit dem Grund mitteilen. Fügen Sie dann einen presenter-Block hinzu (intro / outro, jeweils {"text", "plan"?, "mood"?, "style"?, "claims"}; Pläne folgen dem Format von talking-clip) und bauen Sie mit --presenter. Es benötigt auch features.character. Präsentator- Szenen erhalten auch Untertitel (es sei denn, die Spezifikation setzt "captions": false). examples/explainer/explainer-with-presenter.json ist das Beispiel.

4–5. Fakten-Tor, dann bauen

python3 scripts/verify.py facts --spec explainer.json
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer --estimate
python3 scripts/build_explainer.py --spec explainer.json --project out/explainer [--confirm] [--presenter]

--estimate gibt Länge und ElevenLabs-Guthaben aus; informieren Sie den Benutzer vor dem Ausgeben, dann bauen Sie mit --confirm. Der Builder führt auch das Fakten-Tor aus und stoppt, wenn es fehlschlägt. Untertitel zeigen die eigenen Wörter des Skripts (Groß-/Kleinschreibung, Satzzeichen, Ziffern) zeitlich abgestimmt aus ElevenLabs' Alignment, ASR oder einer Schätzung.

6. Überprüfen (erforderlicher Kreislauf)

python3 scripts/render.py out/explainer --out out/explainer.mp4 --quality draft
python3 scripts/verify.py all --project out/explainer --spec explainer.json --video out/explainer.mp4

Stufe	Besteht, wenn	Bei Fehlschlag
fakten	jede erzählte Behauptung hat eine vorhandene Quelle und Status supported	Quelle prüfen; Behauptung korrigieren oder streichen
assets	Aufnahmen und Code sind bei Ausgabegröße lesbar; OCR (tesseract) / Text-Scan findet keine E-Mails, Schlüssel, Tokens oder Kartennummern	Fokusboxen hinzufügen oder kleiner neu erfassen; capture.py redact; Geheimnisse im Code durch Platzhalter ersetzen
build	npx hyperframes check --json hat keine Fehler oder Warnungen (außer verify.ignore_rules)	Spezifikation oder generierte Komposition korrigieren
render	Sie haben das Kontaktblatt angesehen (Start, jede Szenenänderung, Mitte der Szene, Ende): kein Überlauf, keine Überlappung, kein Abschneiden oder unlesbarer Text; Bilder passen zur Erzählung	korrigieren, neu bauen, neu rendern
audio	ASR des gerenderten Audios stimmt mit dem Skript überein (verify.min_asr_similarity) und die Dauer liegt innerhalb des Limits	Stimme neu generieren oder kürzen

So steuern Sie den Kreislauf:

1. Führen Sie verify.py all aus. Jeder Durchlauf ist eine Iteration (gezählt in <project>/.verify/state.json).
2. render kommt immer zuerst als review zurück: Öffnen Sie die aufgeführten Kontaktblätter, überprüfen Sie jedes Bild, und notieren Sie, was Sie gesehen haben: python3 scripts/verify.py mark render pass --project out/explainer --note "<was Sie überprüft haben>" (oder fail, dann korrigieren). Die Markierung ist an diese genauen Dateien gebunden; jeder Neubau macht sie ungültig.
3. Ohne installiertes OCR oder ASR werden assets / audio ebenfalls zu review: überprüfen Sie mit Auge oder Ohr und geben Sie dies im Bericht an.
4. Korrigieren Sie, was fehlgeschlagen ist, bauen Sie neu oder rendern Sie neu, und führen Sie verify.py all erneut aus. Exit-Code 0 = Auslieferung.
5. Wenn die Anzahl verify.max_iterations (Standard 3) erreicht, beendet es sich mit Exit-Code 2: Stoppen und teilen Sie dem Benutzer mit, was noch fehlschlägt. Liefern Sie nicht stillschweigend aus. Löschen Sie .verify/state.json, um nach einer größeren Änderung einen frischen Zähler zu starten.

VERIFY.md zeigt Zahlen: OCR-Scans und Treffer, ASR-Ähnlichkeit mit gehörten und erwarteten Wörtern, Dauer im Vergleich zum Limit. Zitieren Sie sie in Ihrem Bericht. Szenen werden automatisch verlängert, damit der letzte Untertitel lesbar bleibt; wenn eine line_unread-Warnung bleibt, geben Sie dieser Szene mehr min_dur.

Behalten Sie das normale HOME des Benutzers beim Ausführen der Skripte: Ein temporäres HOME lässt npx, Playwright und whisper alles erneut herunterladen und bricht die gh/npx-Authentifizierung.

Audio-Unstimmigkeiten bei Ziffern, Akronymen oder Fremdwörtern: Setzen Sie language in der Konfiguration und schreiben Sie diese Wörter in der Erzählung so, wie sie klingen sollen ("fünfzehn", "A P I"). VERIFY.md im Projekt ist der Checklistenbericht; fügen Sie seine Zusammenfassung bei, wenn Sie das Video übergeben.

7. Rendern

python3 scripts/render.py out/explainer --out out/explainer.mp4 verwendet render.backend (local, cloud oder preview); render.max_mb kodiert neu, um ein Upload-Limit einzuhalten. Committen Sie niemals mp4- oder wav-Dateien.