Metadata-Version: 2.4
Name: capcut-cli
Version: 0.77.0
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

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](https://pipx.pypa.io/).

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

Upgrade or uninstall:

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

## 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
```

Session mode example:

```bash
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:

```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`.
