The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.
Rust ffmpegfree-video-editormodel-context-protocolnon-linear-editoroffline-firstopen-source-video-editorself-hostedvideo-editingvideo-editing-automationvideo-editing-softwarevideo-editing-toolsvideo-editorvoice-cloningyoutube-automationyoutube-shorts
Move the developer docs to the website and drop the tier prices from the README
Jareer794ca4cb1f8f
diff --git a/README.md b/README.mdindex 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.mdindex 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 windowThe 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 ConcatAPI: `concat-api` is the one dispatcher, and the transports only carry it.