{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/cueframe-ai/json-schema/cueframe-ai-composition-apply-request-schema.json", "title": "CompositionApplyRequest", "description": "POST /projects/:id/composition/apply body — a batch of CompositionOps.", "x-generated": "2026-11-10", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/cueframe-ai-compositions-api-openapi.yml#/components/schemas/CompositionApplyRequest", "type": "object", "properties": { "ops": { "minItems": 1, "type": "array", "items": { "$ref": "#/$defs/CompositionOp" } }, "componentExecutionVersions": { "anyOf": [ { "type": "array", "prefixItems": [ { "type": "number", "const": 3 } ], "items": false, "minItems": 1, "maxItems": 1 }, { "type": "array", "prefixItems": [ { "type": "number", "const": 3 }, { "type": "number", "const": 4 } ], "items": false, "minItems": 2, "maxItems": 2 } ] }, "builtinSources": { "minItems": 1, "maxItems": 512, "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "object", "properties": { "kind": { "type": "string", "const": "builtin" }, "collection": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "kind", "collection" ], "additionalProperties": false }, "componentId": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sourceVersion": { "anyOf": [ { "type": "number", "const": 3 }, { "type": "number", "const": 4 } ] } }, "required": [ "scope", "componentId", "sourceVersionId", "sourceVersion" ], "additionalProperties": false } }, "expectedBrandIdentity": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "concurrency": { "description": "Version 1 shared dependency admission. Guarded requests must name the observed immutable composition with composition_id or concurrency.compositionId; changed or missing dependencies refuse the entire batch.", "$ref": "#/$defs/CompositionConcurrency" }, "if_match": { "description": "OCC precondition: the strong etag (`\"\"`) the caller last saw. Required unless `concurrency` is sent or `dry_run` is true; a write with neither is refused with 428 precondition_required. On mismatch the batch is rejected (409 stale_etag) before any op applies.", "type": "string" }, "dry_run": { "description": "When true, validate the batch (apply + projection accept/reject guards) WITHOUT persisting. Returns `{ valid, errors }` instead of applying.", "type": "boolean" }, "composition_id": { "description": "Target a SPECIFIC composition instead of the project's active one. Omit it and the project's active composition is edited, which is the default and the common case. `preview_frame` and `create_render` already accept a compositionId; this closes the gap so a second composition minted with `new_composition` can actually be authored into — build variant A, mint B, edit B, preview both. Mutually exclusive with `session_id`, which targets the session's scratch.", "type": "string" }, "session_id": { "description": "Optional compose-session id. When present, the ops target the session's SCRATCH composition (a derived sibling) instead of the project's active composition — the server never mutates active until commit.", "type": "string" } }, "required": [ "ops" ], "additionalProperties": false, "$defs": { "ComponentExecutionRef": { "oneOf": [ { "type": "object", "properties": { "version": { "type": "number", "const": 3 }, "componentId": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/ComponentParameterValue" } }, "seed": { "type": "string", "minLength": 1 }, "assets": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 256 }, "additionalProperties": { "type": "string", "minLength": 1 } }, "mediaBindings": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128 }, "additionalProperties": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } } } }, "required": [ "version", "componentId", "sourceVersionId", "params", "seed" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "number", "const": 4 }, "componentId": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/ComponentParameterValue" } }, "seed": { "type": "string", "minLength": 1 }, "assets": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 256 }, "additionalProperties": { "type": "string", "minLength": 1 } }, "mediaBindings": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 128 }, "additionalProperties": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } } } }, "required": [ "version", "componentId", "sourceVersionId", "params", "seed" ], "additionalProperties": false } ] }, "ComponentParameterValue": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/ComponentParameterValue" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/ComponentParameterValue" } } ] }, "CompositionConcurrency": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "exact" }, "expectedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "mode", "expectedRevision" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "guarded" }, "compositionId": { "type": "string", "minLength": 1, "maxLength": 128 }, "observedRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "basis": { "maxItems": 2048, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 256 }, "token": { "type": "string", "maxLength": 65536 } }, "required": [ "key", "token" ], "additionalProperties": false } } }, "required": [ "mode", "observedRevision", "basis" ], "additionalProperties": false } ] }, "CompositionOp": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "clip.add" }, "clip": { "$ref": "#/$defs/TimelineClip" }, "trackId": { "type": "string" }, "newTrack": { "type": "boolean" }, "newTrackId": { "type": "string" } }, "required": [ "type", "clip" ], "additionalProperties": false, "description": "Add a clip to the timeline. The clip self-routes to a track by FAMILY (`clip.kind`, else derived from `source.kind`, else the target track) — a `media` clip MUST carry `kind` (video|audio|image) or a `trackId`, else it is rejected as ambiguous. `trackId` targets an existing SAME-family track; `newTrack:true` (with optional pinned `newTrackId`) creates a fresh track of that family, appended at the BACK (the highest index, painted under every other track); raise it with `reorderTracks` (index 0 is the top layer)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "clip.remove" }, "clipId": { "type": "string" } }, "required": [ "type", "clipId" ], "additionalProperties": false, "description": "Remove a clip by id (located across every track)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "clip.setKeyframes" }, "clipId": { "type": "string", "minLength": 1 }, "property": { "type": "string", "enum": [ "opacity", "scale", "rotation", "position.x", "position.y", "volume" ] }, "keyframes": { "anyOf": [ { "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "time": { "type": "number", "minimum": 0 }, "value": { "type": "number" }, "ease": { "type": "string" } }, "required": [ "time", "value" ], "additionalProperties": false } }, { "type": "null" } ] } }, "required": [ "type", "clipId", "property", "keyframes" ], "additionalProperties": false, "description": "Set (or CLEAR, with `keyframes: null`) ONE keyframed channel of a clip: `opacity`, `scale`, `rotation`, `position.x`, `position.y` or `volume`, with at least two keyframes `{time, value, ease?}` in any order. `time` is seconds from the clip's own start (0 to its duration); `value` uses the property's own unit, as its scalar: opacity 0-1, scale a multiplier, rotation degrees, position.x/position.y a FRACTION of the frame (0.5 = centre, never px), volume 0-4. Each keyframe's optional `ease` shapes the segment ARRIVING at it, in HyperFrames' vocabulary: `none` (linear, the default), named eases such as `power2.out`, `back.out`, `expo.inOut`, `spring-gentle`, `hold`, or `custom(M0,0 Cx1,y1 x2,y2 1,1)` (a cubic, x in [0,1]). Before its first keyframe a channel holds its first value, after its last it holds the last; a channel OVERRIDES the clip's scalar (`opacity`, `scale`, `rotation`, `position`). The op REPLACES that property's keyframes; other channels are untouched. Volume keyframes are linear and only for a video or audio media clip. Trims and splits keep every keyframe on its content. Keyframes are stored as HyperFrames tweens (`tweens`) and automation (`automation`) on the clip; author them with this op, not `clip.update`." }, { "type": "object", "properties": { "type": { "type": "string", "const": "clip.update" }, "clipId": { "type": "string" }, "patch": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "startTime": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "source": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "media" }, "mediaId": { "type": "string" }, "trim": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 } }, "required": [ "start", "end" ] }, "excludedRanges": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 }, "reason": { "type": "string" } }, "required": [ "start", "end" ] } }, "volume": { "type": "number", "minimum": 0, "maximum": 4 }, "muted": { "type": "boolean" }, "playbackRate": { "type": "number", "exclusiveMinimum": 0 }, "sync": { "type": "string", "enum": [ "video", "independent" ] }, "kenBurns": { "description": "Still-image motion. When unset, an image clip slowly pushes in (`in`) unless its fit is `contain` or it keyframes scale, position or rotation, so a keyframed clip renders exactly its keyframed values; set `none` for a still that holds.", "type": "string", "enum": [ "in", "out", "pan-l", "pan-r", "none" ] }, "volumeDb": { "type": "number" }, "fadeInMs": { "type": "number", "minimum": 0 }, "fadeOutMs": { "type": "number", "minimum": 0 }, "loop": { "type": "boolean" }, "audioRole": { "description": "Mix role. A role sets the clip's default gain when it has no `volume` or `volumeDb`: vo 0 dB, sfx -6 dB, music -8 dB (-16 dB when any vo clip exists), ambience -22 dB. Set `volumeDb: 0` to keep a role and play the source at its own level.", "type": "string", "enum": [ "sfx", "music", "vo", "ambience" ] }, "duck": { "type": "object", "properties": { "duckDb": { "type": "number", "maximum": 0 }, "attackMs": { "type": "number", "minimum": 0 }, "releaseMs": { "type": "number", "minimum": 0 }, "windows": { "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "number" }, "endMs": { "type": "number" } }, "required": [ "startMs", "endMs" ] } } }, "required": [ "duckDb", "attackMs", "releaseMs" ] }, "anchor": { "type": "object", "properties": { "clipId": { "type": "string", "minLength": 1 }, "offsetMs": { "type": "number" } }, "required": [ "clipId", "offsetMs" ] }, "reframe": { "type": "object", "properties": { "segments": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "startSec": { "type": "number", "minimum": 0, "description": "Segment START in seconds, clip-relative. Segments tile the clip's duration in order." }, "endSec": { "type": "number", "exclusiveMinimum": 0, "description": "Segment END in seconds, clip-relative. The span (endSec − startSec) is this segment's duration — the window `ease` ramps over." }, "focus": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "frame-center" } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "point" }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "mode", "x", "y" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "face" }, "faceId": { "type": "string", "minLength": 1 }, "shotScale": { "type": "string", "enum": [ "close", "standard", "wide" ] } }, "required": [ "mode", "faceId" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all-faces" } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "active-speaker" } }, "required": [ "mode" ] } ], "description": "WHO/WHAT the camera tracks this segment (the reframe center), selected by `mode`: `frame-center` = no tracking, hold the geometric center (static/graphic footage, or a pure zoom); `point` = lock to a fixed source-normalized {x,y} (a non-moving on-screen element); `face` = track a detected face by `faceId` (from get_media_context), with optional `shotScale` close|standard|wide for tightness; `all-faces` = frame the bounding box of every detected face (group/ensemble shots); `active-speaker` = follow whoever is speaking (diarized talking-head / podcast). Pick by what the beat is about; pair with `zoom` for how tight." }, "intent": { "description": "Optional editorial LABEL for diff/log readability (e.g. 'speaker-tight', 'wide-context'). Cosmetic — NOT honored by the derive math and excluded from the variant cache key.", "type": "string" }, "zoom": { "description": "How TIGHT the framing is — the fraction of the source the output viewport shows. <1 punches IN (a smaller source fraction, magnified to fill the frame); 1 = the full frame (no crop). ~0.6–0.8 is a moderate push-in, ~0.5 a tight close-up, 0.1 the maximum zoom. There is NO zoom-OUT past the full frame (max 1). Omit for the full frame. MUTUALLY EXCLUSIVE with `focus.shotScale`: a face-tracked shot is sized EITHER by the editorial scale (shotScale, calibrated to the detected face) OR by an explicit zoom — never both.", "type": "number", "minimum": 0.1, "maximum": 1 }, "ease": { "description": "Zoom/center ramp DURATIONS in SECONDS at this segment's edges — NOT a unitless 0–1 curve. ~0.3–0.6s reads as a snappy push; >1s reads sluggish. Keep `in` + `out` ≤ the segment's duration (endSec − startSec): the two edges share the span, so to ramp across the WHOLE segment set one edge to the full duration and the other to 0. Omit for an instant cut to this framing.", "type": "object", "properties": { "in": { "type": "number", "minimum": 0, "description": "Ease-IN ramp DURATION in seconds at the segment START." }, "out": { "type": "number", "minimum": 0, "description": "Ease-OUT ramp DURATION in seconds at the segment END." } }, "required": [ "in", "out" ] }, "bias": { "description": "Optional FINE framing nudge off the focus center, source-normalized in [−0.3, 0.3]. A small correction (headroom, rule-of-thirds), NOT a reframe — use `focus`/`zoom` for the actual shot. Omit (treated as 0) to sit dead-center on the focus.", "type": "object", "properties": { "x": { "type": "number", "minimum": -0.3, "maximum": 0.3, "description": "Horizontal nudge, source-normalized (+ = right)." }, "y": { "type": "number", "minimum": -0.3, "maximum": 0.3, "description": "Vertical nudge, source-normalized (+ = down)." } }, "required": [ "x", "y" ] } }, "required": [ "startSec", "endSec", "focus" ] } } }, "required": [ "segments" ] } }, "required": [ "kind", "mediaId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "component" }, "componentId": { "type": "string", "minLength": 1 }, "props": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "zPlane": { "type": "string", "enum": [ "front", "behind-subject" ] }, "execution": { "$ref": "#/$defs/ComponentExecutionRef" }, "placement": { "oneOf": [ { "type": "object", "properties": { "version": { "type": "number", "const": 3 }, "kind": { "type": "string", "const": "clip" } }, "required": [ "version", "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "number", "const": 3 }, "kind": { "type": "string", "const": "content-slots" }, "slots": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 256 }, "additionalProperties": { "type": "object", "properties": { "targetClipIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "ownership": { "type": "string", "enum": [ "reference", "exclusive" ] } }, "required": [ "targetClipIds", "ownership" ], "additionalProperties": false } } }, "required": [ "version", "kind", "slots" ], "additionalProperties": false } ] }, "retired": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "kind", "componentId", "props" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "overlay" }, "primitiveId": { "type": "string", "minLength": 1, "pattern": "^(?!custom$)" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "zPlane": { "type": "string", "enum": [ "front", "behind-subject" ] }, "anchor": { "type": "object", "properties": { "space": { "type": "string", "const": "scene" }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "space", "x", "y" ] }, "parallax": { "type": "number", "minimum": -0.3, "maximum": 0.3 } }, "required": [ "kind", "primitiveId", "params" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "effect" }, "component": { "$ref": "#/$defs/ComponentExecutionRef" }, "targetTrackIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "wrapperOrder": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "primitiveId": { "type": "string", "minLength": 1 }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "html": { "type": "string", "minLength": 1, "description": "Self-contained card markup sized to the format's pixel frame. Motion comes from frame-driven vars, never @keyframes or transition: --cf-frame, --cf-t (seconds), --cf-fps, --cf-duration, --cf-progress, --cf-ease, --cf-enter, --cf-exit. Visible copy goes in the html as plain text. Wrap a run in or \"chars\" and each unit becomes its own span carrying --cf-i (its index, the group carries --cf-n), so one rule staggers it (in chars, spaces count as units), e.g. opacity:clamp(0,calc(var(--cf-t)*4 - var(--cf-i)*.3),1). save_as_template binds that copy with textParams match." }, "tokens": { "description": "Style values the html reads as CSS custom properties: key x becomes --cf-x, so never put dashes in a key. Use tokens for colours and sizes, not visible copy.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "zPlane": { "type": "string", "const": "front" } }, "required": [ "kind", "html" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "composition" }, "compositionId": { "type": "string", "minLength": 1 }, "trim": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 } }, "required": [ "start", "end" ] } }, "required": [ "kind", "compositionId" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "video", "audio", "image", "overlay", "effect" ] }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "scale": { "type": "number", "exclusiveMinimum": 0 }, "rotation": { "type": "number" }, "position": { "type": "object", "properties": { "x": { "type": "number", "minimum": -1, "maximum": 2 }, "y": { "type": "number", "minimum": -1, "maximum": 2 } }, "required": [ "x", "y" ], "description": "Clip CENTRE as a fraction of the frame: {x:0.5,y:0.5} is dead centre, 0 to 1 is inside the frame, and a little overshoot (down to -1, up to 2) is how an entrance starts off-canvas. NOT pixels: the renderer maps x to `left: x*100%`, so `x: 180` sits 180 frame-widths away and draws nothing." }, "region": { "description": "A window in the frame that the clip draws into and is clipped to (top-left corner and size, each a frame fraction). Inside a region, `position` and `scale` act relative to that window, so content moved past its edge is cut off. Omit it to place the clip against the whole frame.", "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "h": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ] }, "fit": { "type": "string", "enum": [ "cover", "contain" ] }, "captionVisibility": { "description": "Video media clip only. Hide native captions while this clip is topmost and covers the lower picture, or when an opaque, effect-free clip has an explicitly full-frame region, even with fit:contain. Caption words and timings remain stored and resume when another visible clip takes over.", "type": "string", "enum": [ "visible", "hidden" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "component": { "$ref": "#/$defs/ComponentExecutionRef" }, "window": { "type": "object", "properties": { "startTime": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "startTime", "duration" ], "additionalProperties": false }, "primitiveId": { "type": "string", "minLength": 1 }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } }, "transitionIn": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "id": { "type": "string", "minLength": 1 }, "component": { "$ref": "#/$defs/ComponentExecutionRef" }, "fromClipId": { "type": "string", "minLength": 1 }, "toClipId": { "type": "string", "minLength": 1 }, "handlePolicy": { "type": "string", "const": "outgoing-overrun-at-cut-v1" } }, "required": [ "type", "duration" ] }, "linkGroupId": { "type": "string", "minLength": 1 }, "tweens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "propertyGroup": { "type": "string", "enum": [ "visual", "scale", "rotation", "position" ] }, "position": { "type": "number" }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "keyframes": { "type": "object", "properties": { "format": { "type": "string", "const": "percentage" }, "easeEach": { "type": "string", "const": "none" }, "keyframes": { "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "ease": { "type": "string" } }, "required": [ "percentage", "properties" ], "additionalProperties": false } } }, "required": [ "format", "easeEach", "keyframes" ], "additionalProperties": false } }, "required": [ "id", "propertyGroup", "position", "duration", "keyframes" ], "additionalProperties": false } }, "automation": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "lanes": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "const": "volume" }, "points": { "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "t": { "type": "number" }, "v": { "type": "number" } }, "required": [ "t", "v" ], "additionalProperties": false } } }, "required": [ "target", "points" ], "additionalProperties": false } } }, "required": [ "version", "lanes" ], "additionalProperties": false }, "color": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "enabled": { "type": "boolean" }, "grade": { "type": "object", "properties": { "exposure": { "type": "number", "minimum": -4, "maximum": 4 }, "contrast": { "type": "number", "minimum": -1, "maximum": 1 }, "highlights": { "type": "number", "minimum": -1, "maximum": 1 }, "shadows": { "type": "number", "minimum": -1, "maximum": 1 }, "whites": { "type": "number", "minimum": -1, "maximum": 1 }, "blacks": { "type": "number", "minimum": -1, "maximum": 1 }, "temperature": { "type": "number", "minimum": -1, "maximum": 1 }, "tint": { "type": "number", "minimum": -1, "maximum": 1 }, "vibrance": { "type": "number", "minimum": -1, "maximum": 1 }, "saturation": { "type": "number", "minimum": -1, "maximum": 1 } }, "required": [ "exposure", "contrast", "highlights", "shadows", "whites", "blacks", "temperature", "tint", "vibrance", "saturation" ], "additionalProperties": false }, "looks": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "mediaId", "sha256", "enabled" ], "additionalProperties": false } }, "display": { "anyOf": [ { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "mediaId", "sha256", "enabled" ], "additionalProperties": false }, { "type": "object", "properties": { "bundled": { "type": "string", "enum": [ "daylight-negative", "tungsten-negative", "soft-negative", "slide", "black-and-white" ] }, "enabled": { "type": "boolean" } }, "required": [ "bundled", "enabled" ], "additionalProperties": false } ] }, "creative": { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" }, "strength": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "mediaId", "sha256", "enabled", "strength" ], "additionalProperties": false }, "halation": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "amount": { "type": "number", "minimum": 0, "maximum": 0.5 }, "radius": { "type": "number", "minimum": 0.0005, "maximum": 0.02 }, "threshold": { "type": "number", "minimum": 0, "maximum": 16 }, "tint": { "type": "array", "prefixItems": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "number", "minimum": 0, "maximum": 1 } ], "items": false, "minItems": 3, "maxItems": 3 } }, "required": [ "enabled", "amount", "radius", "threshold", "tint" ], "additionalProperties": false }, "grain": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "profile": { "type": "string", "enum": [ "daylight-negative", "tungsten-negative", "soft-negative", "slide", "black-and-white" ] }, "gauge": { "type": "string", "enum": [ "super8", "super16", "super35", "65mm" ] }, "amount": { "type": "number", "minimum": 0, "maximum": 2 }, "size": { "type": "number", "minimum": 0.5, "maximum": 4 }, "seed": { "type": "integer", "minimum": 0, "maximum": 4294967295 } }, "required": [ "enabled", "profile", "gauge", "amount", "size", "seed" ], "additionalProperties": false } }, "required": [ "version", "enabled", "grade", "looks" ], "additionalProperties": false }, "legacyKeyframes": { "type": "object", "properties": { "needsUpgrade": { "type": "boolean", "const": true }, "channels": { "type": "array", "items": { "type": "string" } }, "record": {} }, "required": [ "needsUpgrade", "channels", "record" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "type", "clipId", "patch" ], "additionalProperties": false, "description": "Patch an existing clip by id (cross-family). The patch is a partial TimelineClip. NOTE: `source` is REPLACED wholesale — the patch merges at the top level only, so a partial `source` WIPES the source fields you omit. Patch the whole source object when changing it. (To change reframe/excluded ranges, prefer setCropIntents / addExcludedRange, not a source patch.)" }, { "type": "object", "properties": { "type": { "type": "string", "const": "removeClipsByMediaId" }, "mediaId": { "type": "string" } }, "required": [ "type", "mediaId" ], "additionalProperties": false, "description": "Remove EVERY clip sourced from a given mediaId (e.g. after deleting that media)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "loadOverlays" }, "clips": { "type": "array", "items": { "$ref": "#/$defs/TimelineClip" } } }, "required": [ "type", "clips" ], "additionalProperties": false, "description": "Replace the overlay channel wholesale with the given clips (bulk set, not a merge)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "addMarker" }, "marker": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "startTime": { "type": "number", "minimum": 0 }, "endTime": { "type": "number", "minimum": 0 }, "kind": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "startTime", "kind" ], "additionalProperties": false } }, "required": [ "type", "marker" ], "additionalProperties": false, "description": "Add a timeline marker (a named time point/range; carry extensions in `metadata`)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "removeMarker" }, "markerId": { "type": "string" } }, "required": [ "type", "markerId" ], "additionalProperties": false, "description": "Remove a marker by id." }, { "type": "object", "properties": { "type": { "type": "string", "const": "updateMarker" }, "markerId": { "type": "string" }, "updates": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "startTime": { "type": "number", "minimum": 0 }, "endTime": { "type": "number", "minimum": 0 }, "kind": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } }, "required": [ "type", "markerId", "updates" ], "additionalProperties": false, "description": "Patch a marker's fields by id (partial merge)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "setCropIntents" }, "clipId": { "type": "string" }, "segments": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "startSec": { "type": "number", "minimum": 0, "description": "Segment START in seconds, clip-relative. Segments tile the clip's duration in order." }, "endSec": { "type": "number", "exclusiveMinimum": 0, "description": "Segment END in seconds, clip-relative. The span (endSec − startSec) is this segment's duration — the window `ease` ramps over." }, "focus": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "frame-center" } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "point" }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "mode", "x", "y" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "face" }, "faceId": { "type": "string", "minLength": 1 }, "shotScale": { "type": "string", "enum": [ "close", "standard", "wide" ] } }, "required": [ "mode", "faceId" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all-faces" } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "active-speaker" } }, "required": [ "mode" ] } ], "description": "WHO/WHAT the camera tracks this segment (the reframe center), selected by `mode`: `frame-center` = no tracking, hold the geometric center (static/graphic footage, or a pure zoom); `point` = lock to a fixed source-normalized {x,y} (a non-moving on-screen element); `face` = track a detected face by `faceId` (from get_media_context), with optional `shotScale` close|standard|wide for tightness; `all-faces` = frame the bounding box of every detected face (group/ensemble shots); `active-speaker` = follow whoever is speaking (diarized talking-head / podcast). Pick by what the beat is about; pair with `zoom` for how tight." }, "intent": { "description": "Optional editorial LABEL for diff/log readability (e.g. 'speaker-tight', 'wide-context'). Cosmetic — NOT honored by the derive math and excluded from the variant cache key.", "type": "string" }, "zoom": { "description": "How TIGHT the framing is — the fraction of the source the output viewport shows. <1 punches IN (a smaller source fraction, magnified to fill the frame); 1 = the full frame (no crop). ~0.6–0.8 is a moderate push-in, ~0.5 a tight close-up, 0.1 the maximum zoom. There is NO zoom-OUT past the full frame (max 1). Omit for the full frame. MUTUALLY EXCLUSIVE with `focus.shotScale`: a face-tracked shot is sized EITHER by the editorial scale (shotScale, calibrated to the detected face) OR by an explicit zoom — never both.", "type": "number", "minimum": 0.1, "maximum": 1 }, "ease": { "description": "Zoom/center ramp DURATIONS in SECONDS at this segment's edges — NOT a unitless 0–1 curve. ~0.3–0.6s reads as a snappy push; >1s reads sluggish. Keep `in` + `out` ≤ the segment's duration (endSec − startSec): the two edges share the span, so to ramp across the WHOLE segment set one edge to the full duration and the other to 0. Omit for an instant cut to this framing.", "type": "object", "properties": { "in": { "type": "number", "minimum": 0, "description": "Ease-IN ramp DURATION in seconds at the segment START." }, "out": { "type": "number", "minimum": 0, "description": "Ease-OUT ramp DURATION in seconds at the segment END." } }, "required": [ "in", "out" ] }, "bias": { "description": "Optional FINE framing nudge off the focus center, source-normalized in [−0.3, 0.3]. A small correction (headroom, rule-of-thirds), NOT a reframe — use `focus`/`zoom` for the actual shot. Omit (treated as 0) to sit dead-center on the focus.", "type": "object", "properties": { "x": { "type": "number", "minimum": -0.3, "maximum": 0.3, "description": "Horizontal nudge, source-normalized (+ = right)." }, "y": { "type": "number", "minimum": -0.3, "maximum": 0.3, "description": "Vertical nudge, source-normalized (+ = down)." } }, "required": [ "x", "y" ] } }, "required": [ "startSec", "endSec", "focus" ] } }, { "type": "null" } ] } }, "required": [ "type", "clipId", "segments" ], "additionalProperties": false, "description": "Set (or CLEAR, with `segments: null`) the camera/reframe channel on a MEDIA clip — the time-aligned source→output viewport (focus, zoom, ease, bias). This is the PREFERRED way to author reframing; do NOT reframe via a whole-source `clip.update` patch. Segments tile the clip's duration." }, { "type": "object", "properties": { "type": { "type": "string", "const": "setEffects" }, "clipId": { "type": "string" }, "effects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "component": { "$ref": "#/$defs/ComponentExecutionRef" }, "window": { "type": "object", "properties": { "startTime": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "startTime", "duration" ], "additionalProperties": false }, "primitiveId": { "type": "string", "minLength": 1 }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } } }, "required": [ "type", "clipId", "effects" ], "additionalProperties": false, "description": "Set (or CLEAR, with `effects: []`) a clip's EFFECT channel — the pinned component clip wrappers stacked onto that clip, each `{id, component, window}`: a unique `id`, the wrapper component's execution pin as `component`, and `window: {startTime, duration}` in seconds. The built-in primitive effects were removed: a stored one reads, and save and render refuse it (`effect_retired`), so clear it with `effects: []`. WHOLESALE: the array REPLACES the clip's current effects, so send the full stack (read the clip first to add one). This is the ONLY way to change effects on an existing clip — do NOT reach for a `clip.update` patch, whose top-level merge is the source-clobbering footgun documented above." }, { "type": "object", "properties": { "type": { "type": "string", "const": "setMediaInputTransform" }, "mediaId": { "type": "string" }, "inputTransform": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "id": { "type": "string", "enum": [ "rec709", "insta360-ilog", "custom-lut", "apple-log" ] }, "table": { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "mediaId", "sha256", "enabled" ], "additionalProperties": false }, "ycbcr": { "type": "object", "properties": { "matrix": { "type": "string", "enum": [ "bt709", "bt2020", "bt601" ] }, "range": { "type": "string", "enum": [ "limited", "full" ] } }, "required": [ "matrix", "range" ], "additionalProperties": false } }, "required": [ "version", "id" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "type", "mediaId", "inputTransform" ], "additionalProperties": false, "description": "Set (or CLEAR, with `inputTransform: null`) how a MEDIA's pixels are decoded into the working color space, for every clip of that media: `{version: 1, id, table?, ycbcr?}` with `id` one of rec709, insta360-ilog, custom-lut, apple-log. `custom-lut` is a camera LUT (log → Rec.709, e.g. DJI's D-Log M LUT): it requires `table: {mediaId, sha256, enabled}` naming an uploaded .cube LUT, and its output is read as Rec.709 footage; the others take no table. `ycbcr: {matrix, range}` overrides the source's signalled YCbCr matrix and range. The entry lives in the composition's `media` map; the media must be used by a clip in this composition, and removing its last clip removes the entry. To set a camera input for many media, send one `setMediaInputTransform` per media in a single `apply_composition` call." }, { "type": "object", "properties": { "type": { "type": "string", "const": "setClipColor" }, "clipId": { "type": "string" }, "color": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "enabled": { "type": "boolean" }, "grade": { "type": "object", "properties": { "exposure": { "type": "number", "minimum": -4, "maximum": 4 }, "contrast": { "type": "number", "minimum": -1, "maximum": 1 }, "highlights": { "type": "number", "minimum": -1, "maximum": 1 }, "shadows": { "type": "number", "minimum": -1, "maximum": 1 }, "whites": { "type": "number", "minimum": -1, "maximum": 1 }, "blacks": { "type": "number", "minimum": -1, "maximum": 1 }, "temperature": { "type": "number", "minimum": -1, "maximum": 1 }, "tint": { "type": "number", "minimum": -1, "maximum": 1 }, "vibrance": { "type": "number", "minimum": -1, "maximum": 1 }, "saturation": { "type": "number", "minimum": -1, "maximum": 1 } }, "required": [ "exposure", "contrast", "highlights", "shadows", "whites", "blacks", "temperature", "tint", "vibrance", "saturation" ], "additionalProperties": false }, "looks": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "mediaId", "sha256", "enabled" ], "additionalProperties": false } }, "display": { "anyOf": [ { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "mediaId", "sha256", "enabled" ], "additionalProperties": false }, { "type": "object", "properties": { "bundled": { "type": "string", "enum": [ "daylight-negative", "tungsten-negative", "soft-negative", "slide", "black-and-white" ] }, "enabled": { "type": "boolean" } }, "required": [ "bundled", "enabled" ], "additionalProperties": false } ] }, "creative": { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" }, "strength": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "mediaId", "sha256", "enabled", "strength" ], "additionalProperties": false }, "halation": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "amount": { "type": "number", "minimum": 0, "maximum": 0.5 }, "radius": { "type": "number", "minimum": 0.0005, "maximum": 0.02 }, "threshold": { "type": "number", "minimum": 0, "maximum": 16 }, "tint": { "type": "array", "prefixItems": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "number", "minimum": 0, "maximum": 1 } ], "items": false, "minItems": 3, "maxItems": 3 } }, "required": [ "enabled", "amount", "radius", "threshold", "tint" ], "additionalProperties": false }, "grain": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "profile": { "type": "string", "enum": [ "daylight-negative", "tungsten-negative", "soft-negative", "slide", "black-and-white" ] }, "gauge": { "type": "string", "enum": [ "super8", "super16", "super35", "65mm" ] }, "amount": { "type": "number", "minimum": 0, "maximum": 2 }, "size": { "type": "number", "minimum": 0.5, "maximum": 4 }, "seed": { "type": "integer", "minimum": 0, "maximum": 4294967295 } }, "required": [ "enabled", "profile", "gauge", "amount", "size", "seed" ], "additionalProperties": false } }, "required": [ "version", "enabled", "grade", "looks" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "type", "clipId", "color" ], "additionalProperties": false, "description": "Set (or CLEAR, with `color: null`) a video media clip's color correction, WHOLESALE: `{version: 1, enabled, grade, looks, display?, creative?}`. `grade` holds every primary control: `exposure` in stops (-4..4) and `contrast`, `highlights`, `shadows`, `whites`, `blacks`, `temperature`, `tint`, `vibrance`, `saturation` each -1..1 (0 = neutral). `looks` (at most 2), `display` and `creative` name uploaded .cube LUTs as `{mediaId, sha256, enabled}`; `creative` adds `strength` 0..1. `display` may instead name a bundled film look as `{bundled, enabled}`, `bundled` one of daylight-negative, tungsten-negative, soft-negative, slide, black-and-white. `halation?: {enabled, amount 0..0.5, radius (picture heights) 0.0005..0.02, threshold 0..16, tint [r,g,b] 0..1}`; `grain?: {enabled, profile (a film look id), gauge super8|super16|super35|65mm, amount 0..2, size 0.5..4, seed uint32}`. Film presets are whole values, applied by replacing `display`, `halation` and `grain` with exactly what the preset names (absent = removed), writing only the grade keys it names, `display` as `{bundled, enabled: true}`, `halation`/`grain` with `enabled: true`, and grain `seed` kept or any uint32. Presets: {\"id\":\"daylight-negative\",\"name\":\"Daylight Negative\",\"display\":\"daylight-negative\",\"halation\":{\"amount\":0.015,\"radius\":0.0026795284030010718,\"threshold\":0,\"tint\":[1,0.33333333333333337,0]},\"grain\":{\"profile\":\"daylight-negative\",\"gauge\":\"super35\",\"amount\":1,\"size\":1}}; {\"id\":\"tungsten-negative\",\"name\":\"Tungsten Negative\",\"display\":\"tungsten-negative\",\"halation\":{\"amount\":0.015,\"radius\":0.0026795284030010718,\"threshold\":0,\"tint\":[1,0.33333333333333337,0]},\"grain\":{\"profile\":\"tungsten-negative\",\"gauge\":\"super35\",\"amount\":1,\"size\":1}}; {\"id\":\"soft-negative\",\"name\":\"Soft Negative\",\"display\":\"soft-negative\",\"halation\":{\"amount\":0.015,\"radius\":0.0034833869239013935,\"threshold\":0,\"tint\":[1,0.33333333333333337,0]},\"grain\":{\"profile\":\"soft-negative\",\"gauge\":\"super35\",\"amount\":1,\"size\":1}}; {\"id\":\"slide\",\"name\":\"Slide\",\"display\":\"slide\",\"halation\":{\"amount\":0.015,\"radius\":0.0034833869239013935,\"threshold\":0,\"tint\":[1,0.33333333333333337,0]},\"grain\":{\"profile\":\"slide\",\"gauge\":\"super35\",\"amount\":1,\"size\":1}}; {\"id\":\"black-and-white\",\"name\":\"Black and White\",\"display\":\"black-and-white\",\"halation\":{\"amount\":0.015,\"radius\":0.0026795284030010718,\"threshold\":0,\"tint\":[1,0.33333333333333337,0]},\"grain\":{\"profile\":\"black-and-white\",\"gauge\":\"super35\",\"amount\":1,\"size\":1}}; {\"id\":\"grain-only-fine\",\"name\":\"Fine grain\",\"grain\":{\"profile\":\"daylight-negative\",\"gauge\":\"65mm\",\"amount\":1,\"size\":1}}; {\"id\":\"halation-only\",\"name\":\"Halation\",\"halation\":{\"amount\":0.08,\"radius\":0.0026795284030010718,\"threshold\":0,\"tint\":[1,0.25,0]}}. `enabled: false` bypasses the whole correction. Only a media clip on a video track takes color." }, { "type": "object", "properties": { "type": { "type": "string", "const": "setCaptionStyle" }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1 }, "fontSize": { "description": "Font size as % of composition height (1-15, default 5). NOT px.", "type": "number", "minimum": 1, "maximum": 15 }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "color": { "type": "string", "minLength": 1 }, "highlightColor": { "type": "string", "minLength": 1 }, "backgroundColor": { "type": "string" }, "plate": { "type": "string", "enum": [ "glass", "solid", "none" ] }, "position": { "type": "string", "enum": [ "top", "center", "bottom" ] }, "region": { "description": "Optional caption layout box {x,y,w,h} in normalized output-frame coordinates. Overrides position; text starts at its top edge and wraps/pages within its width and height.", "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "h": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ] }, "textTransform": { "type": "string", "enum": [ "none", "uppercase", "capitalize" ] }, "letterSpacing": { "description": "Base caption glyph spacing in pixels.", "type": "number", "minimum": -5, "maximum": 20 }, "wordGapEm": { "description": "Gap between caption runs as a multiple of base font size; default 0.35.", "type": "number", "minimum": 0, "maximum": 2 }, "lineGapEm": { "description": "Gap between caption lines as a multiple of base font size; default 0.25.", "type": "number", "minimum": 0, "maximum": 2 }, "emphasisColor": { "type": "string" }, "emphasisGradient": { "type": "string" }, "emphasisScale": { "type": "number", "exclusiveMinimum": 0 }, "emphasisFontFamily": { "type": "string" }, "emphasisFontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "emphasisTextTransform": { "type": "string", "enum": [ "none", "uppercase", "capitalize" ] }, "emphasisLetterSpacing": { "type": "number" }, "emphasisFontStyle": { "type": "string", "enum": [ "normal", "italic" ] }, "entrance": { "type": "string", "enum": [ "none", "fade", "word-pop", "stagger-up" ] }, "entranceMs": { "type": "number", "minimum": 0 }, "entranceStaggerMs": { "type": "number", "minimum": 0 }, "exitMs": { "type": "number", "minimum": 0 }, "emphasisPlate": { "type": "boolean" }, "emphasisPlateColor": { "type": "string" }, "emphasisPlateTextColor": { "type": "string" }, "emphasisPlateAltColor": { "type": "string" }, "emphasisPlateAltTextColor": { "type": "string" }, "emphasisPlateRadius": { "type": "number", "minimum": 0 }, "emphasisPlatePadX": { "type": "number" }, "emphasisPlatePadY": { "type": "number" }, "emphasisPlateReveal": { "description": "Grow a shared emphasis plate as saved words appear while reserving its final layout width.", "type": "boolean" }, "annotationColor": { "type": "string" }, "annotationStrokeWidth": { "description": "Annotation stroke width in its 100×100 SVG coordinate system; default 4.", "type": "number", "minimum": 0.5, "maximum": 12 }, "annotationTexture": { "description": "Native annotation stroke finish; default clean.", "type": "string", "enum": [ "clean", "pencil" ] }, "maxWidthPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } } } }, "required": [ "type", "style" ], "additionalProperties": false, "description": "Merge style overrides (font/color/position/emphasis) onto the composition's caption layer. Partial — omitted fields keep their current value; creates the caption container if absent." }, { "type": "object", "properties": { "type": { "type": "string", "const": "setCaptionDepth" }, "zPlane": { "type": "string", "enum": [ "front", "behind-subject" ] } }, "required": [ "type", "zPlane" ], "additionalProperties": false, "description": "Set the caption compositing plane. Use `behind-subject` to place captions behind the segmented foreground subject; use `front` for conventional captions above all video layers." }, { "type": "object", "properties": { "type": { "type": "string", "const": "setCaptions" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "words": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1 }, "startMs": { "type": "number", "minimum": 0, "description": "Word start on the composition timeline, in milliseconds." }, "endMs": { "type": "number", "minimum": 0, "description": "Word end on the composition timeline, in milliseconds." }, "emphasis": { "type": "boolean" }, "annotate": { "type": "string", "enum": [ "circle", "underline" ] } }, "required": [ "text", "startMs", "endMs" ] } } }, "required": [ "words" ] } }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1 }, "fontSize": { "description": "Font size as % of composition height (1-15, default 5). NOT px.", "type": "number", "minimum": 1, "maximum": 15 }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "color": { "type": "string", "minLength": 1 }, "highlightColor": { "type": "string", "minLength": 1 }, "backgroundColor": { "type": "string" }, "plate": { "type": "string", "enum": [ "glass", "solid", "none" ] }, "position": { "type": "string", "enum": [ "top", "center", "bottom" ] }, "region": { "description": "Optional caption layout box {x,y,w,h} in normalized output-frame coordinates. Overrides position; text starts at its top edge and wraps/pages within its width and height.", "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "h": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ] }, "textTransform": { "type": "string", "enum": [ "none", "uppercase", "capitalize" ] }, "letterSpacing": { "description": "Base caption glyph spacing in pixels.", "type": "number", "minimum": -5, "maximum": 20 }, "wordGapEm": { "description": "Gap between caption runs as a multiple of base font size; default 0.35.", "type": "number", "minimum": 0, "maximum": 2 }, "lineGapEm": { "description": "Gap between caption lines as a multiple of base font size; default 0.25.", "type": "number", "minimum": 0, "maximum": 2 }, "emphasisColor": { "type": "string" }, "emphasisGradient": { "type": "string" }, "emphasisScale": { "type": "number", "exclusiveMinimum": 0 }, "emphasisFontFamily": { "type": "string" }, "emphasisFontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "emphasisTextTransform": { "type": "string", "enum": [ "none", "uppercase", "capitalize" ] }, "emphasisLetterSpacing": { "type": "number" }, "emphasisFontStyle": { "type": "string", "enum": [ "normal", "italic" ] }, "entrance": { "type": "string", "enum": [ "none", "fade", "word-pop", "stagger-up" ] }, "entranceMs": { "type": "number", "minimum": 0 }, "entranceStaggerMs": { "type": "number", "minimum": 0 }, "exitMs": { "type": "number", "minimum": 0 }, "emphasisPlate": { "type": "boolean" }, "emphasisPlateColor": { "type": "string" }, "emphasisPlateTextColor": { "type": "string" }, "emphasisPlateAltColor": { "type": "string" }, "emphasisPlateAltTextColor": { "type": "string" }, "emphasisPlateRadius": { "type": "number", "minimum": 0 }, "emphasisPlatePadX": { "type": "number" }, "emphasisPlatePadY": { "type": "number" }, "emphasisPlateReveal": { "description": "Grow a shared emphasis plate as saved words appear while reserving its final layout width.", "type": "boolean" }, "annotationColor": { "type": "string" }, "annotationStrokeWidth": { "description": "Annotation stroke width in its 100×100 SVG coordinate system; default 4.", "type": "number", "minimum": 0.5, "maximum": 12 }, "annotationTexture": { "description": "Native annotation stroke finish; default clean.", "type": "string", "enum": [ "clean", "pencil" ] }, "maxWidthPercent": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 } } } }, "required": [ "type", "segments" ], "additionalProperties": false, "description": "Replace the caption SEGMENTS wholesale — author the word-timed caption layer directly (each segment = one sentence/page of `words` with timeline-ms `startMs`/`endMs`, optional `emphasis`). This is how a client with its OWN word timings (e.g. a generated VO take) gets word-synced captions without a source transcript; the compose lane's transcript slice writes the same layer. `style`, when given, merges with setCaptionStyle semantics; an omitted style keeps the existing one. Renderer paginates within a segment and never pools words across two — keep segments sentence-bounded." }, { "type": "object", "properties": { "type": { "type": "string", "const": "setCaptionLayouts" }, "layouts": { "type": "array", "items": { "type": "object", "properties": { "segmentIndex": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "wordStartIndex": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "wordEndIndex": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Exclusive word index in the saved caption segment." }, "region": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "h": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "rotation": { "type": "number", "minimum": -45, "maximum": 45 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1 }, "fontSize": { "description": "Font size as % of composition height (1-15, default 5). NOT px.", "type": "number", "minimum": 1, "maximum": 15 }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "color": { "type": "string", "minLength": 1 }, "highlightColor": { "type": "string", "minLength": 1 }, "backgroundColor": { "type": "string" }, "plate": { "type": "string", "enum": [ "glass", "solid", "none" ] }, "textTransform": { "type": "string", "enum": [ "none", "uppercase", "capitalize" ] }, "letterSpacing": { "description": "Base caption glyph spacing in pixels.", "type": "number", "minimum": -5, "maximum": 20 }, "wordGapEm": { "description": "Gap between caption runs as a multiple of base font size; default 0.35.", "type": "number", "minimum": 0, "maximum": 2 }, "lineGapEm": { "description": "Gap between caption lines as a multiple of base font size; default 0.25.", "type": "number", "minimum": 0, "maximum": 2 }, "emphasisColor": { "type": "string" }, "emphasisScale": { "type": "number", "exclusiveMinimum": 0 }, "emphasisFontFamily": { "type": "string" }, "emphasisFontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "emphasisTextTransform": { "type": "string", "enum": [ "none", "uppercase", "capitalize" ] }, "emphasisLetterSpacing": { "type": "number" }, "emphasisFontStyle": { "type": "string", "enum": [ "normal", "italic" ] }, "emphasisPlate": { "type": "boolean" }, "emphasisPlateColor": { "type": "string" }, "emphasisPlateTextColor": { "type": "string" }, "emphasisPlateAltColor": { "type": "string" }, "emphasisPlateAltTextColor": { "type": "string" }, "emphasisPlateRadius": { "type": "number", "minimum": 0 }, "emphasisPlatePadX": { "type": "number" }, "emphasisPlatePadY": { "type": "number" }, "emphasisPlateReveal": { "description": "Grow a shared emphasis plate as saved words appear while reserving its final layout width.", "type": "boolean" }, "annotationColor": { "type": "string" }, "annotationStrokeWidth": { "description": "Annotation stroke width in its 100×100 SVG coordinate system; default 4.", "type": "number", "minimum": 0.5, "maximum": 12 }, "annotationTexture": { "description": "Native annotation stroke finish; default clean.", "type": "string", "enum": [ "clean", "pencil" ] }, "entrance": { "type": "string", "enum": [ "none", "fade", "word-pop", "stagger-up" ] }, "entranceMs": { "type": "number", "minimum": 0 }, "entranceStaggerMs": { "type": "number", "minimum": 0 }, "exitMs": { "type": "number", "minimum": 0 } }, "additionalProperties": false }, "holdThroughWordIndex": { "description": "Inclusive saved-word index in this segment. The layout stays visible until that word ends.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "wordMarks": { "type": "array", "items": { "type": "object", "properties": { "wordIndex": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "emphasis": { "type": "boolean" }, "annotate": { "anyOf": [ { "type": "string", "enum": [ "circle", "underline" ] }, { "type": "null" } ] } }, "required": [ "wordIndex" ], "additionalProperties": false } } }, "required": [ "segmentIndex", "wordStartIndex", "wordEndIndex", "region" ], "additionalProperties": false } } }, "required": [ "type", "layouts" ], "additionalProperties": false, "description": "Replace native caption placements without changing transcript words or timings. Each layout references a half-open word-index range in one saved segment; a one-word range is valid. region places that group independently, optional bounded scale/rotation/style changes its look, and holdThroughWordIndex keeps it visible through a later saved word in the same segment. All words in a placed range occupy one page; rendering refuses a range that cannot fit its box, so enlarge region or split the range. The box reserves horizontal space of 1.6 font sizes and vertical space of 0.8 font sizes for padding, with at most three lines. Unreferenced words keep the default caption layout. Word ranges must not overlap. Reapply after caption regeneration or timeline cuts." }, { "type": "object", "properties": { "type": { "type": "string", "const": "scene.add" }, "clipId": { "type": "string", "minLength": 1 }, "trackId": { "type": "string", "minLength": 1 }, "newTrack": { "type": "boolean" }, "newTrackId": { "type": "string", "minLength": 1 }, "startTime": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "transitionIn": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "id": { "type": "string", "minLength": 1 }, "component": { "$ref": "#/$defs/ComponentExecutionRef" }, "fromClipId": { "type": "string", "minLength": 1 }, "toClipId": { "type": "string", "minLength": 1 }, "handlePolicy": { "type": "string", "const": "outgoing-overrun-at-cut-v1" } }, "required": [ "type", "duration" ] }, "scene": { "$ref": "#/$defs/SceneShotSpecV2" }, "assets": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": [ "type", "clipId", "startTime", "duration", "scene", "assets" ], "additionalProperties": false, "description": "Author a scene shot and place it on a dedicated overlay track. The host validates the scene, generates and registers an immutable wrapper component source, and emits the ordinary track/clip operations carrying `props.componentRef` — you edit a scene SPEC, never wrapper TSX or a source hash. Registration and the composition update are ONE undoable edit; a failure publishes nothing and leaves no clip pointing at an unresolved source. REQUIRED: `clipId`, `startTime`, `duration`, `scene` and `assets` (send `{}` when no layer references a slot), plus EXACTLY ONE of `trackId` (an existing dedicated scene track) or `newTrack: true` (mint one). A minted scene track is appended at the BACK like every new track, so it paints under existing tracks; raise it with `reorderTracks` (index 0 is the top layer). That track holds scene-shot clips and gaps only — no generic component/primitive/media clips in v1 — and existing generic overlay tracks are unaffected. Scene clips use front zPlane and full-frame placement: outer per-clip `region`, `position`, `scale`, `rotation`, `fit`, `effects`, keyframes (`tweens`/`automation`), `params.transition`, `params.sequenceGroup` and internal fadeIn/fadeOut are REFUSED with a path, because the shot's own layer transforms are the single transform owner. TEXT: `space: \"screen\"` text is composed above the world result, stays fixed in the frame and stays sharp through focus; `space: \"world\"` text is rasterized into the 3D scene, moves with the camera and is occluded by geometry. Screenshots and world text are UNLIT and colour-managed so product UI colours are not tinted by the studio lighting, while device bodies are lit and cast shadows; an unlit surface still occludes. SCOPE GAP (pre-existing, neither closed nor changed by scene shots): global wrap effects — composition-level grades and camera effects — do not reach front-overlay clips, so they do not affect a scene shot. Author the look INSIDE the shot (`post.grain`, `post.vignette`, `post.focus`, `backdrop`, `environment`) instead. DISCOVERY: there is no built-in scene primitive to look up in list_catalog; the wrapper this operation registers appears afterwards as an ordinary INSTALLED component under the existing catalog rules. ASSETS: `assets` binds each slot name a layer references to a media id in the same project, and the slot's declared KIND decides what it admits — an image slot takes PNG, JPEG or WebP, a video slot MP4 or WebM. Binding the wrong kind is refused with the slot's path." }, { "type": "object", "properties": { "type": { "type": "string", "const": "scene.update" }, "clipId": { "type": "string", "minLength": 1 }, "startTime": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "transitionIn": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "id": { "type": "string", "minLength": 1 }, "component": { "$ref": "#/$defs/ComponentExecutionRef" }, "fromClipId": { "type": "string", "minLength": 1 }, "toClipId": { "type": "string", "minLength": 1 }, "handlePolicy": { "type": "string", "const": "outgoing-overrun-at-cut-v1" } }, "required": [ "type", "duration" ] }, "scene": { "$ref": "#/$defs/SceneShotSpecV2" }, "assets": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "string", "minLength": 1 } } }, "required": [ "type", "clipId" ], "additionalProperties": false, "description": "Revise a scene shot in place by clip id. Send a replacement `scene` and/or `assets`; timing changes use the ordinary clip timing fields (`startTime`, `duration`, `transitionIn`). Omitted fields keep their persisted values and the MERGED result is re-validated as a whole, so a partial edit cannot leave the shot invalid. Changing only values or asset IDs updates props and bindings and REUSES the pinned source; changing the referenced SLOT SET regenerates the wrapper manifest and registers a new immutable source version atomically. Undo restores the source reference, spec, bindings and timing together. Topology, asset bindings, text content, font properties, device kind and colours are STATIC within a shot's animation — change them here (a revised spec) rather than trying to animate them. This is not a source trim or slip: a shortened or extended clip resamples the SAME normalized animation over its new duration, and trim/slip requests on generated animation are rejected rather than reinterpreted as media trims. In one batch, `scene.update` may target a shot added by an earlier `scene.add`. ASSETS: `assets` binds each slot name a layer references to a media id in the same project, and the slot's declared KIND decides what it admits — an image slot takes PNG, JPEG or WebP, a video slot MP4 or WebM. Binding the wrong kind is refused with the slot's path." }, { "type": "object", "properties": { "type": { "type": "string", "const": "materializeGrid" }, "clipId": { "type": "string" }, "grid": { "type": "string", "enum": [ "beat", "word", "shot" ] }, "maxMarkers": { "type": "integer", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "type", "clipId", "grid" ], "additionalProperties": false, "description": "Materialize a clip's SOURCE-media temporal GRID as timeline markers — the rhythm authority you cut to. `grid:\"beat\"` reads a MUSIC bed's beat map (get_media_context.beatGrid), `grid:\"word\"` the VO word onsets (wordGrid); each grid point is projected from media time to TIMELINE time through the clip's placement (startTime, trim, playbackRate, excludedRanges) and written as a `kind:\"beat\"|\"word\"` marker (`metadata.sourceClipId` set). Points outside the clip's visible window are skipped. Re-running REPLACES the prior markers from the same clip+grid (idempotent). Land cuts and transition MIDPOINTS on the markers (a 0.5s transition starts 0.25s before its marker). `maxMarkers` (default 500, ceiling 2000) — exceeding it fails loud with the count. `grid:\"shot\"` is not yet exposed (shot_grid_unavailable). The target must be a media clip; absent evidence fails loud (grid_unavailable) naming how to get it (declare audioRole:\"music\" at ingest / transcribe)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "captions.fromTranscript" }, "mediaId": { "type": "string", "minLength": 1 }, "window": { "type": "object", "properties": { "startSec": { "type": "number", "minimum": 0 }, "endSec": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "startSec", "endSec" ], "additionalProperties": false } }, "required": [ "type", "mediaId" ], "additionalProperties": false, "description": "Attach caption CONTENT from the media's cached transcript — no pasting words. ROUTE-MATERIALIZED like materializeGrid: the server slices the word-timed transcript to `window` (source seconds; absent = the whole media), rebases times, sentence-splits into segments, and applies it as `setCaptions`. 422 media_no_transcript when the media has no transcript or no words in the window. For your OWN word timings use setCaptions directly. For edited multi-clip timelines, use captions.fromComposition after saving the edits; that operation projects all selected track clips, trims, exclusions, and placements." }, { "type": "object", "properties": { "type": { "type": "string", "const": "captions.fromComposition" }, "trackId": { "type": "string", "minLength": 1 } }, "required": [ "type", "trackId" ], "additionalProperties": false, "description": "Snapshot word-timed captions from the SAVED edits on one explicit enabled video or audio track. The host reads each source media transcript, projects words through clip trim, excluded ranges and placement, then replaces the caption segments. This is route-materialized to setCaptions; call it AFTER persisting clip edits and call it again when those edits change. The existing caption style and depth are preserved. Missing transcripts, unsupported clips, inconsistent clip durations, and overlapping audible clips fail loud. Playback rate scales source word times and playable duration on both audio and video tracks." }, { "type": "object", "properties": { "type": { "type": "string", "const": "setFormat" }, "format": { "type": "object", "properties": { "aspectRatio": { "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:5" ] }, "fps": { "anyOf": [ { "type": "number", "const": 24 }, { "type": "number", "const": 25 }, { "type": "number", "const": 30 }, { "type": "number", "const": 60 } ] }, "resolution": { "type": "string", "enum": [ "hd", "fhd", "4k" ] } }, "required": [ "aspectRatio" ] } }, "required": [ "type", "format" ], "additionalProperties": false, "description": "Set the output format — `aspectRatio` (16:9|9:16|1:1|4:5) plus optional `fps` and `resolution`. Merges: an omitted field keeps the current value." }, { "type": "object", "properties": { "type": { "type": "string", "const": "addTrack" }, "kind": { "type": "string", "enum": [ "video", "audio", "image", "overlay", "effect" ] }, "name": { "type": "string" }, "id": { "type": "string" } }, "required": [ "type", "kind" ], "additionalProperties": false, "description": "Add an EMPTY track of a given family (video|audio|image|overlay|effect). Optional pinned `id`. The new track is appended, so it starts at the BACK: index 0 is the top layer and higher indices are further back (see `reorderTracks`). Track order is the paint order for every family: a card on a track behind a video or image track draws behind it." }, { "type": "object", "properties": { "type": { "type": "string", "const": "removeTrack" }, "trackId": { "type": "string" } }, "required": [ "type", "trackId" ], "additionalProperties": false, "description": "Remove a track AND all its clips by id." }, { "type": "object", "properties": { "type": { "type": "string", "const": "updateTrack" }, "trackId": { "type": "string" }, "updates": { "type": "object", "properties": { "name": { "type": "string" }, "enabled": { "type": "boolean" }, "volume": { "type": "number", "minimum": 0, "maximum": 4 } }, "additionalProperties": false } }, "required": [ "type", "trackId", "updates" ], "additionalProperties": false, "description": "Patch a track's `name` / `enabled` by id. Track volume is retired: set each clip's own volume." }, { "type": "object", "properties": { "type": { "type": "string", "const": "reorderTracks" }, "fromIndex": { "type": "number" }, "toIndex": { "type": "number" } }, "required": [ "type", "fromIndex", "toIndex" ], "additionalProperties": false, "description": "Move a track from one index to another. ORDER: index 0 is the TOP layer, not the bottom — moving a backdrop to index 0 puts it in FRONT of everything and hides the composition. Higher index = further back. Track order is the paint order for every family, so cards, overlays, images and video interleave by index: a backdrop card, a screenshot and a foreground card on three tracks stack in that order. The one exception is `zPlane:\"behind-subject\"`, which moves the overlay inside its host clip, behind the segmented foreground." }, { "type": "object", "properties": { "type": { "type": "string", "const": "moveClipToTrack" }, "clipId": { "type": "string" }, "targetTrackId": { "type": "string" }, "newStartTime": { "type": "number" } }, "required": [ "type", "clipId", "targetTrackId" ], "additionalProperties": false, "description": "Move a clip to another SAME-family track, optionally at a new `newStartTime`." }, { "type": "object", "properties": { "type": { "type": "string", "const": "duplicateClip" }, "clipId": { "type": "string" }, "newClipId": { "type": "string" } }, "required": [ "type", "clipId" ], "additionalProperties": false, "description": "Duplicate a clip by id. Pin `newClipId` to make the copy's id deterministic (required for a clean undo/inverse)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "cutAndRipple" }, "start": { "type": "number" }, "end": { "type": "number" } }, "required": [ "type", "start", "end" ], "additionalProperties": false, "description": "Server-authoritative: delete the [start,end] time window (seconds) and ripple every downstream clip/marker/caption earlier to close the gap. Cuts apply sequentially in TIMELINE seconds: each cut moves everything after it, so a later cut's coordinates go stale once an earlier one lands. Plan several cuts back to front (latest first), or send them as one `cutRanges`. To drop spans inside one clip, `addExcludedRange` takes SOURCE seconds and is order-independent." }, { "type": "object", "properties": { "type": { "type": "string", "const": "cutRanges" }, "ranges": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number" }, "end": { "type": "number" } }, "required": [ "start", "end" ], "additionalProperties": false } } }, "required": [ "type", "ranges" ], "additionalProperties": false, "description": "Server-authoritative: delete several [start,end] windows (seconds) in one atomic edit, one undo step. Every range is in timeline seconds of the composition as it is BEFORE this op, in any order; overlapping and touching ranges merge. Each must satisfy 0 <= start < end <= the timeline's end. The cuts apply back to front with exactly `cutAndRipple`'s ripple (every track, markers and derived captions move earlier), so no coordinate goes stale." }, { "type": "object", "properties": { "type": { "type": "string", "const": "ripple" }, "time": { "type": "number" }, "amount": { "type": "number" } }, "required": [ "type", "time", "amount" ], "additionalProperties": false, "description": "Server-authoritative: shift everything at/after `time` (seconds) by `amount` seconds (+ opens a gap, − closes one)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "addExcludedRange" }, "clipId": { "type": "string" }, "sourceStart": { "type": "number" }, "sourceEnd": { "type": "number" }, "reason": { "type": "string" } }, "required": [ "type", "clipId", "sourceStart", "sourceEnd" ], "additionalProperties": false, "description": "Server-authoritative: exclude a [sourceStart,sourceEnd] span (seconds) of a clip's SOURCE (an internal trim) and ripple downstream — the preferred way to drop a sub-range vs a source patch. Coordinates are SOURCE seconds, which a cut or another exclusion never shifts, so several exclusions on one clip can be sent in any order." }, { "type": "object", "properties": { "type": { "type": "string", "const": "removeExcludedRange" }, "clipId": { "type": "string" }, "rangeIdx": { "type": "number" } }, "required": [ "type", "clipId", "rangeIdx" ], "additionalProperties": false, "description": "Server-authoritative: remove a clip's previously-added excluded range by index (re-includes that span, ripples downstream)." }, { "type": "object", "properties": { "type": { "type": "string", "const": "component.repin-v3" }, "componentId": { "type": "string", "minLength": 1 }, "from": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "to": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "expectedCompositionEtag": { "type": "string", "minLength": 1 }, "changes": { "minItems": 1, "maxItems": 512, "type": "array", "items": { "type": "object", "properties": { "placementId": { "type": "string", "minLength": 1 }, "before": { "$ref": "#/$defs/ComponentExecutionRef" }, "after": { "$ref": "#/$defs/ComponentExecutionRef" } }, "required": [ "placementId", "before", "after" ], "additionalProperties": false } } }, "required": [ "type", "componentId", "from", "to", "expectedCompositionEtag", "changes" ], "additionalProperties": false, "description": "Atomically repin explicit version3 invocations using complete before/after execution references and an exact composition etag. Persistence must canonically admit scoped source hashes, destination input schemas and every resulting target context before applying, including replay/undo. Never infer a latest head, downgrade versions or accept an admitted flag." } ], "description": "One scoped composition operation. Discriminated by `type` — `clip.add` / `clip.remove` / `clip.update` patch clips across any family; the rest cover markers, reframe, effects, captions, format, tracks, and the server-authoritative ripple recomputes. Every variant is `.strict()`: an unknown field is refused, not ignored." }, "SceneShotSpecV2": { "type": "object", "properties": { "version": { "type": "number", "const": 2 }, "referenceSize": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 16, "maximum": 8192 }, "height": { "type": "integer", "minimum": 16, "maximum": 8192 } }, "required": [ "width", "height" ], "additionalProperties": false }, "camera": { "type": "object", "properties": { "position": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "fov": { "type": "number", "minimum": 0.3141592653589793, "maximum": 1.3962634015954636 } }, "additionalProperties": false }, "environment": { "default": { "lightingProfile": "studio", "preset": "soft", "intensity": 1, "floorY": -420, "shadowOpacity": 0.5 }, "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "studio" }, "lightingProfile": { "default": "studio", "type": "string", "enum": [ "studio", "studio-edge" ] }, "preset": { "default": "soft", "type": "string", "enum": [ "soft", "key", "rim" ] }, "intensity": { "default": 1, "type": "number", "minimum": 0 }, "floorY": { "default": -420, "type": "number" }, "shadowOpacity": { "default": 0.5, "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "photographic-studio-v1" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "owned-hdr-v1" }, "assetSlot": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$", "description": "Image asset slot name bound by the clip assets map; never a URL." }, "intensity": { "default": 1, "type": "number", "minimum": 0, "maximum": 100 }, "rotation": { "default": 0, "type": "number", "minimum": -6.283185307179586, "maximum": 6.283185307179586 } }, "required": [ "kind", "assetSlot" ], "additionalProperties": false } ] }, "backdrop": { "default": { "kind": "transparent" }, "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "transparent" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "solid" }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] } }, "required": [ "kind", "color" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "linear" }, "angle": { "default": 0, "type": "number" }, "stops": { "minItems": 2, "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "minimum": 0, "maximum": 1 }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] } }, "required": [ "at", "color" ], "additionalProperties": false } } }, "required": [ "kind", "stops" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "radial" }, "at": { "default": [ 0.5, 0.5 ], "type": "array", "prefixItems": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "number", "minimum": 0, "maximum": 1 } ], "items": false, "minItems": 2, "maxItems": 2 }, "stops": { "minItems": 2, "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "minimum": 0, "maximum": 1 }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] } }, "required": [ "at", "color" ], "additionalProperties": false } } }, "required": [ "kind", "stops" ], "additionalProperties": false } ] }, "layers": { "minItems": 1, "type": "array", "items": { "$ref": "#/$defs/SceneShotSpecV2Schema0" } }, "animation": { "default": [], "type": "array", "items": { "type": "object", "properties": { "target": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "camera" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "layer" }, "layerId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" } }, "required": [ "kind", "layerId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "environment" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "focus" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "bloom" } }, "required": [ "kind" ], "additionalProperties": false } ] }, "property": { "type": "string", "enum": [ "positionX", "positionY", "positionZ", "rotationX", "rotationY", "rotationZ", "fov", "scale", "opacity", "openAngle", "x", "y", "rotation", "intensity", "distance", "range", "maxBlur", "strength", "threshold", "smoothing", "radius" ] }, "keyframes": { "minItems": 1, "maxItems": 256, "type": "array", "items": { "type": "object", "properties": { "at": { "type": "number", "minimum": 0, "maximum": 1 }, "value": { "type": "number" }, "easing": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "linear" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "hold" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "bezier" }, "x1": { "type": "number", "minimum": 0, "maximum": 1 }, "y1": { "type": "number", "minimum": -4, "maximum": 5 }, "x2": { "type": "number", "minimum": 0, "maximum": 1 }, "y2": { "type": "number", "minimum": -4, "maximum": 5 } }, "required": [ "kind", "x1", "y1", "x2", "y2" ], "additionalProperties": false } ] } }, "required": [ "at", "value" ], "additionalProperties": false } } }, "required": [ "target", "property", "keyframes" ], "additionalProperties": false } }, "post": { "default": { "grain": 0, "vignette": 0, "focus": null, "bloom": null }, "type": "object", "properties": { "grain": { "default": 0, "type": "number", "minimum": 0, "maximum": 0.5 }, "vignette": { "default": 0, "type": "number", "minimum": 0, "maximum": 1 }, "focus": { "default": null, "anyOf": [ { "type": "object", "properties": { "distance": { "type": "number", "exclusiveMinimum": 0 }, "range": { "type": "number", "exclusiveMinimum": 0 }, "maxBlur": { "type": "number", "minimum": 0, "maximum": 64 } }, "required": [ "distance", "range", "maxBlur" ], "additionalProperties": false }, { "type": "null" } ] }, "bloom": { "default": null, "anyOf": [ { "type": "object", "properties": { "profile": { "default": "display-linear-bloom-v1", "type": "string", "const": "display-linear-bloom-v1" }, "strength": { "default": 0.3, "type": "number", "minimum": 0, "maximum": 1 }, "threshold": { "default": 0.8, "type": "number", "minimum": 0, "maximum": 1 }, "smoothing": { "default": 0.03, "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "radius": { "default": 0.85, "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, "constraints": { "default": [], "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "const": "minSeparation" }, "objects": { "minItems": 2, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" } }, "gap": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "kind", "objects", "gap" ], "additionalProperties": false } } }, "required": [ "version", "referenceSize", "layers" ], "additionalProperties": false, "description": "A version-2 scene shot: a self-contained 3D world-object shot that scene.add / scene.update materializes into an ordinary component clip. The shot owns its layers, camera, lighting, backdrop and normalized local animation; the composition owns start, duration, ordering, cuts and transitions. World coordinates are REFERENCE PIXELS: origin at frame centre, +X right, +Y up, +Z toward the viewer. World rotations, camera fov and laptop openAngle are radians. referenceSize must have the SAME aspect ratio as the composition format; mismatch fails instead of cropping. At equal aspect ratio the shot scales uniformly by outputWidth/referenceWidth. A segment's easing belongs to the keyframe it ARRIVES at; the first keyframe has no easing. Authoring limits: 32 layers, 4 devices, 16 distinct image slots, 256 keyframes per channel, 2048 keyframes per shot. Version 2 supports nested groups, procedural slab/page/phone/laptop objects and owned static GLB models with bounded embedded PNG/JPEG textures (static-glb-untextured-v1 or static-glb-textured-v1; model-level transforms and digest-scoped scalar material edits), screen- and world-space text, admitted image/component/video surfaces, fixed photographic, generated studio and owned RGBE 1024x512 environment data assets (up to 8 MiB encoded; intensity 0–100 and rotation ±2π radians), transparent/solid/linear/radial backdrops, constraints, focus, bounded display-linear-bloom-v1 before grain/vignette, measured single-camera half-float/MSAA4 physical transmission, and opaque stateless-fragment-display-linear-v1 mesh.shader fields. mesh.shader owns vec3 field(vec2 uv, vec3 localPosition), at most32 finite typed uniforms and4 owned PNG/JPEG image samplers, deterministic cfFrame/cfRate/cfTime/cfSeed/cfResolution inputs; source is parsed and locally compiled/drawn before first playback or exact frame. It requires non-instanced UV geometry and effective world opacity1. Raw HTML, arbitrary custom shader props or full GLSL, loops/recursion/macros/extensions/derivatives/scene sampling/feedback/depth writes, animated/compressed/skeletal GLB profiles, subnode editing, arbitrary external HDR environments, skeletal animation and physics are refused with an exact field path." }, "SceneShotSpecV2Schema0": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "group" }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "transform": { "default": { "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scale": 1 }, "type": "object", "properties": { "position": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "opacity": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "children": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "$ref": "#/$defs/SceneShotSpecV2Schema0" } } }, "required": [ "kind", "id", "children" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "laptop" }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "transform": { "default": { "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scale": 1 }, "type": "object", "properties": { "position": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "opacity": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 200, "maximum": 4000 }, "openAngle": { "type": "number", "minimum": 0, "maximum": 3.141592653589793 }, "materials": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "physical", "unlit" ] }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "roughness": { "type": "number", "minimum": 0, "maximum": 1 }, "metalness": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoat": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoatRoughness": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropy": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropyRotation": { "type": "number" }, "ior": { "type": "number", "minimum": 1, "maximum": 2.333 }, "reflectivity": { "type": "number", "minimum": 0, "maximum": 1 }, "emissive": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "emissiveIntensity": { "type": "number", "minimum": 0 }, "transmission": { "description": "Nonzero transmission uses the measured pinned single-camera half-float/MSAA4 profile with canonical preparation and observed target allocations; unsupported renderer profiles refuse.", "type": "number", "minimum": 0, "maximum": 1 }, "thickness": { "description": "Optical thickness in scene reference pixels.", "type": "number", "minimum": 0 }, "attenuationColor": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "attenuationDistance": { "description": "Attenuation distance in scene reference pixels.", "type": "number", "exclusiveMinimum": 0 }, "dispersion": { "type": "number", "minimum": 0 } }, "required": [ "role", "type" ], "additionalProperties": false } }, "surfaces": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "image" }, "assetSlot": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$", "description": "Image asset slot name bound by the clip assets map; never a URL." } }, "required": [ "source", "assetSlot" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "color" }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] } }, "required": [ "source", "color" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "component" }, "component": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "componentId": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "version", "componentId", "sourceVersionId" ], "additionalProperties": false }, "captureFrame": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layout": { "type": "object", "properties": { "width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "width", "height" ], "additionalProperties": false }, "bakeScale": { "description": "Optional authored scale. Preparation defaults omission to 2 and may auto-raise it to 3.", "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/SceneShotSpecV2Schema1" } } }, "required": [ "source", "component", "captureFrame", "layout" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "video" }, "mediaId": { "type": "string", "minLength": 1, "maxLength": 256 }, "startFrame": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endFrame": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "source", "mediaId" ], "additionalProperties": false } ] } } }, "required": [ "kind", "id", "width", "openAngle" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "phone" }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "transform": { "default": { "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scale": 1 }, "type": "object", "properties": { "position": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "opacity": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 80, "maximum": 2000 }, "materials": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "physical", "unlit" ] }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "roughness": { "type": "number", "minimum": 0, "maximum": 1 }, "metalness": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoat": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoatRoughness": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropy": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropyRotation": { "type": "number" }, "ior": { "type": "number", "minimum": 1, "maximum": 2.333 }, "reflectivity": { "type": "number", "minimum": 0, "maximum": 1 }, "emissive": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "emissiveIntensity": { "type": "number", "minimum": 0 }, "transmission": { "description": "Nonzero transmission uses the measured pinned single-camera half-float/MSAA4 profile with canonical preparation and observed target allocations; unsupported renderer profiles refuse.", "type": "number", "minimum": 0, "maximum": 1 }, "thickness": { "description": "Optical thickness in scene reference pixels.", "type": "number", "minimum": 0 }, "attenuationColor": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "attenuationDistance": { "description": "Attenuation distance in scene reference pixels.", "type": "number", "exclusiveMinimum": 0 }, "dispersion": { "type": "number", "minimum": 0 } }, "required": [ "role", "type" ], "additionalProperties": false } }, "surfaces": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "image" }, "assetSlot": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$", "description": "Image asset slot name bound by the clip assets map; never a URL." } }, "required": [ "source", "assetSlot" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "color" }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] } }, "required": [ "source", "color" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "component" }, "component": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "componentId": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "version", "componentId", "sourceVersionId" ], "additionalProperties": false }, "captureFrame": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layout": { "type": "object", "properties": { "width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "width", "height" ], "additionalProperties": false }, "bakeScale": { "description": "Optional authored scale. Preparation defaults omission to 2 and may auto-raise it to 3.", "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/SceneShotSpecV2Schema1" } } }, "required": [ "source", "component", "captureFrame", "layout" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "video" }, "mediaId": { "type": "string", "minLength": 1, "maxLength": 256 }, "startFrame": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endFrame": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "source", "mediaId" ], "additionalProperties": false } ] } } }, "required": [ "kind", "id", "width" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "slab" }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "transform": { "default": { "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scale": 1 }, "type": "object", "properties": { "position": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "opacity": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 40, "maximum": 8000 }, "height": { "type": "number", "minimum": 40, "maximum": 8000 }, "thickness": { "default": 32, "type": "number", "minimum": 4, "maximum": 200 }, "cornerRadius": { "default": 32, "type": "number", "minimum": 0 }, "edgeRadius": { "default": 15, "type": "number", "minimum": 0 }, "finish": { "default": "satin", "type": "string", "enum": [ "satin", "brushed" ] }, "materials": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "physical", "unlit" ] }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "roughness": { "type": "number", "minimum": 0, "maximum": 1 }, "metalness": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoat": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoatRoughness": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropy": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropyRotation": { "type": "number" }, "ior": { "type": "number", "minimum": 1, "maximum": 2.333 }, "reflectivity": { "type": "number", "minimum": 0, "maximum": 1 }, "emissive": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "emissiveIntensity": { "type": "number", "minimum": 0 }, "transmission": { "description": "Nonzero transmission uses the measured pinned single-camera half-float/MSAA4 profile with canonical preparation and observed target allocations; unsupported renderer profiles refuse.", "type": "number", "minimum": 0, "maximum": 1 }, "thickness": { "description": "Optical thickness in scene reference pixels.", "type": "number", "minimum": 0 }, "attenuationColor": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "attenuationDistance": { "description": "Attenuation distance in scene reference pixels.", "type": "number", "exclusiveMinimum": 0 }, "dispersion": { "type": "number", "minimum": 0 } }, "required": [ "role", "type" ], "additionalProperties": false } }, "surfaces": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "image" }, "assetSlot": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$", "description": "Image asset slot name bound by the clip assets map; never a URL." } }, "required": [ "source", "assetSlot" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "color" }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] } }, "required": [ "source", "color" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "component" }, "component": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "componentId": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "version", "componentId", "sourceVersionId" ], "additionalProperties": false }, "captureFrame": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layout": { "type": "object", "properties": { "width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "width", "height" ], "additionalProperties": false }, "bakeScale": { "description": "Optional authored scale. Preparation defaults omission to 2 and may auto-raise it to 3.", "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/SceneShotSpecV2Schema1" } } }, "required": [ "source", "component", "captureFrame", "layout" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "video" }, "mediaId": { "type": "string", "minLength": 1, "maxLength": 256 }, "startFrame": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endFrame": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "source", "mediaId" ], "additionalProperties": false } ] } } }, "required": [ "kind", "id", "width", "height" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "page" }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "transform": { "default": { "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scale": 1 }, "type": "object", "properties": { "position": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "opacity": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 40, "maximum": 8000 }, "height": { "type": "number", "minimum": 40, "maximum": 8000 }, "fit": { "default": "contain", "type": "string", "enum": [ "contain", "cover" ] }, "transparency": { "default": "straight", "type": "string", "enum": [ "straight", "premultiplied", "opaque" ] }, "depthWrite": { "default": true, "type": "boolean" }, "backface": { "default": "hidden", "type": "string", "enum": [ "hidden", "visible" ] }, "materials": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "physical", "unlit" ] }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "roughness": { "type": "number", "minimum": 0, "maximum": 1 }, "metalness": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoat": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoatRoughness": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropy": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropyRotation": { "type": "number" }, "ior": { "type": "number", "minimum": 1, "maximum": 2.333 }, "reflectivity": { "type": "number", "minimum": 0, "maximum": 1 }, "emissive": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "emissiveIntensity": { "type": "number", "minimum": 0 }, "transmission": { "description": "Nonzero transmission uses the measured pinned single-camera half-float/MSAA4 profile with canonical preparation and observed target allocations; unsupported renderer profiles refuse.", "type": "number", "minimum": 0, "maximum": 1 }, "thickness": { "description": "Optical thickness in scene reference pixels.", "type": "number", "minimum": 0 }, "attenuationColor": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "attenuationDistance": { "description": "Attenuation distance in scene reference pixels.", "type": "number", "exclusiveMinimum": 0 }, "dispersion": { "type": "number", "minimum": 0 } }, "required": [ "role", "type" ], "additionalProperties": false } }, "surfaces": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "image" }, "assetSlot": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$", "description": "Image asset slot name bound by the clip assets map; never a URL." } }, "required": [ "source", "assetSlot" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "color" }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] } }, "required": [ "source", "color" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "component" }, "component": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "componentId": { "type": "string", "minLength": 1, "maxLength": 256 }, "sourceVersionId": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "version", "componentId", "sourceVersionId" ], "additionalProperties": false }, "captureFrame": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "layout": { "type": "object", "properties": { "width": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "height": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "width", "height" ], "additionalProperties": false }, "bakeScale": { "description": "Optional authored scale. Preparation defaults omission to 2 and may auto-raise it to 3.", "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/SceneShotSpecV2Schema1" } } }, "required": [ "source", "component", "captureFrame", "layout" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "video" }, "mediaId": { "type": "string", "minLength": 1, "maxLength": 256 }, "startFrame": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "endFrame": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "source", "mediaId" ], "additionalProperties": false } ] } } }, "required": [ "kind", "id", "width", "height", "surfaces" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "mesh" }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "transform": { "default": { "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scale": 1 }, "type": "object", "properties": { "position": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "opacity": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "geometry": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "buffer" }, "positions": { "minItems": 9, "maxItems": 196605, "type": "array", "items": { "type": "number", "minimum": -1000000, "maximum": 1000000 } }, "normals": { "minItems": 9, "maxItems": 196605, "type": "array", "items": { "type": "number", "minimum": -1, "maximum": 1 } }, "uvs": { "minItems": 6, "maxItems": 131070, "type": "array", "items": { "type": "number", "minimum": -1000000, "maximum": 1000000 } }, "indices": { "minItems": 3, "maxItems": 750000, "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "required": [ "kind", "positions", "normals", "uvs", "indices" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "tube" }, "points": { "minItems": 2, "maxItems": 256, "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "number", "minimum": -1000000, "maximum": 1000000 }, { "type": "number", "minimum": -1000000, "maximum": 1000000 }, { "type": "number", "minimum": -1000000, "maximum": 1000000 } ], "items": false, "minItems": 3, "maxItems": 3 } }, "radius": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "closed": { "type": "boolean" }, "tubularSegments": { "type": "integer", "minimum": 1, "maximum": 1024 }, "radialSegments": { "type": "integer", "minimum": 3, "maximum": 64 } }, "required": [ "kind", "points", "radius", "closed", "tubularSegments", "radialSegments" ], "additionalProperties": false } ] }, "materials": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "physical", "unlit" ] }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "roughness": { "type": "number", "minimum": 0, "maximum": 1 }, "metalness": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoat": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoatRoughness": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropy": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropyRotation": { "type": "number" }, "ior": { "type": "number", "minimum": 1, "maximum": 2.333 }, "reflectivity": { "type": "number", "minimum": 0, "maximum": 1 }, "emissive": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "emissiveIntensity": { "type": "number", "minimum": 0 }, "transmission": { "description": "Nonzero transmission uses the measured pinned single-camera half-float/MSAA4 profile with canonical preparation and observed target allocations; unsupported renderer profiles refuse.", "type": "number", "minimum": 0, "maximum": 1 }, "thickness": { "description": "Optical thickness in scene reference pixels.", "type": "number", "minimum": 0 }, "attenuationColor": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "attenuationDistance": { "description": "Attenuation distance in scene reference pixels.", "type": "number", "exclusiveMinimum": 0 }, "dispersion": { "type": "number", "minimum": 0 } }, "required": [ "role", "type" ], "additionalProperties": false } }, "shader": { "type": "object", "properties": { "profile": { "default": "stateless-fragment-display-linear-v1", "type": "string", "const": "stateless-fragment-display-linear-v1" }, "source": { "type": "string", "minLength": 1, "maxLength": 32768 }, "uniforms": { "default": {}, "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" }, "additionalProperties": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "float", "int", "uint", "bool", "vec2", "vec3", "vec4", "mat2", "mat3", "mat4" ] }, "value": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "number" } } ] } }, "required": [ "type", "value" ], "additionalProperties": false } }, "samplers": { "default": {}, "type": "object", "propertyNames": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" }, "additionalProperties": { "type": "object", "properties": { "assetSlot": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$", "description": "Image asset slot name bound by the clip assets map; never a URL." }, "colorSpace": { "type": "string", "enum": [ "srgb", "data" ] } }, "required": [ "assetSlot", "colorSpace" ], "additionalProperties": false } } }, "required": [ "source" ], "additionalProperties": false }, "instances": { "minItems": 1, "maxItems": 1024, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "transform": { "default": { "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scale": 1 }, "type": "object", "properties": { "position": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false } } }, "required": [ "kind", "id", "geometry" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "model" }, "profile": { "default": "static-glb-untextured-v1", "type": "string", "enum": [ "static-glb-untextured-v1", "static-glb-textured-v1" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "transform": { "default": { "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scale": 1 }, "type": "object", "properties": { "position": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false }, "opacity": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "assetSlot": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$", "description": "Image asset slot name bound by the clip assets map; never a URL." }, "size": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "materials": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "minLength": 1, "maxLength": 64 }, "type": { "type": "string", "enum": [ "physical", "unlit" ] }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "roughness": { "type": "number", "minimum": 0, "maximum": 1 }, "metalness": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoat": { "type": "number", "minimum": 0, "maximum": 1 }, "clearcoatRoughness": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropy": { "type": "number", "minimum": 0, "maximum": 1 }, "anisotropyRotation": { "type": "number" }, "ior": { "type": "number", "minimum": 1, "maximum": 2.333 }, "reflectivity": { "type": "number", "minimum": 0, "maximum": 1 }, "emissive": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "emissiveIntensity": { "type": "number", "minimum": 0 }, "transmission": { "description": "Nonzero transmission uses the measured pinned single-camera half-float/MSAA4 profile with canonical preparation and observed target allocations; unsupported renderer profiles refuse.", "type": "number", "minimum": 0, "maximum": 1 }, "thickness": { "description": "Optical thickness in scene reference pixels.", "type": "number", "minimum": 0 }, "attenuationColor": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "attenuationDistance": { "description": "Attenuation distance in scene reference pixels.", "type": "number", "exclusiveMinimum": 0 }, "dispersion": { "type": "number", "minimum": 0 } }, "required": [ "role", "type" ], "additionalProperties": false } }, "materialSourceSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "kind", "id", "assetSlot", "size" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "kind": { "type": "string", "const": "text" }, "opacity": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "lines": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "object", "properties": { "runs": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\r\\n]+$" }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "emphasis": { "type": "boolean" } }, "required": [ "text" ], "additionalProperties": false } } }, "required": [ "runs" ], "additionalProperties": false } }, "fontFamily": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9 _.\\-]*$" }, { "type": "string", "enum": [ "$brand:fonts.heading", "$brand:fonts.body", "$brand:fonts.caption" ] } ] }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "fontStyle": { "type": "string", "enum": [ "normal", "italic" ] }, "fontSize": { "type": "number", "minimum": 8, "maximum": 800 }, "lineHeight": { "default": 1.2, "type": "number", "minimum": 0.6, "maximum": 3 }, "letterSpacing": { "default": 0, "type": "number", "minimum": -20, "maximum": 40 }, "align": { "default": "center", "type": "string", "enum": [ "left", "center", "right" ] }, "maxWidth": { "type": "number", "exclusiveMinimum": 0 }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "space": { "type": "string", "const": "world" }, "transform": { "default": { "position": [ 0, 0, 0 ], "rotation": [ 0, 0, 0 ], "scale": 1 }, "type": "object", "properties": { "position": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "rotation": { "default": [ 0, 0, 0 ], "type": "array", "prefixItems": [ { "type": "number" }, { "type": "number" }, { "type": "number" } ], "items": false, "minItems": 3, "maxItems": 3 }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "additionalProperties": false } }, "required": [ "id", "kind", "lines", "fontFamily", "fontWeight", "fontStyle", "fontSize", "color", "space" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*$" }, "kind": { "type": "string", "const": "text" }, "opacity": { "default": 1, "type": "number", "minimum": 0, "maximum": 1 }, "lines": { "minItems": 1, "maxItems": 24, "type": "array", "items": { "type": "object", "properties": { "runs": { "minItems": 1, "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\r\\n]+$" }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "emphasis": { "type": "boolean" } }, "required": [ "text" ], "additionalProperties": false } } }, "required": [ "runs" ], "additionalProperties": false } }, "fontFamily": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9 _.\\-]*$" }, { "type": "string", "enum": [ "$brand:fonts.heading", "$brand:fonts.body", "$brand:fonts.caption" ] } ] }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "fontStyle": { "type": "string", "enum": [ "normal", "italic" ] }, "fontSize": { "type": "number", "minimum": 8, "maximum": 800 }, "lineHeight": { "default": 1.2, "type": "number", "minimum": 0.6, "maximum": 3 }, "letterSpacing": { "default": 0, "type": "number", "minimum": -20, "maximum": 40 }, "align": { "default": "center", "type": "string", "enum": [ "left", "center", "right" ] }, "maxWidth": { "type": "number", "exclusiveMinimum": 0 }, "color": { "anyOf": [ { "type": "string", "pattern": "^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" }, { "type": "string", "enum": [ "$brand:colors.background", "$brand:colors.surface", "$brand:colors.text", "$brand:colors.textMuted", "$brand:colors.accent", "$brand:colors.accentStrong", "$brand:colors.accentSoft", "$brand:colors.success", "$brand:colors.warning", "$brand:colors.danger" ] } ] }, "space": { "type": "string", "const": "screen" }, "x": { "type": "number" }, "y": { "type": "number" }, "rotation": { "default": 0, "type": "number" }, "scale": { "default": 1, "type": "number", "exclusiveMinimum": 0 } }, "required": [ "id", "kind", "lines", "fontFamily", "fontWeight", "fontStyle", "fontSize", "color", "space", "x", "y" ], "additionalProperties": false } ] }, "SceneShotSpecV2Schema1": { "anyOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": { "$ref": "#/$defs/SceneShotSpecV2Schema1" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/SceneShotSpecV2Schema1" } } ] }, "TimelineClip": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "startTime": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "source": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "media" }, "mediaId": { "type": "string" }, "trim": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 } }, "required": [ "start", "end" ] }, "excludedRanges": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 }, "reason": { "type": "string" } }, "required": [ "start", "end" ] } }, "volume": { "type": "number", "minimum": 0, "maximum": 4 }, "muted": { "type": "boolean" }, "playbackRate": { "type": "number", "exclusiveMinimum": 0 }, "sync": { "type": "string", "enum": [ "video", "independent" ] }, "kenBurns": { "description": "Still-image motion. When unset, an image clip slowly pushes in (`in`) unless its fit is `contain` or it keyframes scale, position or rotation, so a keyframed clip renders exactly its keyframed values; set `none` for a still that holds.", "type": "string", "enum": [ "in", "out", "pan-l", "pan-r", "none" ] }, "volumeDb": { "type": "number" }, "fadeInMs": { "type": "number", "minimum": 0 }, "fadeOutMs": { "type": "number", "minimum": 0 }, "loop": { "type": "boolean" }, "audioRole": { "description": "Mix role. A role sets the clip's default gain when it has no `volume` or `volumeDb`: vo 0 dB, sfx -6 dB, music -8 dB (-16 dB when any vo clip exists), ambience -22 dB. Set `volumeDb: 0` to keep a role and play the source at its own level.", "type": "string", "enum": [ "sfx", "music", "vo", "ambience" ] }, "duck": { "type": "object", "properties": { "duckDb": { "type": "number", "maximum": 0 }, "attackMs": { "type": "number", "minimum": 0 }, "releaseMs": { "type": "number", "minimum": 0 }, "windows": { "type": "array", "items": { "type": "object", "properties": { "startMs": { "type": "number" }, "endMs": { "type": "number" } }, "required": [ "startMs", "endMs" ] } } }, "required": [ "duckDb", "attackMs", "releaseMs" ] }, "anchor": { "type": "object", "properties": { "clipId": { "type": "string", "minLength": 1 }, "offsetMs": { "type": "number" } }, "required": [ "clipId", "offsetMs" ] }, "reframe": { "type": "object", "properties": { "segments": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "startSec": { "type": "number", "minimum": 0, "description": "Segment START in seconds, clip-relative. Segments tile the clip's duration in order." }, "endSec": { "type": "number", "exclusiveMinimum": 0, "description": "Segment END in seconds, clip-relative. The span (endSec − startSec) is this segment's duration — the window `ease` ramps over." }, "focus": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "frame-center" } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "point" }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "mode", "x", "y" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "face" }, "faceId": { "type": "string", "minLength": 1 }, "shotScale": { "type": "string", "enum": [ "close", "standard", "wide" ] } }, "required": [ "mode", "faceId" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "all-faces" } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "active-speaker" } }, "required": [ "mode" ] } ], "description": "WHO/WHAT the camera tracks this segment (the reframe center), selected by `mode`: `frame-center` = no tracking, hold the geometric center (static/graphic footage, or a pure zoom); `point` = lock to a fixed source-normalized {x,y} (a non-moving on-screen element); `face` = track a detected face by `faceId` (from get_media_context), with optional `shotScale` close|standard|wide for tightness; `all-faces` = frame the bounding box of every detected face (group/ensemble shots); `active-speaker` = follow whoever is speaking (diarized talking-head / podcast). Pick by what the beat is about; pair with `zoom` for how tight." }, "intent": { "description": "Optional editorial LABEL for diff/log readability (e.g. 'speaker-tight', 'wide-context'). Cosmetic — NOT honored by the derive math and excluded from the variant cache key.", "type": "string" }, "zoom": { "description": "How TIGHT the framing is — the fraction of the source the output viewport shows. <1 punches IN (a smaller source fraction, magnified to fill the frame); 1 = the full frame (no crop). ~0.6–0.8 is a moderate push-in, ~0.5 a tight close-up, 0.1 the maximum zoom. There is NO zoom-OUT past the full frame (max 1). Omit for the full frame. MUTUALLY EXCLUSIVE with `focus.shotScale`: a face-tracked shot is sized EITHER by the editorial scale (shotScale, calibrated to the detected face) OR by an explicit zoom — never both.", "type": "number", "minimum": 0.1, "maximum": 1 }, "ease": { "description": "Zoom/center ramp DURATIONS in SECONDS at this segment's edges — NOT a unitless 0–1 curve. ~0.3–0.6s reads as a snappy push; >1s reads sluggish. Keep `in` + `out` ≤ the segment's duration (endSec − startSec): the two edges share the span, so to ramp across the WHOLE segment set one edge to the full duration and the other to 0. Omit for an instant cut to this framing.", "type": "object", "properties": { "in": { "type": "number", "minimum": 0, "description": "Ease-IN ramp DURATION in seconds at the segment START." }, "out": { "type": "number", "minimum": 0, "description": "Ease-OUT ramp DURATION in seconds at the segment END." } }, "required": [ "in", "out" ] }, "bias": { "description": "Optional FINE framing nudge off the focus center, source-normalized in [−0.3, 0.3]. A small correction (headroom, rule-of-thirds), NOT a reframe — use `focus`/`zoom` for the actual shot. Omit (treated as 0) to sit dead-center on the focus.", "type": "object", "properties": { "x": { "type": "number", "minimum": -0.3, "maximum": 0.3, "description": "Horizontal nudge, source-normalized (+ = right)." }, "y": { "type": "number", "minimum": -0.3, "maximum": 0.3, "description": "Vertical nudge, source-normalized (+ = down)." } }, "required": [ "x", "y" ] } }, "required": [ "startSec", "endSec", "focus" ] } } }, "required": [ "segments" ] } }, "required": [ "kind", "mediaId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "component" }, "componentId": { "type": "string", "minLength": 1 }, "props": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "zPlane": { "type": "string", "enum": [ "front", "behind-subject" ] }, "execution": { "$ref": "#/$defs/ComponentExecutionRef" }, "placement": { "oneOf": [ { "type": "object", "properties": { "version": { "type": "number", "const": 3 }, "kind": { "type": "string", "const": "clip" } }, "required": [ "version", "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "version": { "type": "number", "const": 3 }, "kind": { "type": "string", "const": "content-slots" }, "slots": { "type": "object", "propertyNames": { "type": "string", "minLength": 1, "maxLength": 256 }, "additionalProperties": { "type": "object", "properties": { "targetClipIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "ownership": { "type": "string", "enum": [ "reference", "exclusive" ] } }, "required": [ "targetClipIds", "ownership" ], "additionalProperties": false } } }, "required": [ "version", "kind", "slots" ], "additionalProperties": false } ] }, "retired": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "kind", "componentId", "props" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "overlay" }, "primitiveId": { "type": "string", "minLength": 1, "pattern": "^(?!custom$)" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "zPlane": { "type": "string", "enum": [ "front", "behind-subject" ] }, "anchor": { "type": "object", "properties": { "space": { "type": "string", "const": "scene" }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "space", "x", "y" ] }, "parallax": { "type": "number", "minimum": -0.3, "maximum": 0.3 } }, "required": [ "kind", "primitiveId", "params" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "effect" }, "component": { "$ref": "#/$defs/ComponentExecutionRef" }, "targetTrackIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "wrapperOrder": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "primitiveId": { "type": "string", "minLength": 1 }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "card" }, "html": { "type": "string", "minLength": 1, "description": "Self-contained card markup sized to the format's pixel frame. Motion comes from frame-driven vars, never @keyframes or transition: --cf-frame, --cf-t (seconds), --cf-fps, --cf-duration, --cf-progress, --cf-ease, --cf-enter, --cf-exit. Visible copy goes in the html as plain text. Wrap a run in or \"chars\" and each unit becomes its own span carrying --cf-i (its index, the group carries --cf-n), so one rule staggers it (in chars, spaces count as units), e.g. opacity:clamp(0,calc(var(--cf-t)*4 - var(--cf-i)*.3),1). save_as_template binds that copy with textParams match." }, "tokens": { "description": "Style values the html reads as CSS custom properties: key x becomes --cf-x, so never put dashes in a key. Use tokens for colours and sizes, not visible copy.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "zPlane": { "type": "string", "const": "front" } }, "required": [ "kind", "html" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "composition" }, "compositionId": { "type": "string", "minLength": 1 }, "trim": { "type": "object", "properties": { "start": { "type": "number", "minimum": 0 }, "end": { "type": "number", "minimum": 0 } }, "required": [ "start", "end" ] } }, "required": [ "kind", "compositionId" ], "additionalProperties": false } ] }, "kind": { "type": "string", "enum": [ "video", "audio", "image", "overlay", "effect" ] }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "scale": { "type": "number", "exclusiveMinimum": 0 }, "rotation": { "type": "number" }, "position": { "type": "object", "properties": { "x": { "type": "number", "minimum": -1, "maximum": 2 }, "y": { "type": "number", "minimum": -1, "maximum": 2 } }, "required": [ "x", "y" ], "description": "Clip CENTRE as a fraction of the frame: {x:0.5,y:0.5} is dead centre, 0 to 1 is inside the frame, and a little overshoot (down to -1, up to 2) is how an entrance starts off-canvas. NOT pixels: the renderer maps x to `left: x*100%`, so `x: 180` sits 180 frame-widths away and draws nothing." }, "region": { "description": "A window in the frame that the clip draws into and is clipped to (top-left corner and size, each a frame fraction). Inside a region, `position` and `scale` act relative to that window, so content moved past its edge is cut off. Omit it to place the clip against the whole frame.", "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "w": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "h": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } }, "required": [ "x", "y", "w", "h" ] }, "fit": { "type": "string", "enum": [ "cover", "contain" ] }, "captionVisibility": { "description": "Video media clip only. Hide native captions while this clip is topmost and covers the lower picture, or when an opaque, effect-free clip has an explicitly full-frame region, even with fit:contain. Caption words and timings remain stored and resume when another visible clip takes over.", "type": "string", "enum": [ "visible", "hidden" ] }, "effects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "component": { "$ref": "#/$defs/ComponentExecutionRef" }, "window": { "type": "object", "properties": { "startTime": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "startTime", "duration" ], "additionalProperties": false }, "primitiveId": { "type": "string", "minLength": 1 }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } }, "transitionIn": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "id": { "type": "string", "minLength": 1 }, "component": { "$ref": "#/$defs/ComponentExecutionRef" }, "fromClipId": { "type": "string", "minLength": 1 }, "toClipId": { "type": "string", "minLength": 1 }, "handlePolicy": { "type": "string", "const": "outgoing-overrun-at-cut-v1" } }, "required": [ "type", "duration" ] }, "linkGroupId": { "type": "string", "minLength": 1 }, "tweens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "propertyGroup": { "type": "string", "enum": [ "visual", "scale", "rotation", "position" ] }, "position": { "type": "number" }, "duration": { "type": "number", "exclusiveMinimum": 0 }, "keyframes": { "type": "object", "properties": { "format": { "type": "string", "const": "percentage" }, "easeEach": { "type": "string", "const": "none" }, "keyframes": { "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "percentage": { "type": "number" }, "properties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "ease": { "type": "string" } }, "required": [ "percentage", "properties" ], "additionalProperties": false } } }, "required": [ "format", "easeEach", "keyframes" ], "additionalProperties": false } }, "required": [ "id", "propertyGroup", "position", "duration", "keyframes" ], "additionalProperties": false } }, "automation": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "lanes": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "const": "volume" }, "points": { "minItems": 2, "type": "array", "items": { "type": "object", "properties": { "t": { "type": "number" }, "v": { "type": "number" } }, "required": [ "t", "v" ], "additionalProperties": false } } }, "required": [ "target", "points" ], "additionalProperties": false } } }, "required": [ "version", "lanes" ], "additionalProperties": false }, "color": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "enabled": { "type": "boolean" }, "grade": { "type": "object", "properties": { "exposure": { "type": "number", "minimum": -4, "maximum": 4 }, "contrast": { "type": "number", "minimum": -1, "maximum": 1 }, "highlights": { "type": "number", "minimum": -1, "maximum": 1 }, "shadows": { "type": "number", "minimum": -1, "maximum": 1 }, "whites": { "type": "number", "minimum": -1, "maximum": 1 }, "blacks": { "type": "number", "minimum": -1, "maximum": 1 }, "temperature": { "type": "number", "minimum": -1, "maximum": 1 }, "tint": { "type": "number", "minimum": -1, "maximum": 1 }, "vibrance": { "type": "number", "minimum": -1, "maximum": 1 }, "saturation": { "type": "number", "minimum": -1, "maximum": 1 } }, "required": [ "exposure", "contrast", "highlights", "shadows", "whites", "blacks", "temperature", "tint", "vibrance", "saturation" ], "additionalProperties": false }, "looks": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "mediaId", "sha256", "enabled" ], "additionalProperties": false } }, "display": { "anyOf": [ { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "mediaId", "sha256", "enabled" ], "additionalProperties": false }, { "type": "object", "properties": { "bundled": { "type": "string", "enum": [ "daylight-negative", "tungsten-negative", "soft-negative", "slide", "black-and-white" ] }, "enabled": { "type": "boolean" } }, "required": [ "bundled", "enabled" ], "additionalProperties": false } ] }, "creative": { "type": "object", "properties": { "mediaId": { "type": "string" }, "sha256": { "type": "string" }, "enabled": { "type": "boolean" }, "strength": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "mediaId", "sha256", "enabled", "strength" ], "additionalProperties": false }, "halation": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "amount": { "type": "number", "minimum": 0, "maximum": 0.5 }, "radius": { "type": "number", "minimum": 0.0005, "maximum": 0.02 }, "threshold": { "type": "number", "minimum": 0, "maximum": 16 }, "tint": { "type": "array", "prefixItems": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "number", "minimum": 0, "maximum": 1 } ], "items": false, "minItems": 3, "maxItems": 3 } }, "required": [ "enabled", "amount", "radius", "threshold", "tint" ], "additionalProperties": false }, "grain": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "profile": { "type": "string", "enum": [ "daylight-negative", "tungsten-negative", "soft-negative", "slide", "black-and-white" ] }, "gauge": { "type": "string", "enum": [ "super8", "super16", "super35", "65mm" ] }, "amount": { "type": "number", "minimum": 0, "maximum": 2 }, "size": { "type": "number", "minimum": 0.5, "maximum": 4 }, "seed": { "type": "integer", "minimum": 0, "maximum": 4294967295 } }, "required": [ "enabled", "profile", "gauge", "amount", "size", "seed" ], "additionalProperties": false } }, "required": [ "version", "enabled", "grade", "looks" ], "additionalProperties": false }, "legacyKeyframes": { "type": "object", "properties": { "needsUpgrade": { "type": "boolean", "const": true }, "channels": { "type": "array", "items": { "type": "string" } }, "record": {} }, "required": [ "needsUpgrade", "channels", "record" ], "additionalProperties": false } }, "required": [ "id", "startTime", "duration", "source" ], "additionalProperties": false } } }