talking-clip

Was macht talking-clip?

Ein Clip besteht aus vier Schritten: Zeile schreiben, Stimme erzeugen, Aktion planen, bauen und rendern. Ausgabe: Ein HyperFrames-Projekt und eine MP4-Datei (Standard 1080x1920, vertikal).

1. line    Du schreibst sie, in der Stimme des Charakters
2. voice   scripts/tts.py          (ElevenLabs kostet Credits; say und none sind kostenlos)
3. plan    Du schreibst plan.json   (Gesten und Ausdrücke auf den Wörtern)
4. video   scripts/build_clip.py -> scripts/verify.py -> scripts/render.py

Pfade sind relativ zum Wurzelverzeichnis 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): Lies hyperframes einmal, bevor du eine Komposition von Hand bearbeitest.

0. Preflight (immer zuerst)

Führe python3 scripts/setup.py doctor aus (füge --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 Code 1, wenn eine erforderliche Komponente fehlt.

• Erforderlich fehlend (ffmpeg, Node.js 18+, die HyperFrames-Skills und der ElevenLabs-Schlüssel oder say, wenn diese Stimme konfiguriert ist): Sage dem Benutzer in einem Satz, wofür jede ist, und schlage den gedruckten Befehl vor. Führe ihn erst aus, nachdem der Benutzer ja gesagt hat. Gib niemals selbst einen API-Schlüssel ein oder frage danach: Sage dem Benutzer, er solle ELEVENLABS_API_KEY in seiner Shell exportieren.
• Optional fehlend: Biete sie einmal an und sage, was jede freischaltet. Playwright ermöglicht Web-Aufnahmen mit Element-Zoom-Boxen und Ganzseiten-Screenshots, Tesseract (OCR) ermöglicht den Secrets-Scan auf Screenshots und ASR (mlx-whisper / openai-whisper) ermöglicht den Audio-Check und exakte Wortzeitangaben. Überspringe 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 sie fehlen, empfehle npx hyperframes skills. Lies hyperframes (und hyperframes-cli bei Render-Problemen), bevor du eine Komposition baust oder bearbeitest.

Einrichtung (erster Lauf oder wenn der Benutzer etwas ändern möchte)

Suche nach einer Konfiguration: python3 scripts/setup.py show. Wenn es keine gibt, oder der Benutzer darum bittet, seinen Charakter, seine Stimme, das Rendern oder die Stile zu ändern, interviewe ihn (eine kurze Frage nach der anderen, biete den Standard an) und schreibe sie dann mit Flags:

Frage	Flag	Optionen
Welche Teile?	--features	character, explainer oder beide
Welcher Charakter?	--character	das gebündelte Beispiel (pkg:characters/host/character.json) oder ein Pfad zu seinem (absolut gespeichert)
Erzählsprache	--language	ISO-Code; mit say wird eine klare Stimme dafür ausgewählt (setup.py voices --lang <code> listet sie, --say-voice überschreibt)
Welche Stimme?	--voice	elevenlabs (ihr Schlüssel in ELEVENLABS_API_KEY, ihre --voice-id), say (macOS, kostenlos), none
Credit-Grenzen (ElevenLabs)	--max-chars, --max-seconds, --daily-credit-cap	Zahlen, die sie wählen; leer = keine Grenze
Wie rendern?	--render	local (kostenlos, diese Maschine), cloud (HyperFrames-Cloud, benötigt npx hyperframes auth login), preview (nur Studio)
Größe	--size	1080x1920, 1920x1080, 1080x1080

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

init führt zuerst den Doctor aus und bietet dieselben Installationen an. Wenn bereits eine Konfiguration existiert, fragt es nach, bevor es überschreibt, oder benötigt --force, wenn es nicht interaktiv ist.

Eigener Charakter des Benutzers: python3 scripts/setup.py new-character --name "<name>" --out ./characters/<name> --activate Kopiert das Beispiel und macht es aktiv (kein zweites init). Hilf ihnen dann, die Schlüssel auszufüllen, die es ausgibt: description, personality, speaking_style.rules, rig.colors (oder Sprites), expressions / poses / gestures, set, voice_moods.

Frage niemals nach dem API-Schlüssel, drucke ihn nicht aus und schreibe ihn nicht. Wenn ELEVENLABS_API_KEY fehlt, sage dem Benutzer, er solle ihn in seiner Shell exportieren. Das Konfigurationsschema befindet sich in config/config.schema.json; das Charakterdateiformat befindet sich in der README („Your own character“).

Wähle einen Stil für diesen Clip

Es gibt kein Haus-Look. Wähle für jeden Clip den Stil basierend auf Thema, Zielgruppe und der Marke oder dem Geschmack des Benutzers: das Set ({"type": "color"|"gradient"|"image", ...}), die Rahmung (close, medium, wide) und die Bewegungsintensität (calm, normal, lively). Frage den Benutzer, wenn die Wahl wichtig ist, zum Beispiel wenn der Clip für eine Marke, einen öffentlichen Kanal oder eine Serie ist. Variiere den Stil zwischen den Clips, anstatt den letzten zu wiederholen. Wenn die Konfiguration ein brand-Kit enthält, überschreibt dessen background deine Wahl. Schreibe es in eine Datei und übergib --style:

{"set": {"type": "gradient", "colors": ["#FFF4E6", "#FFD9B3"]}, "framing": "medium", "motion": "lively"}

Das Gleiche gilt für die Wörter: Passe den Ton an das Publikum an, bleibe dabei innerhalb der Persönlichkeit des Charakters und verwende nicht denselben Eröffnungs- oder Schlusssatz von einem Clip zum nächsten.

1. Schreibe die Zeile

Lies die in der Konfiguration genannte Charakterdatei (character-Schlüssel): personality und speaking_style.rules sind die Stimme. Folge ihnen; die Anfrage des Benutzers gewinnt, wenn es einen Konflikt gibt.

• Länge: höchstens styles.talking_clip.max_seconds. Bei speaking_style.chars_per_second (ca. 14) ist ein 20-Sekunden-Clip unter ~260 Zeichen. Eine Idee, ein Schlusssatz.
• Sprache: die des Benutzers, es sei denn, er wünscht etwas anderes.
• ElevenLabs-Modelle mit Audio-Tags (v3 und später) akzeptieren Emotions-Tags in Englisch in eckigen Klammern vor den Wörtern, die sie einfärben: [excited], [calm], [whispers], [laughs], [pause]. say und none ignorieren sie (sie werden entfernt); spiele sie stattdessen mit Gesten.

2. Erzeuge die Stimme

python3 scripts/tts.py estimate --text "<line>" --max-seconds 20
python3 scripts/tts.py speak --text "<line>" --out out/voice.wav [--mood excited] [--confirm]

• ElevenLabs: Führe immer zuerst estimate aus und teile dem Benutzer die Kosten mit; speak verweigert ohne --confirm und verweigert, wenn eine vom Benutzer gesetzte Grenze (max. Zeichen, max. Sekunden, tägliches Kreditlimit) überschritten würde. --takes 2 erstellt Alternativen. Wortzeitangaben landen in out/voice.wav.words.json.
• --mood wählt eine Stimmung aus den voice_moods des Charakters (ElevenLabs-Einstellungen + optionaler ffmpeg-Filter).
• say / none: kostenlos. Mit none gibt es kein Audio; übergib stattdessen --text an den Builder.

3. Plane die Aktion

python3 scripts/timings.py out/voice.wav --text "<line>" liefert Wortstartzeiten. Schreibe plan.json:

{"expression": "neutral",
 "events": [{"t": 0.0, "gesture": "hello"},
            {"t": 2.1, "gesture": "explain", "dur": 2.5},
            {"t": 5.0, "expression": "happy"},
            {"t": 6.2, "gesture": "wink"}]}

• gesture- und expression-IDs stammen aus der Charakterdatei (gestures, expressions); jede Geste hat eine Beschreibung und eine typische dur. Lese sie, bevor du planst.
• Mundbewegungen, Blinzeln, Atmen und sanftes Wippen sind automatisch. Du setzt nur die Schauspiel-Betonungen.
• Platziere eine starke Geste 0,2-0,3 s vor dem Wort, zu dem sie gehört. Eine Reaktion pro Takt; niemals zwei Gesten in derselben Sekunde. Ende mit einer ruhigen, gehaltenen Geste (sie wird automatisch bis zum Ende gehalten).

4. Bauen, verifizieren, rendern

python3 scripts/build_clip.py --audio out/voice.wav --plan out/plan.json --style out/style.json --project out/clip
python3 scripts/render.py out/clip --out out/clip.mp4 --quality draft
python3 scripts/verify.py all --project out/clip --text "<line>" --video out/clip.mp4

Verifikation ist erforderlich (Details im „Verify“-Abschnitt des Explainer-Skills, gleiche Schleife): build muss sauber sein, render liefert ein Kontaktblatt, das du dir ansehen musst (Mundbewegungen, Gesten wie geplant, nichts abgeschnitten), audio überprüft die Wörter mit ASR und die Dauerbegrenzung. Korrigiere und führe ab der fehlgeschlagenen Stufe erneut aus. Jeder verify.py all-Lauf ist eine Iteration; bei verify.max_iterations wird mit Code 2 beendet und du teilst dem Benutzer mit, was immer noch fehlschlägt, anstatt es auszuliefern. render bleibt review, bis du dir das Kontaktblatt ansiehst und es mit verify.py mark render pass|fail --project out/clip --note "..." aufzeichnest, dann führe verify.py all erneut aus (ein Neubau macht die Markierung ungültig).

Rendere dann das Endergebnis mit dem konfigurierten Backend: python3 scripts/render.py out/clip --out out/clip.mp4 (render.max_mb komprimiert neu, um ein Upload-Limit einzuhalten). Übertrage niemals mp4- oder wav-Dateien.