Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

Move the developer docs to the website and drop the tier prices from the README

Jareer794ca4cb1f8f
diff --git a/README.md b/README.md
index ec5072eb..6cf12aec 100644
--- a/README.md
+++ b/README.md
@@ -112,7 +112,7 @@ Download it, open it, drop footage in, cut. No account, no setup.
> [!IMPORTANT]
> The best way to contribute is to grab a build from the [Releases](https://github.com/jub0t/Concat/releases) page and use it: find where it breaks, and say where it could be better.
>
-> Ready to write code? [CONTRIBUTING.md](./CONTRIBUTING.md) covers setup, the layout of the tree, the checks to run, and how contributions are licensed. Driving Concat from a script, a service or an agent? [docs/](./docs/README.md) is the developer reference for the Concat API and its transports: JSON-RPC, gRPC and MCP. [This Discussion](https://github.com/jub0t/Concat/discussions/3) is where the project was announced.
+> Ready to write code? [CONTRIBUTING.md](./CONTRIBUTING.md) covers setup, the layout of the tree, the checks to run, and how contributions are licensed. Driving Concat from a script, a service or an agent? [The developer docs](https://concatenate.pages.dev/docs) cover the Concat API and its transports: JSON-RPC, gRPC and MCP. [This Discussion](https://github.com/jub0t/Concat/discussions/3) is where the project was announced.
>
> Contributors are free to claim a `@Contributor` role in the Discord server, just ask for it.
@@ -142,7 +142,7 @@ The [ROADMAP](./ROADMAP.MD) lays out what sponsorship pays for, and what each pi
**Payment Methods**
-Pick a tier on [the website](https://concatenate.pages.dev/#sponsor) ($25, $100 or $250), or send straight to a wallet.
+Pick a tier on [the website](https://concatenate.pages.dev/#sponsor), or send straight to a wallet.
| Method | Address |
|---|---|
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index 81935ad5..00000000
--- a/docs/README.md
+++ /dev/null
@@ -1,111 +0,0 @@
-<!-- https://github.com/jub0t/Concat/issues/123 -->
-
-# Concat developer docs
-
-**In one line:** anything the Concat window can do to a project, your program
-can do through the Concat API, over JSON-RPC or gRPC.
-
-## Pick a page
-
-| I want to… | Go to |
-|---|---|
-| See a working example in 30 seconds | [Quick start](#quick-start) below |
-| Understand the model: sessions, jobs, errors | [API overview](api/overview.md) |
-| Look up a method and its reply | [Methods](api/methods.md) |
-| Make an edit (add a clip, trim, title, effect) | [Edit commands](api/edits.md) |
-| Know what a clip / project / package looks like as JSON | [Types](api/types.md) |
-| Script Concat over stdin or a socket | [JSON-RPC](transports/json-rpc.md) |
-| Use generated clients over HTTP/2 | [gRPC](transports/grpc.md) |
-| Connect an AI agent (Model Context Protocol) | [MCP](transports/mcp.md) |
-| Copy-paste a whole script | [Recipes](recipes.md) |
-
-## Quick start
-
-**1. Run one call.** From a source checkout:
-
-```sh
-cd src
-cargo run -p concat-cli -- api '{"method":"version"}'
-```
-
-```json
-{"jsonrpc":"2.0","id":null,"result":{"apiVersion":"0.2","concat":"0.2.4","dirs":{"config":"…","data":"…"},"capabilities":["events"]}}
-```
-
-**2. Make a video.** Put these lines in `edit.jsonl` and pipe them in with
-`cargo run -p concat-cli -- api < edit.jsonl`:
-
-```jsonl
-{"jsonrpc":"2.0","id":1,"method":"project.create","params":{"location":"/edits","name":"Reel"}}
-{"jsonrpc":"2.0","id":2,"method":"media.import","params":{"path":"/edits/Reel","file":"/footage/take1.mp4"}}
-{"jsonrpc":"2.0","id":3,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addClipAtFirstFree","mediaId":"m1","start":0}}}
-{"jsonrpc":"2.0","id":4,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addTextClip","start":1,"style":{"content":"Hello"}}}}
-{"jsonrpc":"2.0","id":5,"method":"export.run","params":{"path":"/edits/Reel","output":"/edits/reel.mp4"}}
-```
-
-**3. Watch it finish.** The export answers at once with a job name, then
-reports as events until it is done:
-
-```jsonl
-{"jsonrpc":"2.0","id":5,"result":{"job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4"}}
-{"jsonrpc":"2.0","method":"export.progress","params":{"job":"j1","path":"/edits/Reel","frame":30,"total":150,"stage":"video"}}
-{"jsonrpc":"2.0","method":"export.done","params":{"job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4","width":1920,"height":1080}}
-```
-
-> [!TIP]
-> The same lines work over a socket. `concat-cli serve` listens on
-> `127.0.0.1:7420`, and the window's **Settings › Remote** page serves the
-> same API while the editor is open. See [JSON-RPC](transports/json-rpc.md).
-
-## The three ways in
-
-| Transport | How you reach it | Status |
-|---|---|---|
-| **JSON-RPC 2.0 lines** | `concat-cli api` (stdin), `concat-cli serve` (TCP or Unix socket), the window's Remote page | ✅ Shipped |
-| **gRPC** over HTTP/2 | `concat-cli serve --grpc`, in a build with the `grpc` feature | ✅ Shipped, behind a feature |
-| **MCP** | An MCP server exposing the API as tools | 🚧 Not in this tree yet. [MCP](transports/mcp.md) says what exists and how to bridge today |
-
-All three carry the **same methods, payloads and errors**. A method added
-to the API reaches every transport without a change to any of them.
-
-## Five things to know
-
-1. **Call `version` first.** Its `capabilities` list says what this build
- serves.
-2. **Projects are folders.** Every method names a project by its folder
- path, and the folder must be open (`project.open`) first.
-3. **Edits are commands.** `edit.apply` carries the window's own edit
- vocabulary, unchanged. Same clamps, same refusals.
-4. **Exports are jobs.** `export.run` returns at once; progress comes as
- events; one export runs at a time.
-5. **Errors have codes.** Branch on `code` (`notOpen`, `refused`, `busy`…);
- show `message` to a person.
-
-## Where the code is
-
-| Piece | Path |
-|---|---|
-| The contract: methods, payloads, events, errors | `src/crates/concat-api/src/message.rs` |
-| The dispatcher that runs them | `src/crates/concat-api/src/lib.rs` |
-| The JSON-RPC envelope | `src/crates/concat-api/src/rpc.rs` |
-| The socket server: JSON-RPC lines, gRPC, tokens | `src/crates/concat-server/` |
-| The gRPC service definition | `src/crates/concat-server/proto/concat.proto` |
-| The CLI: `api` and `serve` | `src/crates/concat-cli/src/main.rs` |
-| The edit commands | `src/crates/concat-project/src/commands/mod.rs` |
-
-Related reading: [`ARCHITECTURE.md`](../ARCHITECTURE.md) places the API in
-the engine.
-
-## Licensing
-
-Concat is AGPL-3.0-or-later. A program that talks to it over this API is a
-client. A plugin built on the API may carry its own licence under
-[`LICENSE-EXCEPTIONS.md`](../LICENSE-EXCEPTIONS.md).
-
-## Keeping these pages true
-
-These pages live with the code. A pull request that adds or changes a
-method, command, event, error or transport updates the page that describes
-it. The `apiVersion` a build reports is `API_VERSION` in `message.rs`; the
-rules for bumping it are in the
-[overview](api/overview.md#versioning-and-capabilities).
diff --git a/docs/api/edits.md b/docs/api/edits.md
deleted file mode 100644
index a6b83c39..00000000
--- a/docs/api/edits.md
+++ /dev/null
@@ -1,648 +0,0 @@
-# Edit commands
-
-**In one line:** every edit the window can make, as a JSON object you send
-through `edit.apply`.
-
-```json
-{"method":"edit.apply","path":"/edits/Reel","command":{"op":"trimClip","clipId":"c2","edge":"end","delta":-1.5}}
-```
-
-A command is `{"op": "<name>", …fields}`. Fields are camelCase. The reply
-is an *EditorView* ([Types](types.md#editorview)) of the project after the
-edit; `createdId` names what the command made, if anything.
-
-## Cheat sheet
-
-| Op | Does | Makes |
-|---|---|---|
-| **Media** | | |
-| [`addMedia`](#addmedia) | file into the bin | `m…` |
-| [`removeMedia`](#removemedia) | bin item and every clip of it, out | |
-| [`updateMediaPath`](#updatemediapath) | relink a file | |
-| [`setMediaColorRange`](#setmediacolorrange) | say whether a file is really limited or full range | |
-| [`replaceClipMedia`](#replaceclipmedia) | point a clip at another file | `m…` if new |
-| **Placing clips** | | |
-| [`addClip`](#addclip) | media on a named track | `c…` |
-| [`addClipAtFirstFree`](#addclipatfirstfree) | media on the first free track | `c…` |
-| [`addTextClip`](#addtextclip) | a title | `c…` |
-| [`addLayerClip`](#addlayerclip) | an effect layer over everything beneath | `c…` |
-| [`freezeFrame`](#freezeframe) | a held still, cut into a clip | `c…` |
-| **Moving and cutting** | | |
-| [`moveClips`](#moveclips) | reposition any number of clips | |
-| [`trimClip`](#trimclip) | drag one edge | |
-| [`splitClips`](#splitclips) | cut at a time | `c…` (the tail) |
-| [`mergeClips`](#mergeclips) | rejoin split pieces | |
-| [`removeClips`](#removeclips) | delete | |
-| **Changing a clip** | | |
-| [`updateClip`](#updateclip) | patch: name, volume, fades, opacity, effects, transition, text, crop… | |
-| [`setClipTransform`](#setcliptransform) | scale, offset, rotation, stretch | |
-| [`setClipSpeed`](#setclipspeed) | playback rate | |
-| [`setClipSpeedCurve`](#setclipspeedcurve) | speed over time | |
-| [`setClipKey`](#setclipkey) · [`clearClipKey`](#clearclipkey) · [`clearClipKeys`](#clearclipkeys) | keyframes on scale, offset, rotation, opacity, volume | |
-| [`setEffectKey`](#seteffectkey) · [`clearEffectKey`](#cleareffectkey) · [`clearEffectKeys`](#cleareffectkeys) | keyframes on an effect parameter | |
-| [`setClipCutout`](#setclipcutout) · [`addCutoutStroke`](#addcutoutstroke) | background removal and brush corrections | |
-| [`detachAudio`](#detachaudio) · [`reattachAudio`](#reattachaudio) | a video's sound as its own clip, and back | `c…` |
-| **Tracks** | | |
-| [`addTrack`](#addtrack) | a new lane | `t…` |
-| [`removeTrack`](#removetrack) | a lane and its clips, out | |
-| [`setTrackFlag`](#settrackflag) | visible / muted | |
-| **Timelines** | | |
-| [`addTimeline`](#addtimeline) | a new timeline, made active | `tl…` |
-| [`removeTimeline`](#removetimeline) · [`renameTimeline`](#renametimeline) · [`selectTimeline`](#selecttimeline) · [`moveTimeline`](#movetimeline) · [`setTimelineVideo`](#settimelinevideo) | manage timelines | |
-| **Templates and fonts** | | |
-| [`setMediaPlaceholder`](#setmediaplaceholder) · [`fillSlot`](#fillslot) | template slots | |
-| [`addFont`](#addfont) · [`removeFont`](#removefont) | fonts for titles | |
-| **Grouping** | | |
-| [`batch`](#batch) | several commands as one undo step | last id inside |
-
-## Rules that apply to every command
-
-- **Ids.** Clips are `c…`, tracks `t…` (the first timeline's starter lanes
- are `T1`–`T4`), timelines `tl…` (the first is `TL1`), media `m…`. Ids
- come from the *EditorView* replies.
-- **Unknown ids** are usually a tolerated no-op: the request succeeds,
- nothing changes, no undo step. Where a command errs instead, its entry
- says so.
-- **Times** are seconds on the timeline. A start below 0 lands at 0.
-- **Numbers are clamped**, not refused, into the range each field states.
- A NaN or infinite number is refused: "A number in that edit is not finite."
-- **A refusal** is a `refused` error whose message is the exact sentence
- the window would show. The project is as it was.
-- Commands act on the **active timeline**, except where the entry says
- "all timelines".
-
-## Refusal sentences
-
-| Sentence | Raised by |
-|---|---|
-| That media is no longer in the bin. | a clip-placing command whose media is gone |
-| That track no longer exists. | a clip-placing command whose track is gone |
-| There are no tracks. | first-free placement on a timeline with no tracks |
-| A timeline needs at least one track. | `removeTrack` on the last track |
-| A project needs at least one timeline. | `removeTimeline` on the last timeline |
-| That template slot no longer exists. | `fillSlot` with an unknown id |
-| That media is not a template slot. | `fillSlot` on ordinary media |
-| A number in that edit is not finite. | any command carrying NaN or infinity |
-| *(one of several sentences)* | `mergeClips`, saying why the pieces cannot be rejoined |
-
----
-
-## Media
-
-### `addMedia`
-
-Imports a probed file into the bin, minting an `m` id.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `item` | *NewMedia* | The file as `media.probe` describes it (see [Types](types.md#newmedia)) |
-
-> [!TIP]
-> You rarely need this. `media.import` probes and adds in one request.
-> Use `addMedia` when you already have the probe, or inside a `batch`.
-
-A path already in the bin is a no-op that mints nothing.
-
-### `removeMedia`
-
-Removes a bin item and **every clip referencing it, on all timelines**.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `mediaId` | string | The bin item. Unknown id: no-op |
-
-### `updateMediaPath`
-
-Relinks a bin item to a new path on disk.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `mediaId` | string | The bin item. Unknown id: no-op |
-| `newPath` | string | The new absolute path |
-
-### `setMediaColorRange`
-
-Says what levels a media file's picture really spans, over whatever the
-file claims. The fix for a washed-out or crushed picture.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `mediaId` | string | The bin item. Unknown id: no-op |
-| `range` | `"limited"`, `"full"` or `null` | `limited` is 16-235, `full` is 0-255. `null` goes back to reading the file's own tag |
-
-```json
-{"op":"setMediaColorRange","mediaId":"m1","range":"full"}
-```
-
-When to use which:
-
-- A screen recording that plays **grey where it should be black** is a
- full-range file tagged nothing. Set `full`.
-- A file whose **shadows are crushed** and highlights clipped is a
- video-range file tagged full. Set `limited`.
-- `media.probe` reports what the file claims as `video.colorRange`.
-
-Reaches every clip of the media, on every timeline, in the monitor and
-the export alike. Stored in the document; absent means "as tagged".
-
-### `replaceClipMedia`
-
-Points a clip at another file, adding it to the bin first if it is not
-there. The clip keeps its length, looks and name, and its in-point unless
-`sourceStart` moves it: an enhanced copy stands in frame for frame, a
-reversed span starts at its own zero. The bin keeps the original.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipId` | string | The clip. Unknown id: no-op |
-| `item` | *NewMedia* | The probed file |
-| `sourceStart` | number | *optional*. A new in-point in the copy, in seconds |
-
----
-
-## Placing clips
-
-### `addClip`
-
-Places a clip of a bin item on a named track.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `mediaId` | string | The bin item. Gone: **refused** |
-| `trackId` | string | The lane. Gone: **refused** |
-| `start` | number | Seconds; floored at 0 |
-| `ripple` | bool | *optional*, default `false`. When the drop would overlap, shift every clip at or after `start` right by the new clip's length |
-
-Duration comes from the media: its own length for video and audio, 5 s
-for a still or a file with no reported length.
-
-```json
-{"op":"addClip","mediaId":"m1","trackId":"T1","start":2.5}
-```
-
-### `addClipAtFirstFree`
-
-`addClip` without naming a lane: lands on the lowest track with nothing in
-the clip's span, or on the bottom track (overlapping) rather than refusing.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `mediaId` | string | The bin item. Gone: **refused** |
-| `start` | number | Seconds; floored at 0 |
-
-### `addTextClip`
-
-Places a title: a clip with no media behind it, named after the text's
-first line.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `trackId` | string | *optional*. The lane. Absent picks a free track; a vanished track is **refused** |
-| `above` | bool | *optional*, default `false`. With no `trackId`: land on the first free lane *above* the highest occupied one, minting a lane at the top if needed. What the editor does for its own titles and captions |
-| `start` | number | Seconds; floored at 0 |
-| `style` | *TextStyle* | *optional*. Only the fields you set; the rest are the window's defaults. `{"content": "Hello"}` is enough |
-| `duration` | number | *optional*, default 4 s |
-| `offsetY` | number | *optional*. Vertical placement as a fraction of frame height, clamped to ±3. Lower thirds are made of this |
-
-```json
-{"op":"addTextClip","start":1,"duration":3,"style":{"content":"Chapter one","fontSize":0.12,"color":"#ffcc00"},"offsetY":0.35}
-```
-
-### `addLayerClip`
-
-Places a layer: an effect over a span of the timeline that treats
-everything beneath it. The chain starts as the one package at its
-defaults; the clip's `opacity` is how hard it is applied.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `trackId` | string | *optional*. Absent picks the first free track |
-| `start` | number | Seconds; floored at 0 |
-| `duration` | number | *optional*, default 5 s |
-| `effectId` | string | A package id from `catalogue.list`, e.g. `concat.warm` |
-| `name` | string | What the lane calls it |
-
-### `freezeFrame`
-
-Splits a clip at `time`, inserts a held still, and ripples later clips on
-that track by the hold's length. `createdId` is the freeze clip.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipId` | string | A picture clip under the playhead |
-| `time` | number | Must fall strictly inside the clip |
-| `duration` | number | *optional*, default 1 s; floored at 1/60 s |
-| `still` | *NewMedia* | The probed still (a JPEG of the frame). **Required for video**; an image clip may omit it and reuse its media |
-
-Audio and text clips: no-op.
-
----
-
-## Moving and cutting
-
-### `moveClips`
-
-Repositions any number of clips as one undo step.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `moves` | array of `{clipId, start, trackId}` | Where each clip goes. `start` floors at 0. Unknown `clipId`: that move is skipped. Unknown `trackId`: moved in time, kept on its track |
-
-```json
-{"op":"moveClips","moves":[{"clipId":"c2","start":0,"trackId":"T1"},{"clipId":"c3","start":6.1,"trackId":"T1"}]}
-```
-
-### `trimClip`
-
-Drags one edge of a clip.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipId` | string | Unknown id: no-op |
-| `edge` | `"start"` or `"end"` | Which edge |
-| `delta` | number | Signed timeline seconds. Positive drags the head right (shortening) or the tail right (lengthening) |
-| `ripple` | bool | *optional*, default `false`. Close the lane up behind the trim: later clips on the track move by the change in length |
-
-How the edges differ:
-
-- **`start`** moves the in-point with the edge (scaled by speed), so the
- remaining frames stay where they were.
-- **`end`** only lengthens or shortens.
-- Either edge stops at the 1/60 s minimum duration.
-
-### `splitClips`
-
-Cuts each named clip in two at one time.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipIds` | string[] | The clips under the playhead |
-| `time` | number | The cut point, in timeline seconds |
-
-- The head keeps the id and the transition; the tail is minted fresh and
- stays source-continuous.
-- A clip the time misses, or grazes within 1/60 s of an edge, is skipped.
-
-### `mergeClips`
-
-Rejoins split pieces into the earliest piece, which keeps its id.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipIds` | string[] | The pieces, any order |
-
-**Refused** unless the pieces sit on one track, come from one file at one
-speed, touch within a microsecond, and are in source order. The message
-says which condition failed.
-
-### `removeClips`
-
-Deletes clips from the active timeline.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipIds` | string[] | Unknown ids are ignored |
-| `ripple` | bool | *optional*, default `false`. Leave no gap: on each touched track, later clips move left by the removed spans before them. Untouched tracks stay put |
-
----
-
-## Changing a clip
-
-### `updateClip`
-
-Applies a patch: only the fields present change.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipId` | string | Unknown id: no-op |
-| `patch` | *ClipPatch* | The fields to change |
-
-*ClipPatch* fields (all optional):
-
-| Field | Type | Clamp / meaning |
-|---|---|---|
-| `name` | string | Taken verbatim |
-| `volume` | number | Floored at 0; **not** capped at 1 |
-| `fadeIn`, `fadeOut` | number | Seconds, floored at 0 |
-| `opacity` | number | 0..=1 |
-| `preservePitch` | bool | Keep voices at pitch when speed ≠ 1 |
-| `muted` | bool | Silence the clip's own sound |
-| `flipH`, `flipV` | bool | Mirror |
-| `blend` | string | `normal` (or empty), `multiply`, `screen`, `add`, `lighten`, `darken` |
-| `filters` | *AppliedFilter*[] | **Replaces** the whole audio chain |
-| `videoEffects` | *AppliedFilter*[] | **Replaces** the whole video chain |
-| `crop` | *Crop* or `null` | See below |
-| `transitionIn` | *Transition* or `null` | The transition on the cut into the clip |
-| `text` | *TextStyle* or `null` | Title styling; also renames the clip after its first line |
-| `audioStream` | integer or `null` | Which of the media's audio streams to play; `null` means the file's first |
-
-> [!IMPORTANT]
-> `crop`, `transitionIn`, `text` and `audioStream` have three states:
-> **absent** leaves the value alone, **`null`** clears it, a **value**
-> replaces it.
-
-```json
-{"op":"updateClip","clipId":"c2","patch":{"volume":0.5,"fadeIn":0.5,"videoEffects":[{"id":"concat.gaussian-blur","params":{"radius":4}}],"transitionIn":{"id":"concat.dissolve","duration":0.75}}}
-```
-
-### `setClipTransform`
-
-Places the picture. Send only the fields you moved.
-
-| Field | Type | Clamp |
-|---|---|---|
-| `clipId` | string | Unknown id: no-op |
-| `scale` | number | 0.05..=8 |
-| `offsetX` | number | Fraction of frame width, ±3 |
-| `offsetY` | number | Fraction of frame height, ±3 |
-| `rotation` | number | Degrees, wrapped into (-180, 180] |
-| `stretchX`, `stretchY` | number | 0.1..=10, a multiplier beyond `scale` |
-
-### `setClipSpeed`
-
-Changes the playback rate while holding the source covered constant: the
-timeline length is what stretches.
-
-| Field | Type | Clamp |
-|---|---|---|
-| `clipId` | string | Unknown id: no-op |
-| `speed` | number | 0.0625..=16 |
-
-### `setClipSpeedCurve`
-
-Speed that changes over the clip.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipId` | string | The clip |
-| `curve` | *SpeedPoint*[] or `null` | Points of `{at, speed}`, `at` a fraction 0..=1 of the clip. `null` returns to a constant rate at the current mean |
-
-### `setClipKey`
-
-Puts a keyframe on one property at one point of the clip.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipId` | string | The clip |
-| `property` | `"scale"`, `"offsetX"`, `"offsetY"`, `"rotation"`, `"opacity"`, `"volume"` | Which property |
-| `at` | number | Where in the clip, 0..=1 |
-| `value` | number | The value there, in the property's own units |
-| `ease` | `[x1, y1, x2, y2]` | *optional*, default linear. A CSS-style cubic bezier; the names `"linear"`, `"in"`, `"out"`, `"inOut"` are accepted too |
-
-A key within 0.002 of `at` on the same property is replaced.
-
-### `clearClipKey`
-
-Removes the key at `at` on one property, if there is one.
-
-| Field | Type |
-|---|---|
-| `clipId` | string |
-| `property` | as above |
-| `at` | number, 0..=1 |
-
-### `clearClipKeys`
-
-Removes every key on one property.
-
-| Field | Type |
-|---|---|
-| `clipId` | string |
-| `property` | as above |
-
-### `setEffectKey`
-
-A keyframe on one parameter of one link in the clip's video chain.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipId` | string | The clip |
-| `entry` | integer | Index into `videoEffects`. Out of range: no-op |
-| `key` | string | The parameter's key from `catalogue.list` |
-| `at` | number | 0..=1 |
-| `value` | number | The parameter's own value; keep it within the package's range yourself |
-| `ease` | `[x1, y1, x2, y2]` | *optional*, default linear |
-
-### `clearEffectKey`
-
-Removes the key at `at` on one parameter of one link.
-
-| Field | Type |
-|---|---|
-| `clipId` | string |
-| `entry` | integer |
-| `key` | string |
-| `at` | number |
-
-### `clearEffectKeys`
-
-Removes every key on one parameter of one link.
-
-| Field | Type |
-|---|---|
-| `clipId` | string |
-| `entry` | integer |
-| `key` | string |
-
-### `setClipCutout`
-
-Sets or clears a picture's cutout: the mask that removes its background.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipId` | string | Unknown id: no-op |
-| `cutout` | *Cutout* or `null` | `{"mode": "auto"}` is the usual start; `null` takes it off |
-
-*Cutout* fields: `mode` (`auto` or `custom`), `subject` (`auto`, `person`,
-`object`; default `auto`), `feather` (edge softness as a fraction of the
-picture's width), `strokes` (corrections, see next).
-
-Masks are found at export time; `export.run` reports it as
-`cutout.progress`.
-
-### `addCutoutStroke`
-
-Paints one brush stroke onto a clip's cutout. A clip with no cutout gets a
-custom one; an automatic cutout becomes custom.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `clipId` | string | Unknown id: no-op |
-| `stroke` | *Stroke* | `tool` (`smartBrush`, `brush`, `smartEraser`, `eraser`), `size` (diameter as a fraction of picture width), `points` (`[[x, y], …]` as fractions of the source picture), `at` (*optional* source second the stroke was painted at) |
-
-A stroke with no points is a no-op.
-
-### `detachAudio`
-
-Pulls a video clip's sound out into its own audio clip on a free lane,
-muting the video and moving its audio filters to the sound.
-
-| Field | Type |
-|---|---|
-| `clipId` | string, the video clip |
-
-No-op unless the clip is an unmuted video whose media has audio and is not
-already detached.
-
-### `reattachAudio`
-
-Undoes a detach: deletes the detached sound, unmutes the video, hands the
-filters back.
-
-| Field | Type |
-|---|---|
-| `clipId` | string, the video **or** its detached sound |
-
----
-
-## Tracks
-
-### `addTrack`
-
-Appends a lane, named after the highest "Track N" in use. No fields.
-
-### `removeTrack`
-
-Deletes a lane and every clip on it.
-
-| Field | Type |
-|---|---|
-| `trackId` | string |
-
-**Refused** on the last track.
-
-### `setTrackFlag`
-
-Flips one of a track's two toggles.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `trackId` | string | Unknown id: no-op |
-| `flag` | `"visible"` or `"muted"` | Which toggle |
-| `value` | bool | The new setting |
-
----
-
-## Timelines
-
-### `addTimeline`
-
-Adds a fresh timeline with four lanes and makes it active. No fields.
-
-### `removeTimeline`
-
-Deletes a timeline; the active tab moves to a neighbour if it was this one.
-
-| Field | Type |
-|---|---|
-| `timelineId` | string. Unknown id: no-op |
-
-**Refused** on the last timeline.
-
-### `setTimelineVideo`
-
-Sets a timeline's output frame and rate.
-
-| Field | Type |
-|---|---|
-| `timelineId` | string. Unknown id: no-op |
-| `video` | *VideoSettings* |
-
-A zero dimension or rate is a no-op, not clamped.
-
-### `renameTimeline`
-
-| Field | Type |
-|---|---|
-| `timelineId` | string |
-| `name` | string, trimmed. Whitespace-only is ignored |
-
-### `selectTimeline`
-
-Switches which timeline later commands act on.
-
-| Field | Type |
-|---|---|
-| `timelineId` | string. Unknown id: selection stays |
-
-### `moveTimeline`
-
-Moves a timeline tab to a new position.
-
-| Field | Type |
-|---|---|
-| `timelineId` | string |
-| `index` | integer, 0-based, counted with the tab already removed; clamped to the end |
-
----
-
-## Templates and fonts
-
-### `setMediaPlaceholder`
-
-Marks a bin item as a template slot, or back to ordinary media.
-
-| Field | Type |
-|---|---|
-| `mediaId` | string. Unknown id: no-op |
-| `placeholder` | bool |
-
-### `fillSlot`
-
-Swaps a file into a template slot in place, on all timelines. The slot
-keeps its id, so clips keep working.
-
-| Field | Type |
-|---|---|
-| `mediaId` | string, a placeholder |
-| `item` | *NewMedia* |
-
-**Refused** if the id is unknown or the item is not a placeholder.
-`template.instantiate` does this for every slot for you.
-
-### `addFont`
-
-Registers a font file for titles.
-
-| Field | Type |
-|---|---|
-| `family` | string, the name titles refer to |
-| `path` | string, the font file |
-
-A path already registered is a no-op.
-
-### `removeFont`
-
-| Field | Type |
-|---|---|
-| `family` | string |
-
-Clips keep the family name; the face returns when the file does.
-
----
-
-## Grouping
-
-### `batch`
-
-Several commands as one atomic edit and one undo step.
-
-| Field | Type |
-|---|---|
-| `commands` | *Command*[], applied in order. Nesting is allowed |
-
-- Applied to a staged copy; committed only if **every** command succeeds.
-- `createdId` in the reply is the last id minted inside.
-
-```json
-{"op":"batch","commands":[
- {"op":"addTrack"},
- {"op":"addTextClip","start":0,"duration":2,"style":{"content":"One"}},
- {"op":"addTextClip","start":2,"duration":2,"style":{"content":"Two"}}
-]}
-```
-
-> [!NOTE]
-> A batch cannot refer to an id it mints, because the id is not known
-> until the batch is applied. Use `addClipAtFirstFree` / `addTextClip`
-> with `duration` rather than add-then-trim.
diff --git a/docs/api/methods.md b/docs/api/methods.md
deleted file mode 100644
index 9a679afe..00000000
--- a/docs/api/methods.md
+++ /dev/null
@@ -1,541 +0,0 @@
-# Methods
-
-**In one line:** every method the API answers, what it takes, what it gives
-back.
-
-## Cheat sheet
-
-| Method | Does | Replies with |
-|---|---|---|
-| [`version`](#version) | what this build serves | *VersionInfo* |
-| [`project.create`](#projectcreate) | new project folder, opened | *EditorView* |
-| [`project.open`](#projectopen) | open a folder | *EditorView* |
-| [`project.close`](#projectclose) | close, optionally save | `{}` |
-| [`project.list`](#projectlist) | recent projects | *ProjectInfo*[] |
-| [`project.get`](#projectget) | current state | *EditorView* |
-| [`project.document`](#projectdocument) | the `concat.json` a save writes | JSON object |
-| [`project.save`](#projectsave) | write to disk, optionally rename | `{}` |
-| [`project.setVideo`](#projectsetvideo) | frame size and rate (undoable) | *EditorView* |
-| [`edit.apply`](#editapply) | one edit command | *EditorView* |
-| [`edit.undo`](#editundo) | step back | *EditorView* |
-| [`edit.redo`](#editredo) | step forward | *EditorView* |
-| [`media.probe`](#mediaprobe) | what is in a file | *MediaSummary* |
-| [`media.import`](#mediaimport) | probe + add to bin | *EditorView* |
-| [`catalogue.list`](#cataloguelist) | effect packages and their params | *PackageInfo*[] |
-| [`template.list`](#templatelist) | the template library | *TemplateInfo*[] |
-| [`template.instantiate`](#templateinstantiate) | project from a template | *EditorView* |
-| [`template.save`](#templatesave) | project into a template | *TemplateInfo* |
-| [`export.run`](#exportrun) | render to a file, as a job | *Started* |
-| [`export.cancel`](#exportcancel) | stop a job | `{}` |
-| [`preview.frame`](#previewframe) | one frame as PNG | *Written* or *Picture* |
-
-Types in *italics* are in [Types](types.md).
-
-## How to read this page
-
-- Examples are **bare requests**, the shape `concat-cli api` takes on
- stdin. On a socket or over gRPC the same fields go in `params` inside
- the envelope. See [JSON-RPC](../transports/json-rpc.md).
-- Replies are shown as the `result` payload alone.
-- *optional* parameters may be left out; the default is stated.
-- `path` is always the project **folder**, and it must be open first, or
- the reply is `notOpen`.
-
----
-
-## `version`
-
-What this build serves. **Call it first.**
-
-**Parameters:** none.
-
-```json
-{"method":"version"}
-```
-
-**Reply**, a *VersionInfo*:
-
-```json
-{
- "apiVersion": "0.2",
- "concat": "0.2.4",
- "dirs": {
- "config": "/Users/ada/Library/Application Support/app.concat.editor",
- "data": "/Users/ada/Library/Application Support/app.concat.editor"
- },
- "capabilities": ["events", "gpu", "json-rpc"]
-}
-```
-
-The capability names and the bump rules are in the
-[overview](overview.md#versioning-and-capabilities).
-
----
-
-## `project.create`
-
-Creates a project folder and opens it.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `location` | string | The directory the project folder is made in |
-| `name` | string | The project's name. The folder is named after it; characters a filesystem refuses become `-` |
-| `video` | *VideoSettings* | *optional*. Frame and rate. **Default:** 1920×1080 at 30 fps |
-
-```json
-{"method":"project.create","location":"/edits","name":"Reel","video":{"width":1080,"height":1920,"rateNum":30,"rateDen":1}}
-```
-
-**Reply:** an *EditorView* of the new project.
-
-Good to know:
-
-- A fresh project has one timeline `TL1` with four tracks `T1`–`T4`.
-- It is added to the recents list, like one the window made.
-- A folder that already holds a project is refused (`failed`).
-- Over a socket, `location` must lie under one of the server's write
- roots, or the request is `refused`; see the JSON-RPC transport's
- [Security](../transports/json-rpc.md#security). A folder the window has
- open is `refused` too.
-
----
-
-## `project.open`
-
-Opens a project folder.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-
-```json
-{"method":"project.open","path":"/edits/Reel"}
-```
-
-**Reply:** an *EditorView*.
-
-Good to know:
-
-- Opening a folder already open returns its state as it stands, edits and
- all. The history is untouched.
-
----
-
-## `project.close`
-
-Closes an open project.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-| `save` | bool | *optional*. Write the document first. **Default:** `false` |
-
-```json
-{"method":"project.close","path":"/edits/Reel","save":true}
-```
-
-**Reply:** `{}`.
-
-> [!WARNING]
-> Without `save: true`, unsaved edits are dropped.
-
-A running export is not affected; it holds its own copy of what it needs.
-
----
-
-## `project.list`
-
-The projects this machine opened most recently, newest first.
-
-**Parameters:** none.
-
-**Reply:** an array of *ProjectInfo*.
-
-```json
-[{"path":"/edits/Reel","name":"Reel","width":1920,"height":1080,"rateNum":30,"rateDen":1,"openedAt":1790002385144}]
-```
-
-This is the launch screen's list. It names projects whether or not they
-are open now.
-
----
-
-## `project.get`
-
-The state of an open project.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-
-**Reply:** an *EditorView*.
-
----
-
-## `project.document`
-
-The document exactly as a save writes it: the contents of `concat.json`.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-
-**Reply:** the document, a JSON object.
-
-> [!TIP]
-> To inspect the project as data, prefer `project.get`. Its `project`
-> field is the same model without the flat `tracks` / `clips` / `video`
-> mirror that older builds read.
-
----
-
-## `project.save`
-
-Writes the document to the project folder.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-| `name` | string | *optional*. A new name for the project |
-
-**Reply:** `{}`.
-
----
-
-## `project.setVideo`
-
-Sets the active timeline's frame and rate, as an **undoable** edit.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-| `video` | *VideoSettings* | The frame and rate |
-
-```json
-{"method":"project.setVideo","path":"/edits/Reel","video":{"width":3840,"height":2160,"rateNum":60,"rateDen":1}}
-```
-
-**Reply:** an *EditorView*.
-
-A zero dimension or rate is `refused`.
-
----
-
-## `edit.apply`
-
-Applies **one edit command** and records one undo step.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-| `command` | *Command* | The edit: `{"op": "…", …fields}`. All of them are in [Edit commands](edits.md) |
-
-```json
-{"method":"edit.apply","path":"/edits/Reel","command":{"op":"addClip","mediaId":"m1","trackId":"T1","start":2.5}}
-```
-
-**Reply:** an *EditorView* of the project after the edit.
-
-Good to know:
-
-- `createdId` in the reply is the id of what the command made: a clip
- `c…`, track `t…`, timeline `tl…` or media `m…`. For a `batch` it is the
- last id minted inside.
-- A **refusal** is a `refused` error. Its message is the sentence the
- window would show. Nothing changed.
-- An edit that names something no longer there is, for most commands, a
- **tolerated no-op**: unchanged view, no undo step.
-- Several commands as one undo step: wrap them in `{"op": "batch",
- "commands": [...]}`.
-
----
-
-## `edit.undo`
-
-Steps the history back one edit.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-
-**Reply:** an *EditorView*. With nothing to undo, it is the unchanged view.
-`canUndo` and `canRedo` say where the history stands.
-
----
-
-## `edit.redo`
-
-Steps the history forward one edit.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-
-**Reply:** an *EditorView*.
-
----
-
-## `media.probe`
-
-What is inside a media file. Touches no project.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The file |
-
-```json
-{"method":"media.probe","path":"/footage/take1.mp4"}
-```
-
-**Reply:** a *MediaSummary*.
-
-```json
-{
- "path": "/footage/take1.mp4",
- "duration": 6.121029,
- "kind": "video",
- "video": {"index":0,"codec":"h264","width":854,"height":480,"frameRate":30.0,"frameRateFraction":"30/1"},
- "audio": {"index":1,"codec":"aac","sampleRate":48000,"channels":2,"title":"","language":"und"},
- "audioTracks": [
- {"index":1,"codec":"aac","sampleRate":48000,"channels":2,"title":"","language":"und"},
- {"index":2,"codec":"aac","sampleRate":48000,"channels":2,"title":"","language":"und"}
- ]
-}
-```
-
-A file that cannot be read or decoded is `failed`.
-
----
-
-## `media.import`
-
-Probes a file and adds it to the project's bin. What dropping a file on
-the window does.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-| `file` | string | The file to import |
-
-```json
-{"method":"media.import","path":"/edits/Reel","file":"/footage/take1.mp4"}
-```
-
-**Reply:** an *EditorView*. `createdId` is the new media id (`m1`, `m2`, …).
-
-Good to know:
-
-- A path already in the bin is a no-op, and `createdId` is absent.
-- This is `media.probe` + the `addMedia` command, as one request.
-- The bin item's fields are in [Types → MediaItem](types.md#mediaitem).
-
----
-
-## `catalogue.list`
-
-Every effect package the build knows, with its parameters. Enough to build
-a valid effect chain without reading a manifest.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `kind` | string | *optional*. One of `effect`, `filter`, `audio`, `transition`, `generator`. **Default:** all kinds. Any other word is `invalid` |
-
-```json
-{"method":"catalogue.list","kind":"effect"}
-```
-
-**Reply:** an array of *PackageInfo*, in id order.
-
-```json
-[{
- "id": "concat.gaussian-blur",
- "name": "Gaussian Blur",
- "kind": "effect",
- "category": "Blur",
- "description": "A soft, even blur.",
- "intensity": "radius",
- "params": [
- {"key":"radius","label":"Radius","type":"float","min":1.0,"max":50.0,"default":10.0,"step":1.0,"unit":"px","animate":false,"values":[],"labels":[]}
- ]
-}]
-```
-
-How to use it:
-
-- `id` is what a clip's chain stores: in `videoEffects`, `filters`, or a
- `transitionIn`.
-- each param's `key` is what the chain entry's `params` object stores it
- under. See [Types → AppliedFilter](types.md#appliedfilter).
-
----
-
-## `template.list`
-
-The template library.
-
-**Parameters:** none.
-
-**Reply:** an array of *TemplateInfo*, each naming its slots.
-
-What a template is: a bundle folder under `templates/` in the config
-directory, holding `template.json` (a project document whose placeholder
-media have blank paths), `assets/` (media and fonts that are part of the
-design) and `poster.jpg`.
-
----
-
-## `template.instantiate`
-
-Makes a project from a template with every slot filled, and opens it.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `template` | string | The bundle folder, as `template.list` gave it |
-| `location` | string | The directory the project folder is made in |
-| `name` | string | The project's name |
-| `fills` | array of `{"mediaId", "file"}` | The file for each slot. `mediaId` is the slot's id from `template.list` |
-
-```json
-{"method":"template.instantiate","template":"/Users/ada/Library/Application Support/app.concat.editor/templates/Intro","location":"/edits","name":"My intro","fills":[{"mediaId":"m1","file":"/footage/logo.png"},{"mediaId":"m2","file":"/footage/take1.mp4"}]}
-```
-
-**Reply:** an *EditorView* of the new project.
-
-Good to know:
-
-- **Every slot must be filled.** A set that leaves one empty makes nothing.
-- Every file is probed first, so a bad path refuses the whole request and
- leaves no folder behind.
-- Over a socket, `location` must lie under one of the server's write
- roots, or the request is `refused`.
-
----
-
-## `template.save`
-
-Packs an open project into a new template bundle in the library.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-| `name` | string | The template's name |
-
-**Reply:** the new bundle's *TemplateInfo*.
-
----
-
-## `export.run`
-
-Renders the active timeline to a file, as a **job**. Exactly what the
-window's Export sheet does: cutouts analysed, titles painted, then the
-frame loop and the mix.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-| `output` | string | The file to write. The container follows the extension; `.mp4` is the usual choice |
-| `crf` | integer | *optional*. Constant rate factor; lower is better and bigger. **Default:** 20 |
-| `preset` | string | *optional*. x264 preset name, `ultrafast` … `veryslow`. **Default:** `medium` |
-| `width` | integer | *optional*. **Default:** the timeline's |
-| `height` | integer | *optional*. **Default:** the timeline's |
-| `rateNum` | integer | *optional*. Frame rate numerator. **Default:** the timeline's |
-| `rateDen` | integer | *optional*. Frame rate denominator. **Default:** the timeline's |
-| `codec` | string | *optional*. `h264`, `hevc` or `av1`. **Default:** `h264`. Anything else is `invalid` |
-| `tenBit` | bool | *optional*. Ten bits a channel. **Default:** `false` |
-| `colorRange` | string | *optional*. `limited` (16-235, what every player and YouTube expect) or `full` (0-255, for screen content bound for a PC player). The file is tagged and converted to match. **Default:** `limited`. Anything else is `invalid` |
-
-```json
-{"method":"export.run","path":"/edits/Reel","output":"/edits/reel.mp4","crf":18,"codec":"hevc"}
-```
-
-**Reply**, a *Started*, at once:
-
-```json
-{"job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4"}
-```
-
-**Then events**, until the job ends:
-
-```jsonl
-{"event":"cutout.progress","job":"j1","path":"/edits/Reel","mediaId":"m3","fetching":true,"fraction":0.4}
-{"event":"export.progress","job":"j1","path":"/edits/Reel","frame":30,"total":150,"stage":"video"}
-{"event":"export.progress","job":"j1","path":"/edits/Reel","frame":150,"total":150,"stage":"mux"}
-{"event":"export.done","job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4","width":1920,"height":1080}
-```
-
-or
-
-```json
-{"event":"export.failed","job":"j1","path":"/edits/Reel","error":{"code":"failed","message":"…"}}
-```
-
-Rules:
-
-- **One export at a time.** A second is refused with `busy`. From the
- window's Remote page the slot is the window's own, so an export begun
- in the Export sheet counts.
-- An empty timeline is `refused`.
-- Over a socket, `output` must lie under one of the server's write roots,
- or the request is `refused`.
-- `width` and `height` are at most 8192 a side, the frame rate at most
- 240 a second, `crf` at most 63: anything larger is `invalid`.
-- `cutout.progress` only appears for clips with an automatic cutout whose
- masks are not cached yet. `fetching` is true while the model downloads.
-- Event shapes are in [Types → Events](types.md#events). The job model is
- in the [overview](overview.md#jobs-and-events).
-
----
-
-## `export.cancel`
-
-Stops a running export at its next frame.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `job` | string | The job `export.run` named |
-
-**Reply:** `{}`. The job then ends with `export.failed` whose `error.code`
-is `cancelled`.
-
-A job that is not running (finished, or never existed) is `notFound`.
-
----
-
-## `preview.frame`
-
-Composites the true frame at one instant, titles and effects included, as
-a PNG.
-
-| Parameter | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-| `time` | number | The timeline instant, in seconds |
-| `output` | string | *optional*. The file to write; folders above it are created. **Absent:** the picture comes back inline |
-| `width` | integer | *optional*. Frame width |
-| `height` | integer | *optional*. Frame height |
-
-```json
-{"method":"preview.frame","path":"/edits/Reel","time":1.5,"output":"/edits/frames/1.5.png","width":640,"height":360}
-```
-
-**Reply with `output`**, a *Written*:
-
-```json
-{"path":"/edits/frames/1.5.png","width":640,"height":360}
-```
-
-**Reply without**, a *Picture*:
-
-```json
-{"width":640,"height":360,"png":"iVBORw0KGgo…"}
-```
-
-Rules:
-
-- `width` and `height` count only **together**. Give both or neither;
- neither means the timeline's size.
-- Zero for either is `invalid`, and so is anything over 8192 a side.
-- Over a socket, `output` must lie under one of the server's write roots,
- or the request is `refused`.
-- The PNG is RGBA, 8 bits a channel, base64 in the standard alphabet with
- padding.
diff --git a/docs/api/overview.md b/docs/api/overview.md
deleted file mode 100644
index 6a12e60e..00000000
--- a/docs/api/overview.md
+++ /dev/null
@@ -1,228 +0,0 @@
-# API overview
-
-**In one line:** one dispatcher answers every request; transports only carry
-JSON to it and back.
-
-**On this page:** [Three shapes](#three-shapes) · [Sessions](#sessions) ·
-[Projects on disk](#projects-on-disk) · [Jobs and events](#jobs-and-events) ·
-[Errors](#errors) · [Versioning](#versioning-and-capabilities) ·
-[Tolerance](#tolerance-and-refusal) · [Concurrency](#concurrency) ·
-[Embedding in Rust](#embedding-in-rust) · [App directories](#app-directories)
-
----
-
-## Three shapes
-
-Everything that crosses the API is one of three JSON objects.
-
-| Shape | Looks like | Direction |
-|---|---|---|
-| **Request** | `{"method": "project.open", "path": "…"}` | in |
-| **Response** | `{"result": …}` or `{"error": {"code": "…", "message": "…"}}` | out, one per request |
-| **Event** | `{"event": "export.progress", "job": "j1", …}` | out, any time a job has news |
-
-- Methods are named `area.verb`: `project.open`, `edit.apply`, `export.run`.
-- A result is the method's payload **alone**. Nothing wraps it.
-- Field names are **camelCase** everywhere: requests, replies, the project
- document, the edit commands.
-
-On stdin or a socket the three travel inside the JSON-RPC 2.0 envelope,
-which adds an `id` and nothing else. See [JSON-RPC](../transports/json-rpc.md).
-gRPC carries the same JSON as text inside a protobuf message. See
-[gRPC](../transports/grpc.md).
-
----
-
-## Sessions
-
-A **session** is one open project. The API keeps one per project folder.
-
-- Every project method takes `path`, the project **folder**.
-- The folder must be open. A method on a closed folder is a `notOpen`
- error, never a silent open.
-- `project.open` on a folder already open returns its state as it stands,
- edits and all.
-- The path is canonicalised, so `.` and its absolute spelling are one
- session.
-
-A session holds the **edit history**:
-
-| Method | Does |
-|---|---|
-| `edit.apply` | applies one command, records one undo step |
-| `edit.undo` / `edit.redo` | walk the history |
-| `project.save` | writes `concat.json` |
-| `project.close` | drops the session; saves first only if `save: true` |
-
-> [!WARNING]
-> `project.close` without `save: true` drops unsaved edits, the same as the
-> window's "Don't save".
-
-On a socket, **all connected callers share the sessions**. A project one
-caller opens is open for the others.
-
----
-
-## Projects on disk
-
-A project is a **folder** holding `concat.json`.
-
-`project.create`:
-
-1. makes `<location>/<name>` (characters a filesystem refuses become `-`),
-2. writes the manifest,
-3. opens a session,
-4. puts it at the front of the recents list.
-
-It refuses a folder that already holds a project.
-
-| To read the project as… | Call |
-|---|---|
-| the model the engine holds | `project.get` |
-| the exact bytes a save writes | `project.document` |
-
-Both shapes are in [Types](types.md).
-
----
-
-## Jobs and events
-
-A request that would take long runs as a **job**. Today that is
-`export.run`.
-
-1. The response names the job at once: `{"job": "j1", …}`.
-2. The work runs on its own thread.
-3. Progress arrives as **events**, each carrying `job` and `path`.
-4. The job ends with exactly one of `export.done` or `export.failed`.
-
-| Event | When |
-|---|---|
-| `cutout.progress` | masks for an automatic cutout are being found before the render; a model may download first |
-| `export.progress` | `frame` of `total`, in stage `video`, `audio` or `mux` |
-| `export.done` | the file was written |
-| `export.failed` | the file was not written; `error.code` is `cancelled` if you cancelled it |
-
-Rules:
-
-- **One export at a time.** A second `export.run` is refused with `busy`.
-- Job names are unique for the life of the dispatcher: `j1`, `j2`, …
-- On a socket, events go to **every** connected caller. Filter by `job`.
-- On stdin, the process waits for running jobs before it exits, so a job
- begun on the last line still finishes.
-
----
-
-## Errors
-
-An error has a `code` you branch on and a `message` you can show a person.
-
-| Code | JSON-RPC number | Meaning |
-|---|---|---|
-| `parse` | -32700 | The line was not JSON |
-| `invalid` | -32600 | Not a request: unknown method, missing or ill-typed field, value out of range |
-| `notOpen` | -32001 | That project folder is not open |
-| `notFound` | -32002 | That job, template or package does not exist |
-| `refused` | -32003 | The edit layer said no. Nothing changed. The message is the window's own sentence |
-| `busy` | -32004 | A one-at-a-time job is already running |
-| `cancelled` | -32005 | The job was stopped by `export.cancel`. Only ever inside `export.failed` |
-| `unauthorized` | -32006 | Wrong or missing token. Raised by the socket transports, never by the API itself |
-| `failed` | -32000 | Everything else: a file that would not read or write, a decode that failed, a model that did not download |
-
-In the JSON-RPC envelope the number is `error.code` and the name is
-`error.data.code`. Over gRPC both are fields of the `Error` message.
-
----
-
-## Versioning and capabilities
-
-**Call `version` first.** Its reply has:
-
-| Field | Meaning |
-|---|---|
-| `apiVersion` | The contract this build speaks. Currently `0.2` |
-| `concat` | The build's own version |
-| `dirs` | The config and data directories (see [below](#app-directories)) |
-| `capabilities` | What this build serves, as names to test for |
-
-Capability names:
-
-| Name | Means |
-|---|---|
-| `events` | Jobs report through events. Every build has it |
-| `gpu` | Frames composite on a GPU. Depends on the machine |
-| `json-rpc` | Listening for JSON-RPC lines on TCP |
-| `unix-socket` | Listening for JSON-RPC lines on a Unix socket |
-| `grpc` | Listening for gRPC |
-
-When `apiVersion` changes:
-
-- ✅ Bumped when a method's **shape changes** in a way an old caller would
- misread.
-- ❌ Not bumped for a new method, a new optional field, a new event or a
- new capability. Ignore names you do not know.
-
----
-
-## Tolerance and refusal
-
-The edit layer is forgiving about **state** and strict about **shape**.
-
-| Situation | Outcome |
-|---|---|
-| An edit names a clip, track or media that no longer exists | Usually a tolerated **no-op**: success, nothing changed, no undo step. Each command in [Edit commands](edits.md) says which |
-| A number is outside its range | **Clamped**, not refused. Scale 100 lands at 8; start -2 lands at 0 |
-| A number is NaN or infinite | `refused` |
-| A field has the wrong type, or the `op` / `method` is unknown | `invalid` |
-| A file cannot be probed, read or written | `failed` |
-
----
-
-## Concurrency
-
-- The dispatcher handles **one request at a time**, in order, like the
- window's event loop.
-- Long work is a job, so a request never waits on a render.
-- The socket server queues every caller through that one thread.
-- Responses on one connection come back in the order the requests were
- sent. The envelope's `id` lets you tell them apart anyway.
-
----
-
-## Embedding in Rust
-
-The dispatcher and the server are ordinary workspace crates.
-
-```rust
-use std::sync::Arc;
-use concat_api::{Api, Event, Request, Response};
-
-let mut api = Api::new(Arc::new(|event: Event| {
- println!("{}", serde_json::to_string(&event).unwrap());
-}))?;
-let response: Response = api.dispatch(Request::ProjectList);
-api.finish(); // wait for running jobs before dropping it
-```
-
-| Need | Use |
-|---|---|
-| Your own config and data folders (tests, embedders) | `Api::with_dirs(dirs, sink)` |
-| The API on sockets, with a token | `concat_server::Server::start(config, Api::new)` |
-| Calling the served API from the same process | `Server::hub()` |
-
-`Api` is not `Send`: it lives on one thread. The event sink is called from
-job threads, so it must be `Send + Sync`. The window's Remote page is a
-`Server::start` from the settings sheet.
-
----
-
-## App directories
-
-`version` reports two folders. Recents, settings and templates live in
-`config`; downloaded models and painted titles in `data`.
-
-| Platform | `config` | `data` |
-|---|---|---|
-| macOS | `~/Library/Application Support/app.concat.editor` | same folder |
-| Windows | `%APPDATA%\app.concat.editor` | same folder |
-| Linux | `~/.config/app.concat.editor` (or `$XDG_CONFIG_HOME/…`) | `~/.local/share/app.concat.editor` (or `$XDG_DATA_HOME/…`) |
-| Portable build | `portable/` beside the executable | same folder |
diff --git a/docs/api/types.md b/docs/api/types.md
deleted file mode 100644
index 7d0b93c6..00000000
--- a/docs/api/types.md
+++ /dev/null
@@ -1,448 +0,0 @@
-# Types
-
-**In one line:** the JSON shapes that requests carry and replies return.
-
-**On this page:** [Replies](#replies) · [The project model](#the-project-model)
-· [Media](#media) · [Catalogue](#catalogue) · [Templates](#templates) ·
-[Events](#events) · [Errors](#errors)
-
-Every field is camelCase. A field marked *optional* may be absent from a
-reply; a request may leave it out.
-
----
-
-## Replies
-
-### VersionInfo
-
-Reply to `version`.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `apiVersion` | string | The contract, e.g. `"0.2"` |
-| `concat` | string | The build's version |
-| `dirs` | `{config, data}` | The app's directories, as paths |
-| `capabilities` | string[] | See [overview](overview.md#versioning-and-capabilities) |
-
-### EditorView
-
-Reply to every method that opens or changes a project.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `project` | *Project* | The whole project |
-| `canUndo` | bool | There is something to undo |
-| `canRedo` | bool | There is something to redo |
-| `settings` | `{name, width, height, rateNum, rateDen}` | The project's name and the active timeline's frame and rate |
-| `createdId` | string | *optional*. The id the command just minted |
-
-```json
-{
- "project": { "…": "see Project" },
- "canUndo": true,
- "canRedo": false,
- "settings": {"name":"Reel","width":1920,"height":1080,"rateNum":30,"rateDen":1},
- "createdId": "c2"
-}
-```
-
-### ProjectInfo
-
-One entry of `project.list`.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `path` | string | The project folder |
-| `name` | string | The name in the title bar |
-| `width`, `height` | integer | Output size |
-| `rateNum`, `rateDen` | integer | Frame rate as a fraction |
-| `openedAt` | integer | Milliseconds since the epoch |
-
-### Started
-
-Reply to `export.run`.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `job` | string | `"j1"`, `"j2"`, … Every event about this job carries it |
-| `path` | string | The project folder |
-| `output` | string | The file it will write |
-
-### Written
-
-Reply to `preview.frame` with `output`.
-
-| Field | Type |
-|---|---|
-| `path` | string, the file written |
-| `width`, `height` | integer |
-
-### Picture
-
-Reply to `preview.frame` without `output`.
-
-| Field | Type |
-|---|---|
-| `width`, `height` | integer |
-| `png` | string, the PNG as base64 (standard alphabet, padded) |
-
-### Done
-
-`{}`. The reply of methods with nothing to say beyond having worked.
-
----
-
-## The project model
-
-What `project.get` returns as `project`, and what `project.document` writes
-to `concat.json` (plus a compatibility mirror; see
-[`project.document`](methods.md#projectdocument)).
-
-### Project
-
-| Field | Type | Meaning |
-|---|---|---|
-| `media` | *MediaItem*[] | The bin, shared by all timelines |
-| `fonts` | `{family, path}`[] | Fonts added from disk |
-| `timelines` | *Timeline*[] | In tab order. Always at least one |
-| `activeTimelineId` | string | The timeline commands act on |
-
-### Timeline
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | `"TL1"` for the first, `"tl…"` after |
-| `name` | string | The tab label |
-| `video` | *VideoSettings* | This timeline's frame and rate |
-| `tracks` | *Track*[] | Top to bottom. Never empty |
-| `clips` | *Clip*[] | In insertion order, **not** time order; sort by `start` yourself |
-
-### VideoSettings
-
-| Field | Type | Meaning |
-|---|---|---|
-| `width`, `height` | integer | Frame size in pixels |
-| `rateNum`, `rateDen` | integer | Frame rate as a fraction: 30 fps is `30/1`, 29.97 is `30000/1001` |
-
-### Track
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | `"T1"`–`"T4"` on the first timeline, `"t…"` after |
-| `visible` | bool | Video on this track reaches the composite |
-| `muted` | bool | Audio on this track is silent |
-
-### Clip
-
-A clip as `project.get` returns it. Fields with a default are left out of
-the JSON when they hold it.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | `"c…"`. Survives splits (the head keeps it) and merges |
-| `trackId` | string | The lane |
-| `mediaId` | string | Empty for a text or layer clip |
-| `name` | string | Display label |
-| `kind` | string | `video`, `audio`, `image`, `text`, `layer` |
-| `start` | number | Seconds from the start of the timeline |
-| `duration` | number | Seconds on the timeline. Never below 1/60 |
-| `sourceStart` | number | In-point: seconds into the media |
-| `volume` | number | Linear gain, 1 is unity |
-| `fadeIn`, `fadeOut` | number | Audio ramp seconds |
-| `scale` | number | Multiplier over the fitted size |
-| `offsetX`, `offsetY` | number | Fractions of frame width / height from centred |
-| `rotation` | number | Degrees, clockwise |
-| `stretchX`, `stretchY` | number | *optional*, default 1 |
-| `opacity` | number | 0..1 |
-| `speed` | number | Playback rate; the curve's mean when a curve is set |
-| `speedCurve` | *SpeedPoint*[] | *optional* |
-| `keys` | *ClipKey*[] | *optional*. User keyframes, sorted by property then `at` |
-| `flipH`, `flipV` | bool | *optional* |
-| `blend` | string | *optional*. `multiply`, `screen`, `add`, `lighten`, `darken`; absent is normal |
-| `crop` | *Crop* | *optional* |
-| `cutout` | *Cutout* | *optional* |
-| `preservePitch` | bool | Keep pitch when speed ≠ 1 |
-| `filters` | *AppliedFilter*[] | Audio chain, in order |
-| `videoEffects` | *AppliedFilter*[] | Video chain, in order |
-| `audioStream` | integer | *optional*. Which audio stream of the media plays |
-| `muted` | bool | *optional*. True when the sound is detached |
-| `detachedFrom` | string | *optional*. On a detached audio clip: the video it came from |
-| `transitionIn` | *Transition* | *optional* |
-| `text` | *TextStyle* | *optional*. Present on a text clip |
-
-A clip fresh from `addClip`:
-
-```json
-{"id":"c2","trackId":"T1","mediaId":"m1","name":"take1.mp4","kind":"video","start":0.0,"duration":6.12,"sourceStart":0.0,"volume":1.0,"fadeIn":0.0,"fadeOut":0.0,"scale":1.0,"offsetX":0.0,"offsetY":0.0,"rotation":0.0,"opacity":1.0,"speed":1.0,"preservePitch":true,"filters":[],"videoEffects":[]}
-```
-
-### MediaItem
-
-One entry of the bin. The probe's findings are stored, so a project opens
-meaningfully even when the file is missing.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | `"m…"`, never re-issued |
-| `path` | string | Absolute path. Also the duplicate check |
-| `name` | string | Display name, normally the file's basename |
-| `duration` | number | *optional*. Seconds, when the container says |
-| `kind` | string | `video`, `audio`, `image` |
-| `width`, `height` | integer | *optional* |
-| `frameRate` | number | *optional*. Decimal, for display |
-| `frameRateFraction` | string | *optional*. Exact, e.g. `"30000/1001"` |
-| `videoCodec`, `audioCodec` | string | *optional* |
-| `hasAudio` | bool | The file carries sound |
-| `audioTracks` | *AudioTrack*[] | *optional*. Every audio stream, in file order |
-| `placeholder` | bool | *optional*. True for a template slot |
-| `colorRange` | string | *optional*. `limited` or `full`: the levels the picture is read as, over the file's own tag. Absent means "as tagged". Set with `setMediaColorRange` |
-| `origin` | string | *optional*. `speech` for a file the speech sheet read aloud. Absent for an import. The bin shelves a file with an origin under Generated, not with the imports |
-
-### AudioTrack
-
-| Field | Type |
-|---|---|
-| `index` | integer, the stream's index in the file |
-| `codec` | string |
-| `channels` | integer |
-| `sampleRate` | integer |
-| `title` | string, *optional* |
-| `language` | string, *optional* |
-
-### AppliedFilter
-
-One link of an effect chain, in `filters` or `videoEffects`.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | A package id from `catalogue.list`, e.g. `"concat.gaussian-blur"` |
-| `params` | object | Parameter key → number. Missing keys mean the package's defaults |
-| `enabled` | bool | *optional*, default `true`. False bypasses without losing settings |
-| `keys` | object | *optional*. Parameter key → *ParamKey*[] (`{at, value, ease}`) for animated parameters |
-
-```json
-{"id":"concat.gaussian-blur","params":{"radius":4},"enabled":true}
-```
-
-Every parameter is stored as a number, whatever its `type` in the
-catalogue: a `bool` is 0 or 1, an `enum` is one of its `values`, a `color`
-is packed RGBA, a `point` is two keys `<key>.x` and `<key>.y` in 0..1.
-
-### Transition
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | A transition package id, e.g. `"concat.dissolve"`, `"concat.push"`, `"concat.clock-wipe"` |
-| `duration` | number | Seconds, default 1 |
-
-### TextStyle
-
-A title's styling. Sizes are **fractions of the frame**, so a title made at
-1080p exports right at 4K. In a command you send only the fields you
-change; the rest take these defaults.
-
-| Field | Type | Default | Meaning |
-|---|---|---|---|
-| `content` | string | `"Your text"` | The words, newlines included |
-| `fontFamily` | string | `"\"Cabinet Grotesk\""` | CSS-style family name, quoted where needed. May name an added font |
-| `fontSize` | number | 0.09 | Cap height as a fraction of frame height |
-| `fontWeight` | number | 700 | 100..=900 |
-| `italic` | bool | false | |
-| `color` | string | `"#ffffff"` | CSS hex |
-| `align` | string | `"center"` | `left`, `center`, `right`. Also which point of the block the clip's position pins |
-| `opacity` | number | 1 | 0..=1, multiplied with the clip's |
-| `strokeWidth` | number | 0 | Outline as a fraction of frame height; 0 is none |
-| `strokeColor` | string | `"#000000"` | |
-| `shadow` | bool | true | A drop shadow |
-| `background` | string | `""` | A background colour behind the text, `#rrggbb[aa]`, its alpha the opacity; empty is none |
-| `backgroundRadius` | number | 0.0135 | The background's corner radius as a fraction of frame height; 0 is square |
-| `backgroundPaddingX` | number | 0.0315 | The background's air either side of the words, as a fraction of frame height; ignored on an axis `maxWidth` sizes |
-| `backgroundPaddingY` | number | 0.018 | The same above and below; ignored when `maxHeight` sizes the box |
-| `lineHeight` | number | 1.2 | Multiple of the font size; floored at 0.5 |
-| `tracking` | number | 0 | Extra letter spacing, in frame-height fractions |
-| `maxWidth` | number | 0 | Wrap width as a fraction of frame width; 0 is no wrap |
-| `maxHeight` | number | 0 | Box height as a fraction of frame height; 0 is the words' own |
-
-### Crop
-
-Fractions of the source taken off each edge: `{left, top, right, bottom}`,
-each 0..=0.9, with at least a tenth of the picture left.
-
-### Cutout
-
-| Field | Type | Meaning |
-|---|---|---|
-| `mode` | string | `auto` (the model's mask) or `custom` (the mask plus strokes) |
-| `subject` | string | *optional*, default `auto`. `person`, `object`, or `auto` (person if found, else object) |
-| `feather` | number | Edge softness as a fraction of picture width |
-| `strokes` | *Stroke*[] | *optional*. Corrections, in order |
-
-### Stroke
-
-| Field | Type | Meaning |
-|---|---|---|
-| `tool` | string | `smartBrush`, `brush`, `smartEraser`, `eraser` |
-| `size` | number | Diameter as a fraction of picture width |
-| `points` | `[x, y]`[] | Fractions of the source picture, `[0, 0]` top-left |
-| `at` | number | *optional*. Source second the stroke was painted at |
-
-### ClipKey
-
-| Field | Type | Meaning |
-|---|---|---|
-| `property` | string | `scale`, `offsetX`, `offsetY`, `rotation`, `opacity`, `volume` |
-| `at` | number | 0..=1 of the clip's length |
-| `value` | number | In the property's own units |
-| `ease` | `[x1, y1, x2, y2]` | A cubic bezier; default linear `[0, 0, 1, 1]` |
-
-### SpeedPoint
-
-`{at, speed}`: `at` a fraction 0..=1 of the clip, `speed` source seconds
-per timeline second there.
-
-### NewMedia
-
-A probed file, as `addMedia`, `fillSlot`, `replaceClipMedia` and
-`freezeFrame` take it. The same fields as *MediaItem* minus `id` and
-`placeholder`: `path`, `name`, `duration`, `kind`, `width`, `height`,
-`frameRate`, `frameRateFraction`, `videoCodec`, `audioCodec`, `hasAudio`,
-`audioTracks`, and `origin` (*optional*; leave it out for an import).
-
-> [!TIP]
-> Build one from a `media.probe` reply: copy `path`, `duration`, `kind`
-> and `audioTracks`; take `width`, `height`, `frameRate`,
-> `frameRateFraction` and `videoCodec` from its `video`; `audioCodec`
-> from its `audio`; `hasAudio` is whether `audio` is present; `name` is
-> the file's basename. Or skip all that with `media.import`.
-
----
-
-## Media
-
-### MediaSummary
-
-Reply to `media.probe`.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `path` | string | The file, as given |
-| `duration` | number | *optional*. Container duration in seconds |
-| `kind` | string | `video`, `audio`, `image` |
-| `video` | *VideoStreamInfo* | *optional*. The first video stream |
-| `audio` | *AudioStreamInfo* | *optional*. The first audio stream, what a clip plays unless it names another |
-| `audioTracks` | *AudioStreamInfo*[] | Every audio stream, in file order |
-
-**VideoStreamInfo:** `index`, `codec`, `width`, `height`, `frameRate`
-(decimal), `frameRateFraction` (exact, e.g. `"30/1"`), and `colorRange`
-(`limited` or `full`, present only when the file says; a file that says
-nothing is played as limited).
-
-**AudioStreamInfo:** `index`, `codec`, `sampleRate`, `channels`, `title`,
-`language`.
-
----
-
-## Catalogue
-
-### PackageInfo
-
-One entry of `catalogue.list`.
-
-| Field | Type | Meaning |
-|---|---|---|
-| `id` | string | `author.name`, e.g. `"concat.gaussian-blur"`. What a chain stores |
-| `name` | string | The catalogue card's title |
-| `kind` | string | `effect`, `filter`, `audio`, `transition`, `generator` |
-| `category` | string | The shelf the card sits on |
-| `description` | string | One sentence |
-| `intensity` | string | *optional*. The parameter the simple view shows as its one slider |
-| `params` | *ParamInfo*[] | In inspector order |
-
-### ParamInfo
-
-| Field | Type | Meaning |
-|---|---|---|
-| `key` | string | What `params` stores it under |
-| `label` | string | The control's label |
-| `type` | string | `float`, `int`, `bool`, `enum`, `color`, `point` |
-| `min`, `max` | number | The range |
-| `default` | number | The value an untouched control means |
-| `step` | number | Slider increment; 0 is continuous |
-| `unit` | string | Shown after the number |
-| `animate` | bool | Can carry keyframes |
-| `values` | number[] | For `enum`: the values the document may hold |
-| `labels` | string[] | For `enum`: the name of each value, in `values` order |
-
----
-
-## Templates
-
-### TemplateInfo
-
-| Field | Type | Meaning |
-|---|---|---|
-| `path` | string | The bundle folder. What `template.instantiate` takes |
-| `name` | string | |
-| `width`, `height` | integer | Output size |
-| `rateNum`, `rateDen` | integer | Frame rate |
-| `slots` | *SlotInfo*[] | In the order they first appear on the timeline |
-| `hasPoster` | bool | The bundle carries `poster.jpg` |
-
-### SlotInfo
-
-| Field | Type | Meaning |
-|---|---|---|
-| `mediaId` | string | The placeholder's id. What a fill names |
-| `name` | string | As the creator labelled it |
-| `kind` | string | `video`, `audio`, `image`: what the slot wants |
-| `seconds` | number | Timeline seconds the slot covers |
-
----
-
-## Events
-
-Every event carries `job` and `path`. As a bare object the tag is `event`;
-in the JSON-RPC envelope the tag becomes the notification's `method` and
-the rest its `params`.
-
-### `cutout.progress`
-
-| Field | Type | Meaning |
-|---|---|---|
-| `mediaId` | string | The media being analysed |
-| `fetching` | bool | True while a model downloads, false while it runs |
-| `fraction` | number | 0..=1 |
-
-### `export.progress`
-
-| Field | Type | Meaning |
-|---|---|---|
-| `frame` | integer | Frames done |
-| `total` | integer | Frames in total |
-| `stage` | string | `video`, `audio`, `mux` |
-
-### `export.done`
-
-| Field | Type |
-|---|---|
-| `output` | string, the file written |
-| `width`, `height` | integer |
-
-### `export.failed`
-
-| Field | Type |
-|---|---|
-| `error` | *ApiError*; `code` is `cancelled` when `export.cancel` stopped it |
-
----
-
-## Errors
-
-### ApiError
-
-| Field | Type | Meaning |
-|---|---|---|
-| `code` | string | One of the codes in the [overview](overview.md#errors) |
-| `message` | string | The sentence a person would be shown |
-
-In the JSON-RPC envelope: `{"code": <number>, "message": "…", "data": {"code": "<name>"}}`.
diff --git a/docs/recipes.md b/docs/recipes.md
deleted file mode 100644
index fd37318f..00000000
--- a/docs/recipes.md
+++ /dev/null
@@ -1,265 +0,0 @@
-# Recipes
-
-**In one line:** copy-paste scripts for the things people most often want
-from the API.
-
-Each recipe is shown two ways where it makes sense: as **lines** for
-`concat-cli api` (paste into a `.jsonl` file, or type one at a time), and
-as **Python** against a socket using the `Concat` class from
-[JSON-RPC → Python client](transports/json-rpc.md#a-minimal-python-client).
-
-**Recipes:** [Rough cut from a folder](#1-rough-cut-from-a-folder-of-clips)
-· [Export and show progress](#2-export-and-show-progress) ·
-[A title card](#3-a-title-card) · [A look on every clip](#4-a-look-on-every-clip)
-· [Contact sheet of frames](#5-a-contact-sheet-of-frames) ·
-[A project from a template](#6-a-project-from-a-template) ·
-[Vertical cut of a landscape edit](#7-a-vertical-cut-of-a-landscape-edit) ·
-[Undo, redo, save](#8-undo-redo-save) · [Inspect a project](#9-inspect-a-project-without-changing-it)
-
-Run the CLI from the `src/` folder: `cargo run -p concat-cli -- api < file.jsonl`.
-
----
-
-## 1. Rough cut from a folder of clips
-
-Import every file and lay them end to end on the first track.
-
-**Lines** (two files shown; repeat the pattern):
-
-```jsonl
-{"jsonrpc":"2.0","id":1,"method":"project.create","params":{"location":"/edits","name":"Rough cut"}}
-{"jsonrpc":"2.0","id":2,"method":"media.import","params":{"path":"/edits/Rough cut","file":"/footage/a.mp4"}}
-{"jsonrpc":"2.0","id":3,"method":"media.import","params":{"path":"/edits/Rough cut","file":"/footage/b.mp4"}}
-{"jsonrpc":"2.0","id":4,"method":"edit.apply","params":{"path":"/edits/Rough cut","command":{"op":"addClip","mediaId":"m1","trackId":"T1","start":0}}}
-{"jsonrpc":"2.0","id":5,"method":"project.get","params":{"path":"/edits/Rough cut"}}
-```
-
-Read the clip's `duration` from the `project.get` reply, then place the
-next clip at that `start`. Python does the bookkeeping:
-
-```python
-import glob, os
-c = Concat(token=TOKEN)
-folder = "/edits/Rough cut"
-c.call("project.create", location="/edits", name="Rough cut")
-
-at = 0.0
-for file in sorted(glob.glob("/footage/*.mp4")):
- view = c.call("media.import", path=folder, file=file)
- media_id = view["createdId"]
- view = c.call("edit.apply", path=folder,
- command={"op": "addClip", "mediaId": media_id, "trackId": "T1", "start": at})
- clip = next(cl for cl in view["project"]["timelines"][0]["clips"] if cl["id"] == view["createdId"])
- at += clip["duration"]
-
-c.call("project.save", path=folder)
-```
-
-> [!TIP]
-> `media.import` on a file already in the bin is a no-op and returns no
-> `createdId`. Look the id up in `project.media` by `path` if you re-run.
-
----
-
-## 2. Export and show progress
-
-**Lines:**
-
-```jsonl
-{"jsonrpc":"2.0","id":1,"method":"project.open","params":{"path":"/edits/Reel"}}
-{"jsonrpc":"2.0","id":2,"method":"export.run","params":{"path":"/edits/Reel","output":"/edits/reel.mp4","crf":18,"preset":"slow","codec":"h264"}}
-```
-
-The CLI keeps running until the job ends, printing each event.
-
-**Python**, with a progress line:
-
-```python
-def show(event):
- p = event["params"]
- if event["method"] == "export.progress":
- print(f'\r{p["stage"]:5} {p["frame"]}/{p["total"]}', end="")
- elif event["method"] == "cutout.progress":
- print(f'\rcutout {p["mediaId"]} {"fetching" if p["fetching"] else "analysing"} {p["fraction"]:.0%}', end="")
-
-c = Concat(token=TOKEN, on_event=show)
-c.call("project.open", path="/edits/Reel")
-started = c.call("export.run", path="/edits/Reel", output="/edits/reel.mp4", crf=18)
-end = c.wait_for_job(started["job"])
-print()
-if end["method"] == "export.done":
- print("wrote", end["params"]["output"])
-else:
- print("failed:", end["params"]["error"]["message"])
-```
-
-To stop it from another connection:
-
-```json
-{"jsonrpc":"2.0","id":9,"method":"export.cancel","params":{"job":"j1"}}
-```
-
-The job then ends with `export.failed` and `error.code` = `cancelled`.
-
----
-
-## 3. A title card
-
-A three-second title on its own lane above the footage, then a lower
-third.
-
-```jsonl
-{"jsonrpc":"2.0","id":1,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addTextClip","above":true,"start":0,"duration":3,"style":{"content":"Summer 2026","fontSize":0.14}}}}
-{"jsonrpc":"2.0","id":2,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addTextClip","above":true,"start":5,"duration":4,"offsetY":0.35,"style":{"content":"Ada Lovelace\nEngine designer","fontSize":0.05,"align":"left","background":"#00000099","maxWidth":0.5}}}}
-```
-
-Only the style fields you set change; the rest are the window's defaults
-(white, bold, centred, with a shadow). All of them are in
-[Types → TextStyle](api/types.md#textstyle).
-
-Change a title later with a patch. Absent fields stay, `null` clears:
-
-```json
-{"op":"updateClip","clipId":"c7","patch":{"text":{"content":"Summer 2026","color":"#ffcc00"}}}
-```
-
----
-
-## 4. A look on every clip
-
-Find a filter, then set it on each video clip.
-
-```python
-looks = c.call("catalogue.list", kind="filter")
-print([p["id"] for p in looks]) # e.g. concat.warm, concat.film, concat.mono …
-
-view = c.call("project.get", path="/edits/Reel")
-timeline = next(t for t in view["project"]["timelines"] if t["id"] == view["project"]["activeTimelineId"])
-commands = [
- {"op": "updateClip", "clipId": clip["id"],
- "patch": {"videoEffects": clip["videoEffects"] + [{"id": "concat.film", "params": {}}]}}
- for clip in timeline["clips"] if clip["kind"] == "video"
-]
-c.call("edit.apply", path="/edits/Reel", command={"op": "batch", "commands": commands})
-```
-
-Notes:
-
-- `videoEffects` in a patch **replaces** the chain, so append to what the
- clip has.
-- Empty `params` means the package's defaults. The keys and ranges are in
- the `catalogue.list` reply.
-- One `batch` means one undo step for the whole pass.
-
-The same over everything at once, as a layer instead of per clip:
-
-```json
-{"op":"addLayerClip","start":0,"duration":60,"effectId":"concat.film","name":"Film look"}
-```
-
----
-
-## 5. A contact sheet of frames
-
-One PNG a second, to a folder.
-
-```python
-view = c.call("project.open", path="/edits/Reel")
-timeline = next(t for t in view["project"]["timelines"] if t["id"] == view["project"]["activeTimelineId"])
-length = max((cl["start"] + cl["duration"] for cl in timeline["clips"]), default=0)
-
-t = 0.0
-while t < length:
- c.call("preview.frame", path="/edits/Reel", time=t, output=f"/edits/frames/{t:06.1f}.png", width=320, height=180)
- t += 1.0
-```
-
-Or one frame straight into memory:
-
-```python
-import base64
-pic = c.call("preview.frame", path="/edits/Reel", time=2.5)
-png_bytes = base64.b64decode(pic["png"])
-```
-
----
-
-## 6. A project from a template
-
-```python
-templates = c.call("template.list")
-intro = next(t for t in templates if t["name"] == "Intro")
-for slot in intro["slots"]:
- print(slot["mediaId"], slot["name"], slot["kind"], f'{slot["seconds"]:.1f}s')
-
-fills = [
- {"mediaId": intro["slots"][0]["mediaId"], "file": "/footage/logo.png"},
- {"mediaId": intro["slots"][1]["mediaId"], "file": "/footage/take1.mp4"},
-]
-view = c.call("template.instantiate", template=intro["path"], location="/edits", name="My intro", fills=fills)
-```
-
-Every slot must be filled, and every file is probed before anything is
-made. To make a template from a project you have open:
-
-```json
-{"jsonrpc":"2.0","id":1,"method":"template.save","params":{"path":"/edits/Reel","name":"Reel template"}}
-```
-
----
-
-## 7. A vertical cut of a landscape edit
-
-A second timeline in the same project, 1080×1920, with the same clips
-re-framed.
-
-```jsonl
-{"jsonrpc":"2.0","id":1,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addTimeline"}}}
-{"jsonrpc":"2.0","id":2,"method":"project.setVideo","params":{"path":"/edits/Reel","video":{"width":1080,"height":1920,"rateNum":30,"rateDen":1}}}
-{"jsonrpc":"2.0","id":3,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addClipAtFirstFree","mediaId":"m1","start":0}}}
-{"jsonrpc":"2.0","id":4,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"setClipTransform","clipId":"c9","scale":1.8,"offsetX":-0.1}}}
-{"jsonrpc":"2.0","id":5,"method":"export.run","params":{"path":"/edits/Reel","output":"/edits/reel-vertical.mp4"}}
-```
-
-`addTimeline` makes the new timeline active, so the `project.setVideo`
-and the edits that follow land on it. Switch back with
-`{"op":"selectTimeline","timelineId":"TL1"}`. The clip id `c9` above is
-whatever `createdId` came back from the add.
-
----
-
-## 8. Undo, redo, save
-
-```jsonl
-{"jsonrpc":"2.0","id":1,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"removeClips","clipIds":["c2"],"ripple":true}}}
-{"jsonrpc":"2.0","id":2,"method":"edit.undo","params":{"path":"/edits/Reel"}}
-{"jsonrpc":"2.0","id":3,"method":"edit.redo","params":{"path":"/edits/Reel"}}
-{"jsonrpc":"2.0","id":4,"method":"project.save","params":{"path":"/edits/Reel"}}
-{"jsonrpc":"2.0","id":5,"method":"project.close","params":{"path":"/edits/Reel"}}
-```
-
-Every reply's `canUndo` / `canRedo` tells you where the history stands.
-A tolerated no-op (an unknown id, a value already held) records no undo
-step.
-
----
-
-## 9. Inspect a project without changing it
-
-```sh
-cd src
-cargo run -p concat-cli -- api '{"method":"project.open","path":"/edits/Reel"}' | python3 -c '
-import json, sys
-view = json.loads(sys.stdin.readline())["result"]
-p = view["project"]
-print(view["settings"])
-for t in p["timelines"]:
- print(t["id"], t["name"], f'{t["video"]["width"]}x{t["video"]["height"]}')
- for clip in sorted(t["clips"], key=lambda c: c["start"]):
- print(f' {clip["id"]:5} {clip["kind"]:5} {clip["start"]:7.2f} +{clip["duration"]:6.2f} {clip["name"]}')
-'
-```
-
-Opening does not change the project document; nothing in the folder is
-written unless you call `project.save`. The only side effect is the
-recents list, which moves the project to the front.
diff --git a/docs/transports/grpc.md b/docs/transports/grpc.md
deleted file mode 100644
index 399a5996..00000000
--- a/docs/transports/grpc.md
+++ /dev/null
@@ -1,191 +0,0 @@
-# gRPC
-
-**In one line:** the same API over HTTP/2 with generated clients. Two
-RPCs, `Call` and `Events`, carrying the API's JSON as text.
-
-**On this page:** [Build and run](#build-and-run) · [The service](#the-service)
-· [The token](#the-token) · [Errors](#errors) · [Try it with grpcurl](#try-it-with-grpcurl)
-· [Clients](#clients) · [Why an envelope](#why-an-envelope-and-not-a-second-schema)
-
----
-
-## Build and run
-
-gRPC is behind the `grpc` feature. It is off by default because it brings
-tokio and hyper, which nothing else in the workspace needs. CI builds and
-tests it on every change.
-
-```sh
-cd src
-cargo run -p concat-cli --features grpc -- serve --grpc 127.0.0.1:7421
-```
-
-```
-Concat API 0.2: gRPC on 127.0.0.1:7421
-Concat API 0.2: token 3f9c1e…
-```
-
-`--grpc` combines with `--json` and `--socket`; all callers share one
-dispatcher. A build without the feature refuses `--grpc` with a message
-saying so.
-
-> [!NOTE]
-> The window's Remote page serves JSON-RPC only. For gRPC, run
-> `concat-cli serve`.
-
----
-
-## The service
-
-`src/crates/concat-server/proto/concat.proto`, package `concat.v1`:
-
-```proto
-service Concat {
- rpc Call (Request) returns (Response); // one call, one response
- rpc Events (EventsRequest) returns (stream Event); // every job's events, while open
-}
-
-message Request { string method = 1; string params = 2; } // params: JSON text, or empty
-message Response { oneof outcome { string result = 1; Error error = 2; } }
-message Error { string code = 1; int32 number = 2; string message = 3; }
-message EventsRequest {}
-message Event { string event = 1; string params = 2; } // params: JSON text
-```
-
-| Field | Holds |
-|---|---|
-| `Request.method` | The method name, e.g. `"edit.apply"` |
-| `Request.params` | The params object as JSON text. Empty for a method with none |
-| `Response.result` | The reply as JSON text: exactly what a JSON-RPC `result` holds |
-| `Response.error` | `code` is the API's name (`notOpen`, …), `number` its JSON-RPC number, `message` the sentence |
-| `Event.event` | `"export.progress"`, … |
-| `Event.params` | Its fields as JSON text |
-
-Everything in [Methods](../api/methods.md), [Edit commands](../api/edits.md)
-and [Types](../api/types.md) applies unchanged. Parse `result` and
-`params` with your JSON library.
-
----
-
-## The token
-
-Every call carries the server's token as bearer metadata:
-
-```
-authorization: Bearer 3f9c1e…
-```
-
-Missing or wrong: the RPC fails with status `UNAUTHENTICATED`. This
-applies to `Events` too. The comparison is constant-time. Where the token
-comes from is in [JSON-RPC → The token](json-rpc.md#the-token).
-
----
-
-## Errors
-
-Two layers, deliberately kept apart:
-
-| Layer | Means | Looks like |
-|---|---|---|
-| gRPC status | the transport refused | `UNAUTHENTICATED` (token), `INTERNAL` (the server could not run the call at all) |
-| `Response.error` | the API refused | `{code: "notOpen", number: -32001, message: "…"}` with the call itself returning `OK` |
-
-So a `Call` that returns `OK` still needs its `outcome` checked.
-
----
-
-## Try it with grpcurl
-
-There is no reflection service; hand grpcurl the proto.
-
-```sh
-PROTO=src/crates/concat-server/proto/concat.proto
-TOKEN=3f9c1e…
-
-grpcurl -plaintext -proto $PROTO -H "authorization: Bearer $TOKEN" \
- -d '{"method":"version","params":""}' \
- 127.0.0.1:7421 concat.v1.Concat/Call
-```
-
-```json
-{"result": "{\"apiVersion\":\"0.2\",\"concat\":\"0.2.4\",\"dirs\":{…},\"capabilities\":[\"events\",\"grpc\"]}"}
-```
-
-An edit:
-
-```sh
-grpcurl -plaintext -proto $PROTO -H "authorization: Bearer $TOKEN" \
- -d '{"method":"edit.apply","params":"{\"path\":\"/edits/Reel\",\"command\":{\"op\":\"addTrack\"}}"}' \
- 127.0.0.1:7421 concat.v1.Concat/Call
-```
-
-Events, streamed until you stop it:
-
-```sh
-grpcurl -plaintext -proto $PROTO -H "authorization: Bearer $TOKEN" \
- -d '{}' 127.0.0.1:7421 concat.v1.Concat/Events
-```
-
----
-
-## Clients
-
-### Rust
-
-The generated client ships in the crate under the feature:
-
-```rust
-use concat_server::grpc::proto::{concat_client::ConcatClient, Request as Call, EventsRequest};
-use tonic::Request;
-
-let mut client = ConcatClient::connect("http://127.0.0.1:7421").await?;
-let mut request = Request::new(Call { method: "version".into(), params: String::new() });
-request.metadata_mut().insert("authorization", format!("Bearer {token}").parse()?);
-let response = client.call(request).await?.into_inner();
-```
-
-### Python
-
-```sh
-pip install grpcio grpcio-tools
-python -m grpc_tools.protoc -I src/crates/concat-server/proto \
- --python_out=. --grpc_python_out=. concat.proto
-```
-
-```python
-import json, grpc, concat_pb2, concat_pb2_grpc
-
-channel = grpc.insecure_channel("127.0.0.1:7421")
-stub = concat_pb2_grpc.ConcatStub(channel)
-meta = [("authorization", f"Bearer {TOKEN}")]
-
-def call(method, **params):
- req = concat_pb2.Request(method=method, params=json.dumps(params) if params else "")
- res = stub.Call(req, metadata=meta)
- if res.HasField("error"):
- raise RuntimeError(f"{res.error.code}: {res.error.message}")
- return json.loads(res.result)
-
-print(call("version")["capabilities"])
-for event in stub.Events(concat_pb2.EventsRequest(), metadata=meta):
- print(event.event, json.loads(event.params))
-```
-
-### Anything else
-
-Any language with a protobuf and gRPC toolchain: generate from
-`concat.proto`, send the bearer, parse the JSON text.
-
----
-
-## Why an envelope and not a second schema
-
-The protobuf carries JSON text rather than typed messages on purpose:
-
-- A method added to the API reaches gRPC with **no change** to the proto.
-- There is **one set of docs** for every transport.
-- Both transports parse requests through the same code, so they refuse
- the same things the same way.
-
-What gRPC adds over the line transport is HTTP/2, generated clients, and
-a streamed reply for events.
diff --git a/docs/transports/json-rpc.md b/docs/transports/json-rpc.md
deleted file mode 100644
index ed4746ff..00000000
--- a/docs/transports/json-rpc.md
+++ /dev/null
@@ -1,257 +0,0 @@
-# JSON-RPC
-
-**In one line:** one JSON object per line, in and out, over stdin, TCP or a
-Unix socket. The same lines everywhere.
-
-**On this page:** [The envelope](#the-envelope) · [Over stdin](#over-stdin-concat-cli-api)
-· [Over a socket](#over-a-socket-concat-cli-serve) · [From the window](#from-the-window)
-· [The token](#the-token) · [Events](#events) · [Security](#security) ·
-[Python client](#a-minimal-python-client)
-
----
-
-## The envelope
-
-A call, its response, and an event, as JSON-RPC 2.0:
-
-```json
-{"jsonrpc":"2.0","id":1,"method":"project.open","params":{"path":"/edits/Reel"}}
-```
-```json
-{"jsonrpc":"2.0","id":1,"result":{"project":{"…":"…"},"canUndo":false,"canRedo":false,"settings":{"…":"…"}}}
-```
-```json
-{"jsonrpc":"2.0","id":1,"error":{"code":-32001,"message":"/edits/Reel is not open - open it first","data":{"code":"notOpen"}}}
-```
-```json
-{"jsonrpc":"2.0","method":"export.progress","params":{"job":"j1","path":"/edits/Reel","frame":30,"total":150,"stage":"video"}}
-```
-
-Rules:
-
-| Rule | Detail |
-|---|---|
-| One object per line | Newline-delimited. No pretty printing across lines |
-| `id` is yours | A string, a number or null. It comes back as given. Anything else is `invalid` |
-| Every call is answered | Even one without an `id` (the reply's `id` is `null`) |
-| `params` is an object | The method's fields. Omit it for a method with none |
-| Errors carry two codes | `error.code` is the JSON-RPC number, `error.data.code` is the API's name. See [Errors](../api/overview.md#errors) |
-| Events are notifications | No `id`. `method` is the event's name, `params` its fields |
-
-> [!TIP]
-> **The bare shape is accepted too.** `{"method": "version"}` with no
-> envelope is the request as it is, and it is answered with `"id": null`.
-> Handy when typing by hand.
-
----
-
-## Over stdin: `concat-cli api`
-
-From a source checkout:
-
-```sh
-cd src
-cargo run -p concat-cli -- api '{"method":"catalogue.list","kind":"filter"}' # one request
-cargo run -p concat-cli -- api < edits.jsonl # one call per line
-```
-
-How it behaves:
-
-- Reads a line, answers it, flushes. Blank lines are skipped.
-- Writes events between responses as they happen, never half a line.
-- A line that is not a call gets an error response; the loop goes on.
-- At end of input it **waits for running jobs**, so an export begun on
- the last line still finishes and its events are written.
-
-No token, no socket. The process is yours.
-
----
-
-## Over a socket: `concat-cli serve`
-
-```sh
-cd src
-cargo run -p concat-cli -- serve # JSON-RPC on 127.0.0.1:7420
-cargo run -p concat-cli -- serve --json 0.0.0.0:7420 # any interface (read Security first)
-cargo run -p concat-cli -- serve --socket /tmp/concat.sock # a Unix socket
-cargo run -p concat-cli -- serve --token "my secret" # your own token
-```
-
-It prints where it listens and the token to present, then serves until
-stopped:
-
-```
-Concat API 0.2: JSON-RPC on 127.0.0.1:7420
-Concat API 0.2: token 3f9c1e…
-```
-
-| Flag | Meaning |
-|---|---|
-| `--json ADDR` | TCP address for JSON-RPC lines. Default `127.0.0.1:7420` when nothing else is asked for |
-| `--socket PATH` | A Unix socket path (Unix only). A file already there is replaced |
-| `--grpc ADDR` | gRPC, in a build with the feature. See [gRPC](grpc.md) |
-| `--token TOKEN` | The token every connection presents. Also `CONCAT_API_TOKEN`. Minted when absent |
-| `--root DIR` | A folder the API may write under. Repeatable. Your home when absent; `--root /` for anywhere |
-
-Several flags at once serve on all of them. All callers share one
-dispatcher and its open projects.
-
----
-
-## From the window
-
-**Settings › Remote** serves the same JSON-RPC lines while the editor is
-open.
-
-| Control | Meaning |
-|---|---|
-| **Serve the API** | The switch. Remembered across launches |
-| **Address** | Host and port. Default `127.0.0.1:7420` |
-| **Token** | Yours, or one the window mints and shows you when the field is empty |
-| Status line | "Listening on … · N connected", or why the bind failed |
-
-A caller on the socket edits projects of its own, never the one on
-screen: a folder the window has open is `refused` over the socket, and
-the window refuses to open one a caller holds. The export slot is shared,
-so one export at a time holds across the two. The API writes under your
-home folder.
-
----
-
-## The token
-
-Every connection, **loopback included**, presents the token as its
-**first line**, as a call to `auth`:
-
-```json
-{"jsonrpc":"2.0","id":0,"method":"auth","params":{"token":"3f9c1e…"}}
-```
-```json
-{"jsonrpc":"2.0","id":0,"result":{}}
-```
-
-- Anything else first, or the wrong token: an `unauthorized` error and
- the connection is closed.
-- `auth` is the transport's word, not the API's. It never reaches the
- dispatcher and is not a method you call again.
-- The comparison is constant-time.
-- With no token configured, the server **mints one** (128 bits, 32 hex
- digits) that only the process that started it knows: printed by
- `concat-cli serve`, shown on the window's Remote page.
-
-Why loopback too: another user's process on the same machine reaches
-`127.0.0.1` as easily as yours does.
-
----
-
-## Events
-
-Once authenticated, a connection receives **every** event from every job,
-whoever started it. Each names its `job` and `path`; keep the ones you
-asked for.
-
-Responses and events share one writer per connection, so a line is never
-interleaved with another. But an event can arrive **between** your call
-and its response. Read by `method` versus `id`, not by position:
-
-```
-you → {"jsonrpc":"2.0","id":7,"method":"project.get",...}
- ← {"jsonrpc":"2.0","method":"export.progress","params":{...}} ← someone's job
- ← {"jsonrpc":"2.0","id":7,"result":{...}} ← your answer
-```
-
----
-
-## Security
-
-> [!WARNING]
-> A server is a door into the machine, as the user running it. The door
-> is narrow, and the token is the only key.
-
-- **No encryption.** Bind off loopback only behind something that
- provides it (an SSH tunnel, a reverse proxy with TLS).
-- The token gates the door; the network is the wall. Do not put the port
- on the open internet.
-- **Writes stay under the roots.** A created project, an instantiated
- template, an export and a preview file must land under a `--root` (the
- window: your home folder); anything else is `refused`, and a path with
- `..` in it always is. Reads are not confined: anyone with the token can
- probe any file the server's user can read and open any project folder.
-- **Sizes are bounded.** A frame or an export is at most 8192 a side, an
- export's frame rate at most 240 a second and its `crf` at most 63:
- anything larger is `invalid`.
-- **The transport has limits.** A line is at most 4 MiB (the `auth` line
- 4 KiB); a caller has ten seconds to present its token; at most 64
- callers are connected at once, the next is answered `busy` and closed;
- a caller that stops reading is hung up on once 256 lines are waiting
- for it.
-
----
-
-## A minimal Python client
-
-Standard library only. Handles the handshake, matches responses by `id`,
-and hands events to a callback.
-
-```python
-import json, socket, itertools
-
-class Concat:
- def __init__(self, host="127.0.0.1", port=7420, token="", on_event=None):
- self.sock = socket.create_connection((host, port))
- self.reader = self.sock.makefile("r", encoding="utf-8")
- self.ids = itertools.count(1)
- self.on_event = on_event or (lambda e: None)
- self._send({"jsonrpc": "2.0", "id": 0, "method": "auth", "params": {"token": token}})
- self._wait(0)
-
- def call(self, method, **params):
- rid = next(self.ids)
- self._send({"jsonrpc": "2.0", "id": rid, "method": method, "params": params})
- return self._wait(rid)
-
- def wait_for_job(self, job):
- """Blocks until export.done / export.failed for `job`; returns the event."""
- while True:
- msg = self._read()
- if "id" in msg:
- continue # a response to something else; not expected here
- self.on_event(msg)
- if msg["params"].get("job") == job and msg["method"] in ("export.done", "export.failed"):
- return msg
-
- def _send(self, obj):
- self.sock.sendall((json.dumps(obj) + "\n").encode("utf-8"))
-
- def _read(self):
- line = self.reader.readline()
- if not line:
- raise ConnectionError("server closed the connection")
- return json.loads(line)
-
- def _wait(self, rid):
- while True:
- msg = self._read()
- if "id" not in msg:
- self.on_event(msg) # an event; keep waiting
- continue
- if msg["id"] != rid:
- continue # not ours; keep waiting
- if "error" in msg:
- raise RuntimeError(f'{msg["error"]["data"]["code"]}: {msg["error"]["message"]}')
- return msg["result"]
-```
-
-Use it:
-
-```python
-c = Concat(token="3f9c1e…", on_event=lambda e: print(e["method"], e["params"]))
-print(c.call("version")["capabilities"])
-view = c.call("project.create", location="/edits", name="Reel")
-view = c.call("media.import", path="/edits/Reel", file="/footage/take1.mp4")
-c.call("edit.apply", path="/edits/Reel", command={"op": "addClipAtFirstFree", "mediaId": view["createdId"], "start": 0})
-started = c.call("export.run", path="/edits/Reel", output="/edits/reel.mp4")
-print(c.wait_for_job(started["job"]))
-```
-
-More in [Recipes](../recipes.md).
diff --git a/docs/transports/mcp.md b/docs/transports/mcp.md
deleted file mode 100644
index 96869563..00000000
--- a/docs/transports/mcp.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# MCP
-
-**In one line:** an MCP server for Concat is planned and prototyped, not
-shipped. This page says what exists, what it should look like, and how to
-connect an agent today.
-
-**Status:** 🚧 not in this tree.
-
-**On this page:** [What exists](#what-exists) · [The shape it should take](#the-shape-it-should-take)
-· [Bridging today](#bridging-today) · [Guidance for agents](#guidance-for-agents)
-
----
-
-## What exists
-
-| Thing | Where | State |
-|---|---|---|
-| The API an MCP server would expose | `concat-api` | ✅ Shipped. Every method in [Methods](../api/methods.md) |
-| A socket server with a token and event fan-out | `concat-server` | ✅ Shipped. [JSON-RPC](json-rpc.md), [gRPC](grpc.md) |
-| A prototype: the window serving MCP over Streamable HTTP with 17 tools, plus a stdio Python bridge | [PR #69](https://github.com/jub0t/Concat/pull/69) | ❌ Closed, not merged. It re-implemented the transport instead of reusing `concat-server` |
-| The request | [issue #95 "MCP support"](https://github.com/jub0t/Concat/issues/95) | Closed on 2026-09-19 with a pointer to the documentation issue [#123](https://github.com/jub0t/Concat/issues/123) |
-
-The design direction, from the September 2026 audit: build the MCP server
-on the official Rust SDK (`rmcp`) over `concat-server`'s `Hub`, so it is a
-third transport beside JSON-RPC and gRPC and not a second API.
-
----
-
-## The shape it should take
-
-The API is already close to a tool set. The intended mapping:
-
-| MCP concept | Concat |
-|---|---|
-| A **tool** | One API method. `project.open`, `edit.apply`, `export.run`, … Names, params and results as in [Methods](../api/methods.md) |
-| A tool's **input schema** | The method's params. For `edit.apply`, the `command` union in [Edit commands](../api/edits.md) |
-| A tool **result** | The reply payload as JSON; a `preview.frame` reply as an image content block |
-| A **notification** / progress | The job events: `export.progress`, `export.done`, `export.failed`, `cutout.progress` |
-| A **resource** | `concat://project/<path>` for `project.get`; the catalogue as `concat://catalogue` |
-| **Auth** | The same token `concat-server` mints, as a bearer |
-
-Principles that carry over from the other transports:
-
-- **No new meaning in the transport.** A tool calls a method; it does not
- interpret the edit.
-- **Refusals are the window's sentences.** An agent that hits `refused`
- can show or reason about the message as it is.
-- **Discover, don't assume.** `version` → `capabilities`, and
- `catalogue.list` → what effects exist, before building a chain.
-
----
-
-## Bridging today
-
-Until the server ships, an agent reaches Concat through a small MCP
-server that wraps the JSON-RPC socket. Three moving parts:
-
-1. `concat-cli serve` (or the window's Remote page), listening on
- `127.0.0.1:7420` with a token.
-2. A stdio MCP server, spawned by the agent's host, that opens one socket
- connection and turns tool calls into `call(method, params)`.
-3. Tool definitions that mirror the methods.
-
-A sketch in Python, using the `Concat` class from
-[JSON-RPC → Python client](json-rpc.md#a-minimal-python-client) and the
-`mcp` package:
-
-```python
-# concat_mcp.py — run with: python concat_mcp.py (the host spawns it over stdio)
-import os
-from mcp.server.fastmcp import FastMCP
-from concat_client import Concat # the class from the JSON-RPC page
-
-api = Concat(port=int(os.environ.get("CONCAT_PORT", 7420)), token=os.environ["CONCAT_API_TOKEN"])
-mcp = FastMCP("concat")
-
-def version() -> dict:
- """What this Concat build serves."""
- return api.call("version")
-
-def project_open(path: str) -> dict:
- """Open a project folder. Returns the editor view."""
- return api.call("project.open", path=path)
-
-def project_create(location: str, name: str) -> dict:
- """Create a project folder under `location` and open it."""
- return api.call("project.create", location=location, name=name)
-
-def media_import(path: str, file: str) -> dict:
- """Probe a file and add it to the project's bin."""
- return api.call("media.import", path=path, file=file)
-
-def edit_apply(path: str, command: dict) -> dict:
- """Apply one edit command ({"op": ..., ...}). See docs/api/edits.md."""
- return api.call("edit.apply", path=path, command=command)
-
-def catalogue_list(kind: str | None = None) -> list:
- """Effect packages and their parameters."""
- return api.call("catalogue.list", **({"kind": kind} if kind else {}))
-
-def export_run(path: str, output: str) -> dict:
- """Render the timeline to a file and wait for it to finish."""
- started = api.call("export.run", path=path, output=output)
- return api.wait_for_job(started["job"])["params"]
-
-if __name__ == "__main__":
- mcp.run()
-```
-
-Register it with the host as a stdio server with `CONCAT_API_TOKEN` in
-its environment. The exact registration is the host's; the server above
-speaks standard MCP over stdio.
-
-> [!NOTE]
-> This is a bridge, not the product. It has one connection, no streaming
-> progress, and a hand-picked tool list. The shipped server will expose
-> every method and stream events.
-
----
-
-## Guidance for agents
-
-If you are an agent reading this because you have been pointed at Concat:
-
-1. Call `version`. Check `apiVersion` starts with `0.2` and read
- `capabilities`.
-2. Open or create a project. Keep its **folder path**; every call needs
- it.
-3. Import media with `media.import`. The reply's `createdId` is the media
- id.
-4. Place clips with `addClipAtFirstFree` or `addClip`. Read the returned
- `EditorView` for clip ids; do not guess them.
-5. Prefer one `batch` for a sequence of edits that belong together.
-6. Export with `export.run`, then wait for `export.done` or
- `export.failed` for **that job**. Do not start a second export
- meanwhile; it is refused with `busy`.
-7. Treat a `refused` message as the reason, in plain words. Nothing
- changed.
-8. Save with `project.save` before `project.close`, or pass `save: true`.
-
-[Recipes](../recipes.md) has complete scripts for each of these.
diff --git a/src/README.md b/src/README.md
index dd0c2f0a..26672c68 100644
--- a/src/README.md
+++ b/src/README.md
@@ -134,8 +134,9 @@ number means and what is not measured.
## Driving Concat without the window
The full reference - every method, every edit command, every type, and a
-page per transport - is in [`docs/`](../docs/README.md) at the repository
-root. What follows is the short version.
+page per transport - lives on the website at
+[concatenate.pages.dev/docs](https://concatenate.pages.dev/docs). What follows
+is the short version.
Everything the window does to a project, a script can do through the Concat
API: `concat-api` is the one dispatcher, and the transports only carry it.