CapCutCLI

JSON-first CapCut Desktop CLI for LLM automation.

Features

• Create, inspect, install, and open CapCut projects
• Import and list image, video, and audio assets
• Ensure and inspect structured video, audio, and text tracks
• Add, move, trim, update, and delete image/video clips
• Add and update TTS, BGM, and SFX segments (user-supplied audio)
• Place CapCut library sound effects from the "사운드 효과" panel by effect_id (sfx.add)
• Add subtitle/title text overlays and update text placement/opacity
• Apply text animations (intro/outro/loop) with built-in presets or explicit slots
• Apply camera motion presets to video clips
• Set transitions and manage keyframes
• Lint the timeline for perceptual-quality defects with quality.lint (black gaps, text safe-area/collisions, caption pacing, audio mix, dead-air stills)
• Apply transactional batch edits or use raw.patch as an escape hatch
• Drive the CLI through newline-delimited JSON with session.serve

Install

Requires Python 3.11–3.14 and pipx.

pipx install capcut-cli
capcut --help

Upgrade or uninstall:

pipx upgrade capcut-cli
pipx uninstall capcut-cli

Development

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

Example:

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):

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:

python3 scripts/sync_sfx.py

Session mode example:

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

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:

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:

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.