Metadata-Version: 2.4
Name: capcut-cli
Version: 0.78.1
Summary: JSON-first CLI for CapCut Desktop project automation
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"

# CapCutCLI

CapCut Desktop project automation for humans, scripts, and AI agents.

CapCutCLI creates and edits local CapCut draft folders through a JSON-first
command line and Python API. It gives an agent structured operations for media,
tracks, clips, audio, text, transitions, filters, keyframes, motion, and project
installation without requiring the agent to understand CapCut's internal JSON.

It edits project files. It does **not** render/export video, control the CapCut
editor UI, or guarantee live refresh while a draft is open. Close CapCut before
mutating a project, then install it and select it from CapCut's project list.

## Capabilities

| Area | What an agent can do |
| --- | --- |
| Projects | Create, inspect, validate integrity, install, and launch CapCut Desktop |
| Assets | Import and probe image/video/audio files; list reusable asset IDs |
| Timeline | Create tracks; add, query, move, trim, update, and delete segments |
| Audio | Place TTS/BGM/local SFX, set volume/fades/mute, and duck music under voice |
| Text | Add titles/subtitles, style emphasis ranges, and apply intro/outro/loop animations |
| Visuals | Set transitions and filters; add keyframes; apply camera-motion presets |
| Storyboards | Validate, plan, and transactionally compile a high-level storyboard |
| Quality | Detect structural problems and viewer-visible timeline defects before opening CapCut |
| Automation | Apply atomic batches, stream newline-delimited JSON, or use guarded raw patches |

## Install

Requires Python 3.11–3.14 and [pipx](https://pipx.pypa.io/).

```bash
pipx install capcut-cli
capcut --help
```

Upgrade or uninstall:

```bash
pipx upgrade capcut-cli
pipx uninstall capcut-cli
```

Native wheels are published for CPython 3.11–3.14 on Apple Silicon and Intel
macOS, x64 Windows, and x64 Linux.

## AI Agent Quick Reference

### Recommended workflow

1. Inspect first with `project.inspect`, `asset.list`, or `timeline.summary`.
2. Discover exact arguments with `capcut schema --op <operation>`.
3. Import assets before referencing their `asset_id` from clips or audio.
4. Prefer structured operations. Group related writes with `batch.apply`.
5. Re-inspect, then run `project.integrity` and `quality.lint`.
6. Run `project.install-launch`; the user selects the installed draft in CapCut.

Use `raw.patch` only when no structured operation can express the edit.
`batch.apply` is transactional by default, so a failed operation rolls back the
group instead of leaving a partially edited timeline.

### Operation map

- `project.*`: create, inspect, integrity-check, install, and launch projects
- `asset.*`: import, list, and probe media
- `track.*`: ensure and list `video`, `audio`, or `text` tracks
- `clip.*`: add image/video clips; move, trim, update, or delete segments
- `audio.*`: add TTS/BGM/local SFX; update audio; generate ducking envelopes
- `storyboard.*`: validate, plan, and compile high-level storyboard JSON
- `timeline.*`: summarize, query, move, or delete any segment; delete managed output
- `text.*`: add/update titles and subtitles; list/apply animations
- `transition.*`, `filter.*`, `sfx.*`: use CapCut's built-in effect catalogs
- `keyframe.*`, `motion.*`: edit animation values or apply camera presets
- `quality.*`: lint black gaps, overlaps, text layout, caption pacing, audio mix,
  invisible clips, transition errors, and long motionless stills
- `batch.*`: execute grouped operations, atomically by default
- `raw.*`: patch low-level project JSON as a last-resort escape hatch
- `session.*`: process one JSON request per input line for long-lived agents

List CLI commands or inspect the machine-readable schema for one operation:

```bash
capcut --help
capcut schema --op clip.add-video
capcut schema --op storyboard.compile
```

### Data and response contract

- Public operation times are milliseconds. Stored CapCut timeranges and
  keyframe offsets are microseconds.
- Segments on the same track may not overlap.
- `draft_info.json` and `draft_content.json` are saved together through guarded,
  normalized writes.
- IDs should be discovered from read operations, not guessed.
- Every CLI/session response is JSON. Success uses
  `{"ok": true, "command": "...", "result": {...}, "warnings": []}`. Failure uses
  `{"ok": false, "error": {"code": "...", "message": "...", "details": {...}}}`.
- Error details include `suggested_fix` and, when relevant, conflicting IDs,
  invalid fields, paths, or recovery artifacts.

Important recovery rule: `CLEANUP_RECOVERY_REQUIRED` means the mutation was
already committed. Resolve the listed artifacts and **do not retry the original
operation**, or it may duplicate timeline state. `PROJECT_BUSY` means another
writer holds the lock; wait instead of deleting `.lock`.

### JSON session example

`session.serve` keeps one process alive and accepts one operation object per line:

```bash
printf '%s\n' \
  '{"op":"project.inspect","project_dir":"./workspace/demo"}' \
  '{"op":"timeline.summary","project_dir":"./workspace/demo"}' \
  '{"op":"quality.lint","project_dir":"./workspace/demo"}' \
  | capcut session serve
```

The same operation names and fields are accepted by
`modules.capcut.operations.apply_operation(op, args)` in Python.

## Development

```bash
python -m venv .venv
.venv/bin/pip install -e .[dev]
.venv/bin/pytest
```

Example:

```bash
capcut project create --project-dir ./workspace/demo --title "Demo Project"
capcut project inspect --project-dir ./workspace/demo
capcut timeline summary --project-dir ./workspace/demo
```

Place a CapCut library sound effect (auto-downloads the mp3 on first use):

```bash
capcut sfx list                                                # catalog size
capcut sfx add --project-dir ./workspace/demo \
               --effect-id 6817667030158706690 --start-ms 0    # Poi-n jumping sound
```

The catalog at `modules/capcut/_draft/metadata/capcut_sfx_meta.py` is generated
from your local CapCut `rp.db` cache. Rebuild it after browsing new categories
in the "사운드 효과" panel:

```bash
python3 scripts/sync_sfx.py
```

## Reference Points

- `tests/test_capcut_cli.py`: compact behavior coverage for the public CLI and `apply_operation()`
- `docs/operation-contract.json`: current public operation contract, required fields, and error surface
- `docs/compatibility.md`: package/runtime compatibility targets and smoke-test guidance
- `docs/publishing.md`: private-source PyPI/pipx release procedure
- `docs/motion-api-spec.md`: planned shared camera motion API for builder and CLI

## Demo Scripts

Full feature demo with real local media:

```bash
python3 demo_specs/build_full_feature_demo.py --clean --install
```

This creates reusable demo assets under `demo_assets/full_feature_demo/`, builds a sample project in `workspace/full_feature_demo_project/`, and writes an execution report to `demo_reports/full_feature_demo_report.json`.

Focused demo for the newer list/update/trim operations:

```bash
python3 demo_specs/build_new_ops_demo.py --clean
```

This verifies `asset.list`, `clip.trim`, `clip.update`, `audio.update`, and `text.update`, then writes a report to `demo_reports/new_ops_demo_report.json`.
