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
docs(api): developer documentation for the Concat API under docs/
Jareera0c42068f625
diff --git a/README.md b/README.mdindex 5257858d..e8da0c74 100644--- a/README.md+++ b/README.md@@ -89,7 +89,7 @@ Optional models download from the settings panel on first use and then never nee> [!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. Want to write an effect, a filter or a transition instead? [EFFECTS.md](./EFFECTS.md) is the whole of it: a folder, a manifest, and a chain or a shader, loaded from your effects folder while the app runs. [ROADMAP.MD](./ROADMAP.MD) says where the project is going, and [this Discussion](https://github.com/jub0t/Concat/discussions/3) is where it 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. Want to write an effect, a filter or a transition instead? [EFFECTS.md](./EFFECTS.md) is the whole of it: a folder, a manifest, and a chain or a shader, loaded from your effects folder while the app runs. 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. [ROADMAP.MD](./ROADMAP.MD) says where the project is going, and [this Discussion](https://github.com/jub0t/Concat/discussions/3) is where it was announced.>> Contributors are free to claim a `@Contributor` role in the Discord server, just ask for it.diff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 00000000..be1a1730--- /dev/null+++ b/docs/README.md@@ -0,0 +1,112 @@+<!-- 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.3","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; [`EFFECTS.md`](../EFFECTS.md) is for writing the packages the+catalogue lists.++## 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.mdnew file mode 100644index 00000000..73ffcfc0--- /dev/null+++ b/docs/api/edits.md@@ -0,0 +1,632 @@+# 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 | |+| [`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 | |+| [`setClipAnimation`](#setclipanimation) | a named in/out/combo/loop shape | |+| [`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 |++### `replaceClipMedia`++Points a clip at another file, adding it to the bin first if it is not+there. The clip keeps its in-point, length, looks and name; the copy stands+in frame for frame. The bin keeps the original.++| Field | Type | Meaning |+|---|---|---|+| `clipId` | string | The clip. Unknown id: no-op |+| `item` | *NewMedia* | The probed file |++---++## 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 captions use |+| `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 |+| `reverse` | bool | Play backwards |+| `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 |++### `setClipAnimation`++A named shape on one slot of the clip.++| Field | Type | Meaning |+|---|---|---|+| `clipId` | string | The clip |+| `slot` | `"in"`, `"out"`, `"combo"`, `"loop"` | Which slot |+| `animation` | `{preset, duration}` or `null` | `preset` is a name the inspector's menu offers for that slot (e.g. `"Fade"`, `"Zoom In"`, `"Slide Up"`, `"Pulse"`, `"Shake"`); `duration` in seconds for in/out. `null` takes it off |++### `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.mdnew file mode 100644index 00000000..956a13a1--- /dev/null+++ b/docs/api/methods.md@@ -0,0 +1,526 @@+# 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.3",+ "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`).++---++## `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.++---++## `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` |++```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`.+- An empty timeline is `refused`.+- `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`.+- 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.mdnew file mode 100644index 00000000..6a12e60e--- /dev/null+++ b/docs/api/overview.md@@ -0,0 +1,228 @@+# 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.mdnew file mode 100644index 00000000..650d9b25--- /dev/null+++ b/docs/api/types.md@@ -0,0 +1,443 @@+# 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* |+| `reverse` | bool | *optional* |+| `animationIn`, `animationOut`, `animationCombo`, `animationLoop` | `{preset, duration}` | *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 |++### 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 plate colour behind the text; empty is none |+| `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`.++> [!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"`).++**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.mdnew file mode 100644index 00000000..2954e96f--- /dev/null+++ b/docs/recipes.md@@ -0,0 +1,265 @@+# 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.black-white …++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.mdnew file mode 100644index 00000000..679121fe--- /dev/null+++ b/docs/transports/grpc.md@@ -0,0 +1,191 @@+# 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.3\",\"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.mdnew file mode 100644index 00000000..6f135327--- /dev/null+++ b/docs/transports/json-rpc.md@@ -0,0 +1,243 @@+# 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 |++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 |++Edits made over the socket land in the same session the window shows.+What you can do from the window, you can do from the socket, and the+other way round.++---++## 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]+> The API reads and writes whatever paths it is given, as the user running+> it. A server is a door into the machine.++- **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.+- Anyone with the token can create, edit and export projects and read any+ file the server's user can read.++---++## 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.mdnew file mode 100644index 00000000..6cdab2b8--- /dev/null+++ b/docs/transports/mcp.md@@ -0,0 +1,148 @@+# 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 [roadmap](../../ROADMAP.MD) lists MCP integrations under the Concat API |++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 5c68acfe..8a891606 100644--- a/src/README.md+++ b/src/README.md@@ -133,6 +133,10 @@ number means and what is not measured.## Driving Concat without the window+The full reference - every method, every edit command, every type, and a+page per transport - is in [`docs/`](../docs/README.md) at the repository+root. What follows is the short version.+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.On a line - stdin, TCP, a Unix socket - a call is JSON-RPC 2.0, one object