capcut-edit · diff
git:20260413.09d7557 to git:20260515.3915585
39 added, 89 removed. Audit B to B.
---
- description: Edit CapCut / JianYing video projects — read and write subtitles, timing, speed, volume, templates, and cut long-form to shorts. Use when the user mentions capcut, jianying, subtitles, video editing, draft_content.json, draft_info.json, or cutting videos.
+ description: Edit CapCut / JianYing video projects — read and write subtitles, timing, speed, volume, templates, animations (fade/ken-burns), and cut long-form to shorts. Use when the user mentions capcut, jianying, subtitles, video editing, draft_content.json, draft_info.json, or cutting videos.
---
- # capcut-cli
+ # capcut-edit
- CLI for editing CapCut and JianYing project files directly. Reads and writes `draft_content.json` (Windows) / `draft_info.json` (macOS).
+ CLI for editing CapCut / JianYing draft files (`draft_content.json` on Windows, `draft_info.json` on macOS).
## Project locations
- - **macOS**: `/Users/<user>/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project-name>/`
- - **Windows**: `C:\Users\<user>\AppData\Local\CapCut\User Data\Projects\com.lveditor.draft\<project-name>\`
-
- ## Navigation (progressive disclosure)
-
- Start broad, drill into what you need. Never dump full project JSON.
-
- ```bash
- # Level 0: overview
- capcut info <project> -H
-
- # Level 1: discovery
- capcut tracks <project> -H
- capcut materials <project> -H
- capcut materials <project> --type audios -H
-
- # Level 2: browse
- capcut segments <project> --track video -H
- capcut texts <project> -H
-
- # Level 3: detail (one item)
- capcut segment <project> <id>
- capcut material <project> <id>
- ```
-
- ## Read commands
-
- ```bash
- capcut info <project> # Project overview + material summary
- capcut tracks <project> # List all tracks
- capcut materials <project> # All material types + counts
- capcut materials <project> --type <type> # Items of one type
- capcut segments <project> [--track <type>] # Segments with timing
- capcut texts <project> # Text/subtitle content
- capcut export-srt <project> # Export subtitles to SRT
- capcut segment <project> <id> # Full detail for one segment
- capcut material <project> <id> # Full detail for one material
- ```
-
- ## Write commands
-
- Every write creates a `.bak` backup automatically.
+ - **macOS**: `~/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project>/`
+ - **Windows**: `%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\`
- ```bash
- capcut set-text <project> <id> <text> # Change text
- capcut shift <project> <id> <offset> # Shift timing (+0.5s, -1s)
- capcut shift-all <project> <offset> [--track <t>] # Shift all segments
- capcut speed <project> <id> <multiplier> # Set speed (1.5)
- capcut volume <project> <id> <level> # Set volume (0.0-1.0)
- capcut opacity <project> <id> <alpha> # Set opacity (0.0-1.0)
- capcut trim <project> <id> <start> <duration> # Trim segment
- ```
+ ## Core principle — deterministic scripts
- ## Add commands
+ 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/`.
- ```bash
- capcut add-text <project> <start> <duration> <text> [options]
- --font-size <n> Font size (default: 15)
- --color <hex> Color (default: #FFFFFF)
- --align <0|1|2> Left/center/right (default: 1)
- --x <n> --y <n> Position (-1 to 1)
- --track-name <name> Track name (default: "text")
- ```
+ `references/workflows.md` documents *which script to call and why*, never a reconstructable sequence.
- ## Templates
+ ## Progressive disclosure
- Save any element from one project, stamp into another:
+ Start broad, drill into what you need. Never dump full project JSON.
```bash
- capcut save-template <project> <id> <name> --out <path>
- capcut apply-template <project> <template.json> <start> <duration> [text override]
- --x <n> --y <n> Override position
+ capcut info <project> -H # overview
+ 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
```
- ## Cut (long-form to short)
-
- ```bash
- capcut cut <project> <start> <end> --out <path>
- ```
+ ## Output modes
- Clips edge segments, rebases timing to 0, removes empty tracks, cleans orphaned materials.
+ - **JSON** (default): pipe to `jq`, feed to scripts.
+ - **`-H`**: human-readable tables.
+ - **`-q`**: quiet, exit code only — for write commands in scripts.
- ## Batch
+ ## Batch writes
```bash
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`.
- ## IDs and time formats
-
- - **IDs**: First 6+ chars of UUID work as prefix match
- - **Time**: `1.5s`, `500ms`, `+0.5s`, `-1s`, `1:30`, `0:05.5`
-
- ## Output modes
+ ## Where to look
- - **JSON** (default): pipe to `jq`, feed to scripts
- - **`-H`**: Human-readable tables
- - **`-q`**: Quiet, exit code only
+ - **`references/api-reference.md`** — every command, every flag, every value format (time, percentages, degrees), the ID-prefix rule, the `.bak` invariant.
+ - **`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.
- ## Important
+ ## Invariants
- - Close the project in CapCut before editing, reopen after
- - All writes create `.bak` backups
- - `clip` is `null` on audio segments (no opacity/scale)
- - The `cut` command writes to `--out`, never modifies the source
+ - Close the project in CapCut before editing; reopen after.
+ - Every write creates a `.bak` backup automatically.
+ - `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.