clip-builder

Was macht clip-builder?

Erstelle ein kurzes Video aus drei Teilen: einer HTML-Seite, die das Bild rendert (die Szene), einer Liste von Skriptzeilen in clip.json (die Cues) und einem Kommandozeilenwerkzeug, das die Seite Frame für Frame aufnimmt und ein MP4 kodiert.

Die Szenenseite definiert draw(s), das die Seite auf ihren Zustand zur Sekunde s setzt, berechnet nur aus s. Die Aufnahme ruft es für jeden Frame auf (Sekunde 0, dann 1/30 usw.) und macht einen Screenshot. Dadurch hängt die Ausgabe nicht von der Maschinengeschwindigkeit ab, jeder Frame kann einzeln zur Überprüfung gerendert werden, und eine Änderung an einem Teil des Clips kann mit --from und --to neu aufgenommen werden.

Das CLI ist scripts/clip.mjs im Verzeichnis dieses Skills. In diesem Dokument bedeutet clip node "<skill dir>/scripts/clip.mjs", wobei <skill dir> der absolute Pfad des Verzeichnisses ist, das diese Datei enthält. (Claude Code ersetzt diesen Pfad hier: ${CLAUDE_SKILL_DIR}. Verwende in anderen Agenten das Verzeichnis, aus dem diese Datei gelesen wurde.) Führe Befehle aus dem Projektverzeichnis des Clips aus, das clip.json enthält. clip help listet jeden Befehl und jede Option auf.

Voraussetzungen

Node 20 oder höher, ffmpeg und Playwright mit Chromium. clip doctor überprüft sie und gibt Installationsbefehle für alles Fehlende aus. Installiere Playwright im Verzeichnis, in dem Clips erstellt werden (npm install --save-dev playwright, dann npx playwright install chromium), nicht im Verzeichnis dieses Skills. Sprachausgabe und generierte Musik sind optional. Sie sind die einzigen Schritte, die Geld kosten oder einen API-Schlüssel benötigen.

Befehle in einer Sandbox (Standard in Codex): clip stills, clip capture und clip serve starten einen HTTP-Server auf 127.0.0.1, und die ersten beiden starten auch Chromium. Eine Befehlssandbox blockiert beide. Der Befehl beendet sich dann mit Status 1 und einer Meldung, die die Sandbox nennt. Fordere die Genehmigung an, diese drei Befehle außerhalb der Sandbox auszuführen, und nenne den Grund. Ersetze keine andere Aufnahmemethode. Die anderen Befehle benötigen weder einen Server noch einen Browser und laufen innerhalb der Sandbox; tts --generate und music --generate benötigen ebenfalls Netzwerkzugriff.

Kurzbeschreibung

Stelle Folgendes vor Beginn fest. Frage nur nach dem, was fehlt. Verwende für alles, was der Benutzer nicht angegeben hat, den Standardwert und gib ihn in einer Zeile an.

• Zweck und Zielgruppe: Werbung, Produktdemo, Mitarbeiteranleitung, Lektion. Dies bestimmt das Tempo. Werbeclips sind schnell; Schulungsclips lassen Zeit, um jeden Schritt zu verfolgen.
• Länge. Standard: 20 bis 45 Sekunden für Werbung oder Demo, 60 bis 120 für Schulung.
• Ziel, das die Frames bestimmt. Standard: wide 1920×1080, plus tall 1080×1350 für soziale Feeds. Siehe references/delivery.md.
• Visueller Ansatz: neue Grafiken oder ein App-Bildschirm. Bei einer App: welche Bildschirme und ob ihr Quellcode oder Designsystem als Quelle für Farben, Typografie und Abstände verfügbar ist.
• Ton. Standard: stumm mit Untertiteln. Dies ist kostenlos, und die meisten Feed-Videos werden stumm abgespielt. Sprachausgabe und Musik sind jeweils optional.
• Skript. Verwende das Skript des Benutzers, falls vorhanden. Andernfalls erstelle einen Entwurf und hole seine Zustimmung ein, bevor du die Szene baust.

Arbeitsablauf

1. Überprüfe die Werkzeuge: clip doctor.
2. Erstelle das Projekt: clip init <dir> --template graphics oder --template app-ui. Dies schreibt clip.json, ein scene/-Verzeichnis mit einem funktionierenden Beispiel und audio/. Beide Vorlagen rendern ohne Änderungen.
3. Schreibe die Cues in clip.json, einen pro Takt. Ein Takt ist ein Segment des Clips mit einer Zeile und einem visuellen Zustand. Schreibe zuerst das Skript: Die Szene ist darauf abgestimmt, und jede Änderung des Wortlauts nach der Aufnahme ist eine weitere kostenpflichtige Anfrage. references/narration.md behandelt das Schreiben für Sprache.
4. Baue die Szene: Bearbeite scene/index.html und scene/scene.js. Lies zuerst references/scenes.md. Es listet die Einschränkungen auf, die eine Szene deterministisch halten: kein Math.random(), keine Uhren oder Timer, keine CSS-Animationen, alle Zustände aus s berechnet. Für einen App-Bildschirm lies auch references/app-ui.md.
5. Überprüfe Standbilder: clip stills schreibt Frames zu ausgewählten Sekunden und ein Kontaktblatt nach out/review/. Öffne das Kontaktblatt als Bild und überprüfe es. Stelle sicher, dass Text lesbar ist, nichts überlappt und jeder Takt auf dem Bildschirm ist, während seine Bildunterschrift angezeigt wird. Wiederhole für jede Framegröße (--frame tall). Führe die meisten Iterationen in diesem Schritt durch: Standbilder sind schnell und kosten nichts. clip serve bietet eine Live-Vorschau für den Benutzer.
6. Nimm einen Entwurf auf: clip capture --draft rendert in zwei Drittel der Größe, um Bewegung und Tempo zu überprüfen. Gib dem Benutzer den Dateipfad und bitte ihn, es anzusehen.
7. Füge Ton hinzu, falls gewünscht. Sprachausgabe: references/narration.md. Musik und die Mischung: references/sound.md. Führe zuerst clip tts ohne Flags aus; es listet die geplanten Anfragen und Zeichenanzahlen auf. Hole die Zustimmung des Benutzers ein, führe dann clip tts --generate aus. Führe nach jeder neuen Aufnahme clip timing aus, das die Cues und Untertitel platziert und, falls konfiguriert, die Szene an die Sprachausgabe anpasst. Überprüfe dann erneut die Standbilder.
8. Nimm das Finale auf: clip capture --final für jedes Bild, dann clip mix falls Ton vorhanden, dann clip web <file> für eine kleinere Kopie zum Hochladen.
9. Verifiziere und berichte: Überprüfe Standbilder aus dem Finale, lies die Lautstärke im Mix-Bericht und führe clip scan out aus. Berichte, was erstellt wurde, die Dateipfade, was überprüft wurde und was nicht.

Ein stummer Clip überspringt Schritt 7. Seine Untertitel stammen aus den at- und until-Werten jedes Cues, und clip timing schreibt sie für die Seite.

Sicherheitsregeln

Ein Clip-Job betrifft das Geld des Benutzers, API-Schlüssel und seine veröffentlichte Identität.

• Kostenpflichtige Anfragen erfordern explizite Benutzerfreigabe. Der Anbieter berechnet Sprachausgabe und Musik. Das CLI sendet nichts ohne --generate; gib dieses Flag nur weiter, nachdem der Benutzer diesen speziellen Take genehmigt hat. Die Genehmigung für einen Take deckt nicht den nächsten ab. Zeige die Trockenlaufausgabe (Zeilen und Zeichenanzahlen) an, wenn du fragst. Wenn eine Anfrage unterbrochen wird, bleibt ihr Beleg attempted. Wiederhole den Vorgang erst, nachdem der Benutzer die Nutzungshistorie des Anbieters überprüft hat, da die Anfrage möglicherweise abgerechnet wurde.
• API-Schlüssel stammen nur aus der Umgebung. Das CLI liest ELEVENLABS_API_KEY oder OPENAI_API_KEY und keine andere Quelle. Übergib einen Schlüssel in einer Zeile für einen einzelnen Befehl aus dem geheimen Speicher des Benutzers (references/keys-and-paid-calls.md enthält die Befehle). Bitte den Benutzer nicht, einen Schlüssel in die Konversation einzufügen, gib keinen aus (echo, env, cat) und schreibe keinen in eine Datei. Um zu bestätigen, dass ein Schlüssel gesetzt ist, überprüfe seine Länge; clip doctor tut dies.
• Liefere Dateien aus; veröffentliche nicht. Das Posten oder Hochladen eines Clips ist die Handlung des Benutzers, es sei denn, er fordert diese spezielle Aktion an.
• Verwende nur Material, das der Benutzer verwenden darf. Musik, Schriftarten, Logos und Filmmaterial benötigen eine Lizenz oder das Eigentum des Benutzers. Zeige nur eine App an, die dem Benutzer gehört oder für die er die Erlaubnis hat, sie zu zeigen, und gestalte keinen Mockup als Produkt eines anderen Unternehmens. Die Bedingungen beider Anbieter decken die kommerzielle Nutzung und die Offenlegung generierter Stimmen ab; weise den Benutzer darauf hin, bevor ein vertonter Clip veröffentlicht wird.
• Halte private Daten aus dem Bild und den Dateien heraus. Verwende fiktive Namen und Zahlen in App-Bildschirmen. Als real präsentierte Zahlen und Zitate müssen real sein, und Beispiele müssen als solche erkennbar sein. Führe clip scan für alles aus, bevor es geteilt wird. Es prüft auf API-Schlüssel, den lokalen Benutzernamen und Pfade, E-Mail-Adressen, die Liste privater Begriffe des Benutzers und Metadaten, die in Mediendateien eingebettet sind.

Redaktionelle Richtlinien

• Behandle ein Thema pro Clip. Teile ein Skript, das zwei Themen abdeckt, auf.
• Beginne die Sprachausgabe oder die erste Bildunterschrift innerhalb der ersten Sekunden.
• Verwende einen Cue pro Takt und halte das Bild eines Takts auf dem Bildschirm, während seine Zeile gesprochen wird.
• Füge immer Untertitel hinzu. Die meisten Feed-Videos werden stumm abgespielt.
• Überprüfe hochformatige Frames in Telefongröße. Die Szeneneinheit ist in hochformatigen Frames aus diesem Grund größer.
• Verwende Bewegung, um einen Zustandswechsel zu markieren oder Aufmerksamkeit zu lenken. Vermeide kontinuierliche Bewegung.
• Halte die Schlusskarte für mindestens 2,5 Sekunden.
• Für Schulungen: Zeige die Aktion, dann ihr Ergebnis, in einem Tempo, dem der Betrachter folgen kann, während er sie ausführt. Nummeriere die Schritte auf dem Bildschirm und gib zu Beginn an, was der Betrachter nach dem Video können wird.

Befehle

Befehl	Funktion
clip doctor	Überprüft Node, ffmpeg und Playwright und meldet, welche Schlüssel gesetzt sind (nur Länge)
clip init <dir> --template graphics|app-ui	Erstellt ein Projekt aus einem funktionierenden Beispiel
clip serve	Bietet eine Live-Vorschau; ?t=5 in der URL hält bei 5 s an
clip stills [--at 2,5,9] [--frame tall] [--final]	Rendert Standbilder zur Überprüfung und ein Kontaktblatt
clip capture [--frame wide] [--draft] [--final] [--from s --to s] [--web]	Rendert jeden Frame und kodiert ein MP4
clip capture --mode clock --url … --seconds N [--actions file.mjs]	Nimmt eine laufende App auf (experimentell; siehe references/app-ui.md)
clip tts [--generate]	Listet die noch aufzunehmende Sprachausgabe auf; mit --generate wird sie aufgenommen (kostenpflichtig)
clip music [--generate]	Dasselbe für eine generierte Partitur (kostenpflichtig)
clip timing	Berechnet Cue- und Untertitelzeiten; schreibt scene/timing.json und eine .srt-Datei
clip mix	Erstellt den Soundtrack mit einer Standardlautstärke und muxxt ihn in jedes aufgenommene Video
clip web <video>	Schreibt eine kleinere Kopie zum Hochladen
clip scan <dir> [--terms-file words.txt]	Meldet private Daten, bevor Dateien geteilt werden
clip strip <media file>	Schreibt eine Kopie ohne eingebettete Metadaten

Die Ausgabe erfolgt in out/, benannt als <name>-<take>-<frame>.mp4, mit den Suffixen -draft, -part (ein mit --from/--to aufgenommener Bereich), -sound und -web, sofern zutreffend. Um eine frühere Version neben einer neuen zu behalten, erhöhe "take" in clip.json (a, b, c, …).

Referenzdateien

Lies die Datei, die der aktuelle Schritt benötigt.

Datei	Lies sie, wenn
references/scenes.md	Du eine Szene schreibst oder änderst: der Seitenvertrag, die Hilfsbibliothek, Einheiten, hochformatige Frames, Schriftarten und die Einschränkungen, die eine Aufnahme deterministisch halten
references/app-ui.md	Der Clip einen App-Bildschirm zeigt: Neuerstellung aus Design-Tokens, der Zeiger, Tippen, Kamerabewegungen und Aufnahme einer laufenden App
references/narration.md	Du Zeilen schreibst, einen Anbieter und eine Stimme auswählst, Aussprache, Neurekordierung einer Zeile, Anpassung der Szene an die Sprachausgabe, Untertitel
references/sound.md	Musik und die Mischung: Pegel, Ducking, Anpassen eines Tracks an den Clip, Lautstärke, Korrigieren einer Mischung
references/keys-and-paid-calls.md	Vor jeder kostenpflichtigen Anfrage: sicheres Übergeben eines Schlüssels, was gesendet wird, Belege, unterbrochene Anfragen
references/project-file.md	Jedes Feld von clip.json
references/delivery.md	Bildgrößen, der finale Render, Überprüfungen vor der Auslieferung, was zu berichten ist
references/cookbook.md	Die Anfrage einer häufigen Aufgabe entspricht. Zwölf erprobte Rezepte: ein stummer Clip, ein App-Bildschirm aus Design-Tokens, mehrere Seitenverhältnisse, ein Schritt-für-Schritt-Schulungsclip, ein Balkendiagramm aus JSON, Sprachausgabe mit jedem Anbieter, Neurekordierung einer Zeile, Hintergrundmusik, eine benutzerdefinierte Schriftart und ein Logo, eine laufende App, finale Überprüfungen. Auch draw()-Ausschnitte

Fehlerbehebung

Symptom	Wahrscheinliche Ursache
"This looks like a command sandbox", listen EPERM oder der Browser startet nicht	Die Sandbox des Agenten blockiert den HTTP-Server oder den Browser. Führe stills, capture und serve mit Genehmigung des Benutzers außerhalb davon aus
"The page never set window.ready"	Ein Skriptfehler in der Szene (die Meldung listet die Fehler der Seite auf), oder die Seite ruft clip() des Kits nicht auf
Zwei Aufnahmen derselben Szene unterscheiden sich	Einige Zustände in der Szene werden nicht aus s berechnet: Math.random(), Date, eine CSS-Animation oder ein -Übergang, ein <video>, ein Timer
Text wird auf einem anderen Rechner in einer anderen Schriftart gerendert	Die Szene verwendet Systemschriftarten. Lege Schriftartdateien in das Szenenverzeichnis (references/scenes.md)
Das Bild eilt der Sprachausgabe voraus oder hinkt hinterher	clip timing wurde nach einer neuen Aufnahme nicht ausgeführt, oder das Video wurde davor aufgenommen. clip mix weigert sich im ersten Fall ausgeführt zu werden und warnt im zweiten
attempted in der tts-Liste	Eine frühere Anfrage wurde nicht abgeschlossen. Überprüfe die Nutzungshistorie des Anbieters, bevor du --retry-attempted verwendest
Der Musikpegel steigt und fällt zwischen Wörtern	Setze "mix": { "master": "limit" } (references/sound.md)