Under the Hood

Was macht Under the Hood?

Verwandelt ein Thema (oder den Code des Benutzers) in ein kommentiertes, animiertes Erklärvideo. Der Look ist warm und handgezeichnet:

• ein cremefarbener Punktraster-„Papier“-Hintergrund mit Tinten-Line-Art
• Blau für Anfragen, Orange für Antworten, Grün für Verschlüsselung oder Erfolg
• ein Schritt-Tracker oben und große Untertitel unten
• Pakete, die zwischen Kästchen fliegen, und Kamerafahrten zwischen „Welten“

Das Referenzergebnis ist ${CLAUDE_SKILL_DIR}/assets/example-cookie/, das zeigt, was passiert, wenn Sie „cookie“ in Google eingeben. Öffnen Sie dessen scenes.js, wenn Sie ein Muster für etwas Komplexes benötigen.

Alles wird per Code gesteuert. Eine Canvas-Seite rendert Frames deterministisch, Erzählclips legen die Länge jeder Szene fest, und Musik und Soundeffekte werden aus derselben Zeitachse synthetisiert. Eine Skriptänderung synchronisiert alles neu, und ein 60-Sekunden-Video rendert in etwa 30 Sekunden.

Angefordertes Thema: $ARGUMENTS

Wo die Dinge sind

• Skripte: ${CLAUDE_SKILL_DIR}/scripts/ (nennen Sie es SCRIPTS).
• Laufzeitumgebung: UTH_HOME (Standard: ~/.local/share/under-the-hood) enthält das Node-Modul, die TTS-Venv und gespeicherte Stimmen. doctor.sh gibt die genauen Pfade aus, einschließlich PY (das TTS-Python).
• Projekte: ./explainers/<slug>/ im aktuellen Arbeitsverzeichnis, sofern der Benutzer keinen anderen Ort angibt. Wenn das Arbeitsverzeichnis das Home-Verzeichnis ist, fragen Sie, wo das Projekt abgelegt werden soll, anstatt ~ zu überladen.

Ein Projektordner sieht so aus:

index.html  engine.js  scenes.js  script.json  timeline.js
narration/  (Sprachclips: <id>.wav, <id>_take2.wav, plus Vorschaudateien)
audio/      (Stems und mix.wav)
.shots/     (Screenshots, ein neuer Ordner pro Durchlauf)
<slug>.mp4

Arbeitsablauf

0. Überprüfen Sie die Einrichtung (ein Befehl, wenn alles bereit ist)

bash ${CLAUDE_SKILL_DIR}/scripts/doctor.sh          # --no-tts hinzufügen, wenn das Video keine Erzählung hat

Wenn READY ausgegeben wird, notieren Sie PY und VOICES und fahren Sie fort. Wenn MISSING-Zeilen ausgegeben werden, laden Sie den Skill under-the-hood-setup und befolgen Sie ihn, dann führen Sie den Doctor erneut aus.

1. Kurze Erfassung

Wenn $ARGUMENTS leer ist, fragen Sie nach dem Thema. Fragen Sie dann nur, was Sie nicht vernünftigerweise selbst entscheiden können, in einer Nachricht, mit sinnvollen Voreinstellungen:

• Schwerpunkt, nur wenn das Thema breit gefächert ist. „Wie das Internet funktioniert“ braucht einen Fokus, „was passiert, wenn Sie git push ausführen“ nicht.

• Stimme: Bieten Sie dies immer an, da Benutzer nicht wissen, dass ihre eigene Stimme eine Option ist. Präsentieren Sie es so:

  1. eingebaute Stimme (Standard, funktioniert sofort)
  2. eine gespeicherte Stimme, falls VOICES eine auflistet
  3. Ihre eigene Stimme: Nehmen Sie etwa 20 bis 30 Sekunden auf Ihrem Telefon auf und senden Sie die Datei. Ihre Stimme bleibt auf Ihrem Rechner.
  4. keine Erzählung (nur Musik und Soundeffekte)

  Wenn sie ihre eigene Stimme wählen, lesen Sie ${CLAUDE_SKILL_DIR}/references/voice.md und geben Sie ihnen dessen Aufnahmetipps und den Beispielabsatz, bevor Sie etwas anderes tun. Sie können aufnehmen, während Sie das Storyboard schreiben.

• Länge: Standardmäßig 30 bis 60 Sekunden, 16:9.

Machen Sie daraus keinen Fragebogen. Maximal zwei oder drei kurze Fragen.

2. Verstehen Sie das Thema und holen Sie die Fakten richtig

Wenn der Benutzer Code angegeben hat, lesen Sie ihn und verfolgen Sie den tatsächlichen Ablauf. Tech-Zuschauer werden Fehler aufdecken. Daher:

• Bringen Sie die Reihenfolge der Ereignisse in Ordnung. Beispiel: Auf einer bereits geladenen Seite sind DNS- und TLS-Handshake bereits erfolgt, platzieren Sie sie daher beim ersten Kontakt oder kennzeichnen Sie sie als „erster Besuch“.
• Bevorzugen Sie, was moderne Systeme tatsächlich tun. Beispiel: Chrome kommuniziert mit Google über QUIC und TLS 1.3, nicht über einen lehrbuchmäßigen TCP-Drei-Wege-Handshake.
• Schreiben Sie „vereinfacht“ in eine Untertitel, wenn Sie vereinfachen.
• Verwenden Sie illustrative Werte (Beispiel-IPs, .example-Domains, erfundene Werte) und vermeiden Sie falsche Präzision wie genaue Millisekundenangaben.
• Erstellen Sie keine Logos oder pixelgenauen Benutzeroberflächen echter Produkte nach. Line-Art-Stellvertreter passen sowieso besser zum Stil.

3. Storyboard und Drehbuch, dann Genehmigung einholen, bevor Sie bauen

Planen Sie 4 bis 8 nummerierte Schritte, etwa 30 bis 60 Sekunden, plus eine title-Szene zu Beginn und eine end-Szene am Ende. Schreiben Sie für jede Szene:

• Erzählung (script.json): {"id", "text", "gap"}. gap ist die Pause nach der Zeile, 0,25 bis 0,45 Sekunden.
• Untertitel (cap): 8 Wörter oder weniger, lesbar wenn stummgeschaltet. Unter-Untertitel (sub): eine kurze Zeile.
• Visueller Beat: Was erscheint und sich bewegt, und welches Geräusch jeweils zu hören ist.

Lesen Sie ${CLAUDE_SKILL_DIR}/references/narration.md, bevor Sie die Erzählung schreiben. Eine artikelartige Erzählung klingt wie ein KI, der einen Artikel vorliest. Schreiben Sie so, wie eine Person einem Freund etwas erklärt.

Zeigen Sie dem Benutzer das Drehbuch und das Storyboard als kurze Tabelle und warten Sie auf das Go. Wörter jetzt zu ändern ist kostenlos. Nach der Spracherzeugung kostet es einen erneuten Durchlauf.

Keine Gedankenstriche und keine Semikolons in der Erzählung oder im Bildschirmtext. Die TTS liest sie seltsam, und kurze Sätze klingen natürlicher.

4. Gerüst bauen

bash SCRIPTS/new_project.sh ./explainers/<slug> "<Seitentitel>"

Dies kopiert engine.js, eine Starter-scenes.js (ein kleines funktionierendes „Abschicken“-Beispiel) und script.json. Es weigert sich, einen nicht leeren Ordner zu überschreiben. Ersetzen Sie den Starterinhalt durch das echte Storyboard.

5. scenes.js bauen

Lesen Sie zuerst ${CLAUDE_SKILL_DIR}/references/engine-api.md. Es behandelt das Zeitmodell, jeden Helfer, die Layout-Zonen, die Soundnamen und die Boot-Konfiguration. Schlüsselideen:

• defineScenes([...]) mit Design-Dauern. Animieren Sie in Designzeit mit prog(t, S.id + a, S.id + b). Die Engine dehnt jede Szene, um ihren Sprachclip zu passen, also passen Sie niemals manuell an die Cliplängen an.
• Halten Sie die Welt in y 150 bis 800. Der Tracker sitzt darüber und die Untertitel darunter.
• Dinge, die bestehen bleiben sollen (ein Browser, ein Server), erscheinen in einer Szene und bleiben danach gezeichnet.
• Für einen zweiten „Ort“, wie z. B. in einem Rechenzentrum, zeichnen Sie bei x + 1920 und schwenken Sie mit camera(t). Beginnen Sie während des Schwenks, seinen Inhalt zu enthüllen, damit der Bildschirm während der Bewegung nie leer ist.
• Jedes sichtbare Ereignis erhält einen Sound in sfx(add). Tasten erhalten key, fliegende Pakete erhalten whoosh*, Ankünfte erhalten thunk oder pop, Erfolg erhält chime oder success. Dies trägt wesentlich dazu bei, dass das Video fertig wirkt.

6. Vorschau ohne Stimme, Frames prüfen

node SCRIPTS/shots.js <project>            # Mitte jeder Szene, gespeichert in einem neuen .shots/<time>/ Ordner

Sehen Sie sich jeden Screenshot an. Verkleinern Sie vor dem Lesen (sips -Z 960 auf macOS, ffmpeg -i in.png -vf scale=960:-1 out.png woanders). Prüfen Sie auf:

• Text, der überlappt oder über die Ränder läuft
• leere Frames während Schwenks
• Elemente, die über Dingen gezeichnet sind, hinter denen sie sitzen sollten

Korrigieren und neu schießen. Wenn die Seite nicht startet, gibt das Skript die Seitenfehler aus.

7. Sprache

Eingebaute Stimme (ohne --voice):

$PY SCRIPTS/narrate.py --script <project>/script.json --out <project>/narration --takes 2

Eine gespeicherte Stimme: --voice <UTH_HOME>/voices/<name>.wav hinzufügen.

Eine neue Stimme aus einer Aufnahme: Befolgen Sie ${CLAUDE_SKILL_DIR}/references/voice.md. Es behandelt prep_voice.sh, eine kurze Testzeile und die Einwilligung. Klonen Sie nur die eigene Stimme des Benutzers oder eine Stimme, für die er bestätigt hat, die Einwilligung zur Nutzung zu haben.

Lassen Sie den Benutzer dann zuhören: <project>/narration/narration-preview_take1.wav (open auf macOS, xdg-open auf Linux).

• Der erste Durchlauf lädt etwa 1 GB Modellgewichte herunter. Danach läuft es etwa in Echtzeit auf Apple Silicon oder einer GPU, langsamer auf CPU.
• Sie können kein Audio hören. Sagen Sie dem Benutzer das und bitten Sie ihn, die Takes mit dem Gehör zu beurteilen. Sie können Takes Zeile für Zeile mischen. Wiederholen Sie eine einzelne Zeile mit --only <id>.
• Turbo unterstützt Tags wie [chuckle], [laugh], [sigh], [gasp] und [surprised]. Verwenden Sie maximal ein oder zwei pro Video.

Keine Erzählung: Überspringen Sie diesen Schritt und build_timeline.py. Szenen behalten ihre Design-Dauern, und das Video erhält nur Musik und Soundeffekte.

8. Timeline, Rendern, Überprüfen

python3 SCRIPTS/build_timeline.py <project> [--pick dns=2,enter=2]
node SCRIPTS/render.js <project> [--music-db -12] [--sfx-db 1] [--silent] [--audio-only]

render.js baut die Sprach-, Musik- und SFX-Stems und mischt sie, wobei die Musik unter der Sprache geduckt und auf -16 LUFS normalisiert wird. Es rendert in <slug>.partial.mp4 und benennt es erst in <slug>.mp4 um, nachdem ffprobe die volle Länge bestätigt hat.

Bevor Sie dem Benutzer sagen, dass es fertig ist, überprüfen Sie die tatsächliche Datei:

• ffprobe zeigt die erwartete Dauer sowie Video- und Audiostreams an
• ffmpeg -ss <späte Zeit> -frames:v 1 zeigt die richtige Szene
• die Lautstärke liegt bei etwa -16 LUFS

Öffnen Sie dann die MP4 und die Vorschau index.html. Die Vorschau spielt den Mix synchron ab, mit Kapiteln und Scrubbing.

Berichten Sie klar, was überprüft wurde, was Sie nicht überprüfen konnten (wie das Audio klingt) und welche Teile vereinfacht sind.

Arbeitsregeln

• Keine Glob-Löschungen. Führen Sie kein rm mit Wildcards oder rm -rf auf Projektordnern aus. Neue Ausgaben gehen in neue Ordner, Dateien werden namentlich überschrieben.
• Ein gestoppter Befehl kann teilweise ausgeführt worden sein. Wenn der Benutzer einen mehrstufigen Befehl stoppt, überprüfen Sie, was sich auf der Festplatte geändert hat, bevor Sie fortfahren, und informieren Sie ihn über etwaige Teileffekte. Ein halb ausgetauschter Satz Clips kann ein kurzes teilweises Video hinterlassen, das fertig aussieht.
• Nicht automatisch auf Präferenzhinweise umschalten. Wenn der Benutzer sagt „Ich mag Take 2", während er sich noch entscheidet, bestätigen Sie, bevor Sie neu rendern.
• Anbieten, nicht bauen: eine vertikale Version 9:16, kürzen auf 30 Sekunden oder mehr Feinschliff. Erwähnen Sie sie jeweils in einer Zeile.

Fehlerbehebung

• „'NoneType' object is not callable" bei PerthImplicitWatermarker: führen Sie uv pip install --python $PY "setuptools<81" aus. Die Wasserzeichenbibliothek von Chatterbox benötigt pkg_resources.
• Der erste TTS-Durchlauf ist langsam: Das ist das Aufwärmen und der Modell-Download. Spätere Durchläufe sind schneller.
• Musik zu laut oder leise: --music-db (Standard -12). Effekte: --sfx-db (Standard 1). Verwenden Sie --audio-only, um den Mix schnell zu iterieren.
• Chrome nicht gefunden: Setzen Sie CHROME_PATH, oder laden Sie den Skill under-the-hood-setup.
• Das Offline-Audio von Chrome ist von Lauf zu Lauf nicht bit-identisch, daher unterscheiden sich die Stems zwischen den Renderings leicht. Das Timing ist exakt und die Frames sind pixelidentisch.