{ "openapi": "3.1.0", "info": { "title": "Tomocles", "version": "0.0.1", "description": "The local REST surface of the Tomocles desktop app: every op the editor can perform, on loopback only, authenticated with the per-install bearer token. Generated from the op registry; not a hosted API.", "license": { "name": "Proprietary", "identifier": "LicenseRef-Tomocles-Proprietary" } }, "servers": [ { "url": "http://127.0.0.1:{port}", "description": "The running app, loopback only. The port is chosen at launch.", "variables": { "port": { "default": "8000" } } } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Assets" }, { "name": "Audio" }, { "name": "Auth" }, { "name": "Captions" }, { "name": "Clips" }, { "name": "Documents" }, { "name": "Exports" }, { "name": "Framing" }, { "name": "Groups" }, { "name": "Health" }, { "name": "History" }, { "name": "Licence" }, { "name": "Links" }, { "name": "Lint" }, { "name": "Media" }, { "name": "Presets" }, { "name": "Projection" }, { "name": "Projects" }, { "name": "Quotes" }, { "name": "Render" }, { "name": "Scenes" }, { "name": "Screencast" }, { "name": "Sequences" }, { "name": "Session" }, { "name": "Speed" }, { "name": "Streams" }, { "name": "Suggest" }, { "name": "Takes" }, { "name": "Targets" }, { "name": "Titles" }, { "name": "Tracks" }, { "name": "Transitions" }, { "name": "ops" } ], "paths": { "/api/licenceStatus": { "get": { "operationId": "licenceStatus", "summary": "The install's licence as it stands: the state (`valid`, `trial`, `expired-upgrades`, `invalid`, `none`), the claims that matter, the trial's days left, what the last activation ping said. A pure read: no network, nothing written (the daily ping rides `openProject`).", "tags": [ "ops", "Licence" ], "description": "A read model: derived from the document, records no event.", "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/listRecent": { "get": { "operationId": "listRecent", "summary": "The projects this install has created or opened, newest first — the door's Recent list.", "tags": [ "ops", "Projects" ], "description": "A read model: derived from the document, records no event.", "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentProjects" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/mcpClientConfig": { "get": { "operationId": "mcpClientConfig", "summary": "The MCP client configuration for this install: the server URL and the bearer header, as an entry ready to paste into an MCP client's config.", "tags": [ "ops", "Auth" ], "description": "A read model: derived from the document, records no event.", "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpClientConfigRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/activateLicence": { "post": { "operationId": "activateLicence", "summary": "Ask the site to activate this machine now: a refreshed token and the seat count on 200, `seats-exceeded`, `revoked` or `invalid` recorded otherwise, a transport failure recorded silently — read the outcome with `licenceStatus`. No token installed → `refused: empty`. The app pings on its own on install and daily on `openProject`; this is the button.", "tags": [ "ops", "Licence" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateLicenceArgs" }, "example": { "machineName": "Edit bay" } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/armStream": { "post": { "operationId": "armStream", "summary": "Arm or release one of Rheocles' streams — the set-up screen's toggle. Armed is Rheocles' own definition (the capture session runs; nothing is stamped or written), and the armed set is what `recordScreencast` snapshots at the cue. Install-scoped and eventless like the rest of the Screencast folder: the device lives in Rheocles, nothing is written here.", "tags": [ "ops", "Screencast" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArmStreamArgs" }, "example": { "stream": "camera:0x2300000fd9009c", "armed": true } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/createProject": { "post": { "operationId": "createProject", "summary": "Make a new project file at a path and register it: an empty project, open and on the door's Recent list.", "tags": [ "ops", "Projects" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectArgs" }, "example": { "name": "Morning episode", "path": "/Users/me/Movies/Morning episode.tomocles" } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/deactivateLicence": { "post": { "operationId": "deactivateLicence", "summary": "Free this machine's seat on the site (its 204); the token stays — the licence is still the owner's, and the next activation takes a seat again. Offline the request is recorded as failed and nothing changes. No token installed → `refused: empty`.", "tags": [ "ops", "Licence" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateLicenceArgs" }, "example": {} } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/forgetProject": { "post": { "operationId": "forgetProject", "summary": "Take a project off the door's Recent list. The file is untouched.", "tags": [ "ops", "Projects" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgetProjectArgs" }, "example": { "path": "/Users/me/Movies/Morning episode.tomocles" } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/installLicence": { "post": { "operationId": "installLicence", "summary": "Install a licence token on this Mac: verified through the shared package first (a token that does not verify is `invalidArgs` at `licence`, its reason the message — `bad-signature`, `unknown-key`, `wrong-product`, `bad-format`, `no-keyring`), stored (a record that cannot be written even after the app database is repaired is `invalidArgs` at `licence`, `not-saved: …`), then one activation ping to the site, best effort: offline it still installs (docs/app/licence.md).", "tags": [ "ops", "Licence" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstallLicenceArgs" }, "example": { "licence": "v1.2026-10.eyJpZCI6IjAxSjhaMEMwMDAwMDAwMDAwMDAwMDAwMDAwIn0.c2lnbmF0dXJl" } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/launchRheocles": { "post": { "operationId": "launchRheocles", "summary": "Ask LaunchServices to start Rheocles when it is not answering — what ⌘R does before the set-up screen can list a stream. Fire-and-forget like `recordScreencast`'s own launch (`Daemon::launch`, docs/decisions/rheocles-handoff.md §2): the op returns as soon as the shell has forked `open`, and the page polls `screencastStatus` until the daemon answers `idle`. `applied: true` means the launch was asked for, not that the app is up — and not that it exists: `open` fails silently for a bundle that is not installed, which is what the page's `installed` is for. When the daemon already answers there is nothing to start: `applied: false, reason: rheocles-running`.", "tags": [ "ops", "Screencast" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchRheoclesArgs" }, "example": {} } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/locateProject": { "post": { "operationId": "locateProject", "summary": "Tell the registry where a moved project file is now: its card moves to the new path and opens.", "tags": [ "ops", "Projects" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocateProjectArgs" }, "example": { "path": "/Users/me/Movies/Morning episode.tomocles", "newPath": "/Users/me/Movies/Episodes/Morning episode.tomocles" } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/openProject": { "post": { "operationId": "openProject", "summary": "Open a project file: check it opens, put it at the top of the door's Recent list, and hand the editor its path.", "tags": [ "ops", "Projects" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenProjectArgs" }, "example": { "path": "/Users/me/Movies/Morning episode.tomocles" } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/pairRheocles": { "post": { "operationId": "pairRheocles", "summary": "Pair with a running Rheocles by hand (U-B4): keep the code the user pasted from Rheocles' Settings — its bearer, shown there for clients that cannot read its token file — and ask the daemon with it. The app pairs on its own whenever it can read that file (any process running as the user is paired, rheocles/docs/PROTOCOL.md § Authentication); this is the fallback the card offers when `screencastStatus` reports `unpaired`, asked once and remembered beside the install token. `applied: true` means the daemon let the code in; `rheocles-unpaired` that it answered and did not; `rheocles-unavailable` that nothing answered (the code is kept for when it does); `unwritable` that the code could not be kept on disk. The page then reads `screencastStatus` again. A blank code is `invalidArgs` at `code`.", "tags": [ "ops", "Screencast" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairRheoclesArgs" }, "example": { "code": "f00dfeed0123456789abcdef0123456789abcdef0123456789abcdef0123456789" } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/recordScreencast": { "post": { "operationId": "recordScreencast", "summary": "Start a screencast in Rheocles: create and cue a take from its armed streams, and answer its id (`created: [takeId]`) — the first of the four calls the hand-off is made of (docs/decisions/rheocles-handoff.md): `recordScreencast`, `screencastStatus` until the take is complete, then `createProject` and `deriveTake {folder}` into it.", "tags": [ "ops", "Screencast" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordScreencastArgs" }, "example": { "name": "Episode 12" } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/removeLicence": { "post": { "operationId": "removeLicence", "summary": "Forget the installed token: the install is back on the trial's clock, wherever it stands (removing a licence never restarts the trial). The seat is not freed — `deactivateLicence` first, while online, if the machine is going away. No token → `unchanged`.", "tags": [ "ops", "Licence" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveLicenceArgs" }, "example": {} } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/rotateToken": { "post": { "operationId": "rotateToken", "summary": "Mint a new install token over the old one; every client holding the old token is refused from its next request.", "tags": [ "ops", "Auth" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateTokenArgs" }, "example": {} } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/ops/stopScreencast": { "post": { "operationId": "stopScreencast", "summary": "Stop a take Rheocles is recording — the hand-off's cancel. Rheocles has stop, not cancel: its writers finalize and the take stays in its recents, complete; what is cancelled is the hand-off. This op creates nothing — no project, no document, no event — which is why the Welcome card can promise \"returns here with nothing created\" (docs/decisions/rheocles-handoff.md). `created` is always empty.", "tags": [ "ops", "Screencast" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StopScreencastArgs" }, "example": { "take": "20260912T040433-fd9q" } } } }, "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/assetBucket": { "get": { "operationId": "assetBucket", "summary": "Everything the edit has to work with and where each thing is used: the takes and their streams, the deck's slides, the exhibits, the sponsors card and the captions files in the project's folder, the cards on the tracks, and the library's grounds and supporters — each with the timelines that use it.", "tags": [ "ops", "Assets" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetBucketRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/audioLevels": { "get": { "operationId": "audioLevels", "summary": "The peak and loudness over time of a stream or a timeline clip, at a resolution you choose, and where its sound first rises — the dialog onset an agent lines a J-cut up to.", "tags": [ "ops", "Media" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "takeId", "in": "query", "required": false, "description": "The take whose stream to read (with `streamId`).", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "name": "streamId", "in": "query", "required": false, "description": "The stream to read, on the take clock.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline `clipId` is on; null = the first.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "example": "full" }, { "name": "clipId", "in": "query", "required": false, "description": "A timeline clip to read instead, on the edit clock: a bed, or a take clip (a picture clip reads its linked sound clip).", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "example": "k7" }, { "name": "resolution", "in": "query", "required": false, "description": "Seconds an answered bin covers: 0.02 (the grid) up to 60, rounded to the grid; absent = 0.1.", "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "example": 0.1 }, { "name": "from", "in": "query", "required": false, "description": "The window's start: take seconds for `streamId`, edit seconds for `clipId`; absent = the clip's `at`, or the stream's first second.", "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, { "name": "to", "in": "query", "required": false, "description": "The window's end: take seconds for `streamId`, edit seconds for `clipId`; absent = the clip's end, or the stream's last second.", "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, { "name": "floor", "in": "query", "required": false, "description": "The onset's floor in dBFS: the RMS must rise above it. Absent = -40.", "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, { "name": "hold", "in": "query", "required": false, "description": "Seconds the RMS must stay above the floor for an onset — a breath or a click is shorter. Absent = 0.15.", "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudioLevelsRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/chapters": { "get": { "operationId": "chapters", "summary": "Every chapter with where the edit shows it: `editAt` and `inEdit` are EDIT seconds on the timeline (the clock `placeClip.at` takes); `takeAt` is TAKE seconds (the chapter's `at` in `document`). To put something where a chapter starts in the edit, use `editAt`.", "tags": [ "ops", "Takes" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline whose edit seconds to answer in; null = the sequence the page shows (the session's `activeSequenceId`, else the first). An unknown id is `unknownId` at `sequenceId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "example": "full" } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChaptersRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/document": { "get": { "operationId": "document", "summary": "Read the open project's projection: the document at the head of the log with the log position, the session view state and the undo/redo flags — what a client applies on open and after a missed broadcast (docs/decisions/session-stream.md), and what an Automation reads first to discover the ids it acts on. Chapters' `at` and markers' `t` are TAKE seconds (moments of the recording), clips' `at` EDIT seconds (moments of the timeline): where a chapter or marker falls in the edit is `chapters` / `markers`.", "tags": [ "ops", "Projection" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/events": { "get": { "operationId": "events", "summary": "Read the log after a position: the head's document, position and flags, plus every entry with `seq > since`, ascending by seq — what an agent (or the page without the Electron bridge) polls to follow other writers (docs/decisions/rest-routes.md).", "tags": [ "ops", "Projection" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "The envelope seq the caller last saw; entries after it are returned. 0 = everything.", "schema": { "type": "integer", "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventsPage" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/exportPlan": { "get": { "operationId": "exportPlan", "summary": "What one timeline will become, without rendering any of it: the horizontal export with its chapters in edit time (the list opens at `00:00`, a synthetic `Open` when the first chapter starts late), and one vertical export per chapter with footage — each its length against the Shorts and Reels limits.", "tags": [ "ops", "Exports" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline to read; null = the sequence the page shows (the session's `activeSequenceId`, else the first). An unknown id is `unknownId` at `sequenceId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportPlanRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/linkedClips": { "get": { "operationId": "linkedClips", "summary": "The clips linked to one clip: what a move, trim, slip, roll, blade, removal or speed change to it also does to them.", "tags": [ "ops", "Links" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "clipId", "in": "query", "required": true, "description": "The clip whose link to read. An unknown id is `unknownId` at `clipId`.", "schema": { "type": "string" }, "example": "k1" }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline it is on; null = the first.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedClipsRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/lintEdit": { "get": { "operationId": "lintEdit", "summary": "What is wrong with the edit, in one list: every timeline read the way a renderer will read it — is there anything to render, does every stretch of footage know its scene, does every exhibit have its file, will YouTube keep the chapters, will a Short be a Short, is there a hole with nothing over it.", "tags": [ "ops", "Lint" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LintRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/markers": { "get": { "operationId": "markers", "summary": "Every marker with where the edit shows it: `inEdit` is EDIT seconds on the timeline (the clock `placeClip.at` takes); `takeT` is TAKE seconds (the marker's `t` in `document`). To put something at a marker's moment in the edit, use an `inEdit` entry.", "tags": [ "ops", "Takes" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline whose edit seconds to answer in; null = the sequence the page shows (the session's `activeSequenceId`, else the first). An unknown id is `unknownId` at `sequenceId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "example": "full" }, { "name": "takeId", "in": "query", "required": false, "description": "Only this take's markers; null = every take's. An unknown id is `unknownId` at `takeId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkersRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/markersCsv": { "get": { "operationId": "markersCsv", "summary": "The markers as the recorder's cue CSV (`Timecode In,Name,Comment`) on either clock: the uncut take, or the edit with its kept ranges laid end to end, markers inside a cut gone and a `take:cut` row per dropped span — the bridge to an NLE while one is still in the loop.", "tags": [ "ops", "Exports" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "clock", "in": "query", "required": true, "description": "`take` — the uncut take, a marker at its take time; `edit` — the kept ranges laid end to end, markers inside a cut dropped, a `take:cut` row per dropped span.", "schema": { "type": "string", "enum": [ "take", "edit" ] }, "example": "edit" }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline to read; null = the sequence the page shows (the session's `activeSequenceId`, else the first). An unknown id is `unknownId` at `sequenceId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addChapter": { "post": { "operationId": "addChapter", "summary": "Add a hand chapter with a heading and export flags, without a marker anchor.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddChapterArgs" }, "example": { "takeId": "t1", "at": 5, "name": "Teaser", "flags": [ "bumper" ] } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addExportPreset": { "post": { "operationId": "addExportPreset", "summary": "Add an export preset: how one target is encoded into files (docs/render/manifest-v4.md \"Presets\") — the list stored from here on, the defaults included.", "tags": [ "ops", "Presets" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddExportPresetArgs" }, "example": { "preset": { "targetId": "9:16", "name": "Reels 60", "container": "mp4", "codec": "hevc", "resolution": { "w": 1080, "h": 1920 }, "quality": { "crf": 20 }, "audio": { "codec": "aac", "bitrate": 160 }, "fps": 60, "perChapter": true, "chapterFilter": "all" } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addFramingKeyframe": { "post": { "operationId": "addFramingKeyframe", "summary": "Set the crop at one clip second: a keyframe added to the clip's framing for the target, replacing one already at that second; the first keyframe makes the framing.", "tags": [ "ops", "Framing" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddFramingKeyframeArgs" }, "example": { "sequenceId": "full", "clipId": "k1", "targetId": "9:16", "keyframe": { "at": 30, "focus": { "x": 0.5, "y": 0.45 }, "scale": 1.5, "ease": "hold" } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addGainKeyframe": { "post": { "operationId": "addGainKeyframe", "summary": "Set one gain keyframe on a clip (docs/core/audio.md): at that clip second the level is the keyframe's, linear in dB to the next; one already at that second is replaced. Footage and beds only.", "tags": [ "ops", "Audio" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddGainKeyframeArgs" }, "example": { "sequenceId": "full", "clipId": "k1", "keyframe": { "at": 30.004, "gain": -1 } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addGroup": { "post": { "operationId": "addGroup", "summary": "A group for tracks to fold into: `Footage` over a take's video and audio, say.", "tags": [ "ops", "Groups" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddGroupArgs" }, "example": { "sequenceId": "full", "name": "Cards", "trackIds": [ "stings", "bumpers" ] } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addMarker": { "post": { "operationId": "addMarker", "summary": "Add a hand marker at a take time, with no recorder position to revert to.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddMarkerArgs" }, "example": { "takeId": "t1", "t": 20, "label": "note:here" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addPanel": { "post": { "operationId": "addPanel", "summary": "Add a panel to a baked project scene: where it sits, what track it shows, how the picture fits, its look — at the top of the stack or at `at`.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPanelArgs" }, "example": { "sceneId": "sc1", "panel": { "name": "Background", "trackId": "broll", "rect": { "x": 0, "y": 0, "w": 100, "h": 100 } }, "at": 0 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addSequence": { "post": { "operationId": "addSequence", "summary": "Add a timeline and make it active: seeded with the whole of a take from its cue when one is named, else empty tracks.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddSequenceArgs" }, "example": { "name": "Scratch" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addStream": { "post": { "operationId": "addStream", "summary": "Add a file to a take as one more stream on its cue clock (C-17 `importMedia`'s step on an existing take): the file relative to the project's folder or a media root, its role from the name unless given, offset 0 unless given, and what a probe learned of it.", "tags": [ "ops", "Streams" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddStreamArgs" }, "example": { "takeId": "2026-09-09 13-12-36.mov", "stream": { "file": "b-roll/phone.mov", "role": "cam-b" } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addTake": { "post": { "operationId": "addTake", "summary": "Add a take to the project's bucket — a take, or a whole derived document whose take it is — renumbered past the document's ids; a take with a `Teaser` chapter gets its own timeline.", "tags": [ "ops", "Documents" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTakeArgs" }, "example": { "take": { "captions": { "box": "pill", "font": "sans", "position": "bottom", "safe": true, "size": "medium", "y": 0.8 }, "savedAt": "2026-01-01T00:00:00.000Z", "scene": null, "script": null, "sequences": [ { "fps": 30, "groups": [], "id": "full", "name": "Full", "scenes": { "16:9": [ { "at": 10, "id": "pl1", "sceneId": "full-cam" }, { "at": 30, "id": "pl2", "sceneId": "split" } ], "9:16": [ { "at": 10, "id": "pl3", "sceneId": "full-cam" } ] }, "tracks": [ { "clips": [], "groupId": null, "id": "captions", "locked": false, "medium": "video", "muted": false, "name": "Captions", "order": 0 }, { "clips": [], "groupId": null, "id": "stings", "locked": false, "medium": "video", "muted": false, "name": "Stings", "order": 1 }, { "clips": [], "groupId": null, "id": "bumpers", "locked": false, "medium": "video", "muted": false, "name": "Bumpers", "order": 2 }, { "clips": [ { "at": 40, "duration": 5, "id": "k2", "label": "quote", "pictureTail": 0, "source": { "card": { "body": "", "chapterId": null, "kind": "quote", "src": null, "title": "quote" }, "kind": "card" }, "targets": null } ], "groupId": null, "id": "interstitials", "locked": false, "medium": "video", "muted": false, "name": "Interstitials", "order": 3 }, { "clips": [], "groupId": null, "id": "broll", "locked": false, "medium": "video", "muted": false, "name": "B-roll", "order": 4 }, { "clips": [], "groupId": null, "id": "slides", "locked": false, "medium": "video", "muted": false, "name": "Slides", "order": 5 }, { "clips": [], "groupId": null, "id": "sponsors", "locked": false, "medium": "video", "muted": false, "name": "Sponsors", "order": 6 }, { "clips": [ { "at": 0, "duration": 100, "id": "k1", "label": "Take", "pictureTail": 0, "source": { "in": 0, "kind": "take", "streams": null, "takeId": "teaser-take" }, "targets": null } ], "groupId": null, "id": "footage", "locked": false, "medium": "video", "muted": false, "name": "Footage", "order": 7 } ] } ], "takes": [ { "chapters": [ { "at": 10, "flags": [], "id": "c1", "name": "Cold Open" }, { "at": 30, "flags": [], "id": "c3", "name": "Teaser" }, { "at": 40, "flags": [ "short" ], "id": "c2", "name": "A" } ], "duration": 100, "fps": 30, "id": "teaser-take", "markers": [ { "id": "m1", "label": "take:go", "origin": "manifest", "originalT": 10, "t": 10 }, { "id": "m2", "label": "marker:chapter A", "origin": "manifest", "originalT": 40, "t": 40 } ], "source": { "folder": "t", "id": "t", "kind": "rheocles", "manifest": "manifest.json", "name": "t" }, "spans": [], "streams": [ { "duration": null, "file": "cam.mov", "focus": { "x": 0.5, "y": 0.5 }, "fps": 30, "height": null, "id": "cam", "label": "cam", "medium": "video", "muted": false, "offset": 0, "primary": true, "role": "cam", "timecode": null, "width": null, "codec": null } ] } ], "version": 6, "targets": [ { "id": "16:9", "name": "Horizontal", "aspect": { "w": 16, "h": 9 }, "enabled": true, "safe": { "action": { "top": 3.5, "right": 3.5, "bottom": 3.5, "left": 3.5 }, "title": { "top": 5, "right": 5, "bottom": 5, "left": 5 }, "caption": { "top": 5, "right": 5, "bottom": 7, "left": 5 }, "chrome": null }, "primitives": null }, { "id": "9:16", "name": "Vertical", "aspect": { "w": 9, "h": 16 }, "enabled": true, "safe": { "action": { "top": 10.5, "right": 12.5, "bottom": 17.5, "left": 6.5 }, "title": { "top": 10.5, "right": 12.5, "bottom": 17.5, "left": 6.5 }, "caption": { "top": 68, "right": 12.5, "bottom": 15, "left": 6.5 }, "chrome": { "top": 8, "right": 10, "bottom": 15, "left": 4 } }, "primitives": null } ] } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-large": true, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addTarget": { "post": { "operationId": "addTarget", "summary": "Add a frame to render for: a preset (`16:9`, `9:16`, `1:1`, `4:5`) by id, or a custom aspect with a name — every take gets the frame's base scene from 0, so it has a scene before its first cue as a derived take has.", "tags": [ "ops", "Targets" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTargetArgs" }, "example": { "target": { "aspect": { "h": 3, "w": 4 }, "id": "4:3", "name": "Deck" } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/addTrack": { "post": { "operationId": "addTrack", "summary": "A new track below another (or at the foot), of a kind and medium, optionally in a group.", "tags": [ "ops", "Tracks" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddTrackArgs" }, "example": { "sequenceId": "full", "track": { "name": "B-roll" }, "afterTrackId": "nope" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/adoptCaptions": { "post": { "operationId": "adoptCaptions", "summary": "Put the folder's captions file on the captions track: one clip covering the whole timeline (or the take, whichever reaches further), on the edit clock for a file named `master` or `final` and the take's clock otherwise — the SRT the folder holds, or the one named.", "tags": [ "ops", "Captions" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptCaptionsArgs" }, "example": { "src": "captions:2026_09_09" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/adoptCues": { "post": { "operationId": "adoptCues", "summary": "Light up a take that was opened before its cue CSV arrived: the CSV's rows become the take's markers and the structure is derived from them — chapters, slides, spans, scene cues, the cards — merged around anything added by hand meanwhile; an untouched timeline is re-seeded from `take:go`, a worked-on one keeps its cut and gets the cards laid over it.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdoptCuesArgs" }, "example": { "cues": "twipi-2026-09-09-2026-09-09 13-12-36-cues.csv" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/analyseAudio": { "post": { "operationId": "analyseAudio", "summary": "Start analysing sound: the peak and loudness of each file on a 20 ms grid, decoded by the bundled ffmpeg in the background, for `audioLevels` to read.", "tags": [ "ops", "Media" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyseAudioArgs" }, "example": { "takeId": "2026-09-09 13-12-36.mov" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/applySuggestion": { "post": { "operationId": "applySuggestion", "summary": "Act on one suggestion: a pickup or an omit comes out of every timeline wherever the footage shows it (`removeTakeSpan` per timeline) and the chapter whose read was dropped walks to the keeper (`moveChapter`); a note is a blade at every projection (`bladeAt`); jitter removes the doubled markers (`removeMarker`) — one `batch` of those built-ins, one undo step.", "tags": [ "ops", "Suggest" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplySuggestionArgs" }, "example": { "suggestion": { "id": "pickup:m2+m3", "kind": "pickup", "in": 40, "out": 90, "reason": "B: fired again 50 s after its first cue with the deck unmoved; the read from 0:40.00 looks abandoned and the one from 1:30.00 is the keeper.", "markerIds": [ "m2", "m3" ] } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/applySuggestions": { "post": { "operationId": "applySuggestions", "summary": "Act on several suggestions in list order as one `batch` — every span out of every timeline, every chapter walked, every doubled marker gone — one undo step for the lot.", "tags": [ "ops", "Suggest" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplySuggestionsArgs" }, "example": { "suggestions": [ { "id": "jitter:m3", "kind": "jitter", "in": 41, "out": 41, "reason": "marker:chapter A at 0:41.00 fired 1.0 s from B's first fire: sidecar jitter, not a retake.", "markerIds": [ "m3" ] } ] } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/bakeScene": { "post": { "operationId": "bakeScene", "summary": "Bake a scene for one target's frame: its panels as the family lays them out there, as a new project scene whose panels the panel ops then edit.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BakeSceneArgs" }, "example": { "sceneId": "split", "targetId": "16:9", "name": "Split, wide" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/batch": { "post": { "operationId": "batch", "summary": "Apply several document ops as one step: the steps in order, later ones seeing earlier ones, one event, one undo.", "tags": [ "ops", "Documents" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchArgs" }, "example": { "steps": [ { "op": "addGroup", "args": { "sequenceId": "full", "name": "Pair", "trackIds": [ "broll" ] } }, { "op": "setTrack", "args": { "sequenceId": "full", "trackId": "footage", "patch": { "groupId": "g1" } } }, { "op": "renameGroup", "args": { "sequenceId": "full", "groupId": "g1", "name": "Picture" } } ] } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/bladeAt": { "post": { "operationId": "bladeAt", "summary": "Blade every clip on the given tracks that straddles a point: the head keeps the clip's id and loses its tail, the tail is a new clip that keeps it.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BladeAtArgs" }, "example": { "sequenceId": "full", "at": 40 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/cancelProxy": { "post": { "operationId": "cancelProxy", "summary": "Stop a stream's proxy run: the runner kills ffmpeg and removes the part-written file, so nothing partial is left; a finished proxy stays.", "tags": [ "ops", "Media" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelProxyArgs" }, "example": { "takeId": "2026-09-09 13-12-36.mov", "streamId": "2026-09-09 13-12-36.mov" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/clearFraming": { "post": { "operationId": "clearFraming", "summary": "Drop a clip's framing for one target, or for every target when none is named: the stream's focus and no punch-in again.", "tags": [ "ops", "Framing" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearFramingArgs" }, "example": { "sequenceId": "full", "clipId": "k1" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/copyScenes": { "post": { "operationId": "copyScenes", "summary": "Replace one target's scenes track on a timeline with another's, translated: `split` and `stack` swap because they are the same intent in the two frames.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CopyScenesArgs" }, "example": { "from": "16:9", "to": "9:16" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/createProxy": { "post": { "operationId": "createProxy", "summary": "Start a proxy of a video stream: a lighter H.264 copy for playback, transcoded by the bundled ffmpeg in the background into `/proxies/`, the finished path landing on the stream as one `setStream` step when the run ends.", "tags": [ "ops", "Media" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProxyArgs" }, "example": { "takeId": "2026-09-09 13-12-36.mov", "streamId": "2026-09-09 13-12-36.mov", "preset": "720p" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/createScene": { "post": { "operationId": "createScene", "summary": "Add a scene to the project from scratch: an ordered set of panels laid out for one frame, or a family with its knobs laid out for any (docs/core/scenes.md).", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSceneArgs" }, "example": { "scene": { "name": "Two up, styled", "aspect": { "w": 16, "h": 9 }, "panels": [ { "id": "p1", "name": "Background", "trackId": "broll", "rect": { "x": 0, "y": 0, "w": 100, "h": 100 } }, { "id": "p2", "name": "Screen", "trackId": "slides", "rect": { "x": 4, "y": 8, "w": 58, "h": 84 }, "fit": "contain", "radius": 2, "border": { "width": 0.4, "colour": "frame-ink", "style": "solid" } }, { "id": "p3", "name": "Camera", "trackId": "footage", "rect": { "x": 66, "y": 8, "w": 30, "h": 53.3 }, "transform": { "x": 0, "y": -5, "zoom": 1.2 }, "radius": 3, "shadow": { "blur": 2, "x": 0.5, "y": 0.8, "colour": "frame", "opacity": 0.4 } } ] } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/createSceneFromPlacement": { "post": { "operationId": "createSceneFromPlacement", "summary": "Bake a placement's scene and its mappings into a new project scene (`sc`), which the placement then names.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSceneFromPlacementArgs" }, "example": { "placementId": "pl1", "name": "Close" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/deriveTake": { "post": { "operationId": "deriveTake", "summary": "Read a take folder on this machine into a first edit: the Rheocles manifest, or the OBS recording with its cue CSV, or bare media files — imported as the project's document when it has none, else added as a take.", "tags": [ "ops", "Takes" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeriveTakeArgs" }, "example": { "folder": "/Users/me/Movies/Rheocles/takes/2026-09-12/015436-rheocles-demo" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/duplicateScene": { "post": { "operationId": "duplicateScene", "summary": "Copy a scene into the project — a built-in, one of the project's own, or one of this Mac's library's — under a new `sc` id.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateSceneArgs" }, "example": { "sceneId": "sc1", "name": "Split, baked again" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/duplicateSequence": { "post": { "operationId": "duplicateSequence", "summary": "Copy a timeline, clips and all, and make the copy active. Clip ids are renumbered past every id the document holds so every id still names one thing.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DuplicateSequenceArgs" }, "example": { "sequenceId": "full" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/fillQuotes": { "post": { "operationId": "fillQuotes", "summary": "Put a quote card on the interstitial track for every quote the script and the take agree on that is not there yet, where the span's footage sits in the edit — one `batch` of `placeClip`s, one undo step.", "tags": [ "ops", "Quotes" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillQuotesArgs" }, "example": { "script": "twipi-2026-09-09.md" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/importDocument": { "post": { "operationId": "importDocument", "summary": "Replace the project's document with a whole one: the floor of the log, from which undo has nothing to take back.", "tags": [ "ops", "Documents" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportDocumentArgs" }, "example": { "document": { "version": 6, "savedAt": "2026-09-09T13:12:36.000Z", "takes": [ { "id": "t1", "source": { "kind": "obs", "id": "t1", "name": "episode", "folder": "", "cues": "" }, "fps": 30, "duration": 60, "streams": [], "markers": [], "chapters": [], "slides": [], "spans": [], "scenes": { "16:9": [], "9:16": [] } } ], "sequences": [ { "tracks": [ { "id": "captions", "name": "Captions", "medium": "video", "order": 0, "groupId": null, "clips": [], "muted": false, "locked": false }, { "id": "stings", "name": "Stings", "medium": "video", "order": 1, "groupId": null, "clips": [], "muted": false, "locked": false }, { "id": "bumpers", "name": "Bumpers", "medium": "video", "order": 2, "groupId": null, "clips": [], "muted": false, "locked": false }, { "id": "interstitials", "name": "Interstitials", "medium": "video", "order": 3, "groupId": null, "clips": [], "muted": false, "locked": false }, { "id": "broll", "name": "B-roll", "medium": "video", "order": 4, "groupId": null, "clips": [], "muted": false, "locked": false }, { "id": "slides", "name": "Slides", "medium": "video", "order": 5, "groupId": null, "clips": [], "muted": false, "locked": false }, { "id": "sponsors", "name": "Sponsors", "medium": "video", "order": 6, "groupId": null, "clips": [], "muted": false, "locked": false }, { "id": "footage", "name": "Footage", "medium": "video", "order": 7, "groupId": null, "clips": [], "muted": false, "locked": false } ] } ], "targets": [ { "id": "16:9", "name": "Horizontal", "aspect": { "w": 16, "h": 9 }, "enabled": true, "safe": { "action": { "top": 3.5, "right": 3.5, "bottom": 3.5, "left": 3.5 }, "title": { "top": 5, "right": 5, "bottom": 5, "left": 5 }, "caption": { "top": 5, "right": 5, "bottom": 7, "left": 5 }, "chrome": null }, "primitives": null }, { "id": "9:16", "name": "Vertical", "aspect": { "w": 9, "h": 16 }, "enabled": true, "safe": { "action": { "top": 10.5, "right": 12.5, "bottom": 17.5, "left": 6.5 }, "title": { "top": 10.5, "right": 12.5, "bottom": 17.5, "left": 6.5 }, "caption": { "top": 68, "right": 12.5, "bottom": 15, "left": 6.5 }, "chrome": { "top": 8, "right": 10, "bottom": 15, "left": 4 } }, "primitives": null } ] }, "source": "file" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "x-tomocles-large": true, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/importMedia": { "post": { "operationId": "importMedia", "summary": "Bring footage in: any file `ffprobe` reads becomes a stream — on a new take derived from the files, or on the take named — with its role guessed from the name, then the probe; images become bucket assets by being in the walk; a folder derives as a take folder when it is one.", "tags": [ "ops", "Media" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportMediaArgs" }, "example": { "folder": "/Users/len/Movies/2026-09-27 shoot" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/leaveGroup": { "post": { "operationId": "leaveGroup", "summary": "Take a track out of its group; a group left with one track dissolves.", "tags": [ "ops", "Groups" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveGroupArgs" }, "example": { "sequenceId": "full", "trackId": "stings" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/mapPanel": { "post": { "operationId": "mapPanel", "summary": "Map a panel of a baked project scene to a track by id — what it shows — or to nothing (an empty panel draws its look only).", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapPanelArgs" }, "example": { "sceneId": "sc1", "panelId": "slide", "trackId": "tr1" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/moveChapter": { "post": { "operationId": "moveChapter", "summary": "Move a chapter on the take clock and restore chronological order.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveChapterArgs" }, "example": { "takeId": "t1", "chapterId": "c1", "at": 70 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/moveClip": { "post": { "operationId": "moveClip", "summary": "Lift a clip and place it again: on another track, at another time, by either mode. A plain move stops at the neighbours (the clip lands as close to the time as the track allows, and stays put when it cannot fit); the ⌘-drag carves them instead.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveClipArgs" }, "example": { "sequenceId": "full", "clipId": "k2", "to": { "at": 10, "trackId": "bumpers" } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/moveClipToSequence": { "post": { "operationId": "moveClipToSequence", "summary": "Move (or copy) a clip onto another timeline: lifted from its own and placed on the target's track of the same kind at `at` — its own `at` by default — overwriting or inserting.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveClipToSequenceArgs" }, "example": { "clipId": "k2", "toSequenceId": "teaser", "options": { "copy": true } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/moveFramingKeyframe": { "post": { "operationId": "moveFramingKeyframe", "summary": "Move one keyframe of a clip's framing for a target to another clip second, its value kept.", "tags": [ "ops", "Framing" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveFramingKeyframeArgs" }, "example": { "sequenceId": "full", "clipId": "k1", "targetId": "9:16", "at": 50, "to": 5 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/moveGainKeyframe": { "post": { "operationId": "moveGainKeyframe", "summary": "Move one gain keyframe to another clip second (docs/core/audio.md): its level travels with it; `to` is frame-aligned and kept within the clip. A keyframe already at `to` refuses as `neighbour`.", "tags": [ "ops", "Audio" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveGainKeyframeArgs" }, "example": { "sequenceId": "full", "clipId": "k3", "at": 20, "to": 5 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/moveMarker": { "post": { "operationId": "moveMarker", "summary": "Move a marker on the take clock, preserving its recorder position and label.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveMarkerArgs" }, "example": { "takeId": "t1", "markerId": "m1", "t": 60 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/movePanel": { "post": { "operationId": "movePanel", "summary": "Move a panel of a baked project scene to another place in the stack (index = z-order, 0 the bottom).", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovePanelArgs" }, "example": { "sceneId": "sc1", "panelId": "cam", "to": 0 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/moveScenePlacement": { "post": { "operationId": "moveScenePlacement", "summary": "Move a scene placement along its timeline's scenes track to edit second `at`; a placement already on that frame goes.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveScenePlacementArgs" }, "example": { "placementId": "pl1", "at": -5 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/moveTrack": { "post": { "operationId": "moveTrack", "summary": "Put a track at an index in the stack (0 = top); the rest keep their order around it.", "tags": [ "ops", "Tracks" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveTrackArgs" }, "example": { "sequenceId": "full", "trackId": "footage", "toIndex": 0 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/newDocument": { "post": { "operationId": "newDocument", "summary": "Start from nothing: an empty document — no take yet, one timeline with the four fresh tracks (Cards, Slides, Sponsors, Footage — docs/decisions/track-roles.md §5), the pair of targets — laid as the project's floor. A take arrives with `deriveTake` or `addTake`; a derived take keeps the derivation's eight tracks instead.", "tags": [ "ops", "Documents" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewDocumentArgs" }, "example": {} } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/packageProject": { "post": { "operationId": "packageProject", "summary": "Share the project: write `/.tomocles-package/` — a consistent copy of the project file, `tomocles-package.json` naming every media file the document uses with its size and hash, and with `includeMedia` the files themselves under `media/`. Not a log row: the document does not change; the manifest is the record (docs/decisions/project-file.md §6).", "tags": [ "ops", "Projects" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageProjectArgs" }, "example": { "dest": "/Users/me/Desktop", "includeMedia": true } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/placeClip": { "post": { "operationId": "placeClip", "summary": "Put a clip on a track: `insert` pushes everything at or after it on every unlocked track later by its length; `overwrite` carves the track under it and leaves the rest alone; a take clip on a picture track whose file also carries sound brings that sound on a linked sound track. `clip.at` is edit seconds: to open a chapter, read its `editAt` from `chapters`.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceClipArgs" }, "example": { "sequenceId": "full", "trackId": "bumpers", "clip": { "at": 1, "duration": 1, "label": "quote", "pictureTail": 0, "source": { "card": { "body": "", "chapterId": null, "kind": "quote", "src": null, "title": "quote" }, "kind": "card" }, "targets": null }, "mode": "overwrite" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/probeMedia": { "post": { "operationId": "probeMedia", "summary": "Read the take's files with the bundled `ffprobe` and record what they say: each stream's length (`setStreamDuration`, which pushes the take's duration out) and, for video, its frame size and rate (`setStream {patch: {width, height, fps}}`) — one `batch`, one undo step.", "tags": [ "ops", "Takes" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProbeMediaArgs" }, "example": {} } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/rebuild": { "post": { "operationId": "rebuild", "summary": "Replay the project's whole log through this build and replace its projections — the document, the undo history, the checkpoints — with what the log makes now; answers what changed.", "tags": [ "ops", "Projects" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RebuildArgs" }, "example": {} } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/redo": { "post": { "operationId": "redo", "summary": "Replay the step undo last took back: the document moves forward one document op along the redo branch.", "tags": [ "ops", "History" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorArgs" }, "example": {} } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/regroupMoved": { "post": { "operationId": "regroupMoved", "summary": "Settle a track's group after it moved: inside a group's run it joins that group; away from its own group's run it leaves it (a group left with one track dissolves).", "tags": [ "ops", "Groups" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegroupMovedArgs" }, "example": { "sequenceId": "s", "trackId": "x" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/relabelMarker": { "post": { "operationId": "relabelMarker", "summary": "Replace a marker label without changing its time or recorder position.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelabelMarkerArgs" }, "example": { "takeId": "t1", "markerId": "m1", "label": "take:went" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/relinkMedia": { "post": { "operationId": "relinkMedia", "summary": "Find the streams whose files are missing in a folder they moved to — by name, size and the probe's signature — and point them at it: the folder joins the media roots and each found stream's `file` becomes its path relative to it.", "tags": [ "ops", "Media" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelinkMediaArgs" }, "example": { "folder": "/Volumes/Footage/2026-09-09", "takeId": "2026-09-09 13-12-36.mov" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeChapter": { "post": { "operationId": "removeChapter", "summary": "Remove a chapter while keeping its source marker and the other chapters.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveChapterArgs" }, "example": { "takeId": "t1", "chapterId": "c2" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeClip": { "post": { "operationId": "removeClip", "summary": "Take a clip off its track, leaving a gap; with `ripple` the gap closes on every unlocked track.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveClipArgs" }, "example": { "sequenceId": "full", "clipId": "k3" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeExportPreset": { "post": { "operationId": "removeExportPreset", "summary": "Remove an export preset from the document's list (a default too: the list is the user's once stored).", "tags": [ "ops", "Presets" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveExportPresetArgs" }, "example": { "presetId": "ep2" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeFramingKeyframe": { "post": { "operationId": "removeFramingKeyframe", "summary": "Remove one keyframe of a clip's framing for a target; removing the last one removes the framing (the stream's focus, no punch-in, again).", "tags": [ "ops", "Framing" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveFramingKeyframeArgs" }, "example": { "sequenceId": "full", "clipId": "k1", "targetId": "9:16", "at": 10 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeGainKeyframe": { "post": { "operationId": "removeGainKeyframe", "summary": "Remove one gain keyframe (docs/core/audio.md): the level runs on from its neighbours; the last one removed leaves the clip flat at its gain.", "tags": [ "ops", "Audio" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveGainKeyframeArgs" }, "example": { "sequenceId": "full", "clipId": "k3", "at": 10 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeGroup": { "post": { "operationId": "removeGroup", "summary": "Dissolve a group: its tracks stay, ungrouped.", "tags": [ "ops", "Groups" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveGroupArgs" }, "example": { "sequenceId": "full", "groupId": "g1" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeMarker": { "post": { "operationId": "removeMarker", "summary": "Remove a marker, including a recorder marker; chapters keep their existing anchors.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveMarkerArgs" }, "example": { "takeId": "episode.mov", "markerId": "m4" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removePanel": { "post": { "operationId": "removePanel", "summary": "Remove a panel from a baked project scene; the last panel cannot go (`fixed` — remove the scene).", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovePanelArgs" }, "example": { "sceneId": "sc1", "panelId": "sponsors" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeScene": { "post": { "operationId": "removeScene", "summary": "Remove a project scene; while it is placed on a timeline the answer is `scene-in-use`, with `details.placements` (`[{sequenceId, targetId, placementId, at, fallback: {sceneId, name}}]` — the scene each would fall back to with `force`) and `details.message` saying to remove or change them first — never a silent no-op (F7). `force` removes it anyway and sends those placements back to the base scene.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSceneArgs" }, "example": { "sceneId": "sp1", "force": true } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeScenePlacement": { "post": { "operationId": "removeScenePlacement", "summary": "Take a scene placement off its timeline's scenes track: the placement before it holds on (or, before the first, the frame's base scene). An unknown placement is `unknownId` at `placementId`.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveScenePlacementArgs" }, "example": { "placementId": "pl2" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeSequence": { "post": { "operationId": "removeSequence", "summary": "Take a timeline away — never the last one. When it was the active one, the first remaining timeline becomes active.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSequenceArgs" }, "example": { "sequenceId": "full" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeSpan": { "post": { "operationId": "removeSpan", "summary": "Take a span of edit time out on the given tracks and close the gap: clips inside go, straddlers are bladed at both edges, and what follows moves up — ripple delete, generalised.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveSpanArgs" }, "example": { "sequenceId": "full", "in": 40, "out": 50 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeTakeSpan": { "post": { "operationId": "removeTakeSpan", "summary": "Remove every projection of a take span from the edit, later ones first so earlier ones keep their place.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTakeSpanArgs" }, "example": { "sequenceId": "full", "takeId": "t1", "in": 20, "out": 25 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeTarget": { "post": { "operationId": "removeTarget", "summary": "Take a frame out of the project: refused while a take's cues or a clip still name it (`target-in-use`) unless forced, when the cues go, the id leaves every clip's list and a clip left serving no target is deleted.", "tags": [ "ops", "Targets" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTargetArgs" }, "example": { "targetId": "9:16", "force": true } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/removeTrack": { "post": { "operationId": "removeTrack", "summary": "Take a track away — any track, since version 4 (docs/decisions/track-roles.md §6). One that still holds clips is `not-empty` unless `force`, which takes the clips with it; a group's sibling stays; the sequence normalises.", "tags": [ "ops", "Tracks" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveTrackArgs" }, "example": { "sequenceId": "full", "trackId": "tr1" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/renameChapter": { "post": { "operationId": "renameChapter", "summary": "Replace a chapter heading without changing its time, flags or marker anchor.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameChapterArgs" }, "example": { "takeId": "t1", "chapterId": "c1", "name": "Warm Open" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/renameGroup": { "post": { "operationId": "renameGroup", "summary": "Call a group something else.", "tags": [ "ops", "Groups" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameGroupArgs" }, "example": { "sequenceId": "full", "groupId": "g1", "name": "Camera + Shure" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/renameProject": { "post": { "operationId": "renameProject", "summary": "Call the project something else: the name on its card and in `projectInfo`, kept in the file so it travels with a package — the file's path is untouched.", "tags": [ "ops", "Projects" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameProjectArgs" }, "example": { "name": "Episode nine" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/renameSequence": { "post": { "operationId": "renameSequence", "summary": "Rename a timeline; its id (the slug it was made with) stays.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameSequenceArgs" }, "example": { "sequenceId": "full", "name": "Trailer" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/renameTarget": { "post": { "operationId": "renameTarget", "summary": "Rename a frame — the name the page shows and the plan files carry (`--`).", "tags": [ "ops", "Targets" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameTargetArgs" }, "example": { "targetId": "9:16", "name": "Shorts" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/renameTrack": { "post": { "operationId": "renameTrack", "summary": "Call a track something else.", "tags": [ "ops", "Tracks" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameTrackArgs" }, "example": { "sequenceId": "full", "trackId": "broll", "name": "Cutaways" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/reorderSequences": { "post": { "operationId": "reorderSequences", "summary": "Put the timelines in a new order — the tabs' order: every timeline exactly once.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderSequencesArgs" }, "example": { "sequenceIds": [ "teaser", "full" ] } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/revertMarker": { "post": { "operationId": "revertMarker", "summary": "Put a recorded marker back where the recorder put it; a hand marker is unchanged.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevertMarkerArgs" }, "example": { "takeId": "t1", "markerId": "m1" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/rippleFrom": { "post": { "operationId": "rippleFrom", "summary": "Move everything at or after a point on the given tracks by a number of seconds; a clip straddling the point is bladed first, so the part after it moves and the part before stays — sync lock, as an NLE does it.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RippleFromArgs" }, "example": { "sequenceId": "full", "at": 40, "delta": 5 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/rollEdit": { "post": { "operationId": "rollEdit", "summary": "The roll: the cut between two adjacent clips on one track moves to an edit second, the left one's out and the right one's in together, so what plays before and after the cut changes but nothing moves in the edit. Both keep at least a frame; a take clip's source never runs before its file.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RollEditArgs" }, "example": { "sequenceId": "full", "leftId": "k1", "rightId": "k2", "at": -5 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/saveSceneToLibrary": { "post": { "operationId": "saveSceneToLibrary", "summary": "Save a project scene to this Mac's library — one JSON file per scene beside the token — so every project on this machine can duplicate it in.", "tags": [ "ops", "Scenes" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveSceneToLibraryArgs" }, "example": { "sceneId": "sc1" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setCaptionsClock": { "post": { "operationId": "setCaptionsClock", "summary": "Which clock a captions clip follows: the take's (`in` resets to 0) or the edit's.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCaptionsClockArgs" }, "example": { "sequenceId": "full", "clipId": "k2", "clock": "take" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setChapterFlags": { "post": { "operationId": "setChapterFlags", "summary": "Replace a chapter export flags list, preserving its order and allowing an empty list.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetChapterFlagsArgs" }, "example": { "takeId": "t1", "chapterId": "c2", "flags": [] } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setClipAudio": { "post": { "operationId": "setClipAudio", "summary": "Set a clip's level and fades (docs/core/audio.md): the gain in dB on top of its track's, a fade from silence at its start, a fade to silence at its end. Footage and beds only. The fades together may not outlast the clip; an op that shortens the clip later keeps them within it. Everything back to default drops the clip's audio.", "tags": [ "ops", "Audio" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClipAudioArgs" }, "example": { "sequenceId": "full", "clipId": "k3", "audio": { "gain": -3, "fadeIn": 1, "fadeOut": 2 } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setClipCard": { "post": { "operationId": "setClipCard", "summary": "Change a card clip's words or picture: title, body, src. Other clips are left alone.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClipCardArgs" }, "example": { "sequenceId": "full", "clipId": "k2", "patch": { "body": "World", "title": "Hello" } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setClipLabel": { "post": { "operationId": "setClipLabel", "summary": "The name a clip shows on the timeline.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClipLabelArgs" }, "example": { "sequenceId": "full", "clipId": "k1", "label": "Cam" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setClipOpacity": { "post": { "operationId": "setClipOpacity", "summary": "Set how opaque a still draws (docs/core/titles.md § Stills): 0 to 1; 1 is the default and drops the field.", "tags": [ "ops", "Titles" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClipOpacityArgs" }, "example": { "sequenceId": "full", "clipId": "k2", "opacity": 0.5 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setClipPlacement": { "post": { "operationId": "setClipPlacement", "summary": "Place a title or a still on one target (docs/core/titles.md § Placement): the anchor on the target's title-safe box, the offsets, the width; null puts the target back to the default. The height follows — a title's from its lines, a still's box the frame's aspect.", "tags": [ "ops", "Titles" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClipPlacementArgs" }, "example": { "sequenceId": "full", "clipId": "k2", "targetId": "16:9", "placement": { "anchor": "top-right", "x": 0, "y": 0, "w": 30 } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setClipSpeed": { "post": { "operationId": "setClipSpeed", "summary": "Run a footage clip at a constant speed (docs/core/clips.md § Speed): the same take span in `duration / speed` edit seconds — the clip grows or shrinks at its out edge, stopping at the next clip on its track (`neighbour`). Footage clips only; 1 drops the field.", "tags": [ "ops", "Speed" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClipSpeedArgs" }, "example": { "sequenceId": "full", "clipId": "k1", "speed": 1 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setClipStreams": { "post": { "operationId": "setClipStreams", "summary": "Which of the take's streams a take clip plays; null is all of them.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClipStreamsArgs" }, "example": { "sequenceId": "full", "clipId": "k1", "streamIds": null } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setClipTargets": { "post": { "operationId": "setClipTargets", "summary": "Which targets a clip serves: every one (null), or the ones named — overlaps that now meet are resolved later-wins.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClipTargetsArgs" }, "example": { "sequenceId": "full", "clipId": "k1", "targets": [ "16:9" ] } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setClipTitle": { "post": { "operationId": "setClipTitle", "summary": "Change what a title says and how it is set (docs/core/titles.md): its template, its two lines, its face, size and colour tokens. Where it sits per target is `setClipPlacement`.", "tags": [ "ops", "Titles" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetClipTitleArgs" }, "example": { "sequenceId": "full", "clipId": "k3", "patch": { "style": { "ink": "accent" } } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setFocus": { "post": { "operationId": "setFocus", "summary": "Move a stream's focus point — where the presenter is in the frame, the point a crop centres on.", "tags": [ "ops", "Streams" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFocusArgs" }, "example": { "takeId": "t1", "streamId": "window:1", "focus": { "x": 1.4, "y": -0.2 } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setFraming": { "post": { "operationId": "setFraming", "summary": "How a clip's picture is cropped and panned for one target: the whole framing, replacing what was there — one keyframe is a constant crop, more animate.", "tags": [ "ops", "Framing" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFramingArgs" }, "example": { "sequenceId": "full", "clipId": "k1", "targetId": "16:9", "framing": { "keyframes": [ { "at": 0, "focus": { "x": 0.5, "y": 0.5 }, "scale": 1.25, "ease": "linear" } ] } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setMediaRoots": { "post": { "operationId": "setMediaRoots", "summary": "Name the folders the project reads media from beside its own: the whole list, in walk order, replacing the last — `[]` reads the project's folder alone again.", "tags": [ "ops", "Projects" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMediaRootsArgs" }, "example": { "roots": [ "/Users/me/Movies/2026-09-09 takes" ] } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setPictureTail": { "post": { "operationId": "setPictureTail", "summary": "The J-cut: how long the picture runs past the sound. A clip that is picture over something else; `normalise` clamps it.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPictureTailArgs" }, "example": { "sequenceId": "full", "clipId": "k2", "seconds": 5 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setPresetEnabled": { "post": { "operationId": "setPresetEnabled", "summary": "Turn an export preset on or off: a disabled one renders nothing and stays on the list (the same edit as `updateExportPreset {patch: {enabled}}`).", "tags": [ "ops", "Presets" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPresetEnabledArgs" }, "example": { "presetId": "ep2", "enabled": true } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setPrimary": { "post": { "operationId": "setPrimary", "summary": "Make one video stream the primary and every other stream not: exactly one stream is primary — the transport follows it and the time of day is read from its timecode — so this is the only place the flag moves.", "tags": [ "ops", "Streams" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPrimaryArgs" }, "example": { "takeId": "t1", "streamId": "mic:2" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setScene": { "post": { "operationId": "setScene", "summary": "Place a scene on a timeline's scenes track from edit second `at`, for one target: a placement already on that frame is replaced rather than doubled, so pressing `1` then `2` on the same frame changes the scene instead of stacking two there.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSceneArgs" }, "example": { "at": 20, "sceneId": "sp1", "targetId": "9:16" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setSceneCaptions": { "post": { "operationId": "setSceneCaptions", "summary": "Set a project scene's captions — shown, burnt in, where they sit, how they look — or null for the timeline's default.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSceneCaptionsArgs" }, "example": { "sceneId": "sp1", "captions": { "enabled": true, "burnIn": true, "placement": { "anchor": "top", "x": 0, "y": 2, "w": 70 }, "look": { "font": "display", "size": "large", "tracking": 2, "leading": 1.1, "colour": "frame-ink", "stroke": { "width": 0.3, "colour": "frame" }, "background": { "colour": "frame", "opacity": 0.5, "radius": 1 }, "padding": 1.5 } } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setScenePlacement": { "post": { "operationId": "setScenePlacement", "summary": "Change which scene a placement shows and which tracks its panels read: `sceneId` and, per panel, `mappings`.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetScenePlacementArgs" }, "example": { "placementId": "pl1", "sceneId": "pip" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setSession": { "post": { "operationId": "setSession", "summary": "Set the session view state (playhead, zoom) of the open project.", "tags": [ "ops", "Session" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSessionArgs" }, "example": { "playhead": 12.5, "zoom": 40, "activeSequenceId": "full" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setStream": { "post": { "operationId": "setStream", "summary": "Patch a stream's place on the take clock and its sound in one step: `offset` is where the file's first frame sits in take seconds, `muted` its sound.", "tags": [ "ops", "Streams" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetStreamArgs" }, "example": { "takeId": "episode.mov", "streamId": "episode.mov", "patch": { "muted": true } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setStreamDuration": { "post": { "operationId": "setStreamDuration", "summary": "Record a stream file length and extend the take when its offset plus length reaches further.", "tags": [ "ops", "Takes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetStreamDurationArgs" }, "example": { "takeId": "t1", "streamId": "cam", "duration": 60 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setStreamFile": { "post": { "operationId": "setStreamFile", "summary": "Point a stream at another file — the one it moved to (`relinkMedia`'s step, C-17): a path relative to the project's folder or a media root, never absolute.", "tags": [ "ops", "Streams" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetStreamFileArgs" }, "example": { "takeId": "2026-09-09 13-12-36.mov", "streamId": "2026-09-09 13-12-36.mov", "file": "2026-09-09/2026-09-09 13-12-36.mov" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setStreamOffset": { "post": { "operationId": "setStreamOffset", "summary": "Slip a stream on the take clock: the offset is where the file's first frame sits in take seconds. A hand slip replaces the derived one rather than adding to it — the card shows the absolute number, and typing what you see is the whole interaction.", "tags": [ "ops", "Streams" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetStreamOffsetArgs" }, "example": { "takeId": "t1", "streamId": "mic:2", "offset": -1.25 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setStreamRole": { "post": { "operationId": "setStreamRole", "summary": "Say what a stream's file is for: cam, cam-b, screen, mic, system or other.", "tags": [ "ops", "Streams" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetStreamRoleArgs" }, "example": { "takeId": "t1", "streamId": "window:1", "role": "screen" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setTargetEnabled": { "post": { "operationId": "setTargetEnabled", "summary": "Put a frame in the plans or take it out — its cues and its clips stay either way.", "tags": [ "ops", "Targets" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTargetEnabledArgs" }, "example": { "targetId": "16:9", "enabled": false } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setTrack": { "post": { "operationId": "setTrack", "summary": "Rename, mute, lock or group a track in one edit.", "tags": [ "ops", "Tracks" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTrackArgs" }, "example": { "sequenceId": "full", "trackId": "broll", "patch": { "groupId": "g1" } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setTrackAudio": { "post": { "operationId": "setTrackAudio", "summary": "Set a track's level and solo (docs/core/audio.md): the gain in dB added to every clip on it; solo, which silences every track without one while any is soloed. The mute is `setTrack`'s `muted`; the duck is `setTrackDucking`. Everything back to default drops the track's audio.", "tags": [ "ops", "Audio" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTrackAudioArgs" }, "example": { "sequenceId": "full", "trackId": "footage", "audio": { "gain": 3, "solo": null } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setTrackDucking": { "post": { "operationId": "setTrackDucking", "summary": "Set or clear a track's ducking (docs/core/audio.md): while `under` sounds — `speech`, the dialogue, or another audio track — the track drops by `by` dB, easing down over `attack` ahead and back over `release` after. The plan resolves it into levels; the document holds only the rule.", "tags": [ "ops", "Audio" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTrackDuckingArgs" }, "example": { "sequenceId": "full", "trackId": "music", "duck": null } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/setTransition": { "post": { "operationId": "setTransition", "summary": "Set how a clip arrives (docs/core/transitions.md): a dissolve from the clip before it, or a dip through a colour, held by the clip that starts the join; null is a cut. A dissolve needs the clip before to have footage past its out point — the plan says `transition-no-media` when it has none. Footage, stills, cutaways and titles; not a card, captions or a bed.", "tags": [ "ops", "Transitions" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTransitionArgs" }, "example": { "sequenceId": "full", "clipId": "k5", "transition": { "kind": "dip", "duration": 1, "colour": "frame-ink" } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/slipClip": { "post": { "operationId": "slipClip", "summary": "Slide a take clip's source under it: the clip stays put, the footage in it moves by the delta.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SlipClipArgs" }, "example": { "sequenceId": "full", "clipId": "k2", "delta": -10 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/straightenFootage": { "post": { "operationId": "straightenFootage", "summary": "Close every gap on the footage track, earliest first, each with a ripple so the tracks above move with the footage they sit on. A rough cut made of lifts ends up contiguous, which is what a rough cut wants.", "tags": [ "ops", "Sequences" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StraightenFootageArgs" }, "example": { "sequenceId": "full" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/toggleMuted": { "post": { "operationId": "toggleMuted", "summary": "Flip a stream's sound on or off.", "tags": [ "ops", "Streams" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToggleMutedArgs" }, "example": { "takeId": "t1", "streamId": "window:1" } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/trimClip": { "post": { "operationId": "trimClip", "summary": "Drag one edge of a clip to an edit second. The in edge keeps the clip's out where it is and slides its source in; the out edge keeps the in. Both clamp to a frame of length, to the neighbours that share a variant, and — for a take clip — to the take's own ends. `ripple` on the out edge moves what follows by the change.", "tags": [ "ops", "Clips" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrimClipArgs" }, "example": { "sequenceId": "full", "clipId": "k2", "edge": "out", "at": 23, "options": { "overwrite": true } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/undo": { "post": { "operationId": "undo", "summary": "Take back the last step: the document returns to what it was before the last document op, which moves to the redo branch.", "tags": [ "ops", "History" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CursorArgs" }, "example": {} } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/updateExportPreset": { "post": { "operationId": "updateExportPreset", "summary": "Change an export preset: the fields the patch names, the rest as they were — the target is not one of them (remove and add).", "tags": [ "ops", "Presets" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExportPresetArgs" }, "example": { "presetId": "ep1", "patch": { "name": "YouTube 1080p60", "fps": 60 } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/updatePanel": { "post": { "operationId": "updatePanel", "summary": "Change a panel of a baked project scene: any field but its id — rect, transform, fit, radius, border, shadow, alpha, blur, name, track.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePanelArgs" }, "example": { "sceneId": "sc1", "panelId": "cam", "patch": { "radius": 3, "border": { "width": 0.5, "colour": "accent", "style": "dashed" }, "transform": { "x": 0, "y": 0, "zoom": 1.5 } } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/updateScene": { "post": { "operationId": "updateScene", "summary": "Change a project scene's name, knobs or captions; a field left out is unchanged.", "tags": [ "ops", "Scenes" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSceneArgs" }, "example": { "sceneId": "sp1", "patch": { "name": "Wide split, plain", "knobs": { "camWidth": 38, "sponsors": false } } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/withCaptions": { "post": { "operationId": "withCaptions", "summary": "Change how the captions are drawn — position, size, box, font, safe area — a key at a time.", "tags": [ "ops", "Documents" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithCaptionsArgs" }, "example": { "style": { "position": "top", "size": "large" } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/withScene": { "post": { "operationId": "withScene", "summary": "Attach the project's scene document — the scene editor's export, verbatim — or detach it with null.", "tags": [ "ops", "Documents" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithSceneArgs" }, "example": { "scene": { "aspect": { "h": 9, "ratio": 1.7778, "reference_canvas": { "height": 1080, "width": 1920 }, "w": 16 }, "id": "split-with-sponsors", "layout": { "cam_width_pct": 32.6, "gutter_pct_of_height": 3.7031111111111112, "gutter_pct_of_width": 2.083, "gutter_px_at_reference": 40, "rects_pct": { "cam": { "h": 92.59377777777777, "w": 32.6, "x": 65.31700000000001, "y": 3.7031111111111112 }, "slide": { "h": 61.151, "w": 61.151, "x": 2.083, "y": 3.7031111111111112 }, "sponsors": { "h": 27.739666666666658, "w": 61.151, "x": 2.083, "y": 68.55722222222222 } }, "rects_px_at_reference": { "cam": { "h": 1000, "w": 626, "x": 1254, "y": 40 }, "slide": { "h": 660, "w": 1174, "x": 40, "y": 40 }, "sponsors": { "h": 300, "w": 1174, "x": 40, "y": 740 } }, "stack_split": 0.6 }, "meta": { "authored_with": "The Scene Editor in PteroPrompter, a separate application. Locally it is served at https://pteroprompter.com.test//scenes", "boundary": "This file is the whole interface. PteroPrompter is a separate codebase -- do not read or change anything in it without asking first.", "source_of_truth": "Colour values are generated, not hand-picked: edit them in the Scene Editor and re-export rather than typing new ones here." }, "name": "Split w/ Sponsors", "panel": { "alpha": 0.9, "blur_px": 5, "border": { "radius_pct_of_width": 0.6, "radius_px_at_reference": 12, "style": "accent", "width_pct_of_width": 0.42, "width_px_at_reference": 8 } }, "primitive": "split", "slide": { "aspect": { "h": 9, "w": 16 }, "export": { "height": 1440, "width": 2560 }, "on_screen_px_at_4k": { "height": 1320, "width": 2348 } }, "sponsors": { "carousel": { "full_pass_seconds": 46, "mode": "snap" }, "eyebrow": "Supported by" }, "theme": { "colors": { "accent": "#866300", "accent2": "#866300", "edge": "#866300", "muted": "#625D53", "panel": "#EFE7D6", "strip": "#E2DAC9", "text": "#1C1A17" }, "ground": "paper", "ground_source": { "preset": "paper", "project": "lattice", "seed": 7 }, "hue": 85, "id": "sand", "mode": "light", "name": "Sand", "oklch": { "accent": { "C": 0.107, "H": 84, "L": 0.521 }, "panel": { "C": 0.024, "H": 86, "L": 0.93 } } }, "version": 1 } } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/withTakeDuration": { "post": { "operationId": "withTakeDuration", "summary": "Record the take's length once something has read its files, and re-seed every timeline that still shows the untouched whole take.", "tags": [ "ops", "Documents" ], "description": "A write: one event in the project log, one undo step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithTakeDurationArgs" }, "example": { "takeId": "t1", "duration": 120 } } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/ops/writeOutputs": { "post": { "operationId": "writeOutputs", "summary": "Write what the edit produces beside the project, in its folder: `edit.json`, `render.json`, `markers.take.csv`, `markers.edit.csv`, `chapters.txt` — and `outputs.json`, the record of what was written (each file's bytes and SHA-256, the seq, when); the last step of an Automation.", "tags": [ "ops", "Exports" ], "description": "A write that is not an undo step: recorded, never undone.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteOutputsArgs" }, "example": {} } } }, "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "x-tomocles-step": false, "responses": { "200": { "description": "The op result. `applied: false` carries a reason and is still 200.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpResult" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/outputs": { "get": { "operationId": "outputs", "summary": "What the last `writeOutputs` wrote beside the project: the folder, and `outputs.json` read back — each file's bytes and SHA-256, the seq it was produced from, when — or null when nothing has been written yet.", "tags": [ "ops", "Exports" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutputsRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/previewScene": { "get": { "operationId": "previewScene", "summary": "A parametric draft laid out for a target, before it exists: its family and knobs through the one layout engine, answered as the panels a segment would draw — so an inspector's knob sliders never lay out on their own.", "tags": [ "ops", "Scenes" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "targetId", "in": "query", "required": true, "description": "The target whose frame the draft is laid out for.", "schema": { "type": "string" }, "example": "16:9" }, { "name": "family", "in": "query", "required": true, "description": "The draft's family: `full`, `full-tight`, `screen`, `two-up`, `pip`, `over-shoulder`.", "schema": { "type": "string", "enum": [ "full", "full-tight", "screen", "two-up", "pip", "over-shoulder" ] }, "example": "two-up" }, { "name": "gutter", "in": "query", "required": false, "description": "The gutter, percent of the frame's width (0 up to 50); absent = the default.", "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, { "name": "camWidth", "in": "query", "required": false, "description": "The cam column, percent of the frame's width (above 0, below 100).", "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "example": 40 }, { "name": "stackSplit", "in": "query", "required": false, "description": "Where a stack splits, a third to two thirds.", "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, { "name": "tightInset", "in": "query", "required": false, "description": "The tight shot's inset, percent (0 up to 50).", "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, { "name": "sponsors", "in": "query", "required": false, "description": "Whether a two-up reserves the sponsors strip with an empty track; absent = the family's default (a two-up reserves).", "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "example": false }, { "name": "pipCorner", "in": "query", "required": false, "description": "The PiP corner: top-left, top-right, bottom-left, bottom-right.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "name": "pipSize", "in": "query", "required": false, "description": "The PiP size: small, medium, large.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "name": "shoulderSide", "in": "query", "required": false, "description": "The over-shoulder box's side: left or right.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewSceneRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/projectInfo": { "get": { "operationId": "projectInfo", "summary": "The project file's own story: its format, the product and build that made it, when, and the media roots it reads beside its own folder — the `meta` table, for the door and the inspector.", "tags": [ "ops", "Projects" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectInfoRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/proxyStatus": { "get": { "operationId": "proxyStatus", "summary": "Where each video stream's proxy stands: a run queued or running (with its percent), ready (the path the media map serves), failed (why), cancelled, or none.", "tags": [ "ops", "Media" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "takeId", "in": "query", "required": false, "description": "The take whose streams to report; null = every take's. An unknown id is `unknownId` at `takeId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "example": "2026-09-09 13-12-36.mov" } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyStatusRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/quoteSpans": { "get": { "operationId": "quoteSpans", "summary": "The quotes the script and the take agree on: for every `<|Marker::interstitial_start|>` the presenter fired, the quotation the script has between it and its end token, placed at the markers' take times — what a quote card would say and when.", "tags": [ "ops", "Quotes" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "takeId", "in": "query", "required": false, "description": "The take whose markers place the quotes; null = the primary take (the first). An unknown id is `unknownId` at `takeId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, { "name": "script", "in": "query", "required": false, "description": "The script, a path relative to the project's folder; null = the lone `.md` at its top. None or several is `invalidArgs` at `script`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "example": "twipi-2026-09-09.md" } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteSpansRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/renderPlans": { "get": { "operationId": "renderPlans", "summary": "Every file the edit produces, flattened for a renderer that knows nothing: per timeline, the whole edit for the horizontal frame and one vertical file per chapter with footage in it, each a contiguous list of segments in edit time saying which frames to read from which files and how to composite them (render plan v2, docs/render/manifest-v2.md).", "tags": [ "ops", "Render" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderPlansRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/scenes": { "get": { "operationId": "scenes", "summary": "The scene palette: the built-ins, the project's own and this Mac's library's — those laid out for one target when named, with each scene's panels on that frame (the Background first), every scene otherwise.", "tags": [ "ops", "Scenes" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "targetId", "in": "query", "required": false, "description": "The target whose palette is listed (a baked scene offers itself to its own frame only); null lists every scene.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "example": "16:9" } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenesRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/segmentAt": { "get": { "operationId": "segmentAt", "summary": "The one render segment under an edit second for a target — the segment feed a scrub reads: what to composite at that moment, on the sequence's own clock.", "tags": [ "ops", "Render" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "targetId", "in": "query", "required": true, "description": "The target whose frame is composited.", "schema": { "type": "string" }, "example": "9:16" }, { "name": "at", "in": "query", "required": true, "description": "Edit seconds into the sequence.", "schema": { "type": "number" }, "example": 12.5 }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline; null = the sequence the page shows (the session's `activeSequenceId`, else the first).", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentAtRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/segments": { "get": { "operationId": "segments", "summary": "Every render segment of a sequence for one target, on the sequence's own clock — the list a stage walks to seek, step and skip gaps, for any target (a portrait one too, which `renderPlans` cuts per chapter).", "tags": [ "ops", "Render" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "targetId", "in": "query", "required": true, "description": "The target whose frame the segments composite.", "schema": { "type": "string" }, "example": "9:16" }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline; null = the sequence the page shows (the session's `activeSequenceId`, else the first).", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentsRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/suggestCuts": { "get": { "operationId": "suggestCuts", "summary": "What the take's markers say should not ship: a chapter cued again is a re-read (a pickup — the abandoned read to drop, the chapter walked to the keeper), a `slide:goto` that went backwards is a rewind, a `post:omit` span was marked for the cut at the desk, a `note:pick up here` asks for a blade, a chapter cue doubled by the follower is jitter to delete.", "tags": [ "ops", "Suggest" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "takeId", "in": "query", "required": false, "description": "The take to read; null = the primary take (the first). An unknown id is `unknownId` at `takeId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestionsRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/tracks": { "get": { "operationId": "tracks", "summary": "Every track's immutable id beside its label: what an agent reads when a person names a track and it must know which id that is.", "tags": [ "ops", "Tracks" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline to list; null = every timeline. An unknown id is `unknownId` at `sequenceId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TracksRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/verifyPackage": { "get": { "operationId": "verifyPackage", "summary": "Check a received package against its manifest: every media file hashed (sha256) and compared, on demand — the user's explicit ask, since hashing a 4K take on every lint read is not acceptable; lint compares sizes instead (`media-changed`). A project with no manifest beside it answers `packaged: false`.", "tags": [ "ops", "Projects" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PackageReport" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/projects/{project}/youtubeChapters": { "get": { "operationId": "youtubeChapters", "summary": "The chapter list ready to paste into a YouTube description: one `M:SS name` line per chapter of the timeline's horizontal export (`H:MM:SS` past an hour), the first at `00:00`.", "tags": [ "ops", "Exports" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "project", "in": "path", "required": true, "description": "The open project.", "schema": { "type": "string" } }, { "name": "sequenceId", "in": "query", "required": false, "description": "The timeline to read; null = the sequence the page shows (the session's `activeSequenceId`, else the first). An unknown id is `unknownId` at `sequenceId`.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextRead" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/screencastStatus": { "get": { "operationId": "screencastStatus", "summary": "Read where a screencast is: one take's manifest as Rheocles holds it, or — with no take named — the daemon itself: whether it answers, whether the bundle is installed, what is armed, and whether it is already recording a take of its own. This is what the Welcome card polls, once a second, from ⌘R until the take is complete (docs/decisions/rheocles-handoff.md); it never blocks longer than one bounded call.", "tags": [ "ops", "Screencast" ], "description": "A read model: derived from the document, records no event.", "parameters": [ { "name": "take", "in": "query", "required": false, "description": "The take to report on; null asks about Rheocles itself: whether it answers, what is armed, whether it is already recording.", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "example": "20260912T040433-fd9q" } ], "responses": { "200": { "description": "The read model.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreencastReport" } } } }, "401": { "description": "Refused: `error.code` is one of unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Refused: `error.code` is one of forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Refused: `error.code` is one of unknownOp, unknownProject.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Refused: `error.code` is one of payloadTooLarge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Refused: `error.code` is one of unknownId, invalidArgs, projectNotOpen, locked, documentInvalid, notEmpty, noDocument.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Refused: `error.code` is one of rateLimited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/health": { "get": { "operationId": "getHealth", "summary": "Check the local application health", "description": "Liveness only; no auth, no project.", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Application is reachable", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } } } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "The per-install token the app mints at first boot (P-06). The UI, MCP clients and the SDK all send it." } }, "schemas": { "ActivateLicenceArgs": { "type": "object", "properties": { "machineName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the account page calls this Mac; the hostname when null." } }, "required": [], "additionalProperties": false }, "AddChapterArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "at": { "type": "number", "description": "Take seconds for the chapter start." }, "name": { "type": "string", "description": "The chapter heading, which may be empty." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "Export flags, copied in their given order.", "default": [] } }, "required": [ "takeId", "at", "name" ], "additionalProperties": false }, "AddExportPresetArgs": { "type": "object", "properties": { "preset": { "type": "object", "properties": { "targetId": { "type": "string", "description": "The target this preset renders; `unknownId` at `preset.targetId`." }, "name": { "type": "string", "description": "What the Exports card calls it." }, "container": { "type": "string", "enum": [ "mp4", "mov", "webm" ], "description": "The file: mp4, mov or webm." }, "codec": { "type": "string", "enum": [ "h264", "hevc", "prores", "vp9", "av1" ], "description": "The video codec." }, "resolution": { "type": "object", "properties": { "w": { "type": "integer", "description": "Width in pixels." }, "h": { "type": "integer", "description": "Height in pixels." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame in pixels." }, "quality": { "type": "object", "properties": { "crf": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Constant rate factor (lower is better; 18 is visually lossless for h264); null when `bitrate` rules." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Target bitrate in kbit/s; null when `crf` rules." } }, "required": [], "additionalProperties": false, "description": "Exactly one of `crf` and `bitrate`: `invalidArgs` at `preset.quality` otherwise." }, "audio": { "type": "object", "properties": { "codec": { "type": "string", "enum": [ "aac", "pcm", "opus" ], "description": "aac, pcm or opus." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "kbit/s; null for a codec that has no rate (pcm) or the encoder's default." } }, "required": [ "codec", "bitrate" ], "additionalProperties": false, "description": "The sound: codec and bitrate." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Frames per second; null (the default) renders at the sequence's rate." }, "perChapter": { "type": "boolean", "description": "One file per chapter rather than one for the whole edit.", "default": false }, "chapterFilter": { "type": "string", "enum": [ "all", "short" ], "description": "Which chapters a per-chapter preset renders: all, or the `short` ones.", "default": "all" }, "enabled": { "type": "boolean", "description": "A disabled preset renders nothing and stays on the list.", "default": true }, "naming": { "type": "string", "description": "The file-name template; the default for whole or per-chapter files when omitted." }, "id": { "type": "string", "description": "An id of the caller's (`invalidArgs` when the document has it); minted `ep` when omitted." } }, "required": [ "targetId", "name", "container", "codec", "resolution", "quality", "audio" ], "additionalProperties": false, "description": "The preset to add." } }, "required": [ "preset" ], "additionalProperties": false }, "AddFramingKeyframeArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The footage or image clip." }, "targetId": { "type": "string", "description": "The target the framing is for." }, "keyframe": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false, "description": "The keyframe: `at` in clip seconds, the focus, the scale (1 or more) and how it runs to the next." } }, "required": [ "sequenceId", "clipId", "targetId", "keyframe" ], "additionalProperties": false }, "AddGainKeyframeArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The footage or bed clip." }, "keyframe": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "gain": { "type": "number", "description": "The level in dB: 0 is the clip as recorded, negative quieter." } }, "required": [ "at", "gain" ], "additionalProperties": false, "description": "The keyframe: `at` in clip seconds, the level in dB." } }, "required": [ "sequenceId", "clipId", "keyframe" ], "additionalProperties": false }, "AddGroupArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the group is in." }, "name": { "type": "string", "description": "What the folded row is called." }, "trackIds": { "type": "array", "items": { "type": "string" }, "description": "The tracks that fold into it; `[]` = a group with no tracks yet.", "default": [] } }, "required": [ "sequenceId", "name" ], "additionalProperties": false }, "AddMarkerArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "t": { "type": "number", "description": "Take seconds for the new marker." }, "label": { "type": "string", "description": "The marker text, which may be empty." } }, "required": [ "takeId", "t", "label" ], "additionalProperties": false }, "AddPanelArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The baked project scene." }, "panel": { "type": "object", "additionalProperties": true, "description": "The panel to add (the `Panel` shape, schemas.md). A raw object here: the document's panel parser is the one hydrator." }, "at": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Where in the stack, 0 the bottom; absent = on top." } }, "required": [ "sceneId", "panel" ], "additionalProperties": false }, "AddSequenceArgs": { "type": "object", "properties": { "name": { "type": "string", "description": "What the tab says; the id is its slug." }, "seedFromTakeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A take to seed the timeline from — the whole take from its cue on the footage track; null for empty tracks." } }, "required": [ "name" ], "additionalProperties": false }, "AddStreamArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take the stream joins." }, "stream": { "type": "object", "properties": { "file": { "type": "string", "description": "The file, relative to the project's folder or a media root (never absolute)." }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "What the file is for; absent = guessed from the name (`Files::classify`), `other` when the name says nothing." }, "label": { "type": "string", "description": "Something to print; absent = the file's bare name." }, "offset": { "type": "number", "description": "Where the file's first frame sits, in take seconds; absent = 0." }, "muted": { "type": "boolean", "description": "Whether the stream's sound is off; absent = a picture beside a microphone (on the take or among what joins it) is muted, as the derivation mutes it." }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The file's length in seconds, when known." }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The frame width in pixels, or null for sound alone." }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The frame height in pixels, or null for sound alone." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The frame rate, or null." }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The codec of the stream's own medium as `ffprobe` names it, or null." }, "probe": { "type": "object", "properties": { "fps": { "anyOf": [ { "type": "object", "properties": { "num": { "type": "integer", "description": "The numerator." }, "den": { "type": "integer", "description": "The denominator, never 0." } }, "required": [ "num", "den" ], "additionalProperties": false }, { "type": "null" } ], "description": "The frame rate as a ratio, exact; null for a file with no picture." }, "timecode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timecode the file carries (`10:00:00:00`), or null." }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's channel count, or null without sound." }, "sampleRate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's sample rate in Hz, or null without sound." }, "container": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ffprobe's container name, or null." }, "bytes": { "type": "integer", "description": "The file's size in bytes when probed." }, "sha256Prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the file's first MiB, hex — the signature; null when the file could not be hashed." } }, "required": [ "fps", "timecode", "channels", "sampleRate", "container", "bytes", "sha256Prefix" ], "additionalProperties": false, "description": "The probe block, when the file was probed on the way in." } }, "required": [ "file" ], "additionalProperties": false, "description": "The stream: its file and what is known of it." } }, "required": [ "takeId", "stream" ], "additionalProperties": false }, "AddTakeArgs": { "type": "object", "properties": { "take": { "type": "object", "additionalProperties": true, "description": "The take to add (the `Take` shape, schemas.md) — or a whole derived document (the `EditDocument` shape, told apart by its `takes`), whose primary take is the one added and whose active timeline comes along when the take has a `Teaser` chapter. A raw object here: the document parsers are the one hydrator." } }, "required": [ "take" ], "additionalProperties": false }, "AddTargetArgs": { "type": "object", "properties": { "target": { "type": "object", "properties": { "id": { "type": "string", "description": "A preset's id (`16:9`, `9:16`, `1:1`, `4:5`) or the custom target's own, unique in the document." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The custom target's name (a preset has its own); its slug names the plan files and lint ids, so no two targets may share one." }, "aspect": { "anyOf": [ { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false }, { "type": "null" } ], "description": "The custom target's frame." }, "enabled": { "type": "boolean", "description": "In the plans from the start; default true.", "default": true }, "safe": { "anyOf": [ { "type": "object", "properties": { "action": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Action-safe: nothing that matters outside it." }, "title": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Title-safe: text inside it." }, "caption": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Where the captions band sits." }, "chrome": { "anyOf": [ { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, { "type": "null" } ], "description": "The platform's own overlays (a Reel's top bar, its action rail, its caption strip); null for a frame shown bare." } }, "required": [ "action", "title", "caption", "chrome" ], "additionalProperties": false }, { "type": "null" } ], "description": "The custom target's safe areas; absent = the landscape or portrait set by orientation." }, "primitives": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "full-cam", "full-cam-tight", "split", "full-screen", "stack", "pip", "over-shoulder" ] } }, { "type": "null" } ], "description": "The primitives the frame offers; absent = computed from the aspect." } }, "required": [ "id" ], "additionalProperties": false, "description": "A preset by id, or a custom target with its name and aspect." } }, "required": [ "target" ], "additionalProperties": false }, "AddTrackArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the track joins." }, "track": { "type": "object", "properties": { "medium": { "anyOf": [ { "type": "string", "enum": [ "video", "audio" ] }, { "type": "null" } ], "description": "Picture or sound; null = video." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the track is called; null = Video or Audio." }, "groupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The group it folds into; null = none. Must name a group the sequence has." } }, "required": [], "additionalProperties": false, "description": "The track to add." }, "afterTrackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track it goes below — below that track's whole group when the new track does not join it (a group's tracks stay together); null = at the foot of the stack." } }, "required": [ "sequenceId", "track" ], "additionalProperties": false }, "AdoptCaptionsArgs": { "type": "object", "properties": { "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The captions file's media key (`captions:`, as `document.media` lists it); null = the folder's preferred one — the corrected file over a raw, pre-wrap or scribe pass, then the shortest name. An unknown key is `invalidArgs` at `src`." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track to lay the clip on; null = the derivation's captions track, else the topmost overlay track holding captions or nothing (track-roles.md §2)." } }, "required": [], "additionalProperties": false }, "AdoptCuesArgs": { "type": "object", "properties": { "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take to light up; null = the primary take (the first). An unknown id is `unknownId` at `takeId`." }, "cues": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cue CSV, a path relative to the project's folder; null = the one `*-cues.csv` there, or the one whose name carries the take's footage stem (`invalidArgs` at `cues` when none or several)." }, "sequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline the cue file's scenes are placed on (P2c); null = the first. An unknown id is `unknownId` at `sequenceId`." } }, "required": [], "additionalProperties": false }, "AnalyseAudioArgs": { "type": "object", "properties": { "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take whose sound to analyse; with no `streamId`, every stream of it that has sound." }, "streamId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One stream of the take: a sound stream, or a picture stream with sound." }, "sequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline `clipId` is on; null = the first." }, "clipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A timeline clip instead of a take: a bed's file, or the streams a take clip sounds." } }, "required": [], "additionalProperties": false }, "ApplySuggestionArgs": { "type": "object", "properties": { "suggestion": { "type": "object", "properties": { "id": { "type": "string", "description": "Names the suggestion, not its place in the list: the kind and the markers it was read from (`pickup:m2+m3`, `jitter:m5#2`)." }, "kind": { "type": "string", "enum": [ "pickup", "omit", "jitter" ], "description": "`pickup` (an abandoned read to drop and the chapter walked to the keeper), `omit` (a span marked for the cut at the desk) or `jitter` (doubled markers to delete)." }, "in": { "type": "number", "description": "Take seconds the span starts. For jitter, and for a note that asks for a blade, `in === out`." }, "out": { "type": "number", "description": "Take seconds the span ends." }, "reason": { "type": "string", "description": "One line a card can print: what was seen and why it means this." }, "markerIds": { "type": "array", "items": { "type": "string" }, "description": "The markers that said so. Applying a jitter suggestion removes these." } }, "required": [ "id", "kind", "in", "out", "reason", "markerIds" ], "additionalProperties": false, "description": "A suggestion as `suggestCuts` answered it. What it names is re-read from the document now: a marker it lists that is gone is skipped, a span already out of every timeline is `unchanged`." } }, "required": [ "suggestion" ], "additionalProperties": false }, "ApplySuggestionsArgs": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Names the suggestion, not its place in the list: the kind and the markers it was read from (`pickup:m2+m3`, `jitter:m5#2`)." }, "kind": { "type": "string", "enum": [ "pickup", "omit", "jitter" ], "description": "`pickup` (an abandoned read to drop and the chapter walked to the keeper), `omit` (a span marked for the cut at the desk) or `jitter` (doubled markers to delete)." }, "in": { "type": "number", "description": "Take seconds the span starts. For jitter, and for a note that asks for a blade, `in === out`." }, "out": { "type": "number", "description": "Take seconds the span ends." }, "reason": { "type": "string", "description": "One line a card can print: what was seen and why it means this." }, "markerIds": { "type": "array", "items": { "type": "string" }, "description": "The markers that said so. Applying a jitter suggestion removes these." } }, "required": [ "id", "kind", "in", "out", "reason", "markerIds" ], "additionalProperties": false }, "description": "Suggestions as `suggestCuts` answered them, in the order to apply; each is re-read against the document as the earlier ones have left it." } }, "required": [ "suggestions" ], "additionalProperties": false }, "ArmStreamArgs": { "type": "object", "properties": { "stream": { "type": "string", "description": "Rheocles' stream id, as `screencastStatus` lists it (`display:…`, `camera:…`, `microphone:…`, `systemAudio:system`, `window:…`)." }, "armed": { "type": "boolean", "description": "True to make the device live (the next take records it), false to release it." } }, "required": [ "stream", "armed" ], "additionalProperties": false }, "AssetBucketRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the index was computed from." }, "items": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "take", "stream", "slide", "exhibit", "sponsors", "captions", "audio", "card", "ground", "supporter", "scene" ], "description": "" }, "scope": { "type": "string", "enum": [ "project", "library", "team" ], "description": "" }, "id": { "type": "string", "description": "A take id, a stream id, a media key, a card clip's id, `ground:`, `supporter:`." }, "label": { "type": "string", "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Something to show: a media key or URL the page can resolve to a thumbnail, or null for a glyph." }, "usedIn": { "type": "array", "items": { "type": "string" }, "description": "The sequences that use it." } }, "required": [ "kind", "scope", "id", "label", "src", "usedIn" ], "additionalProperties": false }, "description": "The takes and their streams, the slides, exhibits, sponsors card and captions files the folder holds, the cards on the tracks, then the library's grounds and supporters." } }, "required": [ "seq", "items" ], "additionalProperties": false }, "AudioLevelsRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the document was read at." }, "status": { "type": "string", "description": "`ready` with bins; `running` — poll; `none` — call `analyseAudio`; `failed` — see `error`." }, "clock": { "type": "string", "description": "The clock `from`, `to` and the onset are on: `take` for a stream, `edit` for a timeline clip." }, "bin": { "type": "number", "description": "Seconds each answered bin covers (the asked resolution, rounded to the 0.02 s grid)." }, "from": { "type": "number", "description": "The window's start: take seconds for a stream, edit seconds for a clip." }, "to": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The window's end: take seconds for a stream, edit seconds for a clip (null until the stream is analysed, when its length is not yet known)." }, "peak": { "type": "array", "items": { "type": "number" }, "description": "The loudest sample of each bin, dBFS (-96 is silence); empty unless `ready`." }, "rms": { "type": "array", "items": { "type": "number" }, "description": "The RMS of each bin, dBFS — loudness over time; empty unless `ready`." }, "onset": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "number", "description": "The onset, on the read's clock (take seconds for a stream, edit seconds for a clip), to the grid's 0.02 s." }, "floor": { "type": "number", "description": "The floor it rose above, dBFS." }, "hold": { "type": "number", "description": "The seconds it held there." } }, "required": [ "at", "floor", "hold" ], "additionalProperties": false }, { "type": "null" } ], "description": "The first rise above the floor held for the hold, or null (not ready, or nothing rose)." }, "soundClipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When a picture clip's sound is on a linked audio track, the sound clip these levels are from; else null." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the analysis failed, or which file is missing; null otherwise." } }, "required": [ "seq", "status", "clock", "bin", "from", "to", "peak", "rms", "onset" ], "additionalProperties": false }, "BakeSceneArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The scene to bake: a built-in's id or a project scene's." }, "targetId": { "type": "string", "description": "The target whose frame the panels are laid out for." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The new scene's name; absent = the source's." } }, "required": [ "sceneId", "targetId" ], "additionalProperties": false }, "BatchArgs": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "description": "The registry name of a project-scoped document op (`bladeAt`, `renameTrack`, a nested `batch`)." }, "args": { "type": "object", "additionalProperties": true, "description": "Its arguments, as the op's own page describes them; `{}` for an op that takes none." } }, "required": [ "op", "args" ], "additionalProperties": false }, "description": "The ops to apply in order, later ones seeing earlier ones; one event, one undo step." } }, "required": [ "steps" ], "additionalProperties": false }, "BladeAtArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence to cut." }, "at": { "type": "number", "description": "Edit seconds of the cut." }, "trackIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The tracks to cut; null = every unlocked track." } }, "required": [ "sequenceId", "at" ], "additionalProperties": false }, "CancelProxyArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The stream whose run stops." } }, "required": [ "takeId", "streamId" ], "additionalProperties": false }, "ChaptersRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the read was computed from." }, "sequenceId": { "type": "string", "description": "The timeline whose edit seconds `editAt` and `inEdit` are in." }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "chapterId": { "type": "string", "description": "The chapter's id (`c1` …)." }, "takeId": { "type": "string", "description": "The take the chapter is in." }, "name": { "type": "string", "description": "The chapter heading." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "`short`, `bumper`, `bumper:top_story` … verbatim from the heading." }, "takeAt": { "type": "number", "description": "TAKE seconds (a moment of the recording): the chapter's `at` in `document`, what `moveChapter` takes. Not a timeline position." }, "editAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "EDIT seconds (a moment of the timeline) the chapter starts at — on its bumper card when one names it; what `placeClip.at` takes to put something where the chapter opens. Null when the edit does not show the chapter." }, "inEdit": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds the stretch starts." }, "duration": { "type": "number", "description": "Edit seconds it runs for." } }, "required": [ "at", "duration" ], "additionalProperties": false }, "description": "EDIT seconds: every stretch of the timeline that shows the chapter's footage, in edit order. Empty when the edit does not show it." }, "bumperClipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The bumper card clip that opens the chapter, or null." } }, "required": [ "chapterId", "takeId", "name", "flags", "takeAt", "editAt", "inEdit", "bumperClipId" ], "additionalProperties": false }, "description": "Edit order, then the chapters the edit does not show, in take order." } }, "required": [ "seq", "sequenceId", "chapters" ], "additionalProperties": false }, "ClearFramingArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The clip whose framing goes." }, "targetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The target whose framing goes; omitted, every target's." } }, "required": [ "sequenceId", "clipId" ], "additionalProperties": false }, "CopyScenesArgs": { "type": "object", "properties": { "from": { "type": "string", "description": "The target whose placements are copied, by id." }, "to": { "type": "string", "description": "The target whose placements are replaced, by id; split ↔ stack follow its orientation." }, "sequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline; null = the first. An unknown id is `unknownId` at `sequenceId`." } }, "required": [ "from", "to" ], "additionalProperties": false }, "CreateProjectArgs": { "type": "object", "properties": { "name": { "type": "string", "description": "What the project is called on its card." }, "path": { "type": "string", "description": "Where the file goes: an absolute path ending in the product's extension, in a folder that exists, naming nothing yet." } }, "required": [ "name", "path" ], "additionalProperties": false }, "CreateProxyArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The video stream to make a proxy of." }, "preset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The preset: `720p` or `1080p` (the height; never upscaled); absent = the app's default." } }, "required": [ "takeId", "streamId" ], "additionalProperties": false }, "CreateSceneArgs": { "type": "object", "properties": { "scene": { "type": "object", "additionalProperties": true, "description": "The scene to add (the `Scene` shape, schemas.md): `panels` for one `aspect`, or a `family` with `knobs`. A raw object here: the document's scene parser is the one hydrator." } }, "required": [ "scene" ], "additionalProperties": false }, "CreateSceneFromPlacementArgs": { "type": "object", "properties": { "placementId": { "type": "string", "description": "The placement whose scene and mappings are baked (`pl3`). Unknown: `unknownId` at `placementId`." }, "name": { "type": "string", "description": "The new project scene's name." }, "sequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline to look on; null = any (placement ids are the document's). An unknown id is `unknownId` at `sequenceId`." } }, "required": [ "placementId", "name" ], "additionalProperties": false }, "CursorArgs": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "DeactivateLicenceArgs": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "DeriveTakeArgs": { "type": "object", "properties": { "folder": { "type": "string", "description": "The take folder, an absolute path on this machine: a Rheocles take (its `manifest.json`), an OBS recording beside its cue CSV, or bare media files. The document keeps file names relative to it, never the path itself." } }, "required": [ "folder" ], "additionalProperties": false }, "DocumentRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The log position the document reflects: the head." }, "document": { "type": "object", "properties": { "version": { "type": "integer", "description": "Always 6 here (tracks without roles, B3; scenes as panels were 5, C-22; user-defined tracks 4, C-09; targets 3, C-10); an older file is upgraded on the way in." }, "savedAt": { "type": "string", "description": "When this document was last written, ISO 8601. An input, never the clock: parse and normalise read no time." }, "takes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its own namespace among takes; the source id when the file gave none." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rheocles" ], "description": "The discriminator `TakeSourceCast` keys on; always `rheocles`." }, "id": { "type": "string", "description": "The manifest's `id`." }, "name": { "type": "string", "description": "Something to print; the id when the manifest gave none." }, "folder": { "type": "string", "description": "The folder name, for display. The handle itself is not serialisable." }, "manifest": { "type": "string", "description": "The manifest file's name inside the folder; always `manifest.json`." } }, "required": [ "kind", "id", "name", "folder", "manifest" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "obs" ], "description": "The discriminator `TakeSourceCast` keys on; always `obs`." }, "id": { "type": "string", "description": "The footage file name, which is also the take's identity." }, "name": { "type": "string", "description": "Something to print; the id when the file gave none." }, "folder": { "type": "string", "description": "The folder name, for display." }, "cues": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cue CSV the markers were read from, if one was given." } }, "required": [ "kind", "id", "name", "folder", "cues" ], "additionalProperties": false } ], "description": "Where the take came from, so the page can find it again." }, "fps": { "type": "number", "description": "The frame rate timecodes are shown in. The primary stream's, or 30." }, "duration": { "type": "number", "description": "Take seconds: the furthest any stream reaches." }, "streams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The manifest stream id (`window:13085`), or the file name for a bare file." }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "What the stream is for, which decides where the stage puts it." }, "medium": { "type": "string", "enum": [ "video", "audio" ], "description": "Picture or sound." }, "file": { "type": "string", "description": "File name relative to the take folder. Never an absolute path: the folder moves, the edit must not care." }, "label": { "type": "string", "description": "Something to print: the manifest's `name`, or the file name." }, "offset": { "type": "number", "description": "Take seconds at which the file's first frame sits. A late joiner is positive; a file that started early is negative." }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "File seconds: the file's own length, once a browser has read it. Null until then." }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Pixel width for video, so the stage can pick a crop before the file is loaded." }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Pixel height for video." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Frames per second as recorded, when known. Screen captures are variable-rate; this is nominal." }, "primary": { "type": "boolean", "description": "The one video stream the transport follows. Exactly one stream of a take has this." }, "muted": { "type": "boolean", "description": "Heard or not." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "The point a crop keeps centred." }, "timecode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Local time-of-day of the file's first frame, `HH:MM:SS:FF` at the stream's integer fps, as Rheocles stamps it. Null for a bare file." }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The codec of the stream's own medium as `ffprobe` names it (`hevc`, `h264`, `aac`…); null until `probeMedia` learns it (U-13e)." }, "probe": { "type": "object", "properties": { "fps": { "anyOf": [ { "type": "object", "properties": { "num": { "type": "integer", "description": "The numerator." }, "den": { "type": "integer", "description": "The denominator, never 0." } }, "required": [ "num", "den" ], "additionalProperties": false }, { "type": "null" } ], "description": "The frame rate as a ratio, exact; null for a file with no picture." }, "timecode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timecode the file carries (`10:00:00:00`), or null." }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's channel count, or null without sound." }, "sampleRate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's sample rate in Hz, or null without sound." }, "container": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ffprobe's container name, or null." }, "bytes": { "type": "integer", "description": "The file's size in bytes when probed." }, "sha256Prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the file's first MiB, hex — the signature; null when the file could not be hashed." } }, "required": [ "fps", "timecode", "channels", "sampleRate", "container", "bytes", "sha256Prefix" ], "additionalProperties": false, "description": "What the file was probed to be beyond the flat fields — the exact frame rate, timecode, channels, sample rate, container, the signature relink matches by (C-17). Absent until probed." }, "proxy": { "type": "object", "properties": { "path": { "type": "string", "description": "The proxy file, relative to the project's folder." }, "preset": { "type": "string", "description": "The preset it was made at: `720p`, `1080p`." } }, "required": [ "path", "preset" ], "additionalProperties": false, "description": "The finished proxy for playback — its path beside the project and its preset (C-17b). Absent until one is ready; the manifest never names it." } }, "required": [ "id", "role", "medium", "file", "label", "offset", "duration", "width", "height", "fps", "primary", "muted", "focus", "timecode" ], "additionalProperties": false }, "description": "The files recorded on this cue clock; exactly one is the primary video." }, "markers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`m1`, `m2` …)." }, "t": { "type": "number", "description": "Take seconds (a moment of the recording), not a timeline position: `markers` gives where the edit shows it (`inEdit`). Editable." }, "label": { "type": "string", "description": "`marker:chapter Cold Open`, `obs:scene full-cam-tight`, `take:go` …" }, "origin": { "type": "string", "enum": [ "manifest", "csv", "hand" ], "description": "Where it came from: the recorder's manifest, a cue CSV, or a hand." }, "originalT": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Take seconds: where the recorder put it. Null for a hand-placed marker." } }, "required": [ "id", "t", "label", "origin", "originalT" ], "additionalProperties": false }, "description": "Sorted by `t`." }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`c1`, `c2` …)." }, "name": { "type": "string", "description": "The chapter heading, as the script wrote it." }, "at": { "type": "number", "description": "Take seconds (a moment of the recording), not a timeline position: `chapters` gives the chapter's edit seconds (`editAt`). Editable." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "`short`, `bumper`, `bumper:top_story`, `bumper:end_program` … verbatim from the heading." } }, "required": [ "id", "name", "at", "flags" ], "additionalProperties": false }, "description": "Sorted by `at`." }, "spans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`p1`, `p2` …)." }, "name": { "type": "string", "description": "The `X` of `marker:in X`." }, "in": { "type": "number", "description": "Take seconds, inclusive." }, "out": { "type": "number", "description": "Take seconds, exclusive." }, "markerIds": { "type": "array", "items": { "type": "string" }, "description": "The markers that bound it, so re-deriving can find it again." } }, "required": [ "id", "name", "in", "out", "markerIds" ], "additionalProperties": false }, "description": "Sorted by `in`; never empty or inverted." } }, "required": [ "id", "source", "fps", "duration", "streams", "markers", "chapters", "spans" ], "additionalProperties": false }, "description": "One today; the teaser later." }, "sequences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its own namespace: `full`, `teaser`, a slug of the name." }, "name": { "type": "string", "description": "What the page calls it; the id when the file gave none." }, "fps": { "type": "number", "description": "Every clip time is aligned to whole frames at this rate." }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its immutable id within the sequence (F13): `V` picture, `A` sound — never changed, never reused; a document from before F13 keeps its word ids (`footage`, `mic` …)." }, "name": { "type": "string", "description": "What the track is called; its id when the file gave none." }, "medium": { "type": "string", "enum": [ "video", "audio" ], "description": "Picture or sound — the track's type (docs/decisions/tracks-are-just-tracks.md): a video track takes every picture clip, an audio track take clips and beds." }, "order": { "type": "integer", "description": "Position in the stack, 0 at the top; `tracks[]` is kept sorted by it." }, "groupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The group the track folds into, or null." }, "clips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`k1`, `k2` …)." }, "at": { "type": "number", "description": "Edit seconds, inclusive." }, "duration": { "type": "number", "description": "Edit seconds. Always positive." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "take" ], "description": "The discriminator `ClipSourceCast` keys on; always `take`." }, "takeId": { "type": "string", "description": "The take the footage is from; must name a take the document has." }, "in": { "type": "number", "description": "Take seconds at the clip's first frame." }, "streams": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The streams this clip plays; null is every stream of the take — the automatic group." } }, "required": [ "kind", "takeId", "in", "streams" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ], "description": "The discriminator `ClipSourceCast` keys on; always `card`." }, "card": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bumper", "sting", "quote", "exhibit" ], "description": "Bumper, sting, quote or exhibit." }, "title": { "type": "string", "description": "The card's heading, or the chapter name for a bumper." }, "body": { "type": "string", "description": "The quote text, the bumper's console line (`> top_story`), the exhibit stem." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A media key or URL, for an exhibit." }, "chapterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The chapter a bumper opens." } }, "required": [ "kind", "title", "body", "src", "chapterId" ], "additionalProperties": false, "description": "The card the clip shows." } }, "required": [ "kind", "card" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ], "description": "The discriminator `ClipSourceCast` keys on; always `image`." }, "src": { "type": "string", "description": "A media key (`exhibit:`, a path) or URL. Video media later." }, "placement": { "type": "object", "additionalProperties": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false }, "description": "Where it sits, per target id; a target not named draws full-frame." }, "opacity": { "type": "number", "description": "How opaque, 0 to 1; absent is 1." } }, "required": [ "kind", "src" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "captions" ], "description": "The discriminator `ClipSourceCast` keys on; always `captions`." }, "src": { "type": "string", "description": "The SRT's media key: `captions:`." }, "clock": { "type": "string", "enum": [ "take", "edit" ], "description": "Which clock the file's cues are on." }, "in": { "type": "number", "description": "File seconds at the clip's first frame, on the edit clock. Unused on the take clock." } }, "required": [ "kind", "src", "clock", "in" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audio" ], "description": "The discriminator `ClipSourceCast` keys on; always `audio`." }, "src": { "type": "string", "description": "The file, as a path relative to the project's folder or a media root (`music/bed.mp3`)." }, "in": { "type": "number", "description": "File seconds: where the file reads at the clip's first frame.", "default": 0.0 } }, "required": [ "kind", "src" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "title" ], "description": "The discriminator `ClipSourceCast` keys on; always `title`." }, "style": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "The face by role: `display` (Fraunces), `sans` (Instrument Sans), `mono` (IBM Plex Mono)." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "The line height: small, medium or large." }, "ink": { "type": "string", "description": "The text's colour, a token name (`frame-ink`, `frame`, `frame-card`, `accent`)." }, "panel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The box's fill, a token name, or null for none." } }, "required": [ "font", "size", "ink", "panel" ], "additionalProperties": false, "description": "The face, size and colours; the template's when the wire gives none (a computed property: set here, never required of a payload)." }, "template": { "type": "string", "enum": [ "lower-third", "full-frame", "tag" ], "description": "Which built-in look: a lower-third, a full-frame title, a tag." }, "fields": { "type": "object", "properties": { "title": { "type": "string", "description": "The first line: the name, the headline.", "default": "" }, "subtitle": { "type": "string", "description": "The second line under it: the role, the strapline; a tag never shows it.", "default": "" } }, "required": [], "additionalProperties": false, "description": "The two lines." }, "placement": { "type": "object", "additionalProperties": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false }, "description": "Where it sits, per target id; a target not named takes the template's placement." } }, "required": [ "kind", "style", "template", "fields" ], "additionalProperties": false } ], "description": "What the clip plays: take footage, a card, a still, a captions file, a sound file or a title." }, "pictureTail": { "type": "number", "description": "The picture runs this many seconds past `duration` while the sound stops — the J-cut. A card's, a still's, a cutaway's; always 0 on the ground's footage and on captions; clamped to the gap before the next clip." }, "targets": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The targets this clip serves — their ids — or null for every target. Clips for different targets may overlap on a track (targets-not-formats.md §3; the brief's `'all' | targetId[]`, null being the dialect's `all`)." }, "label": { "type": "string", "description": "What the timeline prints; a card kind when the file gave none." }, "framing": { "type": "object", "additionalProperties": { "type": "object", "properties": { "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "At least one; sorted by `at`, unique per `at`." } }, "required": [ "keyframes" ], "additionalProperties": false }, "description": "How the picture is cropped and panned, per target id — footage and stills only (docs/core/framing.md). Absent (never null) when the clip has none: the stream's focus, no punch-in. Keyframes on the clip's own clock, so the framing travels with the clip; `retimed`/`part` move them when the footage under it moves." }, "audio": { "type": "object", "properties": { "gain": { "type": "number", "description": "The clip's level in dB: 0 is as recorded, negative quieter. Added to its track's.", "default": 0.0 }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "gain": { "type": "number", "description": "The level in dB: 0 is the clip as recorded, negative quieter." } }, "required": [ "at", "gain" ], "additionalProperties": false }, "description": "The level over the clip's own clock, on top of `gain`; sorted by `at`, unique per `at`; empty for a flat clip.", "default": [] }, "fadeIn": { "type": "number", "description": "Seconds from the clip's first frame over which the sound rises from silence to its level. 0 for none.", "default": 0.0 }, "fadeOut": { "type": "number", "description": "Seconds before the clip's last frame over which the sound falls to silence. 0 for none.", "default": 0.0 } }, "required": [], "additionalProperties": false, "description": "How loud the clip plays — footage and beds only (docs/core/audio.md). Absent (never null) when nothing is set: 0 dB, no keyframes, no fades. Keyframes on the clip's own clock, moved by `retimed`/`part` beside the framing; fades are edge lengths, clamped." }, "speed": { "type": "number", "description": "Constant speed, footage clips only (docs/core/clips.md § Speed): the take runs `speed` times as fast as the edit, so the clip covers `duration × speed` take seconds. Absent (never null) is 1. 0.25 to 4. Only the clock functions and the edit ops' bounds read it." }, "transitionIn": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dissolve", "dip" ], "description": "dissolve, or dip." }, "duration": { "type": "number", "description": "Edit seconds the transition runs, from the clip's first frame, frame-aligned: 0.1 to 5." }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A dip's colour, a token name (`frame`, `frame-ink`, `frame-card`, `accent`); null is `frame`." } }, "required": [ "kind", "duration" ], "additionalProperties": false, "description": "How the clip arrives (docs/core/transitions.md): a dissolve from the clip before it, or a dip through a colour; absent (never null) is a cut. The clip that starts owns the join. Footage and overlay clips; a card, a captions clip or a bed never has one." } }, "required": [ "id", "at", "duration", "source", "pictureTail", "targets", "label" ], "additionalProperties": false }, "description": "Sorted by `at`; no two overlap whose variant sets intersect." }, "muted": { "type": "boolean", "description": "Heard or not. A muted track still shows." }, "locked": { "type": "boolean", "description": "Locked = every mutation of its clips is refused as `locked` — a place, move, blade, trim, slip, roll, tail, speed or delete, and ripples pass it by; a clip's own patches (label, card, streams, targets, title, captions clock) still apply." }, "audio": { "type": "object", "properties": { "gain": { "type": "number", "description": "The track's level in dB, added to each clip's: 0 is as recorded.", "default": 0.0 }, "solo": { "type": "boolean", "description": "A solo on any track of the sequence silences every track without one. A listening state; lint notes one left on.", "default": false }, "duck": { "anyOf": [ { "type": "object", "properties": { "under": { "type": "string", "description": "`speech`, or the id of an audio track on the same sequence." }, "by": { "type": "number", "description": "How far the level drops while `under` sounds, in dB: negative, never 0." }, "attack": { "type": "number", "description": "Seconds the level takes to reach `by`, ending as `under` starts." }, "release": { "type": "number", "description": "Seconds the level takes to come back, starting as `under` ends." } }, "required": [ "under", "by", "attack", "release" ], "additionalProperties": false }, { "type": "null" } ], "description": "How the track gives way to speech or to another track, or null." } }, "required": [], "additionalProperties": false, "description": "The track's level, solo and ducking (docs/core/audio.md). Absent (never null) when nothing is set: 0 dB, no solo, no duck. `muted` above is the mute." } }, "required": [ "id", "name", "medium", "order", "groupId", "clips", "muted", "locked" ], "additionalProperties": false }, "description": "`tracks[0]` is the top of the stack: drawn last, wins per pixel. Sorted by `order`." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the sequence (`g1`, `g2` …)." }, "name": { "type": "string", "description": "What the folded row is called." } }, "required": [ "id", "name" ], "additionalProperties": false }, "description": "The tracks' groups, in no order; a track names its group by id." }, "roles": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Which track plays each role the derivation laid (F13): `footage` (the camera), `screen`, `cam-b`, `mic`, `system`, `slides`, `sponsors`, `captions`, `cards`, … → a track id. Absent on a sequence nobody derived since F13; a role then reads the track whose id is the role word (`roleTrack`)." }, "minted": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "The highest track number ever minted per medium (F13, Len: \"track IDs are immutable… never reused\"): `V` and `A` → n. `addTrack` mints past it and nothing lowers it, so a removed track's id never returns." }, "scenes": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`pl1`, `pl2` …)." }, "at": { "type": "number", "description": "Edit seconds on its timeline." }, "sceneId": { "type": "string", "description": "The scene from here: a built-in's id (`split-plain`) or a project scene's (`sc1`)." }, "mappings": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The placement's own tracks for the scene's panels, panel id → track id; absent = the scene's own mappings and roles." } }, "required": [ "id", "at", "sceneId" ], "additionalProperties": false } }, "description": "The scenes track (P2c, F12): per target, the scenes placed on this timeline at edit seconds, each list sorted by `at`. A cue file places the first ones once; the timeline is the truth after that.", "default": {} } }, "required": [ "id", "name", "fps", "tracks", "groups" ], "additionalProperties": false }, "description": "The timelines: the full episode and the teaser are filmed from one script and cut apart, sharing the takes. Never empty." }, "targets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique in the document: a preset's id (`16:9`) or the custom target's." }, "name": { "type": "string", "description": "What the page and the plan names call it (`Horizontal`, `Square`)." }, "aspect": { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame." }, "enabled": { "type": "boolean", "description": "In the plans, or kept with its cues and out of them." }, "safe": { "type": "object", "properties": { "action": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Action-safe: nothing that matters outside it." }, "title": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Title-safe: text inside it." }, "caption": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Where the captions band sits." }, "chrome": { "anyOf": [ { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, { "type": "null" } ], "description": "The platform's own overlays (a Reel's top bar, its action rail, its caption strip); null for a frame shown bare." } }, "required": [ "action", "title", "caption", "chrome" ], "additionalProperties": false, "description": "Its safe areas." }, "primitives": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "full-cam", "full-cam-tight", "split", "full-screen", "stack", "pip", "over-shoulder" ] } }, { "type": "null" } ], "description": "The primitives this frame offers, when the aspect's own list (`Targets::primitivesFor`) is not the one wanted; null = computed from the aspect." } }, "required": [ "id", "name", "aspect", "enabled", "safe" ], "additionalProperties": false }, "description": "The frames the project renders for, in order; never empty. A take's scene cues and a clip's `targets` name them by id (targets-not-formats.md §1)." }, "captions": { "type": "object", "properties": { "position": { "type": "string", "enum": [ "bottom", "top", "custom" ], "description": "Bottom, top, or a custom `y` inside the captions band." }, "y": { "type": "number", "description": "Where in the captions band, for `custom`: 0 at its top, 1 at its floor." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "Small, medium or large type." }, "box": { "type": "string", "enum": [ "pill", "band", "none" ], "description": "A pill, a full-width band, or nothing behind the text." }, "font": { "type": "string", "enum": [ "sans", "serif", "mono" ], "description": "Sans, serif or mono." }, "safe": { "type": "boolean", "description": "Keep them inside the caption-safe area of the frame whatever `position` says." } }, "required": [ "position", "y", "size", "box", "font", "safe" ], "additionalProperties": false, "description": "How the captions track's cues are drawn." }, "scene": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "The project's scene as the scene editor exported it, verbatim; null until attached or when unusable. The scene editor owns its shape — see `Scene`." }, "script": { "anyOf": [ { "type": "object", "properties": { "team": { "type": "string", "description": "The PteroPrompter team slug." }, "slug": { "type": "string", "description": "The script slug inside the team." } }, "required": [ "team", "slug" ], "additionalProperties": false }, { "type": "null" } ], "description": "The script the takes were read from, when the page knows it." }, "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the document's presets (`ep1`, `ep2` …)." }, "targetId": { "type": "string", "description": "The target this preset renders." }, "name": { "type": "string", "description": "What the Exports card calls it: `YouTube 1080p`, `Shorts`." }, "container": { "type": "string", "enum": [ "mp4", "mov", "webm" ], "description": "The file: mp4, mov or webm." }, "codec": { "type": "string", "enum": [ "h264", "hevc", "prores", "vp9", "av1" ], "description": "The video codec." }, "resolution": { "type": "object", "properties": { "w": { "type": "integer", "description": "Width in pixels." }, "h": { "type": "integer", "description": "Height in pixels." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame in pixels." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Frames per second; null renders at the sequence's rate." }, "quality": { "type": "object", "properties": { "crf": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Constant rate factor (lower is better; 18 is visually lossless for h264); null when `bitrate` rules." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Target bitrate in kbit/s; null when `crf` rules." } }, "required": [], "additionalProperties": false, "description": "How hard the video is compressed: `crf` or `bitrate`, one of the two." }, "audio": { "type": "object", "properties": { "codec": { "type": "string", "enum": [ "aac", "pcm", "opus" ], "description": "aac, pcm or opus." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "kbit/s; null for a codec that has no rate (pcm) or the encoder's default." } }, "required": [ "codec", "bitrate" ], "additionalProperties": false, "description": "The sound: codec and bitrate." }, "perChapter": { "type": "boolean", "description": "One file per chapter (`chapterFilter` says which) rather than one for the whole edit." }, "chapterFilter": { "type": "string", "enum": [ "all", "short" ], "description": "Which chapters a per-chapter preset renders: all, or the `short` ones." }, "enabled": { "type": "boolean", "description": "A disabled preset renders nothing and stays on the list." }, "naming": { "type": "string", "description": "The file name: `{take}`, `{sequence}`, `{chapter}`, `{target}` and `{preset}` are slugs; a name handed out twice gets `-2`, `-3`." } }, "required": [ "id", "targetId", "name", "container", "codec", "resolution", "fps", "quality", "audio", "perChapter", "chapterFilter", "enabled", "naming" ], "additionalProperties": false }, "description": "How each target is encoded into files (`render.json`; docs/render/manifest-v4.md \"Presets\"). Absent on a document that never held any: the defaults for its targets are read in its place (`presetsOrDefaults`); once stored, the list is the user's." }, "scenes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A built-in's name (`split-plain`, `pip-bottom-right-small`), a project's `sc1` …, a library id." }, "name": { "type": "string", "description": "" }, "family": { "anyOf": [ { "type": "string", "enum": [ "full", "full-tight", "screen", "two-up", "pip", "over-shoulder" ] }, { "type": "null" } ], "description": "The family across frames (`copyScenes` maps by it); null for a scene made from scratch." }, "knobs": { "anyOf": [ { "type": "object", "properties": { "gutter": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The one gutter, percent of frame width: 0 up to (not including) 50." }, "camWidth": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam column's width, percent of frame width: above 0, below 100." }, "stackSplit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam's share of the stack's height: a third to two thirds (`Layouts::clampSplit`'s range — a value outside it would render clamped)." }, "tightInset": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "How far `full-cam-tight` pushes in, percent: 0 up to (not including) 50." }, "sponsors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the split reserves the sponsor panel." }, "pipCorner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where PiP's small picture sits: `top-left`, `top-right`, `bottom-left`, `bottom-right`." }, "pipSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How wide PiP's small picture is: `small`, `medium`, `large`." }, "shoulderSide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which shoulder the newscast box floats over: `left`, `right`." } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The pre-tuning a parametric scene lays out with; null for a baked one." }, "aspect": { "anyOf": [ { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false }, { "type": "null" } ], "description": "The frame a baked scene is laid out for; null for a parametric one (any frame)." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the scene (`p1`, `p2` …)." }, "name": { "type": "string", "description": "What the inspector calls it (`Camera`, `Screen`, `Sponsors`, `Background`); free text." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track whose clip in force this panel shows; null is an empty panel (its look only)." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where the panel sits, percent of the frame." }, "transform": { "type": "object", "properties": { "x": { "type": "number", "description": "Percent of the rect's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the rect's height, downward.", "default": 0.0 }, "zoom": { "type": "number", "description": "1 = the picture as fitted; up to 8.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "How the picture sits inside the rect, after the clip's own framing.", "default": { "x": 0.0, "y": 0.0, "zoom": 1.0 } }, "fit": { "type": "string", "enum": [ "cover", "contain" ], "description": "How a picture without a framing fits the rect.", "default": "cover" }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 is square.", "default": 0.0 }, "border": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "The stroke's thickness, a percent of the frame's **width** (the one unit on both frames — a radius and a shadow are percents of the height); 0 up to 10." }, "colour": { "type": "string", "description": "A colour token (`frame`, `frame-ink`, `frame-card`, `accent`)." }, "style": { "type": "string", "enum": [ "solid", "dashed", "dotted" ], "description": "", "default": "solid" } }, "required": [ "width", "colour" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "shadow": { "anyOf": [ { "type": "object", "properties": { "blur": { "type": "number", "description": "Blur radius, percent of the frame's height; 0 to 20." }, "x": { "type": "number", "description": "Offset, percent of the frame's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Offset, percent of the frame's height, downward.", "default": 0.0 }, "colour": { "type": "string", "description": "A colour token.", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.5 } }, "required": [ "blur" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "alpha": { "type": "number", "description": "The panel's opacity, 0 to 1.", "default": 1.0 }, "blur": { "type": "number", "description": "Backdrop blur, px; 0 is none (C-14's panel blur, the stage draws it).", "default": 0.0 }, "stream": { "anyOf": [ { "type": "string", "enum": [ "screen", "primary" ] }, { "type": "null" } ], "description": "Which of a take clip's streams, while a take is one clip with several (pre-B4); null is the first video stream." }, "role": { "anyOf": [ { "type": "string", "enum": [ "cam", "screen", "slide", "sponsors", "pip", "background" ] }, { "type": "null" } ], "description": "What the panel reads when `trackId` is null or names a track the sequence lacks: the role's topmost track; null draws empty." }, "hideWhenEmpty": { "type": "boolean", "description": "The panel hides — its look and picture — while its track has no clip in force; the scene's `whenHidden` says what moves.", "default": false } }, "required": [ "id", "name", "trackId", "rect" ], "additionalProperties": false }, "description": "" }, "whenHidden": { "type": "array", "items": { "type": "object", "properties": { "hidden": { "type": "string", "description": "The strip that hides (`role: sponsors`, `hideWhenEmpty`)." }, "panelId": { "type": "string", "description": "The panel that moves while it does." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where it sits then, percent of the frame." } }, "required": [ "hidden", "panelId", "rect" ], "additionalProperties": false }, "description": "" }, "captions": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "", "default": true }, "burnIn": { "type": "boolean", "description": "The export writes them into the picture; false is a sidecar, or none.", "default": true }, "placement": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false, "description": "", "default": { "anchor": "bottom", "x": 0.0, "y": 0.0, "w": 80.0 } }, "look": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "", "default": "sans" }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "", "default": "medium" }, "tracking": { "type": "number", "description": "Letter spacing, percent of the em; -20 to 50.", "default": 0.0 }, "leading": { "type": "number", "description": "Line height as a multiple of the size; 0.8 to 2.", "default": 1.2 }, "colour": { "type": "string", "description": "The text's colour token.", "default": "frame-ink" }, "stroke": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "Percent of the frame's height; 0 to 2." }, "colour": { "type": "string", "description": "", "default": "frame" } }, "required": [ "width" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "background": { "anyOf": [ { "type": "object", "properties": { "colour": { "type": "string", "description": "", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.62 }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 to 10. Stored and returned as set, but not drawn yet: the reference renderer squares the box (libass has no rounded box), and so does the app's preview. Drawing it is RADIUS-2.", "default": 0.0 } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "padding": { "type": "number", "description": "Inside the background, percent of the frame's height; 0 to 10.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "", "default": { "font": "sans", "size": "medium", "tracking": 0.0, "leading": 1.2, "colour": "frame-ink", "stroke": null, "background": null, "padding": 1.0 } } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The scene's captions; null is the timeline's default, shown and burnt in." }, "scope": { "type": "string", "enum": [ "builtin", "project", "library" ], "description": "" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A project scene copied from the library: the library id it came from." } }, "required": [ "id", "name", "family", "knobs", "aspect", "panels", "whenHidden", "captions", "scope" ], "additionalProperties": false }, "description": "The project's own scenes (C-22, docs/core/scenes.md): ordered panels mapped to tracks, or a family with its knobs. Absent = none (the built-ins are code; the library's are copied in when applied)." } }, "required": [ "version", "savedAt", "takes", "sequences", "targets", "captions", "scene", "script" ], "additionalProperties": false, "description": "The whole document at that position." }, "session": { "anyOf": [ { "type": "object", "properties": { "playhead": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Playhead, edit seconds." }, "zoom": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timeline zoom, pixels per second." }, "activeSequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline the page shows; null = the document's `activeSequenceId` (the default for every op that takes a sequence). View state, not history: the spike's `setActiveSequence` is this field, never a document op. Not checked against the document — a view is never refused; the page falls back when the id is gone." }, "activeTargetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The target the stage shows; null = the page's own default (the first enabled one). View state, not history (U-04a1, C-10b): not checked against the document — the page falls back when the id is gone." } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The session view state as last set by `setSession`; null before the first one." }, "undoable": { "type": "boolean", "description": "Whether `undo` has a step to take back." }, "redoable": { "type": "boolean", "description": "Whether `redo` has a step to replay." }, "media": { "type": "object", "additionalProperties": { "type": "object", "properties": { "path": { "type": "string", "description": "The file's path relative to the project's folder, forward slashes." }, "bytes": { "type": "integer", "description": "Its length in bytes." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A signed loopback URL on the media port the page may fetch (with `Range`) until `expires`; null when no media server is known (outside the shell)." }, "expires": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Unix time the URL stops working; re-read `document` for a fresh one. Null with a null URL." } }, "required": [ "path", "bytes", "url", "expires" ], "additionalProperties": false }, "description": "Every file in the project's folder the page can fetch bytes for, under each key it looks one up by (its relative path, bare name, asset key): a signed URL on the media port, or `url: null` outside the shell. Re-read after a take is added or on a 403." } }, "required": [ "seq", "document", "session", "undoable", "redoable", "media" ], "additionalProperties": false }, "DuplicateSceneArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The scene to copy: a built-in's id, a project scene's, a library id." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The copy's name; absent = the source's name with \" copy\"." } }, "required": [ "sceneId" ], "additionalProperties": false }, "DuplicateSequenceArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The timeline to copy." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "What the copy's tab says; absent = ` copy`." } }, "required": [ "sequenceId" ], "additionalProperties": false }, "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unknownId", "invalidArgs", "projectNotOpen", "locked", "documentInvalid", "notEmpty", "noDocument", "unknownOp", "unknownProject", "unauthenticated", "forbidden", "payloadTooLarge", "rateLimited" ], "description": "The stable refusal code (OpCode), the same on every surface." }, "message": { "type": "string", "description": "What was refused, for a human." }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The document or args path the refusal names, when it names one; dotted for nested fields (`source.kind`)." }, "details": { "type": "object", "properties": { "takes": { "type": "array", "items": { "type": "object", "properties": { "folder": { "type": "string", "description": "The take folder, an absolute path on this machine." }, "name": { "type": "string", "description": "The folder's name: what the take is called on disk." } }, "required": [ "folder", "name" ], "additionalProperties": false }, "description": "The take folders a project file written by an older build names, found on this machine — what \"derive again\" starts from. Empty when it names none this machine holds.", "default": [] } }, "required": [], "additionalProperties": false, "description": "What the caller can act on, when the refusal names something (a project file's take folders); absent otherwise." } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "The refusal." } }, "required": [ "error" ], "additionalProperties": false }, "EventsPage": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The head of the log: the position `document` reflects." }, "document": { "type": "object", "properties": { "version": { "type": "integer", "description": "Always 6 here (tracks without roles, B3; scenes as panels were 5, C-22; user-defined tracks 4, C-09; targets 3, C-10); an older file is upgraded on the way in." }, "savedAt": { "type": "string", "description": "When this document was last written, ISO 8601. An input, never the clock: parse and normalise read no time." }, "takes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its own namespace among takes; the source id when the file gave none." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rheocles" ], "description": "The discriminator `TakeSourceCast` keys on; always `rheocles`." }, "id": { "type": "string", "description": "The manifest's `id`." }, "name": { "type": "string", "description": "Something to print; the id when the manifest gave none." }, "folder": { "type": "string", "description": "The folder name, for display. The handle itself is not serialisable." }, "manifest": { "type": "string", "description": "The manifest file's name inside the folder; always `manifest.json`." } }, "required": [ "kind", "id", "name", "folder", "manifest" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "obs" ], "description": "The discriminator `TakeSourceCast` keys on; always `obs`." }, "id": { "type": "string", "description": "The footage file name, which is also the take's identity." }, "name": { "type": "string", "description": "Something to print; the id when the file gave none." }, "folder": { "type": "string", "description": "The folder name, for display." }, "cues": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cue CSV the markers were read from, if one was given." } }, "required": [ "kind", "id", "name", "folder", "cues" ], "additionalProperties": false } ], "description": "Where the take came from, so the page can find it again." }, "fps": { "type": "number", "description": "The frame rate timecodes are shown in. The primary stream's, or 30." }, "duration": { "type": "number", "description": "Take seconds: the furthest any stream reaches." }, "streams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The manifest stream id (`window:13085`), or the file name for a bare file." }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "What the stream is for, which decides where the stage puts it." }, "medium": { "type": "string", "enum": [ "video", "audio" ], "description": "Picture or sound." }, "file": { "type": "string", "description": "File name relative to the take folder. Never an absolute path: the folder moves, the edit must not care." }, "label": { "type": "string", "description": "Something to print: the manifest's `name`, or the file name." }, "offset": { "type": "number", "description": "Take seconds at which the file's first frame sits. A late joiner is positive; a file that started early is negative." }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "File seconds: the file's own length, once a browser has read it. Null until then." }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Pixel width for video, so the stage can pick a crop before the file is loaded." }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Pixel height for video." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Frames per second as recorded, when known. Screen captures are variable-rate; this is nominal." }, "primary": { "type": "boolean", "description": "The one video stream the transport follows. Exactly one stream of a take has this." }, "muted": { "type": "boolean", "description": "Heard or not." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "The point a crop keeps centred." }, "timecode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Local time-of-day of the file's first frame, `HH:MM:SS:FF` at the stream's integer fps, as Rheocles stamps it. Null for a bare file." }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The codec of the stream's own medium as `ffprobe` names it (`hevc`, `h264`, `aac`…); null until `probeMedia` learns it (U-13e)." }, "probe": { "type": "object", "properties": { "fps": { "anyOf": [ { "type": "object", "properties": { "num": { "type": "integer", "description": "The numerator." }, "den": { "type": "integer", "description": "The denominator, never 0." } }, "required": [ "num", "den" ], "additionalProperties": false }, { "type": "null" } ], "description": "The frame rate as a ratio, exact; null for a file with no picture." }, "timecode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timecode the file carries (`10:00:00:00`), or null." }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's channel count, or null without sound." }, "sampleRate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's sample rate in Hz, or null without sound." }, "container": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ffprobe's container name, or null." }, "bytes": { "type": "integer", "description": "The file's size in bytes when probed." }, "sha256Prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the file's first MiB, hex — the signature; null when the file could not be hashed." } }, "required": [ "fps", "timecode", "channels", "sampleRate", "container", "bytes", "sha256Prefix" ], "additionalProperties": false, "description": "What the file was probed to be beyond the flat fields — the exact frame rate, timecode, channels, sample rate, container, the signature relink matches by (C-17). Absent until probed." }, "proxy": { "type": "object", "properties": { "path": { "type": "string", "description": "The proxy file, relative to the project's folder." }, "preset": { "type": "string", "description": "The preset it was made at: `720p`, `1080p`." } }, "required": [ "path", "preset" ], "additionalProperties": false, "description": "The finished proxy for playback — its path beside the project and its preset (C-17b). Absent until one is ready; the manifest never names it." } }, "required": [ "id", "role", "medium", "file", "label", "offset", "duration", "width", "height", "fps", "primary", "muted", "focus", "timecode" ], "additionalProperties": false }, "description": "The files recorded on this cue clock; exactly one is the primary video." }, "markers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`m1`, `m2` …)." }, "t": { "type": "number", "description": "Take seconds (a moment of the recording), not a timeline position: `markers` gives where the edit shows it (`inEdit`). Editable." }, "label": { "type": "string", "description": "`marker:chapter Cold Open`, `obs:scene full-cam-tight`, `take:go` …" }, "origin": { "type": "string", "enum": [ "manifest", "csv", "hand" ], "description": "Where it came from: the recorder's manifest, a cue CSV, or a hand." }, "originalT": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Take seconds: where the recorder put it. Null for a hand-placed marker." } }, "required": [ "id", "t", "label", "origin", "originalT" ], "additionalProperties": false }, "description": "Sorted by `t`." }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`c1`, `c2` …)." }, "name": { "type": "string", "description": "The chapter heading, as the script wrote it." }, "at": { "type": "number", "description": "Take seconds (a moment of the recording), not a timeline position: `chapters` gives the chapter's edit seconds (`editAt`). Editable." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "`short`, `bumper`, `bumper:top_story`, `bumper:end_program` … verbatim from the heading." } }, "required": [ "id", "name", "at", "flags" ], "additionalProperties": false }, "description": "Sorted by `at`." }, "spans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`p1`, `p2` …)." }, "name": { "type": "string", "description": "The `X` of `marker:in X`." }, "in": { "type": "number", "description": "Take seconds, inclusive." }, "out": { "type": "number", "description": "Take seconds, exclusive." }, "markerIds": { "type": "array", "items": { "type": "string" }, "description": "The markers that bound it, so re-deriving can find it again." } }, "required": [ "id", "name", "in", "out", "markerIds" ], "additionalProperties": false }, "description": "Sorted by `in`; never empty or inverted." } }, "required": [ "id", "source", "fps", "duration", "streams", "markers", "chapters", "spans" ], "additionalProperties": false }, "description": "One today; the teaser later." }, "sequences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its own namespace: `full`, `teaser`, a slug of the name." }, "name": { "type": "string", "description": "What the page calls it; the id when the file gave none." }, "fps": { "type": "number", "description": "Every clip time is aligned to whole frames at this rate." }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its immutable id within the sequence (F13): `V` picture, `A` sound — never changed, never reused; a document from before F13 keeps its word ids (`footage`, `mic` …)." }, "name": { "type": "string", "description": "What the track is called; its id when the file gave none." }, "medium": { "type": "string", "enum": [ "video", "audio" ], "description": "Picture or sound — the track's type (docs/decisions/tracks-are-just-tracks.md): a video track takes every picture clip, an audio track take clips and beds." }, "order": { "type": "integer", "description": "Position in the stack, 0 at the top; `tracks[]` is kept sorted by it." }, "groupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The group the track folds into, or null." }, "clips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`k1`, `k2` …)." }, "at": { "type": "number", "description": "Edit seconds, inclusive." }, "duration": { "type": "number", "description": "Edit seconds. Always positive." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "take" ], "description": "The discriminator `ClipSourceCast` keys on; always `take`." }, "takeId": { "type": "string", "description": "The take the footage is from; must name a take the document has." }, "in": { "type": "number", "description": "Take seconds at the clip's first frame." }, "streams": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The streams this clip plays; null is every stream of the take — the automatic group." } }, "required": [ "kind", "takeId", "in", "streams" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ], "description": "The discriminator `ClipSourceCast` keys on; always `card`." }, "card": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bumper", "sting", "quote", "exhibit" ], "description": "Bumper, sting, quote or exhibit." }, "title": { "type": "string", "description": "The card's heading, or the chapter name for a bumper." }, "body": { "type": "string", "description": "The quote text, the bumper's console line (`> top_story`), the exhibit stem." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A media key or URL, for an exhibit." }, "chapterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The chapter a bumper opens." } }, "required": [ "kind", "title", "body", "src", "chapterId" ], "additionalProperties": false, "description": "The card the clip shows." } }, "required": [ "kind", "card" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ], "description": "The discriminator `ClipSourceCast` keys on; always `image`." }, "src": { "type": "string", "description": "A media key (`exhibit:`, a path) or URL. Video media later." }, "placement": { "type": "object", "additionalProperties": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false }, "description": "Where it sits, per target id; a target not named draws full-frame." }, "opacity": { "type": "number", "description": "How opaque, 0 to 1; absent is 1." } }, "required": [ "kind", "src" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "captions" ], "description": "The discriminator `ClipSourceCast` keys on; always `captions`." }, "src": { "type": "string", "description": "The SRT's media key: `captions:`." }, "clock": { "type": "string", "enum": [ "take", "edit" ], "description": "Which clock the file's cues are on." }, "in": { "type": "number", "description": "File seconds at the clip's first frame, on the edit clock. Unused on the take clock." } }, "required": [ "kind", "src", "clock", "in" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audio" ], "description": "The discriminator `ClipSourceCast` keys on; always `audio`." }, "src": { "type": "string", "description": "The file, as a path relative to the project's folder or a media root (`music/bed.mp3`)." }, "in": { "type": "number", "description": "File seconds: where the file reads at the clip's first frame.", "default": 0.0 } }, "required": [ "kind", "src" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "title" ], "description": "The discriminator `ClipSourceCast` keys on; always `title`." }, "style": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "The face by role: `display` (Fraunces), `sans` (Instrument Sans), `mono` (IBM Plex Mono)." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "The line height: small, medium or large." }, "ink": { "type": "string", "description": "The text's colour, a token name (`frame-ink`, `frame`, `frame-card`, `accent`)." }, "panel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The box's fill, a token name, or null for none." } }, "required": [ "font", "size", "ink", "panel" ], "additionalProperties": false, "description": "The face, size and colours; the template's when the wire gives none (a computed property: set here, never required of a payload)." }, "template": { "type": "string", "enum": [ "lower-third", "full-frame", "tag" ], "description": "Which built-in look: a lower-third, a full-frame title, a tag." }, "fields": { "type": "object", "properties": { "title": { "type": "string", "description": "The first line: the name, the headline.", "default": "" }, "subtitle": { "type": "string", "description": "The second line under it: the role, the strapline; a tag never shows it.", "default": "" } }, "required": [], "additionalProperties": false, "description": "The two lines." }, "placement": { "type": "object", "additionalProperties": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false }, "description": "Where it sits, per target id; a target not named takes the template's placement." } }, "required": [ "kind", "style", "template", "fields" ], "additionalProperties": false } ], "description": "What the clip plays: take footage, a card, a still, a captions file, a sound file or a title." }, "pictureTail": { "type": "number", "description": "The picture runs this many seconds past `duration` while the sound stops — the J-cut. A card's, a still's, a cutaway's; always 0 on the ground's footage and on captions; clamped to the gap before the next clip." }, "targets": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The targets this clip serves — their ids — or null for every target. Clips for different targets may overlap on a track (targets-not-formats.md §3; the brief's `'all' | targetId[]`, null being the dialect's `all`)." }, "label": { "type": "string", "description": "What the timeline prints; a card kind when the file gave none." }, "framing": { "type": "object", "additionalProperties": { "type": "object", "properties": { "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "At least one; sorted by `at`, unique per `at`." } }, "required": [ "keyframes" ], "additionalProperties": false }, "description": "How the picture is cropped and panned, per target id — footage and stills only (docs/core/framing.md). Absent (never null) when the clip has none: the stream's focus, no punch-in. Keyframes on the clip's own clock, so the framing travels with the clip; `retimed`/`part` move them when the footage under it moves." }, "audio": { "type": "object", "properties": { "gain": { "type": "number", "description": "The clip's level in dB: 0 is as recorded, negative quieter. Added to its track's.", "default": 0.0 }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "gain": { "type": "number", "description": "The level in dB: 0 is the clip as recorded, negative quieter." } }, "required": [ "at", "gain" ], "additionalProperties": false }, "description": "The level over the clip's own clock, on top of `gain`; sorted by `at`, unique per `at`; empty for a flat clip.", "default": [] }, "fadeIn": { "type": "number", "description": "Seconds from the clip's first frame over which the sound rises from silence to its level. 0 for none.", "default": 0.0 }, "fadeOut": { "type": "number", "description": "Seconds before the clip's last frame over which the sound falls to silence. 0 for none.", "default": 0.0 } }, "required": [], "additionalProperties": false, "description": "How loud the clip plays — footage and beds only (docs/core/audio.md). Absent (never null) when nothing is set: 0 dB, no keyframes, no fades. Keyframes on the clip's own clock, moved by `retimed`/`part` beside the framing; fades are edge lengths, clamped." }, "speed": { "type": "number", "description": "Constant speed, footage clips only (docs/core/clips.md § Speed): the take runs `speed` times as fast as the edit, so the clip covers `duration × speed` take seconds. Absent (never null) is 1. 0.25 to 4. Only the clock functions and the edit ops' bounds read it." }, "transitionIn": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dissolve", "dip" ], "description": "dissolve, or dip." }, "duration": { "type": "number", "description": "Edit seconds the transition runs, from the clip's first frame, frame-aligned: 0.1 to 5." }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A dip's colour, a token name (`frame`, `frame-ink`, `frame-card`, `accent`); null is `frame`." } }, "required": [ "kind", "duration" ], "additionalProperties": false, "description": "How the clip arrives (docs/core/transitions.md): a dissolve from the clip before it, or a dip through a colour; absent (never null) is a cut. The clip that starts owns the join. Footage and overlay clips; a card, a captions clip or a bed never has one." } }, "required": [ "id", "at", "duration", "source", "pictureTail", "targets", "label" ], "additionalProperties": false }, "description": "Sorted by `at`; no two overlap whose variant sets intersect." }, "muted": { "type": "boolean", "description": "Heard or not. A muted track still shows." }, "locked": { "type": "boolean", "description": "Locked = every mutation of its clips is refused as `locked` — a place, move, blade, trim, slip, roll, tail, speed or delete, and ripples pass it by; a clip's own patches (label, card, streams, targets, title, captions clock) still apply." }, "audio": { "type": "object", "properties": { "gain": { "type": "number", "description": "The track's level in dB, added to each clip's: 0 is as recorded.", "default": 0.0 }, "solo": { "type": "boolean", "description": "A solo on any track of the sequence silences every track without one. A listening state; lint notes one left on.", "default": false }, "duck": { "anyOf": [ { "type": "object", "properties": { "under": { "type": "string", "description": "`speech`, or the id of an audio track on the same sequence." }, "by": { "type": "number", "description": "How far the level drops while `under` sounds, in dB: negative, never 0." }, "attack": { "type": "number", "description": "Seconds the level takes to reach `by`, ending as `under` starts." }, "release": { "type": "number", "description": "Seconds the level takes to come back, starting as `under` ends." } }, "required": [ "under", "by", "attack", "release" ], "additionalProperties": false }, { "type": "null" } ], "description": "How the track gives way to speech or to another track, or null." } }, "required": [], "additionalProperties": false, "description": "The track's level, solo and ducking (docs/core/audio.md). Absent (never null) when nothing is set: 0 dB, no solo, no duck. `muted` above is the mute." } }, "required": [ "id", "name", "medium", "order", "groupId", "clips", "muted", "locked" ], "additionalProperties": false }, "description": "`tracks[0]` is the top of the stack: drawn last, wins per pixel. Sorted by `order`." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the sequence (`g1`, `g2` …)." }, "name": { "type": "string", "description": "What the folded row is called." } }, "required": [ "id", "name" ], "additionalProperties": false }, "description": "The tracks' groups, in no order; a track names its group by id." }, "roles": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Which track plays each role the derivation laid (F13): `footage` (the camera), `screen`, `cam-b`, `mic`, `system`, `slides`, `sponsors`, `captions`, `cards`, … → a track id. Absent on a sequence nobody derived since F13; a role then reads the track whose id is the role word (`roleTrack`)." }, "minted": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "The highest track number ever minted per medium (F13, Len: \"track IDs are immutable… never reused\"): `V` and `A` → n. `addTrack` mints past it and nothing lowers it, so a removed track's id never returns." }, "scenes": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`pl1`, `pl2` …)." }, "at": { "type": "number", "description": "Edit seconds on its timeline." }, "sceneId": { "type": "string", "description": "The scene from here: a built-in's id (`split-plain`) or a project scene's (`sc1`)." }, "mappings": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The placement's own tracks for the scene's panels, panel id → track id; absent = the scene's own mappings and roles." } }, "required": [ "id", "at", "sceneId" ], "additionalProperties": false } }, "description": "The scenes track (P2c, F12): per target, the scenes placed on this timeline at edit seconds, each list sorted by `at`. A cue file places the first ones once; the timeline is the truth after that.", "default": {} } }, "required": [ "id", "name", "fps", "tracks", "groups" ], "additionalProperties": false }, "description": "The timelines: the full episode and the teaser are filmed from one script and cut apart, sharing the takes. Never empty." }, "targets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique in the document: a preset's id (`16:9`) or the custom target's." }, "name": { "type": "string", "description": "What the page and the plan names call it (`Horizontal`, `Square`)." }, "aspect": { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame." }, "enabled": { "type": "boolean", "description": "In the plans, or kept with its cues and out of them." }, "safe": { "type": "object", "properties": { "action": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Action-safe: nothing that matters outside it." }, "title": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Title-safe: text inside it." }, "caption": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Where the captions band sits." }, "chrome": { "anyOf": [ { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, { "type": "null" } ], "description": "The platform's own overlays (a Reel's top bar, its action rail, its caption strip); null for a frame shown bare." } }, "required": [ "action", "title", "caption", "chrome" ], "additionalProperties": false, "description": "Its safe areas." }, "primitives": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "full-cam", "full-cam-tight", "split", "full-screen", "stack", "pip", "over-shoulder" ] } }, { "type": "null" } ], "description": "The primitives this frame offers, when the aspect's own list (`Targets::primitivesFor`) is not the one wanted; null = computed from the aspect." } }, "required": [ "id", "name", "aspect", "enabled", "safe" ], "additionalProperties": false }, "description": "The frames the project renders for, in order; never empty. A take's scene cues and a clip's `targets` name them by id (targets-not-formats.md §1)." }, "captions": { "type": "object", "properties": { "position": { "type": "string", "enum": [ "bottom", "top", "custom" ], "description": "Bottom, top, or a custom `y` inside the captions band." }, "y": { "type": "number", "description": "Where in the captions band, for `custom`: 0 at its top, 1 at its floor." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "Small, medium or large type." }, "box": { "type": "string", "enum": [ "pill", "band", "none" ], "description": "A pill, a full-width band, or nothing behind the text." }, "font": { "type": "string", "enum": [ "sans", "serif", "mono" ], "description": "Sans, serif or mono." }, "safe": { "type": "boolean", "description": "Keep them inside the caption-safe area of the frame whatever `position` says." } }, "required": [ "position", "y", "size", "box", "font", "safe" ], "additionalProperties": false, "description": "How the captions track's cues are drawn." }, "scene": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "The project's scene as the scene editor exported it, verbatim; null until attached or when unusable. The scene editor owns its shape — see `Scene`." }, "script": { "anyOf": [ { "type": "object", "properties": { "team": { "type": "string", "description": "The PteroPrompter team slug." }, "slug": { "type": "string", "description": "The script slug inside the team." } }, "required": [ "team", "slug" ], "additionalProperties": false }, { "type": "null" } ], "description": "The script the takes were read from, when the page knows it." }, "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the document's presets (`ep1`, `ep2` …)." }, "targetId": { "type": "string", "description": "The target this preset renders." }, "name": { "type": "string", "description": "What the Exports card calls it: `YouTube 1080p`, `Shorts`." }, "container": { "type": "string", "enum": [ "mp4", "mov", "webm" ], "description": "The file: mp4, mov or webm." }, "codec": { "type": "string", "enum": [ "h264", "hevc", "prores", "vp9", "av1" ], "description": "The video codec." }, "resolution": { "type": "object", "properties": { "w": { "type": "integer", "description": "Width in pixels." }, "h": { "type": "integer", "description": "Height in pixels." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame in pixels." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Frames per second; null renders at the sequence's rate." }, "quality": { "type": "object", "properties": { "crf": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Constant rate factor (lower is better; 18 is visually lossless for h264); null when `bitrate` rules." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Target bitrate in kbit/s; null when `crf` rules." } }, "required": [], "additionalProperties": false, "description": "How hard the video is compressed: `crf` or `bitrate`, one of the two." }, "audio": { "type": "object", "properties": { "codec": { "type": "string", "enum": [ "aac", "pcm", "opus" ], "description": "aac, pcm or opus." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "kbit/s; null for a codec that has no rate (pcm) or the encoder's default." } }, "required": [ "codec", "bitrate" ], "additionalProperties": false, "description": "The sound: codec and bitrate." }, "perChapter": { "type": "boolean", "description": "One file per chapter (`chapterFilter` says which) rather than one for the whole edit." }, "chapterFilter": { "type": "string", "enum": [ "all", "short" ], "description": "Which chapters a per-chapter preset renders: all, or the `short` ones." }, "enabled": { "type": "boolean", "description": "A disabled preset renders nothing and stays on the list." }, "naming": { "type": "string", "description": "The file name: `{take}`, `{sequence}`, `{chapter}`, `{target}` and `{preset}` are slugs; a name handed out twice gets `-2`, `-3`." } }, "required": [ "id", "targetId", "name", "container", "codec", "resolution", "fps", "quality", "audio", "perChapter", "chapterFilter", "enabled", "naming" ], "additionalProperties": false }, "description": "How each target is encoded into files (`render.json`; docs/render/manifest-v4.md \"Presets\"). Absent on a document that never held any: the defaults for its targets are read in its place (`presetsOrDefaults`); once stored, the list is the user's." }, "scenes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A built-in's name (`split-plain`, `pip-bottom-right-small`), a project's `sc1` …, a library id." }, "name": { "type": "string", "description": "" }, "family": { "anyOf": [ { "type": "string", "enum": [ "full", "full-tight", "screen", "two-up", "pip", "over-shoulder" ] }, { "type": "null" } ], "description": "The family across frames (`copyScenes` maps by it); null for a scene made from scratch." }, "knobs": { "anyOf": [ { "type": "object", "properties": { "gutter": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The one gutter, percent of frame width: 0 up to (not including) 50." }, "camWidth": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam column's width, percent of frame width: above 0, below 100." }, "stackSplit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam's share of the stack's height: a third to two thirds (`Layouts::clampSplit`'s range — a value outside it would render clamped)." }, "tightInset": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "How far `full-cam-tight` pushes in, percent: 0 up to (not including) 50." }, "sponsors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the split reserves the sponsor panel." }, "pipCorner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where PiP's small picture sits: `top-left`, `top-right`, `bottom-left`, `bottom-right`." }, "pipSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How wide PiP's small picture is: `small`, `medium`, `large`." }, "shoulderSide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which shoulder the newscast box floats over: `left`, `right`." } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The pre-tuning a parametric scene lays out with; null for a baked one." }, "aspect": { "anyOf": [ { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false }, { "type": "null" } ], "description": "The frame a baked scene is laid out for; null for a parametric one (any frame)." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the scene (`p1`, `p2` …)." }, "name": { "type": "string", "description": "What the inspector calls it (`Camera`, `Screen`, `Sponsors`, `Background`); free text." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track whose clip in force this panel shows; null is an empty panel (its look only)." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where the panel sits, percent of the frame." }, "transform": { "type": "object", "properties": { "x": { "type": "number", "description": "Percent of the rect's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the rect's height, downward.", "default": 0.0 }, "zoom": { "type": "number", "description": "1 = the picture as fitted; up to 8.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "How the picture sits inside the rect, after the clip's own framing.", "default": { "x": 0.0, "y": 0.0, "zoom": 1.0 } }, "fit": { "type": "string", "enum": [ "cover", "contain" ], "description": "How a picture without a framing fits the rect.", "default": "cover" }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 is square.", "default": 0.0 }, "border": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "The stroke's thickness, a percent of the frame's **width** (the one unit on both frames — a radius and a shadow are percents of the height); 0 up to 10." }, "colour": { "type": "string", "description": "A colour token (`frame`, `frame-ink`, `frame-card`, `accent`)." }, "style": { "type": "string", "enum": [ "solid", "dashed", "dotted" ], "description": "", "default": "solid" } }, "required": [ "width", "colour" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "shadow": { "anyOf": [ { "type": "object", "properties": { "blur": { "type": "number", "description": "Blur radius, percent of the frame's height; 0 to 20." }, "x": { "type": "number", "description": "Offset, percent of the frame's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Offset, percent of the frame's height, downward.", "default": 0.0 }, "colour": { "type": "string", "description": "A colour token.", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.5 } }, "required": [ "blur" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "alpha": { "type": "number", "description": "The panel's opacity, 0 to 1.", "default": 1.0 }, "blur": { "type": "number", "description": "Backdrop blur, px; 0 is none (C-14's panel blur, the stage draws it).", "default": 0.0 }, "stream": { "anyOf": [ { "type": "string", "enum": [ "screen", "primary" ] }, { "type": "null" } ], "description": "Which of a take clip's streams, while a take is one clip with several (pre-B4); null is the first video stream." }, "role": { "anyOf": [ { "type": "string", "enum": [ "cam", "screen", "slide", "sponsors", "pip", "background" ] }, { "type": "null" } ], "description": "What the panel reads when `trackId` is null or names a track the sequence lacks: the role's topmost track; null draws empty." }, "hideWhenEmpty": { "type": "boolean", "description": "The panel hides — its look and picture — while its track has no clip in force; the scene's `whenHidden` says what moves.", "default": false } }, "required": [ "id", "name", "trackId", "rect" ], "additionalProperties": false }, "description": "" }, "whenHidden": { "type": "array", "items": { "type": "object", "properties": { "hidden": { "type": "string", "description": "The strip that hides (`role: sponsors`, `hideWhenEmpty`)." }, "panelId": { "type": "string", "description": "The panel that moves while it does." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where it sits then, percent of the frame." } }, "required": [ "hidden", "panelId", "rect" ], "additionalProperties": false }, "description": "" }, "captions": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "", "default": true }, "burnIn": { "type": "boolean", "description": "The export writes them into the picture; false is a sidecar, or none.", "default": true }, "placement": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false, "description": "", "default": { "anchor": "bottom", "x": 0.0, "y": 0.0, "w": 80.0 } }, "look": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "", "default": "sans" }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "", "default": "medium" }, "tracking": { "type": "number", "description": "Letter spacing, percent of the em; -20 to 50.", "default": 0.0 }, "leading": { "type": "number", "description": "Line height as a multiple of the size; 0.8 to 2.", "default": 1.2 }, "colour": { "type": "string", "description": "The text's colour token.", "default": "frame-ink" }, "stroke": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "Percent of the frame's height; 0 to 2." }, "colour": { "type": "string", "description": "", "default": "frame" } }, "required": [ "width" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "background": { "anyOf": [ { "type": "object", "properties": { "colour": { "type": "string", "description": "", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.62 }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 to 10. Stored and returned as set, but not drawn yet: the reference renderer squares the box (libass has no rounded box), and so does the app's preview. Drawing it is RADIUS-2.", "default": 0.0 } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "padding": { "type": "number", "description": "Inside the background, percent of the frame's height; 0 to 10.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "", "default": { "font": "sans", "size": "medium", "tracking": 0.0, "leading": 1.2, "colour": "frame-ink", "stroke": null, "background": null, "padding": 1.0 } } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The scene's captions; null is the timeline's default, shown and burnt in." }, "scope": { "type": "string", "enum": [ "builtin", "project", "library" ], "description": "" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A project scene copied from the library: the library id it came from." } }, "required": [ "id", "name", "family", "knobs", "aspect", "panels", "whenHidden", "captions", "scope" ], "additionalProperties": false }, "description": "The project's own scenes (C-22, docs/core/scenes.md): ordered panels mapped to tracks, or a family with its knobs. Absent = none (the built-ins are code; the library's are copied in when applied)." } }, "required": [ "version", "savedAt", "takes", "sequences", "targets", "captions", "scene", "script" ], "additionalProperties": false, "description": "The whole document at the head." }, "session": { "anyOf": [ { "type": "object", "properties": { "playhead": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Playhead, edit seconds." }, "zoom": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timeline zoom, pixels per second." }, "activeSequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline the page shows; null = the document's `activeSequenceId` (the default for every op that takes a sequence). View state, not history: the spike's `setActiveSequence` is this field, never a document op. Not checked against the document — a view is never refused; the page falls back when the id is gone." }, "activeTargetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The target the stage shows; null = the page's own default (the first enabled one). View state, not history (U-04a1, C-10b): not checked against the document — the page falls back when the id is gone." } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The session view state as last set by `setSession`; null before the first one." }, "undoable": { "type": "boolean", "description": "Whether `undo` has a step to take back." }, "redoable": { "type": "boolean", "description": "Whether `redo` has a step to replay." }, "events": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer", "description": "Dense, 1-based position in the log." }, "op": { "type": "string", "description": "The registry op name." }, "args": { "type": "object", "additionalProperties": true, "description": "The op's arguments as recorded; `{}` for an op that takes none." }, "actor": { "type": "string", "description": "The surface the op came through (`ui`, `rest`, `mcp`, `sdk`, `system`)." }, "step": { "type": "boolean", "description": "Whether the op is an undo step." } }, "required": [ "seq", "op", "args", "actor", "step" ], "additionalProperties": false }, "description": "The log entries with seq greater than `since`, ascending by seq." }, "complete": { "type": "boolean", "description": "False when the page cannot start right after `since` (it is beyond the head, or more than the retention behind it): the caller missed entries and already holds the current document." } }, "required": [ "seq", "document", "session", "undoable", "redoable", "events", "complete" ], "additionalProperties": false }, "ExportPlanRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the plan was computed from." }, "plan": { "type": "object", "properties": { "horizontal": { "type": "object", "properties": { "duration": { "type": "number", "description": "Edit seconds: how long the horizontal export runs." }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds the stretch starts." }, "duration": { "type": "number", "description": "Edit seconds it runs for." } }, "required": [ "at", "duration" ], "additionalProperties": false }, "description": "" }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "editTime": { "type": "number", "description": "" }, "synthetic": { "type": "boolean", "description": "Present and true on the `Open` chapter the plan added so the list starts at 0." } }, "required": [ "name", "editTime" ], "additionalProperties": false }, "description": "Chapters at their edit time; YouTube needs the list to open at `00:00`, so a `synthetic` opener is prepended when the first real one lands later." } }, "required": [ "duration", "ranges", "chapters" ], "additionalProperties": false, "description": "The whole edit as the v2 pair's landscape file saw it — the view the card reads until U-04 (targets-not-formats.md §5)." }, "vertical": { "type": "array", "items": { "type": "object", "properties": { "chapter": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`c1`, `c2` …)." }, "name": { "type": "string", "description": "The chapter heading, as the script wrote it." }, "at": { "type": "number", "description": "Take seconds (a moment of the recording), not a timeline position: `chapters` gives the chapter's edit seconds (`editAt`). Editable." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "`short`, `bumper`, `bumper:top_story`, `bumper:end_program` … verbatim from the heading." } }, "required": [ "id", "name", "at", "flags" ], "additionalProperties": false, "description": "" }, "flags": { "type": "array", "items": { "type": "string" }, "description": "" }, "short": { "type": "boolean", "description": "" }, "duration": { "type": "number", "description": "" }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds the stretch starts." }, "duration": { "type": "number", "description": "Edit seconds it runs for." } }, "required": [ "at", "duration" ], "additionalProperties": false }, "description": "Edit ranges, in order: the cards on the chapter's start, then its footage." }, "overLimit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`shorts` past 60 s, `reels` past 90 s, else null." } }, "required": [ "chapter", "flags", "short", "duration", "ranges", "overLimit" ], "additionalProperties": false }, "description": "One file per chapter as the v2 pair's portrait file saw them, shorts first — the same view." }, "targets": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique in the document: a preset's id (`16:9`) or the custom target's." }, "name": { "type": "string", "description": "What the page and the plan names call it (`Horizontal`, `Square`)." }, "aspect": { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame." }, "enabled": { "type": "boolean", "description": "In the plans, or kept with its cues and out of them." }, "safe": { "type": "object", "properties": { "action": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Action-safe: nothing that matters outside it." }, "title": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Title-safe: text inside it." }, "caption": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Where the captions band sits." }, "chrome": { "anyOf": [ { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, { "type": "null" } ], "description": "The platform's own overlays (a Reel's top bar, its action rail, its caption strip); null for a frame shown bare." } }, "required": [ "action", "title", "caption", "chrome" ], "additionalProperties": false, "description": "Its safe areas." }, "primitives": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "full-cam", "full-cam-tight", "split", "full-screen", "stack", "pip", "over-shoulder" ] } }, { "type": "null" } ], "description": "The primitives this frame offers, when the aspect's own list (`Targets::primitivesFor`) is not the one wanted; null = computed from the aspect." } }, "required": [ "id", "name", "aspect", "enabled", "safe" ], "additionalProperties": false, "description": "" }, "whole": { "anyOf": [ { "type": "object", "properties": { "duration": { "type": "number", "description": "Edit seconds: how long the horizontal export runs." }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds the stretch starts." }, "duration": { "type": "number", "description": "Edit seconds it runs for." } }, "required": [ "at", "duration" ], "additionalProperties": false }, "description": "" }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "editTime": { "type": "number", "description": "" }, "synthetic": { "type": "boolean", "description": "Present and true on the `Open` chapter the plan added so the list starts at 0." } }, "required": [ "name", "editTime" ], "additionalProperties": false }, "description": "Chapters at their edit time; YouTube needs the list to open at `00:00`, so a `synthetic` opener is prepended when the first real one lands later." } }, "required": [ "duration", "ranges", "chapters" ], "additionalProperties": false }, { "type": "null" } ], "description": "The whole edit, for a landscape target; null for the others." }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "chapter": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`c1`, `c2` …)." }, "name": { "type": "string", "description": "The chapter heading, as the script wrote it." }, "at": { "type": "number", "description": "Take seconds (a moment of the recording), not a timeline position: `chapters` gives the chapter's edit seconds (`editAt`). Editable." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "`short`, `bumper`, `bumper:top_story`, `bumper:end_program` … verbatim from the heading." } }, "required": [ "id", "name", "at", "flags" ], "additionalProperties": false, "description": "" }, "flags": { "type": "array", "items": { "type": "string" }, "description": "" }, "short": { "type": "boolean", "description": "" }, "duration": { "type": "number", "description": "" }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds the stretch starts." }, "duration": { "type": "number", "description": "Edit seconds it runs for." } }, "required": [ "at", "duration" ], "additionalProperties": false }, "description": "Edit ranges, in order: the cards on the chapter's start, then its footage." }, "overLimit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`shorts` past 60 s, `reels` past 90 s, else null." } }, "required": [ "chapter", "flags", "short", "duration", "ranges", "overLimit" ], "additionalProperties": false }, "description": "One file per chapter with footage in it, shorts first, for a portrait or square target; empty for a landscape one." } }, "required": [ "target", "whole", "chapters" ], "additionalProperties": false }, "description": "Per enabled target, in document order: the whole edit for a landscape frame, the chapters for the others." } }, "required": [ "horizontal", "vertical", "targets" ], "additionalProperties": false, "description": "The horizontal export (the whole timeline, chapters in edit time) and one vertical export per chapter with footage, shorts first." }, "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the document's presets (`ep1`, `ep2` …)." }, "targetId": { "type": "string", "description": "The target this preset renders." }, "name": { "type": "string", "description": "What the Exports card calls it: `YouTube 1080p`, `Shorts`." }, "container": { "type": "string", "enum": [ "mp4", "mov", "webm" ], "description": "The file: mp4, mov or webm." }, "codec": { "type": "string", "enum": [ "h264", "hevc", "prores", "vp9", "av1" ], "description": "The video codec." }, "resolution": { "type": "object", "properties": { "w": { "type": "integer", "description": "Width in pixels." }, "h": { "type": "integer", "description": "Height in pixels." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame in pixels." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Frames per second; null renders at the sequence's rate." }, "quality": { "type": "object", "properties": { "crf": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Constant rate factor (lower is better; 18 is visually lossless for h264); null when `bitrate` rules." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Target bitrate in kbit/s; null when `crf` rules." } }, "required": [], "additionalProperties": false, "description": "How hard the video is compressed: `crf` or `bitrate`, one of the two." }, "audio": { "type": "object", "properties": { "codec": { "type": "string", "enum": [ "aac", "pcm", "opus" ], "description": "aac, pcm or opus." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "kbit/s; null for a codec that has no rate (pcm) or the encoder's default." } }, "required": [ "codec", "bitrate" ], "additionalProperties": false, "description": "The sound: codec and bitrate." }, "perChapter": { "type": "boolean", "description": "One file per chapter (`chapterFilter` says which) rather than one for the whole edit." }, "chapterFilter": { "type": "string", "enum": [ "all", "short" ], "description": "Which chapters a per-chapter preset renders: all, or the `short` ones." }, "enabled": { "type": "boolean", "description": "A disabled preset renders nothing and stays on the list." }, "naming": { "type": "string", "description": "The file name: `{take}`, `{sequence}`, `{chapter}`, `{target}` and `{preset}` are slugs; a name handed out twice gets `-2`, `-3`." } }, "required": [ "id", "targetId", "name", "container", "codec", "resolution", "fps", "quality", "audio", "perChapter", "chapterFilter", "enabled", "naming" ], "additionalProperties": false }, "description": "The document's export presets — its own, or the defaults for its targets when it holds none (C-12). A default's id is minted in order as the defaults are laid — `ep1`, `ep2`, one per default the targets earn — and is a reading, not a stored id: once the project stores presets of its own, the ids are whatever `addExportPreset` minted. Name a preset from this read only against the same seq." }, "renders": { "type": "array", "items": { "type": "object", "properties": { "presetId": { "type": "string", "description": "The preset these files are for." }, "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The file's name, from the preset's template." }, "chapter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The chapter it is cut for; null for the whole edit." }, "duration": { "type": "number", "description": "Edit seconds." }, "sequenceId": { "type": "string", "description": "The timeline it is cut from." } }, "required": [ "name", "chapter", "duration", "sequenceId" ], "additionalProperties": false }, "description": "The files, in the order render.json lists them." } }, "required": [ "presetId", "files" ], "additionalProperties": false }, "description": "What `render.json` will hold: per enabled preset, the files it renders (name and chapter), across every timeline." } }, "required": [ "seq", "plan", "presets", "renders" ], "additionalProperties": false }, "FillQuotesArgs": { "type": "object", "properties": { "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take whose markers place the quotes; null = the primary take (the first). An unknown id is `unknownId` at `takeId`." }, "script": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The script, a path relative to the project's folder; null = the lone `.md` at its top. None or several is `invalidArgs` at `script`." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track the quote cards go on; null = the derivation's interstitials track, else the topmost overlay track (track-roles.md §2)." } }, "required": [], "additionalProperties": false }, "ForgetProjectArgs": { "type": "object", "properties": { "path": { "type": "string", "description": "The path the registry knows the project by (its card)." } }, "required": [ "path" ], "additionalProperties": false }, "ImportDocumentArgs": { "type": "object", "properties": { "document": { "type": "object", "additionalProperties": true, "description": "The whole document (the `EditDocument` shape, schemas.md), validated on the way in — a raw object here: `ParseDocument` is the one thing that turns it into a document." }, "source": { "type": "string", "enum": [ "file", "derive", "migration", "new" ], "description": "How it arrived: `file`, `derive` or `migration`." } }, "required": [ "document", "source" ], "additionalProperties": false }, "ImportMediaArgs": { "type": "object", "properties": { "files": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Files to import, absolute paths on this machine; with `folder`, both." }, "folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A folder to import, absolute: a take folder (a Rheocles manifest, an OBS recording beside its cue CSV) derives as `deriveTake` does; otherwise its media files, recursively." }, "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take the files join as streams; null = a new take from them. An unknown id is `unknownId` at `takeId`." } }, "required": [], "additionalProperties": false }, "InstallLicenceArgs": { "type": "object", "properties": { "licence": { "type": "string", "description": "The licence token (`v1...`); surrounding whitespace is trimmed. Named `licence`, never `token`: an op argument called `token` is the install token's word (docs/decisions/local-auth-token.md)." } }, "required": [ "licence" ], "additionalProperties": false }, "LaunchRheoclesArgs": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "LeaveGroupArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The timeline." }, "trackId": { "type": "string", "description": "The track leaving its group." } }, "required": [ "sequenceId", "trackId" ], "additionalProperties": false }, "LinkedClipsRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the link was read at." }, "clipId": { "type": "string", "description": "The clip asked about." }, "groupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Its track's group — the link — or null when the track is in none." }, "linked": { "type": "array", "items": { "type": "string" }, "description": "The linked clips on the group's other tracks (the same take, `at`, `in`, duration, speed and targets), top of the stack first; the clip itself is never listed. Empty beside a group: the clips no longer match (an edit made while unlinked), so nothing moves with it." } }, "required": [ "seq", "clipId", "groupId", "linked" ], "additionalProperties": false }, "LintRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the findings were computed from." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable across re-lints: the rule and the thing it is about (`missing-asset:k38`, `gap:full:horizontal:100.000`)." }, "level": { "type": "string", "enum": [ "error", "warning", "note" ], "description": "" }, "at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Edit seconds to seek to, or null for a finding about the whole edit." }, "format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Manifest v2's word for the frame the finding is about (`horizontal` for a landscape target, `vertical` otherwise), or null; `target` names the frame." }, "target": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The target the finding is about, by id, when it is about one (targets-not-formats.md §5)." }, "message": { "type": "string", "description": "" }, "subject": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "marker", "chapter", "clip", "track" ], "description": "A marker, a chapter, a clip or a track." }, "id": { "type": "string", "description": "Its id in the document." } }, "required": [ "kind", "id" ], "additionalProperties": false }, { "type": "null" } ], "description": "What to select so the fix is one click away; null for a finding about the whole edit." }, "sequence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline the finding is about (every rule names one; the take's own findings are reported against the active timeline)." } }, "required": [ "id", "level", "at", "format", "target", "message", "subject", "sequence" ], "additionalProperties": false }, "description": "Errors first, then warnings, then notes; within a level by edit time (a finding about the whole edit first), then id." }, "summary": { "type": "string", "description": "`2 errors · 5 warnings · 1 note`, or `Clean`." } }, "required": [ "seq", "findings", "summary" ], "additionalProperties": false }, "LocateProjectArgs": { "type": "object", "properties": { "path": { "type": "string", "description": "The path the registry knows the project by (its card)." }, "newPath": { "type": "string", "description": "Where the file is now." } }, "required": [ "path", "newPath" ], "additionalProperties": false }, "MapPanelArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The baked project scene." }, "panelId": { "type": "string", "description": "The panel to map." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track it shows, by id; null = nothing." } }, "required": [ "sceneId", "panelId", "trackId" ], "additionalProperties": false }, "MarkersRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the read was computed from." }, "sequenceId": { "type": "string", "description": "The timeline whose edit seconds `inEdit` is in." }, "markers": { "type": "array", "items": { "type": "object", "properties": { "markerId": { "type": "string", "description": "The marker's id (`m1` …)." }, "takeId": { "type": "string", "description": "The take the marker is in." }, "label": { "type": "string", "description": "`marker:chapter Cold Open`, `obs:scene full-cam-tight`, `take:go` …" }, "takeT": { "type": "number", "description": "TAKE seconds (a moment of the recording): the marker's `t` in `document`, what `moveMarker` takes. Not a timeline position." }, "inEdit": { "type": "array", "items": { "type": "number" }, "description": "EDIT seconds (moments of the timeline) where the edit shows the marker's take second, in edit order — what `placeClip.at` takes. Empty when a cut drops it; two entries when the edit shows it twice." } }, "required": [ "markerId", "takeId", "label", "takeT", "inEdit" ], "additionalProperties": false }, "description": "Take order, take by take." } }, "required": [ "seq", "sequenceId", "markers" ], "additionalProperties": false }, "McpClientConfigRead": { "type": "object", "properties": { "url": { "type": "string", "description": "The MCP endpoint of the running app, `http://127.0.0.1:/mcp`." }, "token": { "type": "string", "description": "The install token the endpoint expects as `Authorization: Bearer`." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The request headers to send, ready to copy: `Authorization` with the bearer." }, "server": { "type": "object", "properties": { "type": { "type": "string", "description": "The transport; always `http` — the app speaks MCP over HTTP on loopback only." }, "url": { "type": "string", "description": "The endpoint, `http://127.0.0.1:/mcp`." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "`Authorization: Bearer `." } }, "required": [ "type", "url", "headers" ], "additionalProperties": false, "description": "The server entry for an MCP client config file (`mcpServers.tomocles`)." } }, "required": [ "url", "token", "headers", "server" ], "additionalProperties": false }, "MoveChapterArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "chapterId": { "type": "string", "description": "The chapter to move." }, "at": { "type": "number", "description": "Take seconds to move to; clamped to the take." } }, "required": [ "takeId", "chapterId", "at" ], "additionalProperties": false }, "MoveClipArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The clip to move." }, "to": { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds the clip should start; a plain move lands as close as the track allows." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track to move to; null = the track it is on." } }, "required": [ "at" ], "additionalProperties": false, "description": "Where it goes: a time, and optionally another track." }, "mode": { "type": "string", "enum": [ "insert", "overwrite" ], "description": "`overwrite` (the default) lands it in place; `insert` ripples every unlocked track by its length.", "default": "overwrite" }, "options": { "type": "object", "properties": { "overwrite": { "type": "boolean", "description": "The ⌘-drag: carve the neighbours instead of stopping at them.", "default": false } }, "required": [], "additionalProperties": false, "description": "For an overwrite move: stop at the neighbours (the default) or carve them.", "default": { "overwrite": false } } }, "required": [ "sequenceId", "clipId", "to" ], "additionalProperties": false }, "MoveClipToSequenceArgs": { "type": "object", "properties": { "clipId": { "type": "string", "description": "The clip, on whichever timeline holds it." }, "toSequenceId": { "type": "string", "description": "The timeline it lands on." }, "options": { "type": "object", "properties": { "at": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Edit seconds on the target; absent = the clip's own `at`." }, "copy": { "type": "boolean", "description": "Leave the original where it is; the copy gets a fresh id.", "default": false }, "mode": { "type": "string", "enum": [ "insert", "overwrite" ], "description": "Overwrite what is under it (the default) or insert, rippling the target's unlocked tracks.", "default": "overwrite" } }, "required": [], "additionalProperties": false, "description": "Where and how it lands.", "default": { "at": null, "copy": false, "mode": "overwrite" } } }, "required": [ "clipId", "toSequenceId" ], "additionalProperties": false }, "MoveFramingKeyframeArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The footage or image clip." }, "targetId": { "type": "string", "description": "The target the framing is for." }, "at": { "type": "number", "description": "Clip seconds (0 is the clip's first frame): the moment of the keyframe to move." }, "to": { "type": "number", "description": "Clip seconds (0 is the clip's first frame) to move it to." } }, "required": [ "sequenceId", "clipId", "targetId", "at", "to" ], "additionalProperties": false }, "MoveGainKeyframeArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The footage or bed clip." }, "at": { "type": "number", "description": "Clip seconds (0 is the clip's first frame): the moment of the keyframe to move." }, "to": { "type": "number", "description": "Clip seconds (0 is the clip's first frame) it moves to." } }, "required": [ "sequenceId", "clipId", "at", "to" ], "additionalProperties": false }, "MoveMarkerArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "markerId": { "type": "string", "description": "The marker to move." }, "t": { "type": "number", "description": "Take seconds to move to; clamped to the take." } }, "required": [ "takeId", "markerId", "t" ], "additionalProperties": false }, "MovePanelArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The baked project scene." }, "panelId": { "type": "string", "description": "The panel to move." }, "to": { "type": "integer", "description": "Its new index in the stack, 0 the bottom." } }, "required": [ "sceneId", "panelId", "to" ], "additionalProperties": false }, "MoveScenePlacementArgs": { "type": "object", "properties": { "placementId": { "type": "string", "description": "The placement being dragged (`pl3`). Unknown: `unknownId` at `placementId`." }, "at": { "type": "number", "description": "Edit seconds it lands on; another placement on that frame is dropped." }, "sequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline to look on; null = any (placement ids are the document's). An unknown id is `unknownId` at `sequenceId`." } }, "required": [ "placementId", "at" ], "additionalProperties": false }, "MoveTrackArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the track is in." }, "trackId": { "type": "string", "description": "The track to move." }, "toIndex": { "type": "integer", "description": "Where it goes in the stack, 0 = top of the stack; clamped to the stack." } }, "required": [ "sequenceId", "trackId", "toIndex" ], "additionalProperties": false }, "NewDocumentArgs": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "OpResult": { "type": "object", "properties": { "applied": { "type": "boolean", "description": "Whether the op changed anything; false is a legal op that had nothing to do, never a silent no-op." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why nothing was applied, when `applied` is false; null otherwise." }, "seq": { "type": "integer", "description": "The envelope seq of the event written, or the current seq when nothing was." }, "created": { "type": "array", "items": { "type": "string" }, "description": "Ids the op minted, in creation order, so a client can address what it just created.", "default": [] }, "document": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer", "description": "Always 6 here (tracks without roles, B3; scenes as panels were 5, C-22; user-defined tracks 4, C-09; targets 3, C-10); an older file is upgraded on the way in." }, "savedAt": { "type": "string", "description": "When this document was last written, ISO 8601. An input, never the clock: parse and normalise read no time." }, "takes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its own namespace among takes; the source id when the file gave none." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rheocles" ], "description": "The discriminator `TakeSourceCast` keys on; always `rheocles`." }, "id": { "type": "string", "description": "The manifest's `id`." }, "name": { "type": "string", "description": "Something to print; the id when the manifest gave none." }, "folder": { "type": "string", "description": "The folder name, for display. The handle itself is not serialisable." }, "manifest": { "type": "string", "description": "The manifest file's name inside the folder; always `manifest.json`." } }, "required": [ "kind", "id", "name", "folder", "manifest" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "obs" ], "description": "The discriminator `TakeSourceCast` keys on; always `obs`." }, "id": { "type": "string", "description": "The footage file name, which is also the take's identity." }, "name": { "type": "string", "description": "Something to print; the id when the file gave none." }, "folder": { "type": "string", "description": "The folder name, for display." }, "cues": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cue CSV the markers were read from, if one was given." } }, "required": [ "kind", "id", "name", "folder", "cues" ], "additionalProperties": false } ], "description": "Where the take came from, so the page can find it again." }, "fps": { "type": "number", "description": "The frame rate timecodes are shown in. The primary stream's, or 30." }, "duration": { "type": "number", "description": "Take seconds: the furthest any stream reaches." }, "streams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The manifest stream id (`window:13085`), or the file name for a bare file." }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "What the stream is for, which decides where the stage puts it." }, "medium": { "type": "string", "enum": [ "video", "audio" ], "description": "Picture or sound." }, "file": { "type": "string", "description": "File name relative to the take folder. Never an absolute path: the folder moves, the edit must not care." }, "label": { "type": "string", "description": "Something to print: the manifest's `name`, or the file name." }, "offset": { "type": "number", "description": "Take seconds at which the file's first frame sits. A late joiner is positive; a file that started early is negative." }, "duration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "File seconds: the file's own length, once a browser has read it. Null until then." }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Pixel width for video, so the stage can pick a crop before the file is loaded." }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Pixel height for video." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Frames per second as recorded, when known. Screen captures are variable-rate; this is nominal." }, "primary": { "type": "boolean", "description": "The one video stream the transport follows. Exactly one stream of a take has this." }, "muted": { "type": "boolean", "description": "Heard or not." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "The point a crop keeps centred." }, "timecode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Local time-of-day of the file's first frame, `HH:MM:SS:FF` at the stream's integer fps, as Rheocles stamps it. Null for a bare file." }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The codec of the stream's own medium as `ffprobe` names it (`hevc`, `h264`, `aac`…); null until `probeMedia` learns it (U-13e)." }, "probe": { "type": "object", "properties": { "fps": { "anyOf": [ { "type": "object", "properties": { "num": { "type": "integer", "description": "The numerator." }, "den": { "type": "integer", "description": "The denominator, never 0." } }, "required": [ "num", "den" ], "additionalProperties": false }, { "type": "null" } ], "description": "The frame rate as a ratio, exact; null for a file with no picture." }, "timecode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timecode the file carries (`10:00:00:00`), or null." }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's channel count, or null without sound." }, "sampleRate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's sample rate in Hz, or null without sound." }, "container": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ffprobe's container name, or null." }, "bytes": { "type": "integer", "description": "The file's size in bytes when probed." }, "sha256Prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the file's first MiB, hex — the signature; null when the file could not be hashed." } }, "required": [ "fps", "timecode", "channels", "sampleRate", "container", "bytes", "sha256Prefix" ], "additionalProperties": false, "description": "What the file was probed to be beyond the flat fields — the exact frame rate, timecode, channels, sample rate, container, the signature relink matches by (C-17). Absent until probed." }, "proxy": { "type": "object", "properties": { "path": { "type": "string", "description": "The proxy file, relative to the project's folder." }, "preset": { "type": "string", "description": "The preset it was made at: `720p`, `1080p`." } }, "required": [ "path", "preset" ], "additionalProperties": false, "description": "The finished proxy for playback — its path beside the project and its preset (C-17b). Absent until one is ready; the manifest never names it." } }, "required": [ "id", "role", "medium", "file", "label", "offset", "duration", "width", "height", "fps", "primary", "muted", "focus", "timecode" ], "additionalProperties": false }, "description": "The files recorded on this cue clock; exactly one is the primary video." }, "markers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`m1`, `m2` …)." }, "t": { "type": "number", "description": "Take seconds (a moment of the recording), not a timeline position: `markers` gives where the edit shows it (`inEdit`). Editable." }, "label": { "type": "string", "description": "`marker:chapter Cold Open`, `obs:scene full-cam-tight`, `take:go` …" }, "origin": { "type": "string", "enum": [ "manifest", "csv", "hand" ], "description": "Where it came from: the recorder's manifest, a cue CSV, or a hand." }, "originalT": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Take seconds: where the recorder put it. Null for a hand-placed marker." } }, "required": [ "id", "t", "label", "origin", "originalT" ], "additionalProperties": false }, "description": "Sorted by `t`." }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`c1`, `c2` …)." }, "name": { "type": "string", "description": "The chapter heading, as the script wrote it." }, "at": { "type": "number", "description": "Take seconds (a moment of the recording), not a timeline position: `chapters` gives the chapter's edit seconds (`editAt`). Editable." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "`short`, `bumper`, `bumper:top_story`, `bumper:end_program` … verbatim from the heading." } }, "required": [ "id", "name", "at", "flags" ], "additionalProperties": false }, "description": "Sorted by `at`." }, "spans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`p1`, `p2` …)." }, "name": { "type": "string", "description": "The `X` of `marker:in X`." }, "in": { "type": "number", "description": "Take seconds, inclusive." }, "out": { "type": "number", "description": "Take seconds, exclusive." }, "markerIds": { "type": "array", "items": { "type": "string" }, "description": "The markers that bound it, so re-deriving can find it again." } }, "required": [ "id", "name", "in", "out", "markerIds" ], "additionalProperties": false }, "description": "Sorted by `in`; never empty or inverted." } }, "required": [ "id", "source", "fps", "duration", "streams", "markers", "chapters", "spans" ], "additionalProperties": false }, "description": "One today; the teaser later." }, "sequences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its own namespace: `full`, `teaser`, a slug of the name." }, "name": { "type": "string", "description": "What the page calls it; the id when the file gave none." }, "fps": { "type": "number", "description": "Every clip time is aligned to whole frames at this rate." }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Its immutable id within the sequence (F13): `V` picture, `A` sound — never changed, never reused; a document from before F13 keeps its word ids (`footage`, `mic` …)." }, "name": { "type": "string", "description": "What the track is called; its id when the file gave none." }, "medium": { "type": "string", "enum": [ "video", "audio" ], "description": "Picture or sound — the track's type (docs/decisions/tracks-are-just-tracks.md): a video track takes every picture clip, an audio track take clips and beds." }, "order": { "type": "integer", "description": "Position in the stack, 0 at the top; `tracks[]` is kept sorted by it." }, "groupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The group the track folds into, or null." }, "clips": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`k1`, `k2` …)." }, "at": { "type": "number", "description": "Edit seconds, inclusive." }, "duration": { "type": "number", "description": "Edit seconds. Always positive." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "take" ], "description": "The discriminator `ClipSourceCast` keys on; always `take`." }, "takeId": { "type": "string", "description": "The take the footage is from; must name a take the document has." }, "in": { "type": "number", "description": "Take seconds at the clip's first frame." }, "streams": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The streams this clip plays; null is every stream of the take — the automatic group." } }, "required": [ "kind", "takeId", "in", "streams" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ], "description": "The discriminator `ClipSourceCast` keys on; always `card`." }, "card": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bumper", "sting", "quote", "exhibit" ], "description": "Bumper, sting, quote or exhibit." }, "title": { "type": "string", "description": "The card's heading, or the chapter name for a bumper." }, "body": { "type": "string", "description": "The quote text, the bumper's console line (`> top_story`), the exhibit stem." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A media key or URL, for an exhibit." }, "chapterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The chapter a bumper opens." } }, "required": [ "kind", "title", "body", "src", "chapterId" ], "additionalProperties": false, "description": "The card the clip shows." } }, "required": [ "kind", "card" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ], "description": "The discriminator `ClipSourceCast` keys on; always `image`." }, "src": { "type": "string", "description": "A media key (`exhibit:`, a path) or URL. Video media later." }, "placement": { "type": "object", "additionalProperties": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false }, "description": "Where it sits, per target id; a target not named draws full-frame." }, "opacity": { "type": "number", "description": "How opaque, 0 to 1; absent is 1." } }, "required": [ "kind", "src" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "captions" ], "description": "The discriminator `ClipSourceCast` keys on; always `captions`." }, "src": { "type": "string", "description": "The SRT's media key: `captions:`." }, "clock": { "type": "string", "enum": [ "take", "edit" ], "description": "Which clock the file's cues are on." }, "in": { "type": "number", "description": "File seconds at the clip's first frame, on the edit clock. Unused on the take clock." } }, "required": [ "kind", "src", "clock", "in" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audio" ], "description": "The discriminator `ClipSourceCast` keys on; always `audio`." }, "src": { "type": "string", "description": "The file, as a path relative to the project's folder or a media root (`music/bed.mp3`)." }, "in": { "type": "number", "description": "File seconds: where the file reads at the clip's first frame.", "default": 0.0 } }, "required": [ "kind", "src" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "title" ], "description": "The discriminator `ClipSourceCast` keys on; always `title`." }, "style": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "The face by role: `display` (Fraunces), `sans` (Instrument Sans), `mono` (IBM Plex Mono)." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "The line height: small, medium or large." }, "ink": { "type": "string", "description": "The text's colour, a token name (`frame-ink`, `frame`, `frame-card`, `accent`)." }, "panel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The box's fill, a token name, or null for none." } }, "required": [ "font", "size", "ink", "panel" ], "additionalProperties": false, "description": "The face, size and colours; the template's when the wire gives none (a computed property: set here, never required of a payload)." }, "template": { "type": "string", "enum": [ "lower-third", "full-frame", "tag" ], "description": "Which built-in look: a lower-third, a full-frame title, a tag." }, "fields": { "type": "object", "properties": { "title": { "type": "string", "description": "The first line: the name, the headline.", "default": "" }, "subtitle": { "type": "string", "description": "The second line under it: the role, the strapline; a tag never shows it.", "default": "" } }, "required": [], "additionalProperties": false, "description": "The two lines." }, "placement": { "type": "object", "additionalProperties": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false }, "description": "Where it sits, per target id; a target not named takes the template's placement." } }, "required": [ "kind", "style", "template", "fields" ], "additionalProperties": false } ], "description": "What the clip plays: take footage, a card, a still, a captions file, a sound file or a title." }, "pictureTail": { "type": "number", "description": "The picture runs this many seconds past `duration` while the sound stops — the J-cut. A card's, a still's, a cutaway's; always 0 on the ground's footage and on captions; clamped to the gap before the next clip." }, "targets": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The targets this clip serves — their ids — or null for every target. Clips for different targets may overlap on a track (targets-not-formats.md §3; the brief's `'all' | targetId[]`, null being the dialect's `all`)." }, "label": { "type": "string", "description": "What the timeline prints; a card kind when the file gave none." }, "framing": { "type": "object", "additionalProperties": { "type": "object", "properties": { "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "At least one; sorted by `at`, unique per `at`." } }, "required": [ "keyframes" ], "additionalProperties": false }, "description": "How the picture is cropped and panned, per target id — footage and stills only (docs/core/framing.md). Absent (never null) when the clip has none: the stream's focus, no punch-in. Keyframes on the clip's own clock, so the framing travels with the clip; `retimed`/`part` move them when the footage under it moves." }, "audio": { "type": "object", "properties": { "gain": { "type": "number", "description": "The clip's level in dB: 0 is as recorded, negative quieter. Added to its track's.", "default": 0.0 }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "gain": { "type": "number", "description": "The level in dB: 0 is the clip as recorded, negative quieter." } }, "required": [ "at", "gain" ], "additionalProperties": false }, "description": "The level over the clip's own clock, on top of `gain`; sorted by `at`, unique per `at`; empty for a flat clip.", "default": [] }, "fadeIn": { "type": "number", "description": "Seconds from the clip's first frame over which the sound rises from silence to its level. 0 for none.", "default": 0.0 }, "fadeOut": { "type": "number", "description": "Seconds before the clip's last frame over which the sound falls to silence. 0 for none.", "default": 0.0 } }, "required": [], "additionalProperties": false, "description": "How loud the clip plays — footage and beds only (docs/core/audio.md). Absent (never null) when nothing is set: 0 dB, no keyframes, no fades. Keyframes on the clip's own clock, moved by `retimed`/`part` beside the framing; fades are edge lengths, clamped." }, "speed": { "type": "number", "description": "Constant speed, footage clips only (docs/core/clips.md § Speed): the take runs `speed` times as fast as the edit, so the clip covers `duration × speed` take seconds. Absent (never null) is 1. 0.25 to 4. Only the clock functions and the edit ops' bounds read it." }, "transitionIn": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dissolve", "dip" ], "description": "dissolve, or dip." }, "duration": { "type": "number", "description": "Edit seconds the transition runs, from the clip's first frame, frame-aligned: 0.1 to 5." }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A dip's colour, a token name (`frame`, `frame-ink`, `frame-card`, `accent`); null is `frame`." } }, "required": [ "kind", "duration" ], "additionalProperties": false, "description": "How the clip arrives (docs/core/transitions.md): a dissolve from the clip before it, or a dip through a colour; absent (never null) is a cut. The clip that starts owns the join. Footage and overlay clips; a card, a captions clip or a bed never has one." } }, "required": [ "id", "at", "duration", "source", "pictureTail", "targets", "label" ], "additionalProperties": false }, "description": "Sorted by `at`; no two overlap whose variant sets intersect." }, "muted": { "type": "boolean", "description": "Heard or not. A muted track still shows." }, "locked": { "type": "boolean", "description": "Locked = every mutation of its clips is refused as `locked` — a place, move, blade, trim, slip, roll, tail, speed or delete, and ripples pass it by; a clip's own patches (label, card, streams, targets, title, captions clock) still apply." }, "audio": { "type": "object", "properties": { "gain": { "type": "number", "description": "The track's level in dB, added to each clip's: 0 is as recorded.", "default": 0.0 }, "solo": { "type": "boolean", "description": "A solo on any track of the sequence silences every track without one. A listening state; lint notes one left on.", "default": false }, "duck": { "anyOf": [ { "type": "object", "properties": { "under": { "type": "string", "description": "`speech`, or the id of an audio track on the same sequence." }, "by": { "type": "number", "description": "How far the level drops while `under` sounds, in dB: negative, never 0." }, "attack": { "type": "number", "description": "Seconds the level takes to reach `by`, ending as `under` starts." }, "release": { "type": "number", "description": "Seconds the level takes to come back, starting as `under` ends." } }, "required": [ "under", "by", "attack", "release" ], "additionalProperties": false }, { "type": "null" } ], "description": "How the track gives way to speech or to another track, or null." } }, "required": [], "additionalProperties": false, "description": "The track's level, solo and ducking (docs/core/audio.md). Absent (never null) when nothing is set: 0 dB, no solo, no duck. `muted` above is the mute." } }, "required": [ "id", "name", "medium", "order", "groupId", "clips", "muted", "locked" ], "additionalProperties": false }, "description": "`tracks[0]` is the top of the stack: drawn last, wins per pixel. Sorted by `order`." }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the sequence (`g1`, `g2` …)." }, "name": { "type": "string", "description": "What the folded row is called." } }, "required": [ "id", "name" ], "additionalProperties": false }, "description": "The tracks' groups, in no order; a track names its group by id." }, "roles": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Which track plays each role the derivation laid (F13): `footage` (the camera), `screen`, `cam-b`, `mic`, `system`, `slides`, `sponsors`, `captions`, `cards`, … → a track id. Absent on a sequence nobody derived since F13; a role then reads the track whose id is the role word (`roleTrack`)." }, "minted": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "The highest track number ever minted per medium (F13, Len: \"track IDs are immutable… never reused\"): `V` and `A` → n. `addTrack` mints past it and nothing lowers it, so a removed track's id never returns." }, "scenes": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the whole document (`pl1`, `pl2` …)." }, "at": { "type": "number", "description": "Edit seconds on its timeline." }, "sceneId": { "type": "string", "description": "The scene from here: a built-in's id (`split-plain`) or a project scene's (`sc1`)." }, "mappings": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The placement's own tracks for the scene's panels, panel id → track id; absent = the scene's own mappings and roles." } }, "required": [ "id", "at", "sceneId" ], "additionalProperties": false } }, "description": "The scenes track (P2c, F12): per target, the scenes placed on this timeline at edit seconds, each list sorted by `at`. A cue file places the first ones once; the timeline is the truth after that.", "default": {} } }, "required": [ "id", "name", "fps", "tracks", "groups" ], "additionalProperties": false }, "description": "The timelines: the full episode and the teaser are filmed from one script and cut apart, sharing the takes. Never empty." }, "targets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique in the document: a preset's id (`16:9`) or the custom target's." }, "name": { "type": "string", "description": "What the page and the plan names call it (`Horizontal`, `Square`)." }, "aspect": { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame." }, "enabled": { "type": "boolean", "description": "In the plans, or kept with its cues and out of them." }, "safe": { "type": "object", "properties": { "action": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Action-safe: nothing that matters outside it." }, "title": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Title-safe: text inside it." }, "caption": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Where the captions band sits." }, "chrome": { "anyOf": [ { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, { "type": "null" } ], "description": "The platform's own overlays (a Reel's top bar, its action rail, its caption strip); null for a frame shown bare." } }, "required": [ "action", "title", "caption", "chrome" ], "additionalProperties": false, "description": "Its safe areas." }, "primitives": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "full-cam", "full-cam-tight", "split", "full-screen", "stack", "pip", "over-shoulder" ] } }, { "type": "null" } ], "description": "The primitives this frame offers, when the aspect's own list (`Targets::primitivesFor`) is not the one wanted; null = computed from the aspect." } }, "required": [ "id", "name", "aspect", "enabled", "safe" ], "additionalProperties": false }, "description": "The frames the project renders for, in order; never empty. A take's scene cues and a clip's `targets` name them by id (targets-not-formats.md §1)." }, "captions": { "type": "object", "properties": { "position": { "type": "string", "enum": [ "bottom", "top", "custom" ], "description": "Bottom, top, or a custom `y` inside the captions band." }, "y": { "type": "number", "description": "Where in the captions band, for `custom`: 0 at its top, 1 at its floor." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "Small, medium or large type." }, "box": { "type": "string", "enum": [ "pill", "band", "none" ], "description": "A pill, a full-width band, or nothing behind the text." }, "font": { "type": "string", "enum": [ "sans", "serif", "mono" ], "description": "Sans, serif or mono." }, "safe": { "type": "boolean", "description": "Keep them inside the caption-safe area of the frame whatever `position` says." } }, "required": [ "position", "y", "size", "box", "font", "safe" ], "additionalProperties": false, "description": "How the captions track's cues are drawn." }, "scene": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "The project's scene as the scene editor exported it, verbatim; null until attached or when unusable. The scene editor owns its shape — see `Scene`." }, "script": { "anyOf": [ { "type": "object", "properties": { "team": { "type": "string", "description": "The PteroPrompter team slug." }, "slug": { "type": "string", "description": "The script slug inside the team." } }, "required": [ "team", "slug" ], "additionalProperties": false }, { "type": "null" } ], "description": "The script the takes were read from, when the page knows it." }, "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique across the document's presets (`ep1`, `ep2` …)." }, "targetId": { "type": "string", "description": "The target this preset renders." }, "name": { "type": "string", "description": "What the Exports card calls it: `YouTube 1080p`, `Shorts`." }, "container": { "type": "string", "enum": [ "mp4", "mov", "webm" ], "description": "The file: mp4, mov or webm." }, "codec": { "type": "string", "enum": [ "h264", "hevc", "prores", "vp9", "av1" ], "description": "The video codec." }, "resolution": { "type": "object", "properties": { "w": { "type": "integer", "description": "Width in pixels." }, "h": { "type": "integer", "description": "Height in pixels." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame in pixels." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Frames per second; null renders at the sequence's rate." }, "quality": { "type": "object", "properties": { "crf": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Constant rate factor (lower is better; 18 is visually lossless for h264); null when `bitrate` rules." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Target bitrate in kbit/s; null when `crf` rules." } }, "required": [], "additionalProperties": false, "description": "How hard the video is compressed: `crf` or `bitrate`, one of the two." }, "audio": { "type": "object", "properties": { "codec": { "type": "string", "enum": [ "aac", "pcm", "opus" ], "description": "aac, pcm or opus." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "kbit/s; null for a codec that has no rate (pcm) or the encoder's default." } }, "required": [ "codec", "bitrate" ], "additionalProperties": false, "description": "The sound: codec and bitrate." }, "perChapter": { "type": "boolean", "description": "One file per chapter (`chapterFilter` says which) rather than one for the whole edit." }, "chapterFilter": { "type": "string", "enum": [ "all", "short" ], "description": "Which chapters a per-chapter preset renders: all, or the `short` ones." }, "enabled": { "type": "boolean", "description": "A disabled preset renders nothing and stays on the list." }, "naming": { "type": "string", "description": "The file name: `{take}`, `{sequence}`, `{chapter}`, `{target}` and `{preset}` are slugs; a name handed out twice gets `-2`, `-3`." } }, "required": [ "id", "targetId", "name", "container", "codec", "resolution", "fps", "quality", "audio", "perChapter", "chapterFilter", "enabled", "naming" ], "additionalProperties": false }, "description": "How each target is encoded into files (`render.json`; docs/render/manifest-v4.md \"Presets\"). Absent on a document that never held any: the defaults for its targets are read in its place (`presetsOrDefaults`); once stored, the list is the user's." }, "scenes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A built-in's name (`split-plain`, `pip-bottom-right-small`), a project's `sc1` …, a library id." }, "name": { "type": "string", "description": "" }, "family": { "anyOf": [ { "type": "string", "enum": [ "full", "full-tight", "screen", "two-up", "pip", "over-shoulder" ] }, { "type": "null" } ], "description": "The family across frames (`copyScenes` maps by it); null for a scene made from scratch." }, "knobs": { "anyOf": [ { "type": "object", "properties": { "gutter": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The one gutter, percent of frame width: 0 up to (not including) 50." }, "camWidth": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam column's width, percent of frame width: above 0, below 100." }, "stackSplit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam's share of the stack's height: a third to two thirds (`Layouts::clampSplit`'s range — a value outside it would render clamped)." }, "tightInset": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "How far `full-cam-tight` pushes in, percent: 0 up to (not including) 50." }, "sponsors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the split reserves the sponsor panel." }, "pipCorner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where PiP's small picture sits: `top-left`, `top-right`, `bottom-left`, `bottom-right`." }, "pipSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How wide PiP's small picture is: `small`, `medium`, `large`." }, "shoulderSide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which shoulder the newscast box floats over: `left`, `right`." } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The pre-tuning a parametric scene lays out with; null for a baked one." }, "aspect": { "anyOf": [ { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false }, { "type": "null" } ], "description": "The frame a baked scene is laid out for; null for a parametric one (any frame)." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the scene (`p1`, `p2` …)." }, "name": { "type": "string", "description": "What the inspector calls it (`Camera`, `Screen`, `Sponsors`, `Background`); free text." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track whose clip in force this panel shows; null is an empty panel (its look only)." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where the panel sits, percent of the frame." }, "transform": { "type": "object", "properties": { "x": { "type": "number", "description": "Percent of the rect's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the rect's height, downward.", "default": 0.0 }, "zoom": { "type": "number", "description": "1 = the picture as fitted; up to 8.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "How the picture sits inside the rect, after the clip's own framing.", "default": { "x": 0.0, "y": 0.0, "zoom": 1.0 } }, "fit": { "type": "string", "enum": [ "cover", "contain" ], "description": "How a picture without a framing fits the rect.", "default": "cover" }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 is square.", "default": 0.0 }, "border": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "The stroke's thickness, a percent of the frame's **width** (the one unit on both frames — a radius and a shadow are percents of the height); 0 up to 10." }, "colour": { "type": "string", "description": "A colour token (`frame`, `frame-ink`, `frame-card`, `accent`)." }, "style": { "type": "string", "enum": [ "solid", "dashed", "dotted" ], "description": "", "default": "solid" } }, "required": [ "width", "colour" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "shadow": { "anyOf": [ { "type": "object", "properties": { "blur": { "type": "number", "description": "Blur radius, percent of the frame's height; 0 to 20." }, "x": { "type": "number", "description": "Offset, percent of the frame's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Offset, percent of the frame's height, downward.", "default": 0.0 }, "colour": { "type": "string", "description": "A colour token.", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.5 } }, "required": [ "blur" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "alpha": { "type": "number", "description": "The panel's opacity, 0 to 1.", "default": 1.0 }, "blur": { "type": "number", "description": "Backdrop blur, px; 0 is none (C-14's panel blur, the stage draws it).", "default": 0.0 }, "stream": { "anyOf": [ { "type": "string", "enum": [ "screen", "primary" ] }, { "type": "null" } ], "description": "Which of a take clip's streams, while a take is one clip with several (pre-B4); null is the first video stream." }, "role": { "anyOf": [ { "type": "string", "enum": [ "cam", "screen", "slide", "sponsors", "pip", "background" ] }, { "type": "null" } ], "description": "What the panel reads when `trackId` is null or names a track the sequence lacks: the role's topmost track; null draws empty." }, "hideWhenEmpty": { "type": "boolean", "description": "The panel hides — its look and picture — while its track has no clip in force; the scene's `whenHidden` says what moves.", "default": false } }, "required": [ "id", "name", "trackId", "rect" ], "additionalProperties": false }, "description": "" }, "whenHidden": { "type": "array", "items": { "type": "object", "properties": { "hidden": { "type": "string", "description": "The strip that hides (`role: sponsors`, `hideWhenEmpty`)." }, "panelId": { "type": "string", "description": "The panel that moves while it does." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where it sits then, percent of the frame." } }, "required": [ "hidden", "panelId", "rect" ], "additionalProperties": false }, "description": "" }, "captions": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "", "default": true }, "burnIn": { "type": "boolean", "description": "The export writes them into the picture; false is a sidecar, or none.", "default": true }, "placement": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false, "description": "", "default": { "anchor": "bottom", "x": 0.0, "y": 0.0, "w": 80.0 } }, "look": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "", "default": "sans" }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "", "default": "medium" }, "tracking": { "type": "number", "description": "Letter spacing, percent of the em; -20 to 50.", "default": 0.0 }, "leading": { "type": "number", "description": "Line height as a multiple of the size; 0.8 to 2.", "default": 1.2 }, "colour": { "type": "string", "description": "The text's colour token.", "default": "frame-ink" }, "stroke": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "Percent of the frame's height; 0 to 2." }, "colour": { "type": "string", "description": "", "default": "frame" } }, "required": [ "width" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "background": { "anyOf": [ { "type": "object", "properties": { "colour": { "type": "string", "description": "", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.62 }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 to 10. Stored and returned as set, but not drawn yet: the reference renderer squares the box (libass has no rounded box), and so does the app's preview. Drawing it is RADIUS-2.", "default": 0.0 } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "padding": { "type": "number", "description": "Inside the background, percent of the frame's height; 0 to 10.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "", "default": { "font": "sans", "size": "medium", "tracking": 0.0, "leading": 1.2, "colour": "frame-ink", "stroke": null, "background": null, "padding": 1.0 } } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The scene's captions; null is the timeline's default, shown and burnt in." }, "scope": { "type": "string", "enum": [ "builtin", "project", "library" ], "description": "" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A project scene copied from the library: the library id it came from." } }, "required": [ "id", "name", "family", "knobs", "aspect", "panels", "whenHidden", "captions", "scope" ], "additionalProperties": false }, "description": "The project's own scenes (C-22, docs/core/scenes.md): ordered panels mapped to tracks, or a family with its knobs. Absent = none (the built-ins are code; the library's are copied in when applied)." } }, "required": [ "version", "savedAt", "takes", "sequences", "targets", "captions", "scene", "script" ], "additionalProperties": false }, { "type": "null" } ], "description": "The full document after the op when applied; null otherwise." }, "undoable": { "type": "boolean", "description": "Whether `undo` has a step to take back after this op (`ProjectState::undoable()`: the live chain is not empty).", "default": false }, "redoable": { "type": "boolean", "description": "Whether `redo` has a step to replay after this op (`ProjectState::redoable()`: the redo branch is not empty).", "default": false }, "unlinked": { "type": "array", "items": { "type": "string" }, "description": "Clips the op took out of their link — a linked clip moved to another track leaves its group's link (B3b). Present only when not empty.", "default": [] }, "rebuilt": { "anyOf": [ { "type": "object", "properties": { "changed": { "type": "boolean", "description": "Whether the rebuilt projections differ from the stored ones." }, "summary": { "type": "array", "items": { "type": "string" }, "description": "What changed, one plain sentence each, at most twenty; on a failure, why." }, "failed": { "anyOf": [ { "type": "object", "properties": { "seq": { "type": "integer", "description": "The row's envelope seq." }, "op": { "type": "string", "description": "The row's op." }, "why": { "type": "string", "description": "Why this build cannot replay it." } }, "required": [ "seq", "op", "why" ], "additionalProperties": false }, { "type": "null" } ], "description": "The row the replay could not get past, when it failed; the stored projections are untouched." } }, "required": [ "changed", "summary" ], "additionalProperties": false }, { "type": "null" } ], "description": "What `rebuild` found: whether the projections changed, what changed, and the row it could not replay when it failed. Present only on `rebuild` and on an `openProject` that rebuilt." }, "details": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "description": "What to do about it, in words an agent can relay." }, "placements": { "type": "array", "items": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The timeline it is on." }, "targetId": { "type": "string", "description": "The target whose scenes track holds it." }, "placementId": { "type": "string", "description": "The placement (`pl3`)." }, "at": { "type": "number", "description": "Edit seconds." }, "fallback": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The scene's id: a built-in's (`full-screen`) or a project scene's." }, "name": { "type": "string", "description": "What the page calls it." } }, "required": [ "sceneId", "name" ], "additionalProperties": false, "description": "The scene this placement falls back to if its scene is removed with force: the timeline's seeded base, which since W1 depends on the take's streams (Full screen for a take with a screen and no camera, else the two-up). The core names it; a client never works it out." } }, "required": [ "sequenceId", "targetId", "placementId", "at", "fallback" ], "additionalProperties": false }, "description": "The scene placements the refusal is about, when it is about some.", "default": [] } }, "required": [ "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "What a refusal is about, so the caller can act on it (P2c S1): `removeScene`'s `scene-in-use` names the placements that hold the scene and says how to free them. Present only on a refusal that has any." } }, "required": [ "applied", "reason", "seq" ], "additionalProperties": false }, "OpenProjectArgs": { "type": "object", "properties": { "path": { "type": "string", "description": "The absolute path of the project file." } }, "required": [ "path" ], "additionalProperties": false }, "OutputsRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq now — compare with `written.seq` to see whether the files are stale." }, "folder": { "type": "string", "description": "The project's folder, an absolute path on this machine: where the five files and `outputs.json` are." }, "written": { "anyOf": [ { "type": "object", "properties": { "writtenAt": { "type": "string", "description": "When the files were written, ISO 8601 UTC with milliseconds (`2026-09-17T20:00:00.000Z`)." }, "seq": { "type": "integer", "description": "The envelope seq of the document the files were produced from." }, "files": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The file name, relative to the project's folder (`edit.json`, `render.json`, `markers.take.csv`, `markers.edit.csv`, `chapters.txt`)." }, "bytes": { "type": "integer", "description": "Its length in bytes." }, "sha256": { "type": "string", "description": "SHA-256 of its bytes, hex." } }, "required": [ "name", "bytes", "sha256" ], "additionalProperties": false }, "description": "The five files, in the order they were written." } }, "required": [ "writtenAt", "seq", "files" ], "additionalProperties": false }, { "type": "null" } ], "description": "`outputs.json` as the last `writeOutputs` left it; null when it has never run or the record is unreadable." } }, "required": [ "seq", "folder", "written" ], "additionalProperties": false }, "PackageProjectArgs": { "type": "object", "properties": { "dest": { "type": "string", "description": "An absolute folder that exists and is writable; the package is made inside it as `.tomocles-package/`. One already there is `invalidArgs` at `dest` — nothing is ever overwritten." }, "includeMedia": { "type": "boolean", "description": "Copy every media file the document names under `media/` (default false: the manifest alone, for a recipient who has the files).", "default": false } }, "required": [ "dest" ], "additionalProperties": false }, "PackageReport": { "type": "object", "properties": { "packaged": { "type": "boolean", "description": "Whether a `tomocles-package.json` sits beside the project file at all; false → nothing was checked." }, "verified": { "type": "integer", "description": "Entries whose file is there and hashes as the manifest says." }, "changed": { "type": "array", "items": { "type": "string" }, "description": "The keys whose file hashes differently from the manifest." }, "missing": { "type": "array", "items": { "type": "string" }, "description": "The keys whose file the walk did not find." } }, "required": [ "packaged", "verified", "changed", "missing" ], "additionalProperties": false }, "PairRheoclesArgs": { "type": "object", "properties": { "code": { "type": "string", "description": "The code as shown in Rheocles › Settings › Pairing; surrounding whitespace is dropped." } }, "required": [ "code" ], "additionalProperties": false }, "PlaceClipArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence to place in." }, "trackId": { "type": "string", "description": "The track to place on; it must hold the clip's kind and not be locked." }, "clip": { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds (a moment of the timeline) the clip starts; frame-aligned on the way in. A chapter's or marker's edit second comes from `chapters` (`editAt`) or `markers` (`inEdit`) — never from its `at`/`t` in `document`, which are take seconds." }, "duration": { "type": "number", "description": "Edit seconds; a clip of no length is refused (`empty`)." }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "take" ], "description": "The discriminator `ClipSourceCast` keys on; always `take`." }, "takeId": { "type": "string", "description": "The take the footage is from; must name a take the document has." }, "in": { "type": "number", "description": "Take seconds at the clip's first frame." }, "streams": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The streams this clip plays; null is every stream of the take — the automatic group." } }, "required": [ "kind", "takeId", "in", "streams" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "card" ], "description": "The discriminator `ClipSourceCast` keys on; always `card`." }, "card": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bumper", "sting", "quote", "exhibit" ], "description": "Bumper, sting, quote or exhibit." }, "title": { "type": "string", "description": "The card's heading, or the chapter name for a bumper." }, "body": { "type": "string", "description": "The quote text, the bumper's console line (`> top_story`), the exhibit stem." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A media key or URL, for an exhibit." }, "chapterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The chapter a bumper opens." } }, "required": [ "kind", "title", "body", "src", "chapterId" ], "additionalProperties": false, "description": "The card the clip shows." } }, "required": [ "kind", "card" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image" ], "description": "The discriminator `ClipSourceCast` keys on; always `image`." }, "src": { "type": "string", "description": "A media key (`exhibit:`, a path) or URL. Video media later." }, "placement": { "type": "object", "additionalProperties": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false }, "description": "Where it sits, per target id; a target not named draws full-frame." }, "opacity": { "type": "number", "description": "How opaque, 0 to 1; absent is 1." } }, "required": [ "kind", "src" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "captions" ], "description": "The discriminator `ClipSourceCast` keys on; always `captions`." }, "src": { "type": "string", "description": "The SRT's media key: `captions:`." }, "clock": { "type": "string", "enum": [ "take", "edit" ], "description": "Which clock the file's cues are on." }, "in": { "type": "number", "description": "File seconds at the clip's first frame, on the edit clock. Unused on the take clock." } }, "required": [ "kind", "src", "clock", "in" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "audio" ], "description": "The discriminator `ClipSourceCast` keys on; always `audio`." }, "src": { "type": "string", "description": "The file, as a path relative to the project's folder or a media root (`music/bed.mp3`)." }, "in": { "type": "number", "description": "File seconds: where the file reads at the clip's first frame.", "default": 0.0 } }, "required": [ "kind", "src" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "title" ], "description": "The discriminator `ClipSourceCast` keys on; always `title`." }, "style": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "The face by role: `display` (Fraunces), `sans` (Instrument Sans), `mono` (IBM Plex Mono)." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "The line height: small, medium or large." }, "ink": { "type": "string", "description": "The text's colour, a token name (`frame-ink`, `frame`, `frame-card`, `accent`)." }, "panel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The box's fill, a token name, or null for none." } }, "required": [ "font", "size", "ink", "panel" ], "additionalProperties": false, "description": "The face, size and colours; the template's when the wire gives none (a computed property: set here, never required of a payload)." }, "template": { "type": "string", "enum": [ "lower-third", "full-frame", "tag" ], "description": "Which built-in look: a lower-third, a full-frame title, a tag." }, "fields": { "type": "object", "properties": { "title": { "type": "string", "description": "The first line: the name, the headline.", "default": "" }, "subtitle": { "type": "string", "description": "The second line under it: the role, the strapline; a tag never shows it.", "default": "" } }, "required": [], "additionalProperties": false, "description": "The two lines." }, "placement": { "type": "object", "additionalProperties": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false }, "description": "Where it sits, per target id; a target not named takes the template's placement." } }, "required": [ "kind", "style", "template", "fields" ], "additionalProperties": false } ], "description": "What the clip plays: take footage, a card, a still or a captions file." }, "pictureTail": { "type": "number", "description": "The J-cut, overlay tracks only; `normalise` zeroes it on footage and clamps it to the next clip.", "default": 0.0 }, "targets": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The targets the clip serves, by id; null (the default) for every target." }, "label": { "type": "string", "description": "What the timeline prints.", "default": "" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The id to keep, or null to mint the next free `kN`." } }, "required": [ "at", "duration", "source" ], "additionalProperties": false, "description": "The clip, without an id unless one is to be kept." }, "mode": { "type": "string", "enum": [ "insert", "overwrite" ], "description": "`insert` ripples every unlocked track by the clip's length; `overwrite` carves the track under it." } }, "required": [ "sequenceId", "trackId", "clip", "mode" ], "additionalProperties": false }, "PreviewSceneRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the project was read at." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the scene (`p1`, `p2` …)." }, "name": { "type": "string", "description": "What the inspector calls it (`Camera`, `Screen`, `Sponsors`, `Background`); free text." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track whose clip in force this panel shows; null is an empty panel (its look only)." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where the panel sits, percent of the frame." }, "transform": { "type": "object", "properties": { "x": { "type": "number", "description": "Percent of the rect's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the rect's height, downward.", "default": 0.0 }, "zoom": { "type": "number", "description": "1 = the picture as fitted; up to 8.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "How the picture sits inside the rect, after the clip's own framing.", "default": { "x": 0.0, "y": 0.0, "zoom": 1.0 } }, "fit": { "type": "string", "enum": [ "cover", "contain" ], "description": "How a picture without a framing fits the rect.", "default": "cover" }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 is square.", "default": 0.0 }, "border": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "The stroke's thickness, a percent of the frame's **width** (the one unit on both frames — a radius and a shadow are percents of the height); 0 up to 10." }, "colour": { "type": "string", "description": "A colour token (`frame`, `frame-ink`, `frame-card`, `accent`)." }, "style": { "type": "string", "enum": [ "solid", "dashed", "dotted" ], "description": "", "default": "solid" } }, "required": [ "width", "colour" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "shadow": { "anyOf": [ { "type": "object", "properties": { "blur": { "type": "number", "description": "Blur radius, percent of the frame's height; 0 to 20." }, "x": { "type": "number", "description": "Offset, percent of the frame's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Offset, percent of the frame's height, downward.", "default": 0.0 }, "colour": { "type": "string", "description": "A colour token.", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.5 } }, "required": [ "blur" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "alpha": { "type": "number", "description": "The panel's opacity, 0 to 1.", "default": 1.0 }, "blur": { "type": "number", "description": "Backdrop blur, px; 0 is none (C-14's panel blur, the stage draws it).", "default": 0.0 }, "stream": { "anyOf": [ { "type": "string", "enum": [ "screen", "primary" ] }, { "type": "null" } ], "description": "Which of a take clip's streams, while a take is one clip with several (pre-B4); null is the first video stream." }, "role": { "anyOf": [ { "type": "string", "enum": [ "cam", "screen", "slide", "sponsors", "pip", "background" ] }, { "type": "null" } ], "description": "What the panel reads when `trackId` is null or names a track the sequence lacks: the role's topmost track; null draws empty." }, "hideWhenEmpty": { "type": "boolean", "description": "The panel hides — its look and picture — while its track has no clip in force; the scene's `whenHidden` says what moves.", "default": false } }, "required": [ "id", "name", "trackId", "rect" ], "additionalProperties": false }, "description": "The panels as a segment on the target would draw them, from the family's layout with the draft's knobs." } }, "required": [ "seq", "panels" ], "additionalProperties": false }, "ProbeMediaArgs": { "type": "object", "properties": { "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take whose files to probe; null = the primary take (the first). An unknown id is `unknownId` at `takeId`." }, "streamId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One stream of it; null = every stream. An unknown id is `unknownId` at `streamId`." }, "force": { "type": "boolean", "description": "Run `ffprobe` again even for a file whose size and mtime match the cache's row.", "default": false } }, "required": [], "additionalProperties": false }, "ProjectInfoRead": { "type": "object", "properties": { "path": { "type": "string", "description": "The absolute path of the project file." }, "name": { "type": "string", "description": "What the project is called: the registry's name, else the file name." }, "format": { "type": "string", "description": "The format id — `cutroom`, whatever the product is called." }, "product": { "type": "string", "description": "The product that made the file." }, "build": { "type": "string", "description": "The build that made the file." }, "upgradedBy": { "type": "string", "description": "The build that last migrated the file's schema: the one that made it until an `upgrade` event." }, "createdAt": { "type": "string", "description": "When the file was made, ISO 8601." }, "mediaRoots": { "type": "array", "items": { "type": "string" }, "description": "The folders beside the project's own that the media walk reads, absolute, in walk order." } }, "required": [ "path", "name", "format", "product", "build", "upgradedBy", "createdAt", "mediaRoots" ], "additionalProperties": false }, "ProxyStatusRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the document was read at." }, "proxies": { "type": "array", "items": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The stream." }, "status": { "type": "string", "description": "`none` (no run and no proxy), `queued`, `running`, `ready`, `failed`, `cancelled`." }, "percent": { "type": "number", "description": "How far a running transcode has come, 0–100; 100 when ready." }, "path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The proxy's path relative to the project's folder when one is ready (the media map's key for its URL), else null." }, "preset": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The preset of the ready proxy or the run in flight, else null." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why a run failed, else null." } }, "required": [ "takeId", "streamId", "status", "percent", "path", "preset", "error" ], "additionalProperties": false }, "description": "One row per video stream, in document order." } }, "required": [ "seq", "proxies" ], "additionalProperties": false }, "QuoteSpansRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the spans were computed from." }, "spans": { "type": "array", "items": { "type": "object", "properties": { "markerIds": { "type": "array", "items": { "type": "string" }, "description": "The start marker's id, then the end's when it fired." }, "in": { "type": "number", "description": "Take seconds the card goes up." }, "out": { "type": "number", "description": "Take seconds it comes down: the end marker, or the default length when the end never fired." }, "body": { "type": "string", "description": "The quotation, as the script wrote it." } }, "required": [ "markerIds", "in", "out", "body" ], "additionalProperties": false }, "description": "Every quote the script and the take agree on, in script order: its markers, its take times, its text." } }, "required": [ "seq", "spans" ], "additionalProperties": false }, "RebuildArgs": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "RecentProjects": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "What the project is called: the name it was created with, else its file name." }, "path": { "type": "string", "description": "The absolute path of the project file." }, "lastOpenedAt": { "type": "string", "description": "When it was last opened here, ISO 8601; `listRecent` orders by it, newest first." }, "exists": { "type": "boolean", "description": "Whether the file is where the registry last saw it: a moved or deleted project keeps its card, shown as missing." }, "state": { "type": "string", "enum": [ "ok", "missing", "newer" ], "description": "`ok`, `missing` (= `!exists`), or `newer` — made by a newer build, so opening it is refused until the app is updated. Read off the file each time, never stored." }, "thumbnail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A poster once the project has one (C-18b); null until then." } }, "required": [ "name", "path", "lastOpenedAt", "exists", "state", "thumbnail" ], "additionalProperties": false }, "description": "Newest first, at most twenty; missing files kept." } }, "required": [ "projects" ], "additionalProperties": false }, "RecordScreencastArgs": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take's name in Rheocles (its folder is slugged from it); null lets Rheocles name it by the clock." } }, "required": [], "additionalProperties": false }, "RegroupMovedArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The timeline." }, "trackId": { "type": "string", "description": "The track that moved." } }, "required": [ "sequenceId", "trackId" ], "additionalProperties": false }, "RelabelMarkerArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "markerId": { "type": "string", "description": "The marker to relabel." }, "label": { "type": "string", "description": "The replacement text, which may be empty." } }, "required": [ "takeId", "markerId", "label" ], "additionalProperties": false }, "RelinkMediaArgs": { "type": "object", "properties": { "folder": { "type": "string", "description": "The folder the files moved to, absolute on this machine; searched recursively." }, "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take whose missing streams to relink; null = every take's. An unknown id is `unknownId` at `takeId`." } }, "required": [ "folder" ], "additionalProperties": false }, "RemoveChapterArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "chapterId": { "type": "string", "description": "The chapter to remove." } }, "required": [ "takeId", "chapterId" ], "additionalProperties": false }, "RemoveClipArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The clip to take off its track." }, "options": { "type": "object", "properties": { "ripple": { "type": "boolean", "description": "Close the gap on every unlocked track (a ripple delete), or leave it.", "default": false } }, "required": [], "additionalProperties": false, "description": "Lift (the default) or ripple.", "default": { "ripple": false } } }, "required": [ "sequenceId", "clipId" ], "additionalProperties": false }, "RemoveExportPresetArgs": { "type": "object", "properties": { "presetId": { "type": "string", "description": "The preset to remove." } }, "required": [ "presetId" ], "additionalProperties": false }, "RemoveFramingKeyframeArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The footage or image clip." }, "targetId": { "type": "string", "description": "The target the framing is for." }, "at": { "type": "number", "description": "Clip seconds (0 is the clip's first frame): the moment of the keyframe to remove." } }, "required": [ "sequenceId", "clipId", "targetId", "at" ], "additionalProperties": false }, "RemoveGainKeyframeArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The footage or bed clip." }, "at": { "type": "number", "description": "Clip seconds (0 is the clip's first frame): the moment of the keyframe to remove." } }, "required": [ "sequenceId", "clipId", "at" ], "additionalProperties": false }, "RemoveGroupArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the group is in." }, "groupId": { "type": "string", "description": "The group to dissolve." } }, "required": [ "sequenceId", "groupId" ], "additionalProperties": false }, "RemoveLicenceArgs": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "RemoveMarkerArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "markerId": { "type": "string", "description": "The marker to remove." } }, "required": [ "takeId", "markerId" ], "additionalProperties": false }, "RemovePanelArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The baked project scene." }, "panelId": { "type": "string", "description": "The panel to remove." } }, "required": [ "sceneId", "panelId" ], "additionalProperties": false }, "RemoveSceneArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The project scene to remove." }, "force": { "type": "boolean", "description": "Remove it although placements name it: each falls back to its `fallback` (the timeline's seeded base: Full screen for a take with no camera, else the two-up).", "default": false } }, "required": [ "sceneId" ], "additionalProperties": false }, "RemoveScenePlacementArgs": { "type": "object", "properties": { "placementId": { "type": "string", "description": "The placement to take off the scenes track (`pl3`). Unknown: `unknownId` at `placementId`." }, "sequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline to look on; null = any (placement ids are the document's). An unknown id is `unknownId` at `sequenceId`." } }, "required": [ "placementId" ], "additionalProperties": false }, "RemoveSequenceArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The timeline to remove." } }, "required": [ "sequenceId" ], "additionalProperties": false }, "RemoveSpanArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence to cut from." }, "in": { "type": "number", "description": "Edit seconds the span starts, inclusive." }, "out": { "type": "number", "description": "Edit seconds the span ends, exclusive." }, "trackIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The tracks to cut from; null = every unlocked track." } }, "required": [ "sequenceId", "in", "out" ], "additionalProperties": false }, "RemoveTakeSpanArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence to cut from." }, "takeId": { "type": "string", "description": "The take whose span is removed wherever the edit shows it." }, "in": { "type": "number", "description": "Take seconds the span starts, inclusive." }, "out": { "type": "number", "description": "Take seconds the span ends, exclusive." } }, "required": [ "sequenceId", "takeId", "in", "out" ], "additionalProperties": false }, "RemoveTargetArgs": { "type": "object", "properties": { "targetId": { "type": "string", "description": "The target to remove. An unknown id is `unknownId` at `targetId`." }, "force": { "type": "boolean", "description": "Drop the takes' cues under it and the id from every clip's list (a clip left serving no target is deleted); without it a target still named anywhere is `target-in-use`.", "default": false } }, "required": [ "targetId" ], "additionalProperties": false }, "RemoveTrackArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the track is in." }, "trackId": { "type": "string", "description": "The track to take away — any track (track-roles.md §6)." }, "force": { "type": "boolean", "description": "Take it away with its clips. Without this a track that holds clips is `not-empty`.", "default": false } }, "required": [ "sequenceId", "trackId" ], "additionalProperties": false }, "RenameChapterArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "chapterId": { "type": "string", "description": "The chapter to rename." }, "name": { "type": "string", "description": "The replacement heading, which may be empty." } }, "required": [ "takeId", "chapterId", "name" ], "additionalProperties": false }, "RenameGroupArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the group is in." }, "groupId": { "type": "string", "description": "The group to rename." }, "name": { "type": "string", "description": "What the folded row is called from now on." } }, "required": [ "sequenceId", "groupId", "name" ], "additionalProperties": false }, "RenameProjectArgs": { "type": "object", "properties": { "name": { "type": "string", "description": "What the project is called from now on — on its card, in `projectInfo`, and in the file itself. Trimmed; empty is `invalidArgs` at `name`." } }, "required": [ "name" ], "additionalProperties": false }, "RenameSequenceArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The timeline." }, "name": { "type": "string", "description": "What the tab says from now on." } }, "required": [ "sequenceId", "name" ], "additionalProperties": false }, "RenameTargetArgs": { "type": "object", "properties": { "targetId": { "type": "string", "description": "The target. An unknown id is `unknownId` at `targetId`." }, "name": { "type": "string", "description": "The new name; its slug names the plan files and lint ids, so one another target's name already slugs to is `invalidArgs`." } }, "required": [ "targetId", "name" ], "additionalProperties": false }, "RenameTrackArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the track is in." }, "trackId": { "type": "string", "description": "The track to rename." }, "name": { "type": "string", "description": "What the track is called from now on." } }, "required": [ "sequenceId", "trackId", "name" ], "additionalProperties": false }, "RenderPlansRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the plans were computed from." }, "plans": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer", "description": "" }, "target": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique in the document: a preset's id (`16:9`) or the custom target's." }, "name": { "type": "string", "description": "What the page and the plan names call it (`Horizontal`, `Square`)." }, "aspect": { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame." }, "enabled": { "type": "boolean", "description": "In the plans, or kept with its cues and out of them." }, "safe": { "type": "object", "properties": { "action": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Action-safe: nothing that matters outside it." }, "title": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Title-safe: text inside it." }, "caption": { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false, "description": "Where the captions band sits." }, "chrome": { "anyOf": [ { "type": "object", "properties": { "top": { "type": "number", "description": "Percent of the frame's height, in from the top." }, "right": { "type": "number", "description": "Percent of the frame's width, in from the right." }, "bottom": { "type": "number", "description": "Percent of the frame's height, in from the bottom." }, "left": { "type": "number", "description": "Percent of the frame's width, in from the left." } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, { "type": "null" } ], "description": "The platform's own overlays (a Reel's top bar, its action rail, its caption strip); null for a frame shown bare." } }, "required": [ "action", "title", "caption", "chrome" ], "additionalProperties": false, "description": "Its safe areas." }, "primitives": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "full-cam", "full-cam-tight", "split", "full-screen", "stack", "pip", "over-shoulder" ] } }, { "type": "null" } ], "description": "The primitives this frame offers, when the aspect's own list (`Targets::primitivesFor`) is not the one wanted; null = computed from the aspect." } }, "required": [ "id", "name", "aspect", "enabled", "safe" ], "additionalProperties": false, "description": "The target this plan renders for: the frame's id, name, aspect and safe areas (targets-not-formats.md §5; v2's `format`/`aspect` are its orientation and aspect)." }, "fps": { "type": "number", "description": "" }, "duration": { "type": "number", "description": "Edit seconds: the sum of the segments." }, "take": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rheocles" ], "description": "The discriminator `TakeSourceCast` keys on; always `rheocles`." }, "id": { "type": "string", "description": "The manifest's `id`." }, "name": { "type": "string", "description": "Something to print; the id when the manifest gave none." }, "folder": { "type": "string", "description": "The folder name, for display. The handle itself is not serialisable." }, "manifest": { "type": "string", "description": "The manifest file's name inside the folder; always `manifest.json`." } }, "required": [ "kind", "id", "name", "folder", "manifest" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "obs" ], "description": "The discriminator `TakeSourceCast` keys on; always `obs`." }, "id": { "type": "string", "description": "The footage file name, which is also the take's identity." }, "name": { "type": "string", "description": "Something to print; the id when the file gave none." }, "folder": { "type": "string", "description": "The folder name, for display." }, "cues": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cue CSV the markers were read from, if one was given." } }, "required": [ "kind", "id", "name", "folder", "cues" ], "additionalProperties": false }, { "type": "null" } ], "description": "The take the footage comes from, verbatim; null when the document holds no take (stills and cards alone)." }, "name": { "type": "string", "description": "`--` for a landscape target's whole edit, `---` for a portrait or square target's chapter — a preset's `naming` renders its own in `render.json`." }, "sequence": { "type": "object", "properties": { "id": { "type": "string", "description": "" }, "name": { "type": "string", "description": "" } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "" }, "chapter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The chapter a vertical plan is cut for; null for the whole edit." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "" }, "short": { "type": "boolean", "description": "" }, "scene": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "The project's scene, verbatim from the edit, for the compositor's palette and panel." }, "captions": { "type": "object", "properties": { "position": { "type": "string", "enum": [ "bottom", "top", "custom" ], "description": "Bottom, top, or a custom `y` inside the captions band." }, "y": { "type": "number", "description": "Where in the captions band, for `custom`: 0 at its top, 1 at its floor." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "Small, medium or large type." }, "box": { "type": "string", "enum": [ "pill", "band", "none" ], "description": "A pill, a full-width band, or nothing behind the text." }, "font": { "type": "string", "enum": [ "sans", "serif", "mono" ], "description": "Sans, serif or mono." }, "safe": { "type": "boolean", "description": "Keep them inside the caption-safe area of the frame whatever `position` says." } }, "required": [ "position", "y", "size", "box", "font", "safe" ], "additionalProperties": false, "description": "How the captions track's cues are drawn, verbatim from the edit." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds: where this segment starts in the finished file, and how long it runs." }, "duration": { "type": "number", "description": "Edit seconds the segment runs for." }, "takeIn": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Take seconds under the segment's start, or null over a gap." }, "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "clipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The footage clip under the segment's start — the one `takeIn` maps through — or null over a gap (C-12 follow-up: the page finds the clip without a take-clock guess)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, "description": "Every stream whose file covers this span, with where to read from. Empty over a gap." }, "scene": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The scene the cue named — a built-in's id or the project's." }, "name": { "type": "string", "description": "" }, "family": { "anyOf": [ { "type": "string", "enum": [ "full", "full-tight", "screen", "two-up", "pip", "over-shoulder" ] }, { "type": "null" } ], "description": "The family the panels were laid out from; null for a scene made from scratch." }, "knobs": { "anyOf": [ { "type": "object", "properties": { "gutter": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The one gutter, percent of frame width: 0 up to (not including) 50." }, "camWidth": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam column's width, percent of frame width: above 0, below 100." }, "stackSplit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam's share of the stack's height: a third to two thirds (`Layouts::clampSplit`'s range — a value outside it would render clamped)." }, "tightInset": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "How far `full-cam-tight` pushes in, percent: 0 up to (not including) 50." }, "sponsors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the split reserves the sponsor panel." }, "pipCorner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where PiP's small picture sits: `top-left`, `top-right`, `bottom-left`, `bottom-right`." }, "pipSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How wide PiP's small picture is: `small`, `medium`, `large`." }, "shoulderSide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which shoulder the newscast box floats over: `left`, `right`." } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The knobs the panels were laid out with, sponsors as it stood on this segment; null for a baked scene." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "panelId": { "type": "string", "description": "The scene's panel id — what a cue's `mappings` and `mapPanel` key on." }, "name": { "type": "string", "description": "" }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track the panel resolved to, or null (empty, or a role no track fills)." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Percent of the frame." }, "transform": { "type": "object", "properties": { "x": { "type": "number", "description": "Percent of the rect's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the rect's height, downward.", "default": 0.0 }, "zoom": { "type": "number", "description": "1 = the picture as fitted; up to 8.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "The picture's translate and zoom inside the rect, after the clip's framing." }, "fit": { "type": "string", "enum": [ "cover", "contain" ], "description": "How a picture with no framing fits the rect." }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height." }, "border": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "The stroke's thickness, a percent of the frame's **width** (the one unit on both frames — a radius and a shadow are percents of the height); 0 up to 10." }, "colour": { "type": "string", "description": "A colour token (`frame`, `frame-ink`, `frame-card`, `accent`)." }, "style": { "type": "string", "enum": [ "solid", "dashed", "dotted" ], "description": "", "default": "solid" } }, "required": [ "width", "colour" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "shadow": { "anyOf": [ { "type": "object", "properties": { "blur": { "type": "number", "description": "Blur radius, percent of the frame's height; 0 to 20." }, "x": { "type": "number", "description": "Offset, percent of the frame's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Offset, percent of the frame's height, downward.", "default": 0.0 }, "colour": { "type": "string", "description": "A colour token.", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.5 } }, "required": [ "blur" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "alpha": { "type": "number", "description": "The panel's opacity, 0 to 1." }, "blur": { "type": "number", "description": "Backdrop blur, px." }, "source": { "anyOf": [ { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, { "type": "null" } ], "description": "A take stream in force on the panel's track at the segment's start, with the clip's framing for this target; null for a still or an empty panel." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A still's media key (a slide, an image clip); null for a stream, the sponsor carousel or an empty panel." }, "shows": { "type": "string", "enum": [ "stream", "image", "sponsors", "nothing" ], "description": "What the panel shows — what its bound track has in force: a stream, an image, the sponsor carousel, or nothing." }, "empty": { "anyOf": [ { "type": "string", "enum": [ "unbound", "no-camera", "no-screen", "not-drawable", "nothing-now" ] }, { "type": "null" } ], "description": "Why the panel shows nothing — `unbound`, `no-camera`, `no-screen`, `not-drawable`, `nothing-now`; null unless `shows` is `nothing`." }, "stream": { "anyOf": [ { "type": "string", "enum": [ "screen", "primary" ] }, { "type": "null" } ], "description": "Which of a take clip's streams the panel asked for (`screen`), while a take is one clip with several (pre-B4); null is the camera." } }, "required": [ "panelId", "name", "trackId", "rect", "transform", "fit", "radius", "border", "shadow", "alpha", "blur", "source", "src", "shows", "empty" ], "additionalProperties": false }, "description": "" }, "captions": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Captions show on this segment at all." }, "burnIn": { "type": "boolean", "description": "The export writes them into the picture; false is a sidecar, or none." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where a line sits, percent of the frame: the scene's placement resolved (`Placed::rect`, the caption-safe box), or the default style's band." }, "look": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "", "default": "sans" }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "", "default": "medium" }, "tracking": { "type": "number", "description": "Letter spacing, percent of the em; -20 to 50.", "default": 0.0 }, "leading": { "type": "number", "description": "Line height as a multiple of the size; 0.8 to 2.", "default": 1.2 }, "colour": { "type": "string", "description": "The text's colour token.", "default": "frame-ink" }, "stroke": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "Percent of the frame's height; 0 to 2." }, "colour": { "type": "string", "description": "", "default": "frame" } }, "required": [ "width" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "background": { "anyOf": [ { "type": "object", "properties": { "colour": { "type": "string", "description": "", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.62 }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 to 10. Stored and returned as set, but not drawn yet: the reference renderer squares the box (libass has no rounded box), and so does the app's preview. Drawing it is RADIUS-2.", "default": 0.0 } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "padding": { "type": "number", "description": "Inside the background, percent of the frame's height; 0 to 10.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "" }, "own": { "type": "boolean", "description": "True when the scene set these; false when the timeline's default style stands in." } }, "required": [ "enabled", "burnIn", "rect", "look", "own" ], "additionalProperties": false, "description": "The segment's captions, resolved for the target: the scene's own, else the timeline's default style translated (C-22b)." } }, "required": [ "sceneId", "name", "family", "knobs", "panels", "captions" ], "additionalProperties": false, "description": "" }, "slide": { "anyOf": [ { "type": "object", "properties": { "slide": { "type": "integer", "description": "" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" } }, "required": [ "slide", "name", "src" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "interstitial": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bumper", "sting", "quote", "exhibit" ], "description": "" }, "title": { "type": "string", "description": "" }, "body": { "type": "string", "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "audible": { "type": "boolean", "description": "Whether the card's sound is still on: false during its picture tail, and for cards with no sound." }, "elapsed": { "type": "number", "description": "Edit seconds since the card began, for a typewriter or a sting that is mid-way." } }, "required": [ "kind", "title", "body", "src", "audible", "elapsed" ], "additionalProperties": false }, { "type": "null" } ], "description": "The topmost card over the frame, or null." }, "overlays": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string", "description": "" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "A still's crop and pan over this segment (C-11); a cutaway's rides its `sources`. Absent when the clip has none for the target." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where a placed still sits, percent of the frame (C-16); absent draws full-frame, as before." }, "opacity": { "type": "number", "description": "How opaque, 0 to 1 (C-16); absent is 1, as before." }, "fadeIn": { "type": "number", "description": "Seconds from the clip's first frame over which it fades in from what is beneath (C-16b: an overlay-track clip's transition, clamped to the clip); present only on a segment that starts inside the fade, with `elapsed`." }, "elapsed": { "type": "number", "description": "Seconds since the clip began at the segment's start — where in the fade it stands; present with `fadeIn`." } }, "required": [ "clipId", "sources", "src" ], "additionalProperties": false }, "description": "Every cutaway or placed still with picture in force below any card, topmost first (C-16: the single `overlay` became this list). Empty over nothing." }, "caption": { "anyOf": [ { "type": "object", "properties": { "clipId": { "type": "string", "description": "" }, "src": { "type": "string", "description": "" }, "clock": { "type": "string", "enum": [ "take", "edit" ], "description": "" }, "fileTime": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Where the captions file reads at the segment's start: take seconds when `clock` is `take` (the file is timed to the take), file seconds when it is `edit`; null when no take second is under the start." } }, "required": [ "clipId", "src", "clock", "fileTime" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "chapter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "audio": { "type": "object", "properties": { "mix": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string", "description": "The clip that sounds." }, "streamId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A footage clip's stream — the plan's carrier — or the stream an audio track's take clip sounds; null for a bed." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A bed's file (its `source.src`), or an audio track's take stream's file — either read on its own clock, at 1×; null for the footage's carrier." }, "fileTime": { "type": "number", "description": "Seconds into the file at the segment's start." }, "gain": { "type": "number", "description": "The level at the segment's start, in dB: the track's gain, the clip's, its keyframes, fades and ducking summed." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Plan seconds (the plan's own clock, as `segments[].at`)." }, "gain": { "type": "number", "description": "The level in dB from here, linear to the next point." } }, "required": [ "at", "gain" ], "additionalProperties": false }, "description": "The levels that change inside the segment, on the plan's clock — one on the first frame is `gain`, one on the last belongs to the next segment." }, "rate": { "type": "number", "description": "How fast an audio track's take stream plays — its clip's speed, present only when not 1× (B3b: a sped linked pair; the pitch as `audio.preservePitch`). Absent: 1×." } }, "required": [ "clipId", "streamId", "src", "fileTime", "gain", "keyframes" ], "additionalProperties": false }, "description": "" } }, "required": [ "mix" ], "additionalProperties": false, "description": "What sounds and how loud (C-15); absent when the document sets no audio on the sequence — `plan.audio.carrier` alone plays, as before." }, "titles": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string", "description": "" }, "template": { "type": "string", "enum": [ "lower-third", "full-frame", "tag" ], "description": "" }, "fields": { "type": "object", "properties": { "title": { "type": "string", "description": "The first line: the name, the headline.", "default": "" }, "subtitle": { "type": "string", "description": "The second line under it: the role, the strapline; a tag never shows it.", "default": "" } }, "required": [], "additionalProperties": false, "description": "" }, "style": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "The face by role: `display` (Fraunces), `sans` (Instrument Sans), `mono` (IBM Plex Mono)." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "The line height: small, medium or large." }, "ink": { "type": "string", "description": "The text's colour, a token name (`frame-ink`, `frame`, `frame-card`, `accent`)." }, "panel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The box's fill, a token name, or null for none." } }, "required": [ "font", "size", "ink", "panel" ], "additionalProperties": false, "description": "" }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where it sits, percent of the frame, inside the target's title-safe box unless the lint says otherwise." }, "panelAlpha": { "type": "number", "description": "The panel's opacity, the template's." }, "elapsed": { "type": "number", "description": "Edit seconds since the title began, rounded to six decimals (a card's `elapsed`)." } }, "required": [ "clipId", "template", "fields", "style", "rect", "panelAlpha", "elapsed" ], "additionalProperties": false }, "description": "Every title with picture in force, topmost first, its rect resolved for this target (C-16); absent when the sequence holds no title." }, "speed": { "type": "number", "description": "The footage's constant speed over this segment (C-16b): the take runs this many times as fast as the edit; absent is 1." }, "transition": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dissolve", "dip" ], "description": "" }, "duration": { "type": "number", "description": "Edit seconds, the segment's own length." }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A dip's colour token; null is `frame`." }, "from": { "type": "array", "items": { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, "description": "The left clip's streams continuing past its out point, read from where its handle starts; empty for a dip with no handle." }, "speed": { "type": "number", "description": "The outgoing clip's own speed, at which `from` runs (C-16b: distinct from the segment's `speed`, the arriving clip's); absent is 1." } }, "required": [ "kind", "duration", "colour", "from" ], "additionalProperties": false }, { "type": "null" } ], "description": "The transition this segment is (C-16b): the join it starts, resolved — or null on a segment that is no transition, or one a dissolve could not read media for (the lint says). Absent when the sequence holds no transition." } }, "required": [ "at", "duration", "takeIn", "takeId", "clipId", "sources", "scene", "slide", "interstitial", "overlays", "caption", "chapter" ], "additionalProperties": false }, "description": "" }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "" }, "at": { "type": "number", "description": "" }, "synthetic": { "type": "boolean", "description": "Present and true on the `Open` chapter the plan added so the list starts at 0." } }, "required": [ "name", "at" ], "additionalProperties": false }, "description": "Chapter starts in edit time, YouTube-style: the first at 0, synthetic if it had to be." }, "audio": { "type": "object", "properties": { "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The mic if there is one, else the primary video; null when neither sounds." }, "preservePitch": { "type": "boolean", "description": "C-16b: a renderer retiming a sped segment keeps the pitch; present (`true`) once the sequence holds a clip at a speed other than 1." } }, "required": [ "carrier" ], "additionalProperties": false, "description": "" }, "sponsorsOutro": { "anyOf": [ { "type": "object", "properties": { "seconds": { "type": "number", "description": "" } }, "required": [ "seconds" ], "additionalProperties": false }, { "type": "null" } ], "description": "A portrait or square export ends on the sponsors card; null for a landscape one." }, "preset": { "type": "object", "properties": { "id": { "type": "string", "description": "The preset's id on the document." }, "name": { "type": "string", "description": "What the Exports card calls it." }, "container": { "type": "string", "enum": [ "mp4", "mov", "webm" ], "description": "The file: mp4, mov or webm." }, "codec": { "type": "string", "enum": [ "h264", "hevc", "prores", "vp9", "av1" ], "description": "The video codec." }, "resolution": { "type": "object", "properties": { "w": { "type": "integer", "description": "Width in pixels." }, "h": { "type": "integer", "description": "Height in pixels." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame in pixels." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Frames per second to encode at; null is the plan's `fps`." }, "quality": { "type": "object", "properties": { "crf": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Constant rate factor (lower is better; 18 is visually lossless for h264); null when `bitrate` rules." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Target bitrate in kbit/s; null when `crf` rules." } }, "required": [], "additionalProperties": false, "description": "How hard the video is compressed: `crf` or `bitrate`, one of the two." }, "audio": { "type": "object", "properties": { "codec": { "type": "string", "enum": [ "aac", "pcm", "opus" ], "description": "aac, pcm or opus." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "kbit/s; null for a codec that has no rate (pcm) or the encoder's default." } }, "required": [ "codec", "bitrate" ], "additionalProperties": false, "description": "The sound: codec and bitrate." }, "naming": { "type": "string", "description": "The template the plan's `name` was rendered from." } }, "required": [ "id", "name", "container", "codec", "resolution", "fps", "quality", "audio", "naming" ], "additionalProperties": false, "description": "How to encode this file (`render.json`, one plan per enabled preset); absent in the `renderPlans` read, which is the geometry alone." }, "captionSidecar": { "type": "string", "description": "A plain SRT output beside the video, named before rendering; omitted when no segment requests unburnt captions. Empty or unavailable source cues produce no file." } }, "required": [ "version", "target", "fps", "duration", "take", "name", "sequence", "chapter", "flags", "short", "scene", "captions", "segments", "chapters", "audio", "sponsorsOutro" ], "additionalProperties": false }, "description": "One plan per export: per timeline, the whole edit for the horizontal frame, then one per chapter with footage for the vertical, shorts first." } }, "required": [ "seq", "plans" ], "additionalProperties": false }, "ReorderSequencesArgs": { "type": "object", "properties": { "sequenceIds": { "type": "array", "items": { "type": "string" }, "description": "Every timeline's id, in the order the tabs show them." } }, "required": [ "sequenceIds" ], "additionalProperties": false }, "RevertMarkerArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "markerId": { "type": "string", "description": "The recorded marker to restore." } }, "required": [ "takeId", "markerId" ], "additionalProperties": false }, "RippleFromArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence to ripple." }, "at": { "type": "number", "description": "Edit seconds from which everything moves." }, "delta": { "type": "number", "description": "Seconds to move by; negative closes a gap." }, "trackIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The tracks to move; null = every unlocked track." } }, "required": [ "sequenceId", "at", "delta" ], "additionalProperties": false }, "RollEditArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clips are in." }, "leftId": { "type": "string", "description": "The clip before the cut; its out moves." }, "rightId": { "type": "string", "description": "The clip after the cut, on the same track, starting where the left one ends; its in moves." }, "at": { "type": "number", "description": "Edit seconds the cut should land on; kept a frame inside either clip." } }, "required": [ "sequenceId", "leftId", "rightId", "at" ], "additionalProperties": false }, "RotateTokenArgs": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "SaveSceneToLibraryArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The project scene to save." } }, "required": [ "sceneId" ], "additionalProperties": false }, "ScenesRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the list was read at." }, "scenes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A built-in's name (`split-plain`, `pip-bottom-right-small`), a project's `sc1` …, a library id." }, "name": { "type": "string", "description": "" }, "family": { "anyOf": [ { "type": "string", "enum": [ "full", "full-tight", "screen", "two-up", "pip", "over-shoulder" ] }, { "type": "null" } ], "description": "The family across frames (`copyScenes` maps by it); null for a scene made from scratch." }, "knobs": { "anyOf": [ { "type": "object", "properties": { "gutter": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The one gutter, percent of frame width: 0 up to (not including) 50." }, "camWidth": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam column's width, percent of frame width: above 0, below 100." }, "stackSplit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam's share of the stack's height: a third to two thirds (`Layouts::clampSplit`'s range — a value outside it would render clamped)." }, "tightInset": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "How far `full-cam-tight` pushes in, percent: 0 up to (not including) 50." }, "sponsors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the split reserves the sponsor panel." }, "pipCorner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where PiP's small picture sits: `top-left`, `top-right`, `bottom-left`, `bottom-right`." }, "pipSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How wide PiP's small picture is: `small`, `medium`, `large`." }, "shoulderSide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which shoulder the newscast box floats over: `left`, `right`." } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The pre-tuning a parametric scene lays out with; null for a baked one." }, "aspect": { "anyOf": [ { "type": "object", "properties": { "w": { "type": "number", "description": "The frame's width, in the units of `h` (16 of 16:9)." }, "h": { "type": "number", "description": "The frame's height, in the units of `w` (9 of 16:9)." } }, "required": [ "w", "h" ], "additionalProperties": false }, { "type": "null" } ], "description": "The frame a baked scene is laid out for; null for a parametric one (any frame)." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the scene (`p1`, `p2` …)." }, "name": { "type": "string", "description": "What the inspector calls it (`Camera`, `Screen`, `Sponsors`, `Background`); free text." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track whose clip in force this panel shows; null is an empty panel (its look only)." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where the panel sits, percent of the frame." }, "transform": { "type": "object", "properties": { "x": { "type": "number", "description": "Percent of the rect's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the rect's height, downward.", "default": 0.0 }, "zoom": { "type": "number", "description": "1 = the picture as fitted; up to 8.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "How the picture sits inside the rect, after the clip's own framing.", "default": { "x": 0.0, "y": 0.0, "zoom": 1.0 } }, "fit": { "type": "string", "enum": [ "cover", "contain" ], "description": "How a picture without a framing fits the rect.", "default": "cover" }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 is square.", "default": 0.0 }, "border": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "The stroke's thickness, a percent of the frame's **width** (the one unit on both frames — a radius and a shadow are percents of the height); 0 up to 10." }, "colour": { "type": "string", "description": "A colour token (`frame`, `frame-ink`, `frame-card`, `accent`)." }, "style": { "type": "string", "enum": [ "solid", "dashed", "dotted" ], "description": "", "default": "solid" } }, "required": [ "width", "colour" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "shadow": { "anyOf": [ { "type": "object", "properties": { "blur": { "type": "number", "description": "Blur radius, percent of the frame's height; 0 to 20." }, "x": { "type": "number", "description": "Offset, percent of the frame's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Offset, percent of the frame's height, downward.", "default": 0.0 }, "colour": { "type": "string", "description": "A colour token.", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.5 } }, "required": [ "blur" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "alpha": { "type": "number", "description": "The panel's opacity, 0 to 1.", "default": 1.0 }, "blur": { "type": "number", "description": "Backdrop blur, px; 0 is none (C-14's panel blur, the stage draws it).", "default": 0.0 }, "stream": { "anyOf": [ { "type": "string", "enum": [ "screen", "primary" ] }, { "type": "null" } ], "description": "Which of a take clip's streams, while a take is one clip with several (pre-B4); null is the first video stream." }, "role": { "anyOf": [ { "type": "string", "enum": [ "cam", "screen", "slide", "sponsors", "pip", "background" ] }, { "type": "null" } ], "description": "What the panel reads when `trackId` is null or names a track the sequence lacks: the role's topmost track; null draws empty." }, "hideWhenEmpty": { "type": "boolean", "description": "The panel hides — its look and picture — while its track has no clip in force; the scene's `whenHidden` says what moves.", "default": false } }, "required": [ "id", "name", "trackId", "rect" ], "additionalProperties": false }, "description": "" }, "whenHidden": { "type": "array", "items": { "type": "object", "properties": { "hidden": { "type": "string", "description": "The strip that hides (`role: sponsors`, `hideWhenEmpty`)." }, "panelId": { "type": "string", "description": "The panel that moves while it does." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where it sits then, percent of the frame." } }, "required": [ "hidden", "panelId", "rect" ], "additionalProperties": false }, "description": "" }, "captions": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "", "default": true }, "burnIn": { "type": "boolean", "description": "The export writes them into the picture; false is a sidecar, or none.", "default": true }, "placement": { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false, "description": "", "default": { "anchor": "bottom", "x": 0.0, "y": 0.0, "w": 80.0 } }, "look": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "", "default": "sans" }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "", "default": "medium" }, "tracking": { "type": "number", "description": "Letter spacing, percent of the em; -20 to 50.", "default": 0.0 }, "leading": { "type": "number", "description": "Line height as a multiple of the size; 0.8 to 2.", "default": 1.2 }, "colour": { "type": "string", "description": "The text's colour token.", "default": "frame-ink" }, "stroke": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "Percent of the frame's height; 0 to 2." }, "colour": { "type": "string", "description": "", "default": "frame" } }, "required": [ "width" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "background": { "anyOf": [ { "type": "object", "properties": { "colour": { "type": "string", "description": "", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.62 }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 to 10. Stored and returned as set, but not drawn yet: the reference renderer squares the box (libass has no rounded box), and so does the app's preview. Drawing it is RADIUS-2.", "default": 0.0 } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "padding": { "type": "number", "description": "Inside the background, percent of the frame's height; 0 to 10.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "", "default": { "font": "sans", "size": "medium", "tracking": 0.0, "leading": 1.2, "colour": "frame-ink", "stroke": null, "background": null, "padding": 1.0 } } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The scene's captions; null is the timeline's default, shown and burnt in." }, "scope": { "type": "string", "enum": [ "builtin", "project", "library" ], "description": "" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A project scene copied from the library: the library id it came from." } }, "required": [ "id", "name", "family", "knobs", "aspect", "panels", "whenHidden", "captions", "scope" ], "additionalProperties": false }, "description": "Built-ins first, then the project's, then the library's; each laying out for the target when one was named." }, "invalid": { "type": "array", "items": { "type": "string" }, "description": "Library files that did not read, by name with why (the lint says so too)." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The scene, as it is in `scenes`." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique within the scene (`p1`, `p2` …)." }, "name": { "type": "string", "description": "What the inspector calls it (`Camera`, `Screen`, `Sponsors`, `Background`); free text." }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track whose clip in force this panel shows; null is an empty panel (its look only)." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where the panel sits, percent of the frame." }, "transform": { "type": "object", "properties": { "x": { "type": "number", "description": "Percent of the rect's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the rect's height, downward.", "default": 0.0 }, "zoom": { "type": "number", "description": "1 = the picture as fitted; up to 8.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "How the picture sits inside the rect, after the clip's own framing.", "default": { "x": 0.0, "y": 0.0, "zoom": 1.0 } }, "fit": { "type": "string", "enum": [ "cover", "contain" ], "description": "How a picture without a framing fits the rect.", "default": "cover" }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 is square.", "default": 0.0 }, "border": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "The stroke's thickness, a percent of the frame's **width** (the one unit on both frames — a radius and a shadow are percents of the height); 0 up to 10." }, "colour": { "type": "string", "description": "A colour token (`frame`, `frame-ink`, `frame-card`, `accent`)." }, "style": { "type": "string", "enum": [ "solid", "dashed", "dotted" ], "description": "", "default": "solid" } }, "required": [ "width", "colour" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "shadow": { "anyOf": [ { "type": "object", "properties": { "blur": { "type": "number", "description": "Blur radius, percent of the frame's height; 0 to 20." }, "x": { "type": "number", "description": "Offset, percent of the frame's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Offset, percent of the frame's height, downward.", "default": 0.0 }, "colour": { "type": "string", "description": "A colour token.", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.5 } }, "required": [ "blur" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "alpha": { "type": "number", "description": "The panel's opacity, 0 to 1.", "default": 1.0 }, "blur": { "type": "number", "description": "Backdrop blur, px; 0 is none (C-14's panel blur, the stage draws it).", "default": 0.0 }, "stream": { "anyOf": [ { "type": "string", "enum": [ "screen", "primary" ] }, { "type": "null" } ], "description": "Which of a take clip's streams, while a take is one clip with several (pre-B4); null is the first video stream." }, "role": { "anyOf": [ { "type": "string", "enum": [ "cam", "screen", "slide", "sponsors", "pip", "background" ] }, { "type": "null" } ], "description": "What the panel reads when `trackId` is null or names a track the sequence lacks: the role's topmost track; null draws empty." }, "hideWhenEmpty": { "type": "boolean", "description": "The panel hides — its look and picture — while its track has no clip in force; the scene's `whenHidden` says what moves.", "default": false } }, "required": [ "id", "name", "trackId", "rect" ], "additionalProperties": false }, "description": "Its panels on the target's frame, bottom first." } }, "required": [ "sceneId", "panels" ], "additionalProperties": false }, "description": "With a target: each scene's panels laid out on its frame, in `scenes` order — a built-in's too (its `panels` stay empty: it is parametric). Empty without a target.", "default": [] } }, "required": [ "seq", "scenes", "invalid" ], "additionalProperties": false }, "ScreencastReport": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "unavailable", "unpaired", "outdated", "idle", "created", "recording", "complete", "incomplete" ], "description": "Where things are: `unavailable`, `unpaired`, `outdated`, `idle`, or the take's own `created`, `recording`, `complete`, `incomplete`." }, "installed": { "type": "boolean", "description": "Whether the Rheocles bundle sits where an install puts it; what the page says when `state` is `unavailable`." }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The daemon's version as `GET /` reports it; null when it did not answer. What the page says when `state` is `outdated`." }, "minVersion": { "type": "string", "description": "The oldest daemon the hand-off works with — the floor `outdated` is judged against." }, "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take reported on — the one asked for, or the one Rheocles is recording right now; null when neither." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take's name; null when Rheocles named it by the clock, or there is no take." }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the cue happened, UTC ISO 8601 with milliseconds; null before it." }, "stoppedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the take stopped; null while it records." }, "streams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Rheocles' stream id (`display:…`, `window:…`, `camera:…`, `microphone:…`, `systemAudio:system`)." }, "kind": { "type": "string", "description": "The stream's kind: display, window, camera, microphone or systemAudio." }, "name": { "type": "string", "description": "The device or window name as Rheocles shows it." }, "file": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The file this stream is written to, relative to the take folder; null for a stream not on a take." }, "armed": { "type": "boolean", "description": "Whether the device is live in Rheocles (its own definition of armed); on a take, always true." } }, "required": [ "id", "kind", "name", "file", "armed" ], "additionalProperties": false }, "description": "The take's streams (each with its file), or — for the daemon — every stream it sees, with `armed`." }, "folder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The take folder, absolute (`outputRoot/destination`): what `deriveTake` is handed once the take is complete; null when there is no take." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Rheocles' reason when the take is `incomplete`, or its refusal's message when `unavailable` or `unpaired` because it answered with one; null otherwise." } }, "required": [ "state", "installed", "version", "minVersion", "takeId", "name", "startedAt", "stoppedAt", "streams", "folder", "reason" ], "additionalProperties": false }, "SegmentAtRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the segment was computed from." }, "sequenceId": { "type": "string", "description": "The timeline the segment is from." }, "targetId": { "type": "string", "description": "The target it is composited for." }, "at": { "type": "number", "description": "Edit seconds: the moment asked for." }, "segment": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds: where this segment starts in the finished file, and how long it runs." }, "duration": { "type": "number", "description": "Edit seconds the segment runs for." }, "takeIn": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Take seconds under the segment's start, or null over a gap." }, "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "clipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The footage clip under the segment's start — the one `takeIn` maps through — or null over a gap (C-12 follow-up: the page finds the clip without a take-clock guess)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, "description": "Every stream whose file covers this span, with where to read from. Empty over a gap." }, "scene": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The scene the cue named — a built-in's id or the project's." }, "name": { "type": "string", "description": "" }, "family": { "anyOf": [ { "type": "string", "enum": [ "full", "full-tight", "screen", "two-up", "pip", "over-shoulder" ] }, { "type": "null" } ], "description": "The family the panels were laid out from; null for a scene made from scratch." }, "knobs": { "anyOf": [ { "type": "object", "properties": { "gutter": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The one gutter, percent of frame width: 0 up to (not including) 50." }, "camWidth": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam column's width, percent of frame width: above 0, below 100." }, "stackSplit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam's share of the stack's height: a third to two thirds (`Layouts::clampSplit`'s range — a value outside it would render clamped)." }, "tightInset": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "How far `full-cam-tight` pushes in, percent: 0 up to (not including) 50." }, "sponsors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the split reserves the sponsor panel." }, "pipCorner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where PiP's small picture sits: `top-left`, `top-right`, `bottom-left`, `bottom-right`." }, "pipSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How wide PiP's small picture is: `small`, `medium`, `large`." }, "shoulderSide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which shoulder the newscast box floats over: `left`, `right`." } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The knobs the panels were laid out with, sponsors as it stood on this segment; null for a baked scene." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "panelId": { "type": "string", "description": "The scene's panel id — what a cue's `mappings` and `mapPanel` key on." }, "name": { "type": "string", "description": "" }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track the panel resolved to, or null (empty, or a role no track fills)." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Percent of the frame." }, "transform": { "type": "object", "properties": { "x": { "type": "number", "description": "Percent of the rect's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the rect's height, downward.", "default": 0.0 }, "zoom": { "type": "number", "description": "1 = the picture as fitted; up to 8.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "The picture's translate and zoom inside the rect, after the clip's framing." }, "fit": { "type": "string", "enum": [ "cover", "contain" ], "description": "How a picture with no framing fits the rect." }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height." }, "border": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "The stroke's thickness, a percent of the frame's **width** (the one unit on both frames — a radius and a shadow are percents of the height); 0 up to 10." }, "colour": { "type": "string", "description": "A colour token (`frame`, `frame-ink`, `frame-card`, `accent`)." }, "style": { "type": "string", "enum": [ "solid", "dashed", "dotted" ], "description": "", "default": "solid" } }, "required": [ "width", "colour" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "shadow": { "anyOf": [ { "type": "object", "properties": { "blur": { "type": "number", "description": "Blur radius, percent of the frame's height; 0 to 20." }, "x": { "type": "number", "description": "Offset, percent of the frame's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Offset, percent of the frame's height, downward.", "default": 0.0 }, "colour": { "type": "string", "description": "A colour token.", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.5 } }, "required": [ "blur" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "alpha": { "type": "number", "description": "The panel's opacity, 0 to 1." }, "blur": { "type": "number", "description": "Backdrop blur, px." }, "source": { "anyOf": [ { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, { "type": "null" } ], "description": "A take stream in force on the panel's track at the segment's start, with the clip's framing for this target; null for a still or an empty panel." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A still's media key (a slide, an image clip); null for a stream, the sponsor carousel or an empty panel." }, "shows": { "type": "string", "enum": [ "stream", "image", "sponsors", "nothing" ], "description": "What the panel shows — what its bound track has in force: a stream, an image, the sponsor carousel, or nothing." }, "empty": { "anyOf": [ { "type": "string", "enum": [ "unbound", "no-camera", "no-screen", "not-drawable", "nothing-now" ] }, { "type": "null" } ], "description": "Why the panel shows nothing — `unbound`, `no-camera`, `no-screen`, `not-drawable`, `nothing-now`; null unless `shows` is `nothing`." }, "stream": { "anyOf": [ { "type": "string", "enum": [ "screen", "primary" ] }, { "type": "null" } ], "description": "Which of a take clip's streams the panel asked for (`screen`), while a take is one clip with several (pre-B4); null is the camera." } }, "required": [ "panelId", "name", "trackId", "rect", "transform", "fit", "radius", "border", "shadow", "alpha", "blur", "source", "src", "shows", "empty" ], "additionalProperties": false }, "description": "" }, "captions": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Captions show on this segment at all." }, "burnIn": { "type": "boolean", "description": "The export writes them into the picture; false is a sidecar, or none." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where a line sits, percent of the frame: the scene's placement resolved (`Placed::rect`, the caption-safe box), or the default style's band." }, "look": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "", "default": "sans" }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "", "default": "medium" }, "tracking": { "type": "number", "description": "Letter spacing, percent of the em; -20 to 50.", "default": 0.0 }, "leading": { "type": "number", "description": "Line height as a multiple of the size; 0.8 to 2.", "default": 1.2 }, "colour": { "type": "string", "description": "The text's colour token.", "default": "frame-ink" }, "stroke": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "Percent of the frame's height; 0 to 2." }, "colour": { "type": "string", "description": "", "default": "frame" } }, "required": [ "width" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "background": { "anyOf": [ { "type": "object", "properties": { "colour": { "type": "string", "description": "", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.62 }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 to 10. Stored and returned as set, but not drawn yet: the reference renderer squares the box (libass has no rounded box), and so does the app's preview. Drawing it is RADIUS-2.", "default": 0.0 } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "padding": { "type": "number", "description": "Inside the background, percent of the frame's height; 0 to 10.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "" }, "own": { "type": "boolean", "description": "True when the scene set these; false when the timeline's default style stands in." } }, "required": [ "enabled", "burnIn", "rect", "look", "own" ], "additionalProperties": false, "description": "The segment's captions, resolved for the target: the scene's own, else the timeline's default style translated (C-22b)." } }, "required": [ "sceneId", "name", "family", "knobs", "panels", "captions" ], "additionalProperties": false, "description": "" }, "slide": { "anyOf": [ { "type": "object", "properties": { "slide": { "type": "integer", "description": "" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" } }, "required": [ "slide", "name", "src" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "interstitial": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bumper", "sting", "quote", "exhibit" ], "description": "" }, "title": { "type": "string", "description": "" }, "body": { "type": "string", "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "audible": { "type": "boolean", "description": "Whether the card's sound is still on: false during its picture tail, and for cards with no sound." }, "elapsed": { "type": "number", "description": "Edit seconds since the card began, for a typewriter or a sting that is mid-way." } }, "required": [ "kind", "title", "body", "src", "audible", "elapsed" ], "additionalProperties": false }, { "type": "null" } ], "description": "The topmost card over the frame, or null." }, "overlays": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string", "description": "" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "A still's crop and pan over this segment (C-11); a cutaway's rides its `sources`. Absent when the clip has none for the target." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where a placed still sits, percent of the frame (C-16); absent draws full-frame, as before." }, "opacity": { "type": "number", "description": "How opaque, 0 to 1 (C-16); absent is 1, as before." }, "fadeIn": { "type": "number", "description": "Seconds from the clip's first frame over which it fades in from what is beneath (C-16b: an overlay-track clip's transition, clamped to the clip); present only on a segment that starts inside the fade, with `elapsed`." }, "elapsed": { "type": "number", "description": "Seconds since the clip began at the segment's start — where in the fade it stands; present with `fadeIn`." } }, "required": [ "clipId", "sources", "src" ], "additionalProperties": false }, "description": "Every cutaway or placed still with picture in force below any card, topmost first (C-16: the single `overlay` became this list). Empty over nothing." }, "caption": { "anyOf": [ { "type": "object", "properties": { "clipId": { "type": "string", "description": "" }, "src": { "type": "string", "description": "" }, "clock": { "type": "string", "enum": [ "take", "edit" ], "description": "" }, "fileTime": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Where the captions file reads at the segment's start: take seconds when `clock` is `take` (the file is timed to the take), file seconds when it is `edit`; null when no take second is under the start." } }, "required": [ "clipId", "src", "clock", "fileTime" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "chapter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "audio": { "type": "object", "properties": { "mix": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string", "description": "The clip that sounds." }, "streamId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A footage clip's stream — the plan's carrier — or the stream an audio track's take clip sounds; null for a bed." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A bed's file (its `source.src`), or an audio track's take stream's file — either read on its own clock, at 1×; null for the footage's carrier." }, "fileTime": { "type": "number", "description": "Seconds into the file at the segment's start." }, "gain": { "type": "number", "description": "The level at the segment's start, in dB: the track's gain, the clip's, its keyframes, fades and ducking summed." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Plan seconds (the plan's own clock, as `segments[].at`)." }, "gain": { "type": "number", "description": "The level in dB from here, linear to the next point." } }, "required": [ "at", "gain" ], "additionalProperties": false }, "description": "The levels that change inside the segment, on the plan's clock — one on the first frame is `gain`, one on the last belongs to the next segment." }, "rate": { "type": "number", "description": "How fast an audio track's take stream plays — its clip's speed, present only when not 1× (B3b: a sped linked pair; the pitch as `audio.preservePitch`). Absent: 1×." } }, "required": [ "clipId", "streamId", "src", "fileTime", "gain", "keyframes" ], "additionalProperties": false }, "description": "" } }, "required": [ "mix" ], "additionalProperties": false, "description": "What sounds and how loud (C-15); absent when the document sets no audio on the sequence — `plan.audio.carrier` alone plays, as before." }, "titles": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string", "description": "" }, "template": { "type": "string", "enum": [ "lower-third", "full-frame", "tag" ], "description": "" }, "fields": { "type": "object", "properties": { "title": { "type": "string", "description": "The first line: the name, the headline.", "default": "" }, "subtitle": { "type": "string", "description": "The second line under it: the role, the strapline; a tag never shows it.", "default": "" } }, "required": [], "additionalProperties": false, "description": "" }, "style": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "The face by role: `display` (Fraunces), `sans` (Instrument Sans), `mono` (IBM Plex Mono)." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "The line height: small, medium or large." }, "ink": { "type": "string", "description": "The text's colour, a token name (`frame-ink`, `frame`, `frame-card`, `accent`)." }, "panel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The box's fill, a token name, or null for none." } }, "required": [ "font", "size", "ink", "panel" ], "additionalProperties": false, "description": "" }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where it sits, percent of the frame, inside the target's title-safe box unless the lint says otherwise." }, "panelAlpha": { "type": "number", "description": "The panel's opacity, the template's." }, "elapsed": { "type": "number", "description": "Edit seconds since the title began, rounded to six decimals (a card's `elapsed`)." } }, "required": [ "clipId", "template", "fields", "style", "rect", "panelAlpha", "elapsed" ], "additionalProperties": false }, "description": "Every title with picture in force, topmost first, its rect resolved for this target (C-16); absent when the sequence holds no title." }, "speed": { "type": "number", "description": "The footage's constant speed over this segment (C-16b): the take runs this many times as fast as the edit; absent is 1." }, "transition": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dissolve", "dip" ], "description": "" }, "duration": { "type": "number", "description": "Edit seconds, the segment's own length." }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A dip's colour token; null is `frame`." }, "from": { "type": "array", "items": { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, "description": "The left clip's streams continuing past its out point, read from where its handle starts; empty for a dip with no handle." }, "speed": { "type": "number", "description": "The outgoing clip's own speed, at which `from` runs (C-16b: distinct from the segment's `speed`, the arriving clip's); absent is 1." } }, "required": [ "kind", "duration", "colour", "from" ], "additionalProperties": false }, { "type": "null" } ], "description": "The transition this segment is (C-16b): the join it starts, resolved — or null on a segment that is no transition, or one a dissolve could not read media for (the lint says). Absent when the sequence holds no transition." } }, "required": [ "at", "duration", "takeIn", "takeId", "clipId", "sources", "scene", "slide", "interstitial", "overlays", "caption", "chapter" ], "additionalProperties": false }, { "type": "null" } ], "description": "The segment holding `at`, its own `at`/`duration` in sequence seconds; null past the end or on an empty sequence." } }, "required": [ "seq", "sequenceId", "targetId", "at", "segment" ], "additionalProperties": false }, "SegmentsRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the list was computed from." }, "sequenceId": { "type": "string", "description": "The timeline the segments are of." }, "targetId": { "type": "string", "description": "The target they are composited for." }, "duration": { "type": "number", "description": "The sequence's length in edit seconds — the sum of the segments." }, "segments": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Edit seconds: where this segment starts in the finished file, and how long it runs." }, "duration": { "type": "number", "description": "Edit seconds the segment runs for." }, "takeIn": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Take seconds under the segment's start, or null over a gap." }, "takeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "clipId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The footage clip under the segment's start — the one `takeIn` maps through — or null over a gap (C-12 follow-up: the page finds the clip without a take-clock guess)." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, "description": "Every stream whose file covers this span, with where to read from. Empty over a gap." }, "scene": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The scene the cue named — a built-in's id or the project's." }, "name": { "type": "string", "description": "" }, "family": { "anyOf": [ { "type": "string", "enum": [ "full", "full-tight", "screen", "two-up", "pip", "over-shoulder" ] }, { "type": "null" } ], "description": "The family the panels were laid out from; null for a scene made from scratch." }, "knobs": { "anyOf": [ { "type": "object", "properties": { "gutter": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The one gutter, percent of frame width: 0 up to (not including) 50." }, "camWidth": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam column's width, percent of frame width: above 0, below 100." }, "stackSplit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The cam's share of the stack's height: a third to two thirds (`Layouts::clampSplit`'s range — a value outside it would render clamped)." }, "tightInset": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "How far `full-cam-tight` pushes in, percent: 0 up to (not including) 50." }, "sponsors": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the split reserves the sponsor panel." }, "pipCorner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where PiP's small picture sits: `top-left`, `top-right`, `bottom-left`, `bottom-right`." }, "pipSize": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How wide PiP's small picture is: `small`, `medium`, `large`." }, "shoulderSide": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Which shoulder the newscast box floats over: `left`, `right`." } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "The knobs the panels were laid out with, sponsors as it stood on this segment; null for a baked scene." }, "panels": { "type": "array", "items": { "type": "object", "properties": { "panelId": { "type": "string", "description": "The scene's panel id — what a cue's `mappings` and `mapPanel` key on." }, "name": { "type": "string", "description": "" }, "trackId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The track the panel resolved to, or null (empty, or a role no track fills)." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Percent of the frame." }, "transform": { "type": "object", "properties": { "x": { "type": "number", "description": "Percent of the rect's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the rect's height, downward.", "default": 0.0 }, "zoom": { "type": "number", "description": "1 = the picture as fitted; up to 8.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "The picture's translate and zoom inside the rect, after the clip's framing." }, "fit": { "type": "string", "enum": [ "cover", "contain" ], "description": "How a picture with no framing fits the rect." }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height." }, "border": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "The stroke's thickness, a percent of the frame's **width** (the one unit on both frames — a radius and a shadow are percents of the height); 0 up to 10." }, "colour": { "type": "string", "description": "A colour token (`frame`, `frame-ink`, `frame-card`, `accent`)." }, "style": { "type": "string", "enum": [ "solid", "dashed", "dotted" ], "description": "", "default": "solid" } }, "required": [ "width", "colour" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "shadow": { "anyOf": [ { "type": "object", "properties": { "blur": { "type": "number", "description": "Blur radius, percent of the frame's height; 0 to 20." }, "x": { "type": "number", "description": "Offset, percent of the frame's width, rightward.", "default": 0.0 }, "y": { "type": "number", "description": "Offset, percent of the frame's height, downward.", "default": 0.0 }, "colour": { "type": "string", "description": "A colour token.", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.5 } }, "required": [ "blur" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "alpha": { "type": "number", "description": "The panel's opacity, 0 to 1." }, "blur": { "type": "number", "description": "Backdrop blur, px." }, "source": { "anyOf": [ { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, { "type": "null" } ], "description": "A take stream in force on the panel's track at the segment's start, with the clip's framing for this target; null for a still or an empty panel." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A still's media key (a slide, an image clip); null for a stream, the sponsor carousel or an empty panel." }, "shows": { "type": "string", "enum": [ "stream", "image", "sponsors", "nothing" ], "description": "What the panel shows — what its bound track has in force: a stream, an image, the sponsor carousel, or nothing." }, "empty": { "anyOf": [ { "type": "string", "enum": [ "unbound", "no-camera", "no-screen", "not-drawable", "nothing-now" ] }, { "type": "null" } ], "description": "Why the panel shows nothing — `unbound`, `no-camera`, `no-screen`, `not-drawable`, `nothing-now`; null unless `shows` is `nothing`." }, "stream": { "anyOf": [ { "type": "string", "enum": [ "screen", "primary" ] }, { "type": "null" } ], "description": "Which of a take clip's streams the panel asked for (`screen`), while a take is one clip with several (pre-B4); null is the camera." } }, "required": [ "panelId", "name", "trackId", "rect", "transform", "fit", "radius", "border", "shadow", "alpha", "blur", "source", "src", "shows", "empty" ], "additionalProperties": false }, "description": "" }, "captions": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Captions show on this segment at all." }, "burnIn": { "type": "boolean", "description": "The export writes them into the picture; false is a sidecar, or none." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where a line sits, percent of the frame: the scene's placement resolved (`Placed::rect`, the caption-safe box), or the default style's band." }, "look": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "", "default": "sans" }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "", "default": "medium" }, "tracking": { "type": "number", "description": "Letter spacing, percent of the em; -20 to 50.", "default": 0.0 }, "leading": { "type": "number", "description": "Line height as a multiple of the size; 0.8 to 2.", "default": 1.2 }, "colour": { "type": "string", "description": "The text's colour token.", "default": "frame-ink" }, "stroke": { "anyOf": [ { "type": "object", "properties": { "width": { "type": "number", "description": "Percent of the frame's height; 0 to 2." }, "colour": { "type": "string", "description": "", "default": "frame" } }, "required": [ "width" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "background": { "anyOf": [ { "type": "object", "properties": { "colour": { "type": "string", "description": "", "default": "frame" }, "opacity": { "type": "number", "description": "0 to 1.", "default": 0.62 }, "radius": { "type": "number", "description": "Corner radius, percent of the frame's height; 0 to 10. Stored and returned as set, but not drawn yet: the reference renderer squares the box (libass has no rounded box), and so does the app's preview. Drawing it is RADIUS-2.", "default": 0.0 } }, "required": [], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "padding": { "type": "number", "description": "Inside the background, percent of the frame's height; 0 to 10.", "default": 1.0 } }, "required": [], "additionalProperties": false, "description": "" }, "own": { "type": "boolean", "description": "True when the scene set these; false when the timeline's default style stands in." } }, "required": [ "enabled", "burnIn", "rect", "look", "own" ], "additionalProperties": false, "description": "The segment's captions, resolved for the target: the scene's own, else the timeline's default style translated (C-22b)." } }, "required": [ "sceneId", "name", "family", "knobs", "panels", "captions" ], "additionalProperties": false, "description": "" }, "slide": { "anyOf": [ { "type": "object", "properties": { "slide": { "type": "integer", "description": "" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" } }, "required": [ "slide", "name", "src" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "interstitial": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bumper", "sting", "quote", "exhibit" ], "description": "" }, "title": { "type": "string", "description": "" }, "body": { "type": "string", "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "audible": { "type": "boolean", "description": "Whether the card's sound is still on: false during its picture tail, and for cards with no sound." }, "elapsed": { "type": "number", "description": "Edit seconds since the card began, for a typewriter or a sting that is mid-way." } }, "required": [ "kind", "title", "body", "src", "audible", "elapsed" ], "additionalProperties": false }, { "type": "null" } ], "description": "The topmost card over the frame, or null." }, "overlays": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string", "description": "" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, "description": "" }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "A still's crop and pan over this segment (C-11); a cutaway's rides its `sources`. Absent when the clip has none for the target." }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where a placed still sits, percent of the frame (C-16); absent draws full-frame, as before." }, "opacity": { "type": "number", "description": "How opaque, 0 to 1 (C-16); absent is 1, as before." }, "fadeIn": { "type": "number", "description": "Seconds from the clip's first frame over which it fades in from what is beneath (C-16b: an overlay-track clip's transition, clamped to the clip); present only on a segment that starts inside the fade, with `elapsed`." }, "elapsed": { "type": "number", "description": "Seconds since the clip began at the segment's start — where in the fade it stands; present with `fadeIn`." } }, "required": [ "clipId", "sources", "src" ], "additionalProperties": false }, "description": "Every cutaway or placed still with picture in force below any card, topmost first (C-16: the single `overlay` became this list). Empty over nothing." }, "caption": { "anyOf": [ { "type": "object", "properties": { "clipId": { "type": "string", "description": "" }, "src": { "type": "string", "description": "" }, "clock": { "type": "string", "enum": [ "take", "edit" ], "description": "" }, "fileTime": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Where the captions file reads at the segment's start: take seconds when `clock` is `take` (the file is timed to the take), file seconds when it is `edit`; null when no take second is under the start." } }, "required": [ "clipId", "src", "clock", "fileTime" ], "additionalProperties": false }, { "type": "null" } ], "description": "" }, "chapter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "" }, "audio": { "type": "object", "properties": { "mix": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string", "description": "The clip that sounds." }, "streamId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A footage clip's stream — the plan's carrier — or the stream an audio track's take clip sounds; null for a bed." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A bed's file (its `source.src`), or an audio track's take stream's file — either read on its own clock, at 1×; null for the footage's carrier." }, "fileTime": { "type": "number", "description": "Seconds into the file at the segment's start." }, "gain": { "type": "number", "description": "The level at the segment's start, in dB: the track's gain, the clip's, its keyframes, fades and ducking summed." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Plan seconds (the plan's own clock, as `segments[].at`)." }, "gain": { "type": "number", "description": "The level in dB from here, linear to the next point." } }, "required": [ "at", "gain" ], "additionalProperties": false }, "description": "The levels that change inside the segment, on the plan's clock — one on the first frame is `gain`, one on the last belongs to the next segment." }, "rate": { "type": "number", "description": "How fast an audio track's take stream plays — its clip's speed, present only when not 1× (B3b: a sped linked pair; the pitch as `audio.preservePitch`). Absent: 1×." } }, "required": [ "clipId", "streamId", "src", "fileTime", "gain", "keyframes" ], "additionalProperties": false }, "description": "" } }, "required": [ "mix" ], "additionalProperties": false, "description": "What sounds and how loud (C-15); absent when the document sets no audio on the sequence — `plan.audio.carrier` alone plays, as before." }, "titles": { "type": "array", "items": { "type": "object", "properties": { "clipId": { "type": "string", "description": "" }, "template": { "type": "string", "enum": [ "lower-third", "full-frame", "tag" ], "description": "" }, "fields": { "type": "object", "properties": { "title": { "type": "string", "description": "The first line: the name, the headline.", "default": "" }, "subtitle": { "type": "string", "description": "The second line under it: the role, the strapline; a tag never shows it.", "default": "" } }, "required": [], "additionalProperties": false, "description": "" }, "style": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "The face by role: `display` (Fraunces), `sans` (Instrument Sans), `mono` (IBM Plex Mono)." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "The line height: small, medium or large." }, "ink": { "type": "string", "description": "The text's colour, a token name (`frame-ink`, `frame`, `frame-card`, `accent`)." }, "panel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The box's fill, a token name, or null for none." } }, "required": [ "font", "size", "ink", "panel" ], "additionalProperties": false, "description": "" }, "rect": { "type": "object", "properties": { "x": { "type": "number", "description": "" }, "y": { "type": "number", "description": "" }, "w": { "type": "number", "description": "" }, "h": { "type": "number", "description": "" } }, "required": [ "x", "y", "w", "h" ], "additionalProperties": false, "description": "Where it sits, percent of the frame, inside the target's title-safe box unless the lint says otherwise." }, "panelAlpha": { "type": "number", "description": "The panel's opacity, the template's." }, "elapsed": { "type": "number", "description": "Edit seconds since the title began, rounded to six decimals (a card's `elapsed`)." } }, "required": [ "clipId", "template", "fields", "style", "rect", "panelAlpha", "elapsed" ], "additionalProperties": false }, "description": "Every title with picture in force, topmost first, its rect resolved for this target (C-16); absent when the sequence holds no title." }, "speed": { "type": "number", "description": "The footage's constant speed over this segment (C-16b): the take runs this many times as fast as the edit; absent is 1." }, "transition": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dissolve", "dip" ], "description": "" }, "duration": { "type": "number", "description": "Edit seconds, the segment's own length." }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A dip's colour token; null is `frame`." }, "from": { "type": "array", "items": { "type": "object", "properties": { "streamId": { "type": "string", "description": "" }, "file": { "type": "string", "description": "" }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "" }, "fileTime": { "type": "number", "description": "File seconds: how far into `file` the segment's start reads." }, "muted": { "type": "boolean", "description": "" }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "" }, "framing": { "type": "object", "properties": { "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred at the segment's start." }, "scale": { "type": "number", "description": "How far it is pushed in at the segment's start (1 = the whole source)." }, "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "The keyframes inside the segment, `at` on the plan's clock (seconds into the finished file)." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from the segment's start to the first keyframe inside it — the clip keyframe before the segment's ease, as the stage plays it: `linear` runs, `hold` stands (and stands when no keyframe is inside)." } }, "required": [ "focus", "scale", "keyframes", "ease" ], "additionalProperties": false, "description": "The crop and pan over this segment (C-11); absent when the clip has no framing for the target — `focus`, no punch-in." } }, "required": [ "streamId", "file", "role", "fileTime", "muted", "focus" ], "additionalProperties": false }, "description": "The left clip's streams continuing past its out point, read from where its handle starts; empty for a dip with no handle." }, "speed": { "type": "number", "description": "The outgoing clip's own speed, at which `from` runs (C-16b: distinct from the segment's `speed`, the arriving clip's); absent is 1." } }, "required": [ "kind", "duration", "colour", "from" ], "additionalProperties": false }, { "type": "null" } ], "description": "The transition this segment is (C-16b): the join it starts, resolved — or null on a segment that is no transition, or one a dissolve could not read media for (the lint says). Absent when the sequence holds no transition." } }, "required": [ "at", "duration", "takeIn", "takeId", "clipId", "sources", "scene", "slide", "interstitial", "overlays", "caption", "chapter" ], "additionalProperties": false }, "description": "Contiguous, gapless, in order, `at` in sequence seconds; empty on an empty sequence." } }, "required": [ "seq", "sequenceId", "targetId", "duration", "segments" ], "additionalProperties": false }, "SetCaptionsClockArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The captions clip to change." }, "clock": { "type": "string", "enum": [ "take", "edit" ], "description": "`take`: cues are on the take's clock and `in` is unused; `edit`: cues are on the edit's clock from `in`." } }, "required": [ "sequenceId", "clipId", "clock" ], "additionalProperties": false }, "SetChapterFlagsArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "chapterId": { "type": "string", "description": "The chapter whose flags change." }, "flags": { "type": "array", "items": { "type": "string" }, "description": "Replacement export flags; an empty list clears them." } }, "required": [ "takeId", "chapterId", "flags" ], "additionalProperties": false }, "SetClipAudioArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The footage or bed clip." }, "audio": { "type": "object", "properties": { "gain": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The clip's level in dB, −96 to +20." }, "fadeIn": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Seconds of fade from silence at the clip's start; 0 for none." }, "fadeOut": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Seconds of fade to silence at the clip's end; 0 for none." } }, "required": [], "additionalProperties": false, "description": "The level and the fades to set; what is absent stays." } }, "required": [ "sequenceId", "clipId", "audio" ], "additionalProperties": false }, "SetClipCardArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The card clip to change." }, "patch": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bumper", "sting", "quote", "exhibit" ], "description": "Bumper, sting, quote or exhibit." }, "title": { "type": "string", "description": "The card's heading, or the chapter name for a bumper." }, "body": { "type": "string", "description": "The quote text, the bumper's console line, the exhibit stem." }, "src": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A media key or URL for an exhibit; null clears it." }, "chapterId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The chapter a bumper opens; null clears it. Must name a chapter the document has." } }, "required": [], "additionalProperties": false, "description": "The card fields to change; the rest stay." } }, "required": [ "sequenceId", "clipId", "patch" ], "additionalProperties": false }, "SetClipLabelArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The clip to name." }, "label": { "type": "string", "description": "What the timeline prints; may be empty." } }, "required": [ "sequenceId", "clipId", "label" ], "additionalProperties": false }, "SetClipOpacityArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The still." }, "opacity": { "type": "number", "description": "0 (invisible) to 1 (opaque)." } }, "required": [ "sequenceId", "clipId", "opacity" ], "additionalProperties": false }, "SetClipPlacementArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The title or still." }, "targetId": { "type": "string", "description": "The target the placement is for." }, "placement": { "anyOf": [ { "type": "object", "properties": { "anchor": { "type": "string", "enum": [ "top-left", "top", "top-right", "left", "centre", "right", "bottom-left", "bottom", "bottom-right" ], "description": "The point of the target's title-safe box the box hangs from." }, "x": { "type": "number", "description": "Percent of the frame's width the box's anchor point moves from the safe box's — rightward from a left edge, leftward from a right edge, from the centreline otherwise (positive rightward).", "default": 0.0 }, "y": { "type": "number", "description": "Percent of the frame's height, likewise — downward from a top edge, upward from a bottom edge, from the centreline otherwise (positive downward).", "default": 0.0 }, "w": { "type": "number", "description": "The box's width, percent of the frame's width: 1 to 100.", "default": 60.0 } }, "required": [ "anchor" ], "additionalProperties": false }, { "type": "null" } ], "description": "Where it sits on that target — the anchor, the offsets, the width — or null for the default (a title's template's; a still full-frame)." } }, "required": [ "sequenceId", "clipId", "targetId", "placement" ], "additionalProperties": false }, "SetClipSpeedArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The footage clip." }, "speed": { "type": "number", "description": "How many times as fast as the edit the take runs: 0.25 to 4; 1 is real time." } }, "required": [ "sequenceId", "clipId", "speed" ], "additionalProperties": false }, "SetClipStreamsArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The take clip to change." }, "streamIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The streams of the clip's take it plays; null = every stream (the automatic group), `[]` = none." } }, "required": [ "sequenceId", "clipId", "streamIds" ], "additionalProperties": false }, "SetClipTargetsArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The clip to change." }, "targets": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The targets the clip serves, by id; null for every target. An id the document lacks is `unknownId` at `targets`." } }, "required": [ "sequenceId", "clipId", "targets" ], "additionalProperties": false }, "SetClipTitleArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The title clip." }, "patch": { "type": "object", "properties": { "template": { "type": "string", "enum": [ "lower-third", "full-frame", "tag" ], "description": "lower-third, full-frame or tag." }, "fields": { "type": "object", "properties": { "title": { "type": "string", "description": "The first line." }, "subtitle": { "type": "string", "description": "The second line; a tag never shows it." } }, "required": [], "additionalProperties": false, "description": "The lines to change." }, "style": { "type": "object", "properties": { "font": { "type": "string", "enum": [ "display", "sans", "mono" ], "description": "The face by role: display, sans or mono." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "small, medium or large." }, "ink": { "type": "string", "description": "The text's colour token: frame-ink, frame, frame-card or accent." }, "panel": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The panel's colour token, or null for no panel." } }, "required": [], "additionalProperties": false, "description": "The style fields to change." } }, "required": [], "additionalProperties": false, "description": "What changes; the rest stays." } }, "required": [ "sequenceId", "clipId", "patch" ], "additionalProperties": false }, "SetFocusArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The stream whose focus point moves." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "The point, as fractions of the frame; clamped into it." } }, "required": [ "takeId", "streamId", "focus" ], "additionalProperties": false }, "SetFramingArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The footage or image clip to frame." }, "targetId": { "type": "string", "description": "The target the framing is for." }, "framing": { "type": "object", "properties": { "keyframes": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "description": "Clip seconds: 0 is the clip's first frame. Frame-aligned at the sequence's fps." }, "focus": { "type": "object", "properties": { "x": { "type": "number", "description": "Fraction of the frame's width, 0 at the left edge." }, "y": { "type": "number", "description": "Fraction of the frame's height, 0 at the top." } }, "required": [ "x", "y" ], "additionalProperties": false, "description": "Where the window is centred, as fractions of the source's width and height." }, "scale": { "type": "number", "description": "How far the window is pushed in: 1 is the whole source, 2 half its width and height. Never below 1." }, "ease": { "type": "string", "enum": [ "linear", "hold" ], "description": "How the value runs from here to the next keyframe." } }, "required": [ "at", "focus", "scale", "ease" ], "additionalProperties": false }, "description": "At least one; sorted by `at`, unique per `at`." } }, "required": [ "keyframes" ], "additionalProperties": false, "description": "The framing: at least one keyframe." } }, "required": [ "sequenceId", "clipId", "targetId", "framing" ], "additionalProperties": false }, "SetMediaRootsArgs": { "type": "object", "properties": { "roots": { "type": "array", "items": { "type": "string" }, "description": "Absolute folders the media walk reads after the project's own, in this order; `[]` clears them. A folder that is not there is `invalidArgs` at `roots[i]`." } }, "required": [ "roots" ], "additionalProperties": false }, "SetPictureTailArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The overlay clip whose picture holds past its sound." }, "seconds": { "type": "number", "description": "Seconds the picture runs past `duration`; negative reads as 0." } }, "required": [ "sequenceId", "clipId", "seconds" ], "additionalProperties": false }, "SetPresetEnabledArgs": { "type": "object", "properties": { "presetId": { "type": "string", "description": "The preset to turn on or off." }, "enabled": { "type": "boolean", "description": "On: the preset renders; off: it stays on the list and renders nothing." } }, "required": [ "presetId", "enabled" ], "additionalProperties": false }, "SetPrimaryArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The video stream that drives the clock from now on." } }, "required": [ "takeId", "streamId" ], "additionalProperties": false }, "SetSceneArgs": { "type": "object", "properties": { "targetId": { "type": "string", "description": "The target whose scenes track: its id (`16:9`). An unknown id is `unknownId` at `targetId`." }, "at": { "type": "number", "description": "Edit seconds the scene starts at; a placement on the same frame is replaced." }, "sceneId": { "type": "string", "description": "The scene from here: a built-in's id (`split`, `pip-bottom-right-small`) or a project scene's (`sc1`). Unknown: `unknownId` at `sceneId`; a scene laid out for another frame: `aspect`." }, "sequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline; null = the first. An unknown id is `unknownId` at `sequenceId`." }, "mappings": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The placement's own tracks for the scene's panels, panel id → track id of the timeline (Full Cam and Full Screen are one scene mapped differently); absent = the scene's own." } }, "required": [ "targetId", "at", "sceneId" ], "additionalProperties": false }, "SetSceneCaptionsArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The project scene." }, "captions": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "The scene's captions (the `SceneCaptions` shape, schemas.md), or null for the timeline's default: shown, burnt in." } }, "required": [ "sceneId", "captions" ], "additionalProperties": false }, "SetScenePlacementArgs": { "type": "object", "properties": { "placementId": { "type": "string", "description": "The placement (`pl3`). Unknown: `unknownId` at `placementId`." }, "sceneId": { "type": "string", "description": "The scene from here: a built-in's id or a project scene's. Unknown: `unknownId` at `sceneId`; a scene laid out for another frame: `aspect`." }, "sequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline to look on; null = any (placement ids are the document's). An unknown id is `unknownId` at `sequenceId`." }, "mappings": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The placement's own tracks for the scene's panels, panel id → track id of its timeline; absent = keep the placement's, `{}` clears them." } }, "required": [ "placementId", "sceneId" ], "additionalProperties": false }, "SetSessionArgs": { "type": "object", "properties": { "playhead": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Playhead, edit seconds." }, "zoom": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Timeline zoom, pixels per second." }, "activeSequenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timeline the page shows; null = the document's `activeSequenceId` (the default for every op that takes a sequence). View state, not history: the spike's `setActiveSequence` is this field, never a document op. Not checked against the document — a view is never refused; the page falls back when the id is gone." }, "activeTargetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The target the stage shows; null = the page's own default (the first enabled one). View state, not history (U-04a1, C-10b): not checked against the document — the page falls back when the id is gone." } }, "required": [], "additionalProperties": false }, "SetStreamArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The stream being patched." }, "patch": { "type": "object", "properties": { "offset": { "type": "number", "description": "Where the file's first frame sits, in take seconds." }, "muted": { "type": "boolean", "description": "Whether the stream's sound is off." }, "width": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The file's frame width in pixels, or null for a stream with no picture (what `probeMedia` learns)." }, "height": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The file's frame height in pixels, or null for a stream with no picture." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The file's frame rate, or null when unknown (`30000/1001` is `29.97…`)." }, "codec": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The codec of the stream's own medium as `ffprobe` names it (`hevc`, `aac`…), or null when unknown (U-13e; what `probeMedia` learns)." }, "probe": { "type": "object", "properties": { "fps": { "anyOf": [ { "type": "object", "properties": { "num": { "type": "integer", "description": "The numerator." }, "den": { "type": "integer", "description": "The denominator, never 0." } }, "required": [ "num", "den" ], "additionalProperties": false }, { "type": "null" } ], "description": "The frame rate as a ratio, exact; null for a file with no picture." }, "timecode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The timecode the file carries (`10:00:00:00`), or null." }, "channels": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's channel count, or null without sound." }, "sampleRate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The sound's sample rate in Hz, or null without sound." }, "container": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ffprobe's container name, or null." }, "bytes": { "type": "integer", "description": "The file's size in bytes when probed." }, "sha256Prefix": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA-256 of the file's first MiB, hex — the signature; null when the file could not be hashed." } }, "required": [ "fps", "timecode", "channels", "sampleRate", "container", "bytes", "sha256Prefix" ], "additionalProperties": false, "description": "The probe block — the exact frame rate, timecode, channels, sample rate, container, the file's signature (C-17; what `probeMedia` learns)." }, "proxy": { "anyOf": [ { "type": "object", "properties": { "path": { "type": "string", "description": "The proxy file, relative to the project's folder." }, "preset": { "type": "string", "description": "The preset it was made at: `720p`, `1080p`." } }, "required": [ "path", "preset" ], "additionalProperties": false }, { "type": "null" } ], "description": "The finished proxy — its path beside the project and its preset (C-17b; what `proxy:run` records when a transcode ends); null removes it." } }, "required": [], "additionalProperties": false, "description": "The keys to set; a key left out is left alone." } }, "required": [ "takeId", "streamId", "patch" ], "additionalProperties": false }, "SetStreamDurationArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the edited item." }, "streamId": { "type": "string", "description": "The stream whose file length was read." }, "duration": { "type": "number", "description": "File seconds: the file's length; a negative length is stored as unknown." } }, "required": [ "takeId", "streamId", "duration" ], "additionalProperties": false }, "SetStreamFileArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The stream whose file moves." }, "file": { "type": "string", "description": "The file, relative to the project's folder or a media root (never absolute); the take's own `folder` no longer applies to it." } }, "required": [ "takeId", "streamId", "file" ], "additionalProperties": false }, "SetStreamOffsetArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The stream being slipped." }, "offset": { "type": "number", "description": "Where the file's first frame sits, in take seconds; replaces the current offset." } }, "required": [ "takeId", "streamId", "offset" ], "additionalProperties": false }, "SetStreamRoleArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The stream whose role changes." }, "role": { "type": "string", "enum": [ "cam", "cam-b", "screen", "mic", "system", "other" ], "description": "What the file is for." } }, "required": [ "takeId", "streamId", "role" ], "additionalProperties": false }, "SetTargetEnabledArgs": { "type": "object", "properties": { "targetId": { "type": "string", "description": "The target. An unknown id is `unknownId` at `targetId`." }, "enabled": { "type": "boolean", "description": "In the plans, or kept with its cues and out of them." } }, "required": [ "targetId", "enabled" ], "additionalProperties": false }, "SetTrackArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the track is in." }, "trackId": { "type": "string", "description": "The track to change." }, "patch": { "type": "object", "properties": { "name": { "type": "string", "description": "What the track is called." }, "muted": { "type": "boolean", "description": "Heard or not; a muted track still shows." }, "locked": { "type": "boolean", "description": "Locked: ripples pass the track by and nothing is placed on it." }, "groupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The group the track folds into; null leaves its group. Must name a group the sequence has." } }, "required": [], "additionalProperties": false, "description": "The track fields to change; the rest stay." } }, "required": [ "sequenceId", "trackId", "patch" ], "additionalProperties": false }, "SetTrackAudioArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the track is in." }, "trackId": { "type": "string", "description": "The track." }, "audio": { "type": "object", "properties": { "gain": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The track's level in dB, −96 to +20, added to each clip's." }, "solo": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Solo: while any track is soloed, only soloed tracks are heard." } }, "required": [], "additionalProperties": false, "description": "The level and the solo to set; what is absent stays." } }, "required": [ "sequenceId", "trackId", "audio" ], "additionalProperties": false }, "SetTrackDuckingArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the track is in." }, "trackId": { "type": "string", "description": "The track that gives way." }, "duck": { "anyOf": [ { "type": "object", "properties": { "under": { "type": "string", "description": "`speech`, or the id of an audio track on the same sequence." }, "by": { "type": "number", "description": "How far the level drops while `under` sounds, in dB: negative, never 0." }, "attack": { "type": "number", "description": "Seconds the level takes to reach `by`, ending as `under` starts." }, "release": { "type": "number", "description": "Seconds the level takes to come back, starting as `under` ends." } }, "required": [ "under", "by", "attack", "release" ], "additionalProperties": false }, { "type": "null" } ], "description": "How it ducks — `under` is `speech` or another audio track's id, `by` dB below 0, `attack` and `release` seconds — or null to stop ducking." } }, "required": [ "sequenceId", "trackId", "duck" ], "additionalProperties": false }, "SetTransitionArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The clip that starts the join: it owns how it arrives." }, "transition": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "dissolve", "dip" ], "description": "dissolve, or dip." }, "duration": { "type": "number", "description": "Edit seconds the transition runs, from the clip's first frame, frame-aligned: 0.1 to 5." }, "colour": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A dip's colour, a token name (`frame`, `frame-ink`, `frame-card`, `accent`); null is `frame`." } }, "required": [ "kind", "duration" ], "additionalProperties": false }, { "type": "null" } ], "description": "A dissolve or a dip with its length (0.1–5 s) and a dip's colour token — or null for a cut." } }, "required": [ "sequenceId", "clipId", "transition" ], "additionalProperties": false }, "SlipClipArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The take clip whose footage slides." }, "delta": { "type": "number", "description": "Take seconds to move the source by; positive shows later footage. Clamped to the file." } }, "required": [ "sequenceId", "clipId", "delta" ], "additionalProperties": false }, "Status": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "valid", "trial", "expired-upgrades", "invalid", "none" ], "description": "`valid`, `trial`, `expired-upgrades`, `invalid` or `none`." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why `invalid`: `bad-signature`, `unknown-key`, `wrong-product`, `bad-format`, `revoked` or `no-keyring`; null otherwise." }, "edits": { "type": "boolean", "description": "Whether document edits go through in this state." }, "daysLeft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Whole days of trial left while `trial`; null otherwise." }, "upgradesUntil": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The licence's `upgrades_until` (`Y-m-d`) when a token verifies; null otherwise." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The licence's e-mail when a token verifies; null otherwise." }, "seats": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The licence's seat count when a token verifies; null otherwise." }, "releasedAt": { "type": "string", "description": "This build's release date (`Y-m-d`), what `upgradesUntil` is measured against." }, "machineId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The hash the site knows this machine by; null where no machine id can be derived (not macOS)." }, "activation": { "anyOf": [ { "type": "object", "properties": { "used": { "type": "integer", "description": "Seats in use across the licence's machines, this one included." }, "limit": { "type": "integer", "description": "The licence's seat limit." }, "activatedAt": { "type": "string", "description": "ISO-8601, when this machine's activation was recorded." } }, "required": [ "used", "limit", "activatedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "What the last successful activation said; null before one, or after a deactivation." }, "lastPingAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO-8601, when the site was last asked; null before the first ping." }, "lastPingError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the last ping did not activate: a transport failure, `seats-exceeded`, `revoked`, `invalid`, `machine-id-unavailable`; null when it did." }, "unreadable": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Set when the licence record could not be read (the app's database is missing it or refused): the line to show; the state then reads as a full trial, never an error. Null normally." } }, "required": [ "state", "reason", "edits", "daysLeft", "upgradesUntil", "email", "seats", "releasedAt", "machineId", "activation", "lastPingAt", "lastPingError" ], "additionalProperties": false }, "StopScreencastArgs": { "type": "object", "properties": { "take": { "type": "string", "description": "The take id `recordScreencast` answered in `created`." } }, "required": [ "take" ], "additionalProperties": false }, "StraightenFootageArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence whose footage track is pulled straight." } }, "required": [ "sequenceId" ], "additionalProperties": false }, "SuggestionsRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the suggestions were computed from." }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Names the suggestion, not its place in the list: the kind and the markers it was read from (`pickup:m2+m3`, `jitter:m5#2`)." }, "kind": { "type": "string", "enum": [ "pickup", "omit", "jitter" ], "description": "`pickup` (an abandoned read to drop and the chapter walked to the keeper), `omit` (a span marked for the cut at the desk) or `jitter` (doubled markers to delete)." }, "in": { "type": "number", "description": "Take seconds the span starts. For jitter, and for a note that asks for a blade, `in === out`." }, "out": { "type": "number", "description": "Take seconds the span ends." }, "reason": { "type": "string", "description": "One line a card can print: what was seen and why it means this." }, "markerIds": { "type": "array", "items": { "type": "string" }, "description": "The markers that said so. Applying a jitter suggestion removes these." } }, "required": [ "id", "kind", "in", "out", "reason", "markerIds" ], "additionalProperties": false }, "description": "The take's pickups, omits and jitter, sorted by `in` then `out`; each with a stable id a client applies or dismisses by." } }, "required": [ "seq", "suggestions" ], "additionalProperties": false }, "TextRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the text was computed from." }, "text": { "type": "string", "description": "The text with no trailing newline — the CSV as `markers..csv` holds it; the chapter list as `chapters.txt` holds it less its final newline." } }, "required": [ "seq", "text" ], "additionalProperties": false }, "ToggleMutedArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take that owns the stream." }, "streamId": { "type": "string", "description": "The stream whose sound flips." } }, "required": [ "takeId", "streamId" ], "additionalProperties": false }, "TracksRead": { "type": "object", "properties": { "seq": { "type": "integer", "description": "The envelope seq the list was read at." }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The timeline the track is on." }, "id": { "type": "string", "description": "The immutable id every op takes (`V1`, `A2` …): never changes on a rename, never reused." }, "label": { "type": "string", "description": "Its label, the user's convenience: what a person calls it." }, "medium": { "type": "string", "enum": [ "video", "audio" ], "description": "`video` or `audio`." }, "groupId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The group it is linked in (a derived take's picture and sound), or null." }, "roles": { "type": "array", "items": { "type": "string" }, "description": "What a scene's panel or the derivation finds it by, when anything does (`footage` — the camera, `slides`, `mic` …); empty otherwise." }, "drawable": { "type": "boolean", "description": "Whether a scene's panel can show this track: a picture track whose clips are all takes or stills (none is fine — bind it, then add media), and not a card or captions track. What a panel picker offers." } }, "required": [ "sequenceId", "id", "label", "medium", "groupId", "roles", "drawable" ], "additionalProperties": false }, "description": "The tracks." } }, "required": [ "seq", "tracks" ], "additionalProperties": false }, "TrimClipArgs": { "type": "object", "properties": { "sequenceId": { "type": "string", "description": "The sequence the clip is in." }, "clipId": { "type": "string", "description": "The clip whose edge moves." }, "edge": { "type": "string", "enum": [ "in", "out" ], "description": "Which edge: `in` slides the source, `out` changes the length." }, "at": { "type": "number", "description": "Edit seconds the edge should land on; clamped to what the track and the file allow." }, "options": { "type": "object", "properties": { "ripple": { "type": "boolean", "description": "On the out edge: move what follows on every unlocked track by the change.", "default": false }, "overwrite": { "type": "boolean", "description": "The ⌘-trim: eat into the neighbours instead of stopping at them.", "default": false } }, "required": [], "additionalProperties": false, "description": "Ripple what follows an out trim, or carve the neighbours.", "default": { "ripple": false, "overwrite": false } } }, "required": [ "sequenceId", "clipId", "edge", "at" ], "additionalProperties": false }, "UpdateExportPresetArgs": { "type": "object", "properties": { "presetId": { "type": "string", "description": "The preset to change." }, "patch": { "type": "object", "properties": { "name": { "type": "string", "description": "What the Exports card calls it." }, "container": { "type": "string", "enum": [ "mp4", "mov", "webm" ], "description": "The file: mp4, mov or webm." }, "codec": { "type": "string", "enum": [ "h264", "hevc", "prores", "vp9", "av1" ], "description": "The video codec." }, "resolution": { "type": "object", "properties": { "w": { "type": "integer", "description": "Width in pixels." }, "h": { "type": "integer", "description": "Height in pixels." } }, "required": [ "w", "h" ], "additionalProperties": false, "description": "The frame in pixels." }, "fps": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "null renders at the sequence's rate." }, "quality": { "type": "object", "properties": { "crf": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Constant rate factor (lower is better; 18 is visually lossless for h264); null when `bitrate` rules." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Target bitrate in kbit/s; null when `crf` rules." } }, "required": [], "additionalProperties": false, "description": "Exactly one of `crf` and `bitrate`." }, "audio": { "type": "object", "properties": { "codec": { "type": "string", "enum": [ "aac", "pcm", "opus" ], "description": "aac, pcm or opus." }, "bitrate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "kbit/s; null for a codec that has no rate (pcm) or the encoder's default." } }, "required": [ "codec", "bitrate" ], "additionalProperties": false, "description": "The sound: codec and bitrate." }, "perChapter": { "type": "boolean", "description": "One file per chapter rather than one for the whole edit." }, "chapterFilter": { "type": "string", "enum": [ "all", "short" ], "description": "Which chapters a per-chapter preset renders: all, or the `short` ones." }, "enabled": { "type": "boolean", "description": "A disabled preset renders nothing and stays on the list." }, "naming": { "type": "string", "description": "The file-name template (`{take}`, `{sequence}`, `{chapter}`, `{target}`, `{preset}`)." } }, "required": [], "additionalProperties": false, "description": "The fields to change; one left out is unchanged." } }, "required": [ "presetId", "patch" ], "additionalProperties": false }, "UpdatePanelArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The baked project scene." }, "panelId": { "type": "string", "description": "The panel to change." }, "patch": { "type": "object", "additionalProperties": true, "description": "The fields to change, as the `Panel` shape spells them; one left out is unchanged." } }, "required": [ "sceneId", "panelId", "patch" ], "additionalProperties": false }, "UpdateSceneArgs": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "The project scene to change." }, "patch": { "type": "object", "additionalProperties": true, "description": "The fields to change — `name`, `knobs`, `captions` — as the `Scene` shape spells them; one left out is unchanged." } }, "required": [ "sceneId", "patch" ], "additionalProperties": false }, "WithCaptionsArgs": { "type": "object", "properties": { "style": { "type": "object", "properties": { "position": { "type": "string", "enum": [ "bottom", "top", "custom" ], "description": "Where the line sits: `bottom`, `top`, or `custom` (then `y`)." }, "y": { "type": "number", "description": "The line's vertical centre as a fraction of the frame, for `custom`; kept inert otherwise." }, "size": { "type": "string", "enum": [ "small", "medium", "large" ], "description": "The type size: `small`, `medium`, `large`." }, "box": { "type": "string", "enum": [ "pill", "band", "none" ], "description": "The backing behind the line: `pill`, `band`, `none`." }, "font": { "type": "string", "enum": [ "sans", "serif", "mono" ], "description": "The face: `sans`, `serif`, `mono`." }, "safe": { "type": "boolean", "description": "Keep the line inside the title-safe area." } }, "required": [], "additionalProperties": false, "description": "The keys to set; a key left out is left alone." } }, "required": [ "style" ], "additionalProperties": false }, "WithSceneArgs": { "type": "object", "properties": { "scene": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "The scene document as the scene editor exported it, or null to detach. The scene editor owns its shape (`Scene`)." } }, "required": [ "scene" ], "additionalProperties": false }, "WithTakeDurationArgs": { "type": "object", "properties": { "takeId": { "type": "string", "description": "The take whose length was read." }, "duration": { "type": "number", "description": "Take seconds; a negative length is stored as 0." } }, "required": [ "takeId", "duration" ], "additionalProperties": false }, "WriteOutputsArgs": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }