/reel: Videoproduktion für Claude Code
Ein mehrschichtiges Tool, das auf ffmpeg aufbaut. Sie (Claude) sehen sich das Material an, entscheiden, was gezeigt werden soll, und schreiben einen Plan; der Code erledigt die Bildgeometrie, das Rendern und die Prüfungen. Die Ausgabegröße ist konfigurierbar (Standard Hochformat 1080x1920).
Befehle und Dateiformate sind in docs/ENGINE.md des reel-Repositorys dokumentiert. Lesen Sie es vor dem ersten Befehl: cat "$(reel --root)/docs/ENGINE.md". reel <command> --help listet alle Optionen auf. Jeder Befehl gibt ein JSON-Objekt aus ({"ok": true, "result": ...} oder {"ok": false, "error": {"code": ..., ...}}) und beendet sich bei Fehler mit Exit-Code 1.
Arbeitsreihenfolge: zuerst Regie, dann Schnitt
Für jedes Video, das jemand anderes als der Benutzer sehen wird, folgen Sie SOP.md: S0 Aufnahme, S1 Quellpaket, S2 Asset-Inventar, S3-S4: Ein director-Agent schreibt direction/BRIEF.md und ein Storyboard, dann sofort Schnitt (der Genehmigungsschritt G1 blockiert standardmäßig nicht), dann das Auslieferungsgate unten. Bei S7 überprüft ein separater director-Agent den Schnitt anhand des BRIEFs. Als Plugin installiert heißt der Agent reel:director.
- Geben Sie dem Regisseur die Pfade des Originalmaterials, nicht Ihre eigenen Schlussfolgerungen darüber.
- Wenn ein genehmigtes BRIEF existiert und sich Zweck, Zielgruppe und Materialumfang nicht geändert haben, folgen Sie ihm.
- Wenn der Benutzer sagt, das Video sei langweilig oder sinnlos, gehen Sie zurück zu S3 und überdenken Sie das Stück; führen Sie nicht nur einen Neuschnitt durch.
Auslieferungs-Gate (obligatorisch)
Jeder Schritt wird durch Code erzwungen: Überspringen Sie einen, können Sie keinen endgültigen Schnitt ausliefern.
- Schreiben Sie zuerst das Briefing (
$P/brief.json, Vorlage unten) und registrieren Sie es:reel register brief.json. Auslieferungssprache, endgültig oder Muster, Auslieferungsordner und was sich nicht ändern darf: Wenn Sie diese Angaben nicht ausfüllen können, fragen Sie den Benutzer. Nach der Registrierung verweigert der Bash-Guard-Hookcp/mv/ffmpeg-Schreibvorgänge in den Auslieferungsordner. - Hören Sie die Stimme an. Es gibt keine Standardstimme. Wählen Sie eine, die zum Briefing passt, rendern Sie eine 10–20 s lange Probe und führen Sie
reel voice check sample.mp3 --script sample.txt --brief brief.jsonaus. Lokales Whisper transkribiert die Probe und vergleicht sie mit dem Text (--langstandardmäßigen; für eine chinesische Sprachausgabe übergeben Sie--lang zh, was nach tonlosem Pinyin vergleicht, sodass homophone Schreibweise nicht als Fehler zählt); nur eine Fehlerrate von 10 % oder weniger schreibt die Genehmigung inbrief.voice.approved(by: claude, mit dem Transkript als Nachweis). Wenn der Benutzer zugehört hat, notieren Sie stattdessen seine genauen Worte.- STT beweist, dass die Wörter korrekt und deutlich gelesen werden. Es beweist nicht, dass die Stimme zum Stück passt: Sagen Sie in Ihrer Antwort, dass Sie die Stimme ausgewählt haben, und wechseln Sie die Stimme in der nächsten Version, wenn der Benutzer sie nicht mag.
- Eine neue Stimme benötigt eine neue Überprüfung. Die macOS
say-Stimme ist nur für interne Entwürfe, niemals für ein ausgeliefertes Video.
- Überprüfen Sie den Render:
reel check final.mp4 --plan plan.json --brief brief.json [--profile vertical-strict|project-profile.json] [--text caption.txt].- Exit-Code 1 bedeutet, dass es nicht ausgeliefert werden kann. Lesen Sie
result.gate.blockers(technische Fehler: selbst eine Probe kann nicht ausgeliefert werden) undresult.gate.pending_review(Punkte, die ein Prüfer ansehen muss). - Verlassen Sie sich nicht allein auf
ok.result.gate.not_coveredlistet auf, was nicht geprüft wurde (z. B. Bildschirmtext, für den es kein OCR gibt); sagen Sie niemals, dass diese Punkte geprüft wurden.
- Exit-Code 1 bedeutet, dass es nicht ausgeliefert werden kann. Lesen Sie
- Überprüfung. Sehen Sie sich jedes
needs_review-Element an (reel scrub, Frame-Abzüge) und schreiben Sie einen Überprüfungsdatensatz pro Element mit zeitcodierten Beobachtungen. Sehen Sie sich den gesamten Schnitt selbst an und unterschreiben Siefinal_watch(mindestens ein Frame pro Einstellung); hören Sie von Anfang bis Ende zu und unterschreiben Siefinal_listen(eine Agentenunterschrift benötigt zeitcodierte Beobachtungen; wenn der Benutzer zugehört hat, notieren Sie seine genauen Worte alsquote). Wenn Sie beide unterschrieben haben, liefern Sie es als endgültig aus: Die Quittung sagtapproved_by: agent, und Ihre Antwort sagt „Endschnitt, von Claude überprüft, noch nicht von Ihnen gesehen“. Das Feedback des Benutzers wird zur nächsten Version. Das Format vonreviews.jsonfinden Sie indocs/ENGINE.md. - Ausliefern:
reel deliver final.mp4 --brief brief.json --version v3 --plan plan.json --reviews reviews.json.- Wenn die endgültigen Bedingungen nicht erfüllt sind, schlägt es mit
DELIVERY_NOT_FINALfehl und listet die Gründe auf. Dann ist nur--samplemöglich: Der Dateiname trägtsample-pending-review, und Sie müssen es als Muster bezeichnen, wenn Sie es dem Benutzer mitteilen. - Eine Versionsnummer kann nur einmal ausgeliefert werden; alte Versionen werden niemals gelöscht oder überschrieben. Nur wenn der Benutzer ausdrücklich darum bittet, alte Versionen zu entfernen:
reel register brief.json --remove, löschen, dann erneut registrieren.
- Wenn die endgültigen Bedingungen nicht erfüllt sind, schlägt es mit
- „Fertig“ sagen erfordert eine Quittung mit
status: final(reel receipt <receipt.json>überprüft sie erneut). Andernfalls geben Sie den wahren Status an: „nicht fertig“, „Muster ausstehend“, „Stimme nicht geprüft“. Der Stop-Hook blockiert eine Behauptung der Fertigstellung ohne passende Quittung. - Videos, die durch das eigene Render-Skript eines Projekts (
build_*.pyund ähnliche) oder in einem anderen Tool erstellt und exportiert wurden, durchlaufen ebenfalls die Schritte 3–6.
{"version": "reel.brief.v1", "name": "spring-promo", "language": "en", "deliverable": "final",
"delivery_root": "~/Videos/deliveries/spring-promo", "must_not_change": ["end card credit"],
"voice": {"mode": "recorded"}, "profile": "default"}
voice.mode:none(keine Stimme),recorded(eine echte Aufnahme),ttsoderclone(diese beiden benötigen auchvoice_idund einen vonreel voice checkgeschriebenenapproved-Block oder eine menschliche Genehmigung mitquote,sampleundsample_sha256).delivery_rootmuss ein vorhandener absoluter Pfad sein (oder mit~beginnen). Es darf nicht das Home-Verzeichnis, Desktop, Dokumente, Downloads, das iCloud Drive-Root, der Projektordner oder ein darüber liegender Ordner sein.- Eine stumme Version verwendet ein Projektprofil:
{"extends": "default", "audio": "silent"}. - Profile:
default(allgemeine Starts chwellwerte) undvertical-strict(1080x1920 30 fps, -16 LUFS, streng). Projektunterschiede in ein Projektprofil mitextendsaufnehmen; beabsichtigte lange Halte inallowmit Grund eintragen; verbotene Wörter (alte Produktnamen, Fülltext) zutext.extra_bannedhinzufügen.
Zu Beginn jedes Bash-Aufrufs
Jeder Bash-Aufruf startet eine neue Shell, daher beginnen Sie jeden Aufruf mit:
REEL_PROJECT=spring-promo # Name dieses Projekts
command -v reel >/dev/null || { echo "reel ist nicht im PATH (Plugin aktivieren, oder ./install.sh --link ausführen)" >&2; return 1 2>/dev/null || exit 1; }
command -v ffmpeg >/dev/null || { echo "ffmpeg nicht gefunden" >&2; return 1 2>/dev/null || exit 1; }
P="${REEL_PROJECTS_DIR:-$HOME/reel-projects}/$REEL_PROJECT"; mkdir -p "$P/preview" && cd "$P"
Alle Ausgaben befinden sich in $P, niemals in einem temporären Ordner; relative Pfade unten sind relativ zu $P.
Schnitt erstellen
Sie treffen die Entscheidungen (welche Aufnahmen, welches Motiv, Kamerabewegungen, Tempo); Wahrnehmung, Geometrie, Rendering und Prüfungen werden vom Code erledigt. Die vollständige Befehlssyntax finden Sie in docs/ENGINE.md.
- Material in
$P(Assets,observations.json,plan.json, Vorschauen, Renderings und Prüfberichte befinden sich dort; ein Plan pro Ordner). - Skript und Stimme. Schreiben Sie das Voice-Over-Skript, wählen Sie eine Stimme, die zum Briefing passt, und bestehen Sie das Vorsprechen (Gate Schritt 2). Produzieren Sie
voice.mp3(oder.wav) und, falls Sie Untertitel wünschen,voice.vtt. Verwenden Sie für veröffentlichte Arbeiten bevorzugt eine echte Aufnahme oder eine Stimme, deren Lizenz die Verwendung abdeckt; für ein musikalisches Stück zeigen Sie mitaudio.voiceauf die Musikspur (sie ist der Timeline-Anker). - Anschauen und Ziele auswählen:
reel inspect(jede Datei auflisten) →reel frame(Bild mit dem 0-1-Raster lesen und die Box des Motivs ablesen) →reel observezum Registrieren, oderreel locate --query ... --check-png ...(OWLv2; schauen Sie sich das Prüfbild an, bevor Sie eine Erkennung verwenden). plan.jsonschreiben (EditPlan v1):camera: []hält das Bild still;zoom_tomit einerobservation_idzoomt auf ein registriertes Motiv; verwenden Sietrack, wenn sich das Motiv in einem Video bewegt;transition_outfür Übergänge. Lassen Sie keine Videoaufnahme einen voninspectgemeldeten Szenenwechsel kreuzen.audio.voiceist erforderlich und wird relativ zusrc_diraufgelöst.- Validieren und Vorschau:
reel validate→reel compile→reel preview plan.json s2 --out preview/s2.mp4 --sheet preview/s2.png, dann lesen Sie das Kontaktblatt, um die Kamerabewegung zu beurteilen. - Rendern:
reel render plan.json --out "$P/final.mp4" --sheet "$P/preview/final.png" --where local(verwenden Sie--where remotenur, wenn der Benutzer eine Remote-GPU konfiguriert hat und darum bittet). Das Bestehen der Render-Prüfungen bedeutet nur, dass die Datei nicht defekt ist; fahren Sie mit den Gate-Schritten 3–6 fort.
Andere Einstiegspunkte, jeder mit einem Abschnitt in docs/ENGINE.md:
- Timeline inspizieren und ändern:
reel timeline(--format textoder ein--png-Mehrspurbild),reel scrub(Frames um jeden Schnitt),reel edit/undo/history,reel preview --range(Vorschau mit niedriger Auflösung und Ton). - Zum Beat schneiden:
reel beats music.mp3 --out beats.json→reel snap plan.json --beats beats.json --mode downbeat; dann jeden Schnitt mitreel timeline --png --beatsüberprüfen. Erfordert./install.sh --beats. - Webseite mit Highlights erzählen: eine Aufnahme mit
kind: "web"; Textpositionen stammen aus dem DOM (kein OCR), daher muss ein hervorgehobener Satz exakt dem Seitentext entsprechen;reel words voice.mp3liefert die Wort-Zeitsteuerung. Erfordert./install.sh --web. - Shotcut-Projekte:
reel mlt project.mlt --video-only;--dupesfindet doppelt verwendetes Quellmaterial.
Verfügbar: Plan-Assemblierung, Sub-Pixel-Hineinzoomen auf ein Motivfeld, Verfolgung eines sich bewegenden Motivs, Xfade-Übergänge, eingebrannte Untertitel, Hintergrundmusik, Grading und LUTs, Web-Aufnahmen, OWLv2-Motivsuche, technische Prüfungen, gated-Auslieferung. Nicht eingebaut: Eased-Übergänge, Frame-Interpolation, Sprachklonung.
Remote-GPU (optional)
Die Teile mit --where remote werden durch Code erzwungen.
- Verwenden Sie es nur, wenn der Benutzer
REEL_REMOTE(ein SSH-Ziel) konfiguriert hat und darum bittet; andernfalls rendern Sie mit--where local. - Der VRAM-Verbrauch ist standardmäßig auf 80 % begrenzt. Wenn ein Job mehr benötigt, gibt das Tool
NEED_USER_APPROVALzurück: Informieren Sie zuerst den Benutzer und fügen Sie--allow-over-80nur mit seiner Zustimmung hinzu. Eine GPU-Auslastung von 50 % oder mehr bedeutet, dass jemand anderes sie verwendet; nehmen Sie sie nicht in Betrieb. - Ein reel-GPU-Job gleichzeitig (Remote-Dateisperre). Ändern Sie keine Energiegrenzwerte. Starten Sie den Host niemals neu oder fahren Sie ihn herunter.
reel remote probemeldet den Host;reel remote setup-visioninstalliert eine separate venv mit torch und den OWLv2-Gewichten auf dem Remote-Host.
Begleitdateien
SOP.md: Regie-erster-Workflow, Rollen, Schritte und Ausstiegsbedingungen.- Der
director-Agent (agents/director.mdim Repository): Briefing, Storyboard und Review. docs/ENGINE.mdim Repository: Befehle, EditPlan, Briefings, Reviews, Quittungen und Profile.