# Cocut

**An open-source video editor where you and an AI agent edit the same timeline.**

Cut, trim, layer, caption and mix in the browser while Claude Code, Codex or any MCP client edits the same project. Every change, yours or the agent's, appears live, is labelled with who made it, and can be undone. Motion graphics are generated by a built-in engine and can be split into separately editable layers.

[中文说明](README.zh-CN.md)

![Cocut](docs/screenshot.png)

## Why

Agents are good at precise, repetitive, describable edits: "make every caption 52px", "shift everything after the chart by half a second", "add a lower third at 0:10". People are good at taste: what looks right, what feels late. Cocut puts both on one timeline:

- **One source of truth.** The edit is a plain `project.json`. The editor, the `cocut` CLI and the MCP server all read and write it, atomically and versioned.
- **Live.** When the agent changes something, the timeline updates in your browser within a quarter-second. Agent clips are marked orange.
- **Undoable.** Every change from anyone is a snapshot. `⌘Z` undoes the agent's last step as easily as your own.

## Features

**Editing**
- Video, image, generated, audio and text tracks; any number of each. The first track is drawn on top.
- Drag media from the bin, or drop files anywhere to import. Move clips, including across tracks, and trim their edges. Split at the playhead, delete, ripple delete, copy and paste. Snapping to clip edges, the playhead and markers.
- **Marquee select**: drag across empty space. `⌘A`, shift- or cmd-click, ⌥-click selects a clip and everything after it on its track.
- **Batch edit**: with many clips selected, the inspector edits them all, showing *mixed* where values differ. "Make all look like the first", group and ungroup (`⌘G`), nudge, and find & replace across text.
- Per-clip fades, opacity, position, scale and speed. Audio gain, fades, ducking under a voice track, and an optional musical ending, where the track lands on a downbeat and ends on a hit.
- Text clips with size, width, alignment, colour and word-by-word highlight. Drag text directly on the picture.
- Thumbnails and waveforms on the timeline, markers, zoom, and full keyboard control (`?` lists the shortcuts).
- English and 中文 interface.

**Generated motion graphics**
- Built-in templates: `title`, `numbers` (count-up with a grid of squares), `lowerthird` and `bars`. Each is a small JavaScript file in `cocut/engine/templates/`, so adding one is easy.
- **Split into editable elements.** A generated clip can be re-rendered as separate layers: background, graphics, counters and text, each with transparency (VP9 + alpha) on its own track. Its text can come back as native text clips you can retype, restyle and retime.

**Agents**
- **In the editor:** the AI tab sends a request to Claude Code (headless `claude -p`) or Codex (`codex exec`). Its commands and replies stream into the chat as it works.
- **From a terminal:** any agent can use the `cocut` CLI; see [AGENTS.md](AGENTS.md).
- **Over MCP:** `cocut mcp` exposes the editor as tools to Claude Code, Codex and other MCP clients.

**Export**
- H.264 + AAC MP4 at −14 LUFS, rendered by ffmpeg with exactly the same layout rules as the preview.

## Install

Requires Python 3.9+, [ffmpeg](https://ffmpeg.org) on your PATH (with libvpx-vp9 for transparent layers) and Chromium for Playwright (motion graphics).

```bash
git clone https://github.com/csy2443470971-ui/cocut && cd cocut
pip install -e .            # or: pip install numpy scipy soundfile pillow playwright
python3 -m playwright install chromium
pip install librosa         # optional: musical endings for music clips
```

## Quick start

```bash
cocut new my-video --size 1920x1080      # or: python3 -m cocut.demo  (builds a demo project)
cocut serve                              # → http://localhost:8770
```

Projects live in `./cocut-projects/` by default (set `COCUT_WORKSPACE` to change it).

## Working with agents

**Claude Code, inside the editor:** open the AI tab, type what you want, and press ⌘↩. Requires the `claude` CLI.

**Claude Code over MCP:**
```bash
claude mcp add cocut -- python3 -m cocut.cli mcp
```

**Codex over MCP** (`~/.codex/config.toml`):
```toml
[mcp_servers.cocut]
command = "python3"
args = ["-m", "cocut.cli", "mcp"]
```

**Any agent with a shell:**
```bash
cocut show                                         # timeline with clip ids
cocut set size=52 y-=0.03 --kind text --by claude  # batch edit every text clip
cocut gen lowerthird V2 10 --params '{"name": "Ada Lovelace", "role": "Analyst"}'
cocut layers <clip> --text-clips                   # split a generated clip into editable elements
cocut shift 0.5 --range 7: --by codex              # move everything after 7 s
cocut undo
```
`cocut -h` lists every command and the selector flags (`--ids`, `--track`, `--kind`, `--range`, `--text`, `--group`, `--author`).

## How it works

```
 browser editor ──┐                       ┌── cocut CLI  (people, Claude Code, Codex …)
                  ├──►  project.json  ◄───┤
 MCP clients ─────┘   (atomic, versioned) └── server: watches the file → pushes changes to every open editor
                              │
                    export.py → ffmpeg → MP4        engine/ → headless Chromium → generated clips / layers
```

More detail in [docs/architecture.md](docs/architecture.md).

## Project format

```jsonc
{
  "meta":   { "name": "demo", "width": 1920, "height": 1080, "fps": 30, "version": 12 },
  "tracks": [ { "id": "T1", "kind": "text", "name": "Text" }, { "id": "V1", "kind": "video", "name": "Video" },
              { "id": "A1", "kind": "audio", "name": "Voice", "role": "voice" } ],
  "clips":  [ { "id": "c1a2b3", "track": "V1", "kind": "mg", "src": "assets/generated/g1/title.mp4",
                "start": 0, "in": 0, "out": 3, "opacity": 1, "fadeIn": 0, "fadeOut": 0, "x": 0, "y": 0, "scale": 1, "by": "human" },
              { "id": "c4d5e6", "track": "T1", "kind": "text", "text": "Hello", "start": 0.3, "dur": 2.4,
                "x": 0.06, "y": 0.86, "w": 0.88, "size": 58, "color": "#ECE6EA", "karaoke": true, "words": [ { "w": "Hello", "t": 0.5 } ], "by": "claude" } ],
  "markers": [ { "t": 3, "label": "Numbers" } ],
  "log":     [ { "at": 1760000000.0, "by": "claude", "what": "set size on 3 clip(s)" } ]
}
```

## Status

Version 0.1. The editing model, the CLI, MCP, layer splitting and export are tested end to end. Still to come:
- transitions beyond crossfades
- keyframed properties
- audio fades drawn on clips
- multi-user (several people at once)
- previewing a music ending before you export

Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT. Any music, footage or fonts you put into a project keep their own licences.