Document & settings

This content is for v0.4. Switch to the latest version for up-to-date documentation.

Generated from project.v1.schema.json at the documented engine version. The schema checks shape only; the engine’s validation also checks ranges, limits, references and keyframe order.

`Project`

The deserialized shape of a Project, before its invariants are checked.

This is the wire contract, and the published JSON Schema is derived from it: a document the schema accepts has the right shape, and validate then decides whether it means anything.

Field	Type	Description
`audio`	MasterAudio	Master bus applied to the summed track audio. Default: `{"effects":[],"gain":{"mode":"constant","value":1},"limit…`
`compositions`	Composition[]	Composition graphs that clips show. Default: `[]`
`effect_resources`	EffectResource[]	Non-media resources referenced by effect invocations. Default: `[]`
`id`required	ProjectId	Stable identity of this project.
`name`required	string	Human-readable project name. It has no semantic meaning.
`schema_version`required	`1`	Document version. This build reads and writes only `CURRENT_SCHEMA_VERSION`.
`settings`required	ProjectSettings	Output-wide timeline settings.
`sources`required	MediaSource[]	Media resources referenced by clips.
`timeline`required	Timeline	Ordered visual and audio tracks.

`AudioStreamShape`

An audio stream's channel count and sample rate.

Field	Type	Description
`channels`required	integer (uint32)	Channel count.
`sample_rate`required	integer (uint32)	Samples per second per channel.

`EffectResource`

Host-resolved, non-media data consumed by one or more visual effects.

Field	Type	Description
`id`required	EffectResourceId	Stable identity referenced by effect invocations.
`kind`required	EffectResourceKind	Resource representation expected by the effect definition.
`locator`required	string	Opaque host locator. The core never opens it directly.

`EffectResourceId`

A stable effect-resource identifier.

Type: string

`EffectResourceKind`

Portable effect-resource categories supported by the render ABI.

"lut3d" A cubic, filterable RGB lookup table, normally authored as a .cube file.

`FrameRate`

A positive rational frame rate in reduced form, at most one frame per tick (120 000 frames per second).

Field	Type	Description
`den`required	integer (uint32)	Seconds per `num` frames. Positive.
`num`required	integer (uint32)	Frames per `den` seconds. Positive, and at most 120 000 times `den`.

`HdrSources`

What a project does with HDR sources.

"tone_map" Tone-map them into the SDR working space.
"reject" Refuse to render them.

`LoopMode`

How each pass of a Loop follows the one before.

"repeat" Every pass plays forward, from the start again. Sound fades out and in over LOOP_FADE_SECONDS at each wrap, so the jump does not click.
"ping_pong" Passes alternate forward and backward.

`MediaFingerprint`

Evidence of a source's media, each part recorded only when it was known.

A matching content hash proves the same bytes. Without one, the other parts can only show a difference. modified_ms narrows a search for candidates and never decides whether a candidate is the same media.

Field	Type	Description
`byte_length`	integer \| null	The file's length in bytes.
`color`	ColorMetadata \| null	The color the decoded pictures carry.
`content_sha256`	string \| null	SHA-256 of the whole file, as 64 lowercase hexadecimal digits.
`duration_ticks`	integer \| null	Where the media ends on its own timeline, in ticks: its first presentation plus its length, the end of any source range that reads it. A transport stream that starts at 1.4 s and lasts 2 s ends at 3.4 s. Non-negative.
`modified_ms`	integer \| null	The file's modification time, in milliseconds since the Unix epoch.
`streams`	StreamTopology \| null	The streams the file carries.

`MediaKind`

The payload domain of a source.

"video" A video stream, potentially with an audio stream.
"audio" An audio stream.
"image" A still visual image.
"generated" A picture the engine draws from the source's Generator. The host supplies nothing for it.
"composition" A composition of the project, drawn at the source time as its own time. The host supplies nothing for it; the media its nodes read, it supplies as for any composition.

`MediaSource`

A host-resolved media resource.

Field	Type	Description
`color_metadata`	ColorMetadata \| null	The color a `Video` source's pictures are in, which wins over what its frames and its stream are tagged with on every host: a host records it at import, or a document declares it to correct missing or wrong tags. `None` leaves the tags in charge. A still is read as sRGB code values whatever it declares. Default: `null`
`composition`	CompositionId \| null	The composition a `Composition` source shows; present exactly for that kind.
`fingerprint`	MediaFingerprint \| null	What the host found at the locator when the project recorded it, so another host can tell whether media it finds is the same. A generated source has none.
`generator`	Generator \| null	What a `Generated` source draws; present exactly for that kind. Default: `null`
`has_audio`	boolean	Whether this source's media has an audio stream: a fact of the file, so every host that imports it records the same, whether or not that host can decode the stream. A host that cannot reports so at run time and plays the source silent; the document keeps the stream for the hosts that can. `Audio` always does. A `Video` source declares it so that clips on a visual track contribute to the mix; leaving it unset keeps a video clip silent. Default: `false`
`id`required	SourceId	Stable source identity.
`kind`required	MediaKind	Media payload domain.
`locator`	string	Opaque URI or host locator. The engine does not open it directly. Required, except that a `Generated` or `Composition` source has none. Default: `""`
`provider`	ProviderSource \| null	The extension provider that supplies this source's media, and its settings, when the host's own decoders do not read it.

`MissingFrames`

How an image sequence shows a frame missing from its numbering.

"reject" A sequence with a missing frame is refused.
"hold" The frame before it is shown.
"blank" Nothing is shown: a transparent frame.

`ProjectId`

A stable project identifier.

Type: string

`ProjectSettings`

Output-wide settings independent of a renderer or encoder.

Field	Type	Description
`background`	Rgb	Opaque color under every layer, in preview and export alike. Empty canvas, and whatever shows through a translucent layer, is this color rather than something a host or encoder decides. Default: `{"blue":0,"green":0,"red":0}`
`blend_space`	BlendSpace	The space in which clips' blend modes are evaluated, in preview and export alike. Default: `"linear_light"`
`color`	ColorPipeline	How sources' colors come into the working space. Default: `{"hdr":"tone_map","hdr_peak_nits":1000}`
`frame_rate`required	FrameRate	Timeline frame rate.
`height`required	integer (uint32)	Canvas height in output pixels, at most `MAX_CANVAS_DIMENSION`. The canvas area is at most `MAX_CANVAS_PIXELS`.
`sample_rate`required	integer (uint32)	Internal audio sample rate, within `SAMPLE_RATE_RANGE`.
`width`required	integer (uint32)	Canvas width in output pixels, at most `MAX_CANVAS_DIMENSION`.

`ProviderSource`

A source whose media an extension provider supplies, rather than the host's video and image decoders.

A host picks the provider by probing the bytes at import, never by a file name, and records it here with the settings the source needs, so every host opens the source the same way. The engine does not read it: a provider source needs frames like any video or image source.

One of:

format: "svg"

A static SVG document, rasterized at the size it is shown. The source's kind is image.

format: "animated_image"

A GIF, animated WebP, or APNG: one cycle of frames, each with its own duration. Repetition is the clip's. The source's kind is video.

format: "lottie"

A Lottie animation, from a Lottie JSON file or a dotLottie package, evaluated at its own frames. The source's kind is video.

Field	Type	Description
`animation`	string \| null	The dotLottie animation shown, by its ID; the package's first when absent, and absent for a Lottie JSON file.

format: "image_sequence"

Still images played in order at a fixed rate. The source's kind is video.

Field	Type	Description
`frame_rate`required	FrameRate	The rate the frames play at.
`frames`required	string \| null[]	Each frame's locator, in play order. `null` is a number missing from the sequence, allowed only when `missing` says how to show it.
`missing`	MissingFrames	How a missing frame is shown. Default: `"reject"`
`primaries`	LinearPrimaries \| null	The primaries OpenEXR frames' linear RGB is in, overriding what the first frame's chromaticities say. Only for OpenEXR frames.
`start_number`	integer (uint64)	The number of the first frame, as its file was numbered. Default: `0`

format: "exr"

A still OpenEXR image: linear-light RGB(A), read at half precision. The source's kind is image.

Field	Type	Description
`primaries`	LinearPrimaries \| null	The primaries its linear RGB is in, overriding what the file's chromaticities say (BT.709 when it says nothing, as OpenEXR defines).

`SourceId`

A stable media-source identifier.

Type: string

`StreamTopology`

The streams a media file carries.

Field	Type	Description
`audio`	AudioStreamShape \| null	The primary audio stream, if there is one.
`video`	VideoStreamShape \| null	The primary video stream, if there is one.

`VideoStreamShape`

A video stream's displayed size and frame rate.

Field	Type	Description
`frame_rate`	FrameRate \| null	The rate its first frames are presented at, as every host measures it from packet times and rounds it (`alpha2_assets::FrameRateEvidence`), when it can be measured. Not the rate a stream declares: a declared rate is a guess for variable-rate media, and browsers report none.
`height`required	integer (uint32)	Displayed height in square pixels: the stored height stretched by a pixel aspect ratio taller than wide, then turned.
`width`required	integer (uint32)	Displayed width in square pixels: the stored width stretched by a pixel aspect ratio wider than tall, then turned by the stream's orientation.