capcut-edit

CLI for editing CapCut / JianYing drafts through a version-aware store. v0.11 detects and synchronizes readable timelines across draft_content.json, draft_info.json, draft_meta_info.json, and template-2.tmp.

Project locations

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

Core principle — deterministic scripts

Any recipe involving more than one capcut call, any arithmetic, or any branching ships as a parameterised shell script in scripts/. Claude invokes the script with inputs; the script runs a fixed sequence. If a recipe can be a script, it must be a script — not a narrative in references/.

references/workflows.md documents which script to call and why, never a reconstructable sequence.

Progressive disclosure

Start broad, drill into what you need. Never dump full project JSON.

capcut info <project> -H           # overview
capcut doctor -H                   # installed media/transcription capabilities
capcut diagnose <project> -H       # canonical files, divergence, editor safety
capcut tracks <project> -H         # all tracks
capcut materials <project> -H      # material summary
capcut segments <project> -H       # segments with timing
capcut segment <project> <id>      # one item, full detail

Output modes

• JSON (default): pipe to jq, feed to scripts.
• -H: human-readable tables.
• -q: quiet, exit code only — for write commands in scripts.

Batch writes

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

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

Batch is transactional: one failing operation writes nothing. Use --continue-on-error only when the user explicitly accepts a partial commit; it still exits non-zero.

Where to look

• references/api-reference.md — every command, every flag, every value format (time, percentages, degrees), the ID-prefix rule, the .bak invariant.
• ../../docs/command-reference.md — generated command-contract v2 with typed positionals/options, mutability, prerequisites, output form, and exit codes.
• references/workflows.md — recipes = which scripts/X.sh to run and why.
• references/pitfalls.md — close-project-first, .bak, clip=null on audio, source_timerange math with speed, alpha-keyframes-don't-render-use-animation-materials, etc.
• Enum discovery — call capcut enums --<category> (or -H for a table) to list every CapCut slug. Categories: --transitions, --masks, --image-intros, --image-outros, --image-combos, --text-intros, --text-outros, --text-loop-anims, --scene-effects, --character-effects, --audio-effects, --fonts. Add --jianying to switch namespace. The enums.json bundle is generated once via python3 scripts/extract-enums.py; runtime is Python-free.
• scripts/ — the client library. Current:
  • anim.sh — attach any of 9 CapCut intro/outro animations; fade-in.sh and fade-out.sh are thin wrappers.
  • ken-burns.sh — scale + pan keyframes via capcut keyframe --batch (motion properties render; alpha does not — use anim.sh fade-in instead).
  • long-to-short.sh — cut a range, stamp title + CTA text.
  • stamp-cta.sh — apply a saved text template (see assets/examples/subscribe-cta.json).
  • _test.sh — run every wrapper against the fixture; run after any change here.
• assets/examples/ — raw JSON snippets for hand-editing.

Invariants

• Close the project in CapCut before editing; reopen after.
• Every write is conflict-checked, prepared atomically, and synchronized to every readable timeline target. Every target receives .bak and rolling history snapshots.
• Never pass --force-write unless the user explicitly accepts overwriting changed-on-disk state or an open editor.
• clip is null on audio segments (no opacity/scale).
• capcut cut writes to --out, never modifies the source.
• IDs: first 6+ chars of the UUID match as a prefix.
• Time formats: 1.5s, 500ms, +0.5s, -1s, 1:30, 0:05.5, bare number = seconds.

v0.11 high-value paths

• Whole draft: capcut compile spec.json --check, then capcut compile spec.json --out <dir>. Specs support refs, transforms, decorators, templates, captions, keyframes, and fades.
• Karaoke: capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke.
• Proxy: capcut render <project> --all-video-tracks --burn-captions; run doctor first for FFmpeg capability flags.
• Automation: capcut serve --workers N --retries N --timeout MS; give jobs stable id fields and let the runner serialize writes per project.
• Agent schema: on CLI v0.28.0 or newer, start with capcut describe --compact to discover commands, then fetch complete contracts with capcut describe --command <name> (repeat for several names). Plain capcut describe returns the full registry and works on older versions. Use these contracts as the source of truth; do not scrape help text or invent flags.