capcut-cli — CapCut/JianYing Draft-Ship

capcut-edit

CLI zum Bearbeiten von CapCut / JianYing-Entwürfen durch einen versionsbewussten Speicher. v0.11 erkennt und synchronisiert lesbare Zeitachsen über draft_content.json, draft_info.json, draft_meta_info.json und template-2.tmp.

Projektverzeichnisse

• macOS: ~/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project>/
• Windows: %LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\

Kernprinzip — deterministische Skripte

Jedes Rezept, das mehr als einen capcut-Aufruf, Arithmetik oder Verzweigungen umfasst, wird als parametrisiertes Shell-Skript in scripts/ ausgeliefert. Claude ruft das Skript mit Eingaben auf; das Skript führt eine feste Sequenz aus. Wenn ein Rezept als Skript umgesetzt werden kann, muss es ein Skript sein — keine Erzählung in references/.

references/workflows.md dokumentiert welches Skript aufzurufen ist und warum, niemals eine rekonstruierbare Sequenz.

Progressive Offenlegung

Beginnen Sie allgemein, tauchen Sie dann in das ein, was Sie benötigen. Geben Sie niemals das vollständige Projekt-JSON aus.

capcut info <project> -H           # Übersicht
capcut doctor -H                   # Installierte Medien-/Transkriptionsfähigkeiten
capcut diagnose <project> -H       # Kanonische Dateien, Abweichungen, Editorsicherheit
capcut tracks <project> -H         # Alle Spuren
capcut materials <project> -H      # Materialzusammenfassung
capcut segments <project> -H       # Segmente mit Zeitangaben
capcut segment <project> <id>      # Ein Element, vollständige Details

Ausgabemodi

• JSON (Standard): an jq weiterleiten, an Skripte übergeben.
• -H: menschenlesbare Tabellen.
• -q: leise, nur Exit-Code — für Schreibbefehle in Skripten.

Batch-Schreibvorgänge

echo '{"cmd":"set-text","id":"a1b2c3","text":"Fixed"}
{"cmd":"volume","id":"d4e5f6","volume":0.5}' | capcut batch <project>

Operationen: set-text, shift, shift-all, speed, volume, opacity, trim.

Batch ist transaktional: Ein fehlschlagender Vorgang schreibt nichts. Verwenden Sie --continue-on-error nur, wenn der Benutzer explizit einen teilweisen Commit akzeptiert; es wird dennoch mit einem Fehler beendet.

Wo nachschlagen

• references/api-reference.md — jeder Befehl, jede Flagge, jedes Werteformat (Zeit, Prozent, Grad), die ID-Präfix-Regel, die .bak-Invariante.
• ../../docs/command-reference.md — generierter Befehl-Vertrag v2 mit typisierten Positions-/Optionsparametern, Veränderbarkeit, Voraussetzungen, Ausgabeform und Exit-Codes.
• references/workflows.md — Rezepte = welches scripts/X.sh ausgeführt wird und warum.
• references/pitfalls.md — Projekt-zuerst-schließen, .bak, clip=null bei Audio, source_timerange-Berechnung mit speed, Alpha-Keyframes-rendern-nicht-Animationsmaterialien-verwenden, usw.
• Aufzählungsermittlung — Rufen Sie capcut enums --<category> (oder -H für eine Tabelle) auf, um jeden CapCut-Slug aufzulisten. Kategorien: --transitions, --masks, --image-intros, --image-outros, --image-combos, --text-intros, --text-outros, --text-loop-anims, --scene-effects, --character-effects, --audio-effects, --fonts. Fügen Sie --jianying hinzu, um den Namensraum zu wechseln. Das enums.json-Bundle wird einmalig über python3 scripts/extract-enums.py generiert; zur Laufzeit ist kein Python erforderlich.
• scripts/ — die Client-Bibliothek. Aktuell:
  • anim.sh — jede der 9 CapCut-Intro/Outro-Animationen anhängen; fade-in.sh und fade-out.sh sind dünne Wrapper.
  • ken-burns.sh — Skalierungs- + Schwenk-Keyframes über capcut keyframe --batch (Bewegungseigenschaften werden gerendert; Alpha nicht — stattdessen anim.sh fade-in verwenden).
  • long-to-short.sh — einen Bereich schneiden, Titel + CTA-Text einfügen.
  • stamp-cta.sh — eine gespeicherte Textvorlage anwenden (siehe assets/examples/subscribe-cta.json).
  • _test.sh — jeden Wrapper gegen die Testumgebung ausführen; nach jeder Änderung hier ausführen.
• assets/examples/ — rohe JSON-Ausschnitte zur manuellen Bearbeitung.

Invarianten

• Schließen Sie das Projekt in CapCut vor der Bearbeitung; nach der Bearbeitung wieder öffnen.
• Jeder Schreibvorgang wird auf Konflikte geprüft, atomar vorbereitet und mit jedem lesbaren Zeitachsen-Ziel synchronisiert. Jedes Ziel erhält .bak und fortlaufende Verlaufs-Schnappschüsse.
• Verwenden Sie --force-write nur, wenn der Benutzer explizit das Überschreiben des geänderten Zustands auf der Festplatte oder eines geöffneten Editors akzeptiert.
• clip ist bei Audiosegmenten null (keine Deckkraft/Skalierung).
• capcut cut schreibt in --out, ändert die Quelle nie.
• IDs: Die ersten 6+ Zeichen der UUID stimmen als Präfix überein.
• Zeitformate: 1.5s, 500ms, +0.5s, -1s, 1:30, 0:05.5, bloße Zahl = Sekunden.

v0.11 Hochwert-Pfade

• Ganzer Entwurf: capcut compile spec.json --check, dann capcut compile spec.json --out <dir>. Spezifikationen unterstützen Referenzen, Transformationen, Dekorateure, Vorlagen, Untertitel, Keyframes und Überblendungen.
• Karaoke: capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke.
• Proxy: capcut render <project> --all-video-tracks --burn-captions; führen Sie zuerst doctor für FFmpeg-Fähigkeitsflags aus.
• Automatisierung: capcut serve --workers N --retries N --timeout MS; geben Sie Jobs stabile id-Felder und lassen Sie den Runner Schreibvorgänge pro Projekt serialisieren.
• Agent-Schema: capcut describe ist die Quelle der Wahrheit. Keinen Hilfetext extrahieren oder Flags erfinden.