{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/cueframe-ai/json-schema/cueframe-ai-composition-read-response-schema.json", "title": "CompositionReadResponse", "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/CompositionReadResponse", "anyOf": [ { "type": "object", "properties": { "composition": { "$ref": "#/$defs/Composition" }, "composition_id": { "type": "string" }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dependencies": { "$ref": "#/$defs/CompositionDependencyRead" }, "expectedBrandIdentity": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "brandAuthorityError": { "type": "string" }, "needsUpgrade": { "type": "array", "items": { "$ref": "#/$defs/CompositionUpgradeNeed" } } }, "required": [ "composition", "composition_id", "revision", "dependencies" ], "additionalProperties": false }, { "$ref": "#/$defs/CompositionRead" } ], "$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" } } ] }, "Composition": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "format": { "$ref": "#/$defs/Format" }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "video", "audio", "image", "overlay", "effect" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "volume": { "type": "number", "minimum": 0, "maximum": 4 }, "contents": { "type": "array", "items": { "anyOf": [ { "$ref": "#/$defs/TimelineClip" }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "startTime": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "id", "startTime", "duration" ], "additionalProperties": false } ] } } }, "required": [ "id", "kind", "contents" ], "additionalProperties": false } }, "markers": { "type": "array", "items": { "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 } }, "captions": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "derived" }, "from": { "type": "object", "properties": { "clipId": { "type": "string" } }, "required": [ "clipId" ] }, "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 } } }, "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 } }, "wordSignature": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "segmentIndex", "wordStartIndex", "wordEndIndex", "region", "wordSignature" ], "additionalProperties": false } }, "zPlane": { "type": "string", "enum": [ "front", "behind-subject" ] } }, "required": [ "source", "from", "segments" ] }, { "type": "object", "properties": { "source": { "type": "string", "const": "authored" }, "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 } } }, "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 } }, "wordSignature": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "segmentIndex", "wordStartIndex", "wordEndIndex", "region", "wordSignature" ], "additionalProperties": false } }, "zPlane": { "type": "string", "enum": [ "front", "behind-subject" ] } }, "required": [ "source", "segments" ] } ] }, "sourceSuggestionId": { "readOnly": true, "type": "string" }, "license": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "source": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "type" ] }, "licenseVerification": { "readOnly": true, "type": "string", "enum": [ "attested", "cueframe-verified", "third-party-verified" ] }, "accessibility": { "type": "object", "properties": { "audioDescriptionTrackId": { "type": "string" }, "captionsTrackId": { "type": "string" }, "signLanguageTrackId": { "type": "string" }, "notes": { "type": "string" } } }, "ownerOrgId": { "readOnly": true, "type": "string" }, "acl": { "readOnly": true, "type": "object", "properties": { "public": { "type": "boolean" }, "readerOrgIds": { "type": "array", "items": { "type": "string" } }, "writerOrgIds": { "type": "array", "items": { "type": "string" } } } }, "media": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "inputTransform": { "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 } }, "required": [ "inputTransform" ], "additionalProperties": false } } }, "required": [ "v", "format", "tracks" ], "additionalProperties": false }, "CompositionDependencyRead": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "guarded" }, "basis": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 256 }, "token": { "type": "string", "maxLength": 65536 } }, "required": [ "key", "token" ], "additionalProperties": false } }, "absentClipToken": { "type": "string", "const": "null" } }, "required": [ "mode", "basis", "absentClipToken" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "exact" }, "reason": { "type": "string" } }, "required": [ "mode", "reason" ], "additionalProperties": false } ] }, "CompositionRead": { "type": "object", "properties": { "v": { "type": "number", "const": 1 }, "format": { "$ref": "#/$defs/Format" }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "video", "audio", "image", "overlay", "effect" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "volume": { "type": "number", "minimum": 0, "maximum": 4 }, "contents": { "type": "array", "items": { "anyOf": [ { "$ref": "#/$defs/TimelineClip" }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "startTime": { "type": "number", "minimum": 0 }, "duration": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "id", "startTime", "duration" ], "additionalProperties": false } ] } } }, "required": [ "id", "kind", "contents" ], "additionalProperties": false } }, "markers": { "type": "array", "items": { "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 } }, "captions": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "derived" }, "from": { "type": "object", "properties": { "clipId": { "type": "string" } }, "required": [ "clipId" ] }, "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 } } }, "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 } }, "wordSignature": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "segmentIndex", "wordStartIndex", "wordEndIndex", "region", "wordSignature" ], "additionalProperties": false } }, "zPlane": { "type": "string", "enum": [ "front", "behind-subject" ] } }, "required": [ "source", "from", "segments" ] }, { "type": "object", "properties": { "source": { "type": "string", "const": "authored" }, "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 } } }, "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 } }, "wordSignature": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "segmentIndex", "wordStartIndex", "wordEndIndex", "region", "wordSignature" ], "additionalProperties": false } }, "zPlane": { "type": "string", "enum": [ "front", "behind-subject" ] } }, "required": [ "source", "segments" ] } ] }, "sourceSuggestionId": { "readOnly": true, "type": "string" }, "license": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "source": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "type" ] }, "licenseVerification": { "readOnly": true, "type": "string", "enum": [ "attested", "cueframe-verified", "third-party-verified" ] }, "accessibility": { "type": "object", "properties": { "audioDescriptionTrackId": { "type": "string" }, "captionsTrackId": { "type": "string" }, "signLanguageTrackId": { "type": "string" }, "notes": { "type": "string" } } }, "ownerOrgId": { "readOnly": true, "type": "string" }, "acl": { "readOnly": true, "type": "object", "properties": { "public": { "type": "boolean" }, "readerOrgIds": { "type": "array", "items": { "type": "string" } }, "writerOrgIds": { "type": "array", "items": { "type": "string" } } } }, "media": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "inputTransform": { "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 } }, "required": [ "inputTransform" ], "additionalProperties": false } }, "needsUpgrade": { "type": "array", "items": { "$ref": "#/$defs/CompositionUpgradeNeed" } } }, "required": [ "v", "format", "tracks" ], "additionalProperties": false, "description": "A composition as GET /projects/:id/composition answers it: the kernel's Composition, plus `needsUpgrade` when clips are stored in a retired form (absent otherwise)." }, "CompositionUpgradeNeed": { "type": "object", "properties": { "clipId": { "type": "string" }, "kind": { "type": "string", "enum": [ "unpinned-component", "v3-component", "retired-primitive", "legacy-keyframes" ] }, "channels": { "type": "array", "items": { "type": "string" } }, "componentId": { "type": "string" }, "sourceVersionId": { "type": "string" }, "primitiveId": { "type": "string" }, "successorComponentId": { "type": "string" }, "successorSourceVersionId": { "type": "string" } }, "required": [ "clipId", "kind" ], "additionalProperties": false }, "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" ] }, "platform": { "type": "string" } }, "required": [ "aspectRatio" ] }, "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 } } }