{ "slug": "video/reference", "title": "Video reference", "description": "Composition model, SDK surfaces, DSL fields, and renderer options for Cuitty Video.", "url": "https://cuitty.com/docs/video/reference", "markdown_url": "https://cuitty.com/docs/video/reference.md", "json_url": "https://cuitty.com/docs/video/reference.json", "frontmatter": { "title": "Video reference", "description": "Composition model, SDK surfaces, DSL fields, and renderer options for Cuitty Video.", "order": 2, "section": "Video", "updatedAt": "2026-05-24" }, "headings": [ { "depth": 1, "slug": "video-reference", "text": "Video reference" }, { "depth": 2, "slug": "composition-ir", "text": "Composition IR" }, { "depth": 2, "slug": "typescript-sdk", "text": "TypeScript SDK" }, { "depth": 2, "slug": "yaml-dsl", "text": "YAML DSL" }, { "depth": 2, "slug": "render-options", "text": "Render options" }, { "depth": 2, "slug": "server-workflow", "text": "Server workflow" }, { "depth": 2, "slug": "observe-integration", "text": "Observe integration" } ], "body_markdown": "# Video reference\n\nCuitty Video has four core surfaces:\n\n| Surface | Package | Purpose |\n| --- | --- | --- |\n| SDK | `@cuitty/video` | Build a composition in TypeScript and export Composition IR. |\n| DSL | `@cuitty/video-dsl` | Parse YAML or JSON into the same Composition IR. |\n| Renderer | `@cuitty/video-render` | Render frames with Playwright and encode with FFmpeg. |\n| Player | `@cuitty/video-player` | Preview Composition IR in the browser. |\n\nThe CLI and server are thin workflow layers over those packages.\n\n## Composition IR\n\nEvery composition resolves to the same shape:\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `id` | `string` | Stable composition identifier. |\n| `width` | `number` | Output width in pixels. |\n| `height` | `number` | Output height in pixels. |\n| `fps` | `number` | Frames per second. |\n| `durationInFrames` | `number` | Timeline length after duration parsing. |\n| `layers` | `LayerIR[]` | Ordered visual layers. |\n| `audioTracks` | `AudioIR[]` | Optional audio tracks. |\n| `transitions` | `TransitionIR[]` | Optional clip transitions. |\n\nLayers contain clips. Clips define `startFrame`, `endFrame`, `renderType`, `renderProps`, and optional animation metadata.\n\n## TypeScript SDK\n\nUse the SDK when composition data comes from code:\n\n```ts\nimport { composition, tween, Easing } from \"@cuitty/video\";\nimport { render } from \"@cuitty/video-render\";\n\nconst video = composition({\n id: \"status-report\",\n width: 1920,\n height: 1080,\n fps: 30,\n durationInFrames: 180,\n});\n\nvideo.layer(\"title\").clip({\n startFrame: 0,\n endFrame: 120,\n render: (ctx) => {\n const opacity = tween(ctx.frame, [0, 30], [0, 1], {\n clamp: true,\n easing: Easing.out(Easing.cubic),\n });\n\n return `

Weekly status

`;\n },\n});\n\nawait render({\n composition: video,\n outputPath: \"./output/status-report.mp4\",\n codec: \"h264\",\n crf: 18,\n});\n```\n\n## YAML DSL\n\nUse the DSL when a composition should be editable as data:\n\n```yaml\ncomposition:\n id: status-report\n width: 1920\n height: 1080\n fps: 30\n duration: 6s\n\nlayers:\n - id: title\n clips:\n - id: headline\n start: 0s\n end: 4s\n render:\n type: text\n text: \"Weekly status\"\n fontSize: 72\n color: \"#ffffff\"\n animate:\n - property: opacity\n from: 0\n to: 1\n start: 0s\n duration: 1s\n easing: cubic-out\n```\n\nThe DSL accepts YAML or JSON. `duration`, `start`, and `end` can be frame numbers or time strings such as `500ms`, `2s`, or `00:00:02`.\n\n## Render options\n\n| Option | Default | Notes |\n| --- | --- | --- |\n| `outputPath` | Required | Final output file path. |\n| `codec` | `h264` | Supports `h264`, `h265`, `vp9`, `prores`, and `gif`. |\n| `crf` | `18` | Lower is higher quality for CRF-based codecs. |\n| `concurrency` | CPU-dependent | Parallel frame rendering. |\n| `onProgress` | None | Receives frame count, total frames, and render FPS. |\n\n## Server workflow\n\nThe render server accepts composition payloads, creates jobs, reports status, and runs the same render pipeline behind an HTTP boundary. Use it when renders should be queued or called by another service instead of run directly in the CLI.\n\n## Observe integration\n\nVideo render jobs can emit progress, failure, and encoding metadata into Observe. The standalone Video product owns authoring and rendering; the existing [Video module](/docs/modules/video) remains the Observe module for browser-session recording job metadata.", "body_html": "

Video reference

\n

Cuitty Video has four core surfaces:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SurfacePackagePurpose
SDK@cuitty/videoBuild a composition in TypeScript and export Composition IR.
DSL@cuitty/video-dslParse YAML or JSON into the same Composition IR.
Renderer@cuitty/video-renderRender frames with Playwright and encode with FFmpeg.
Player@cuitty/video-playerPreview Composition IR in the browser.
\n

The CLI and server are thin workflow layers over those packages.

\n

Composition IR

\n

Every composition resolves to the same shape:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeNotes
idstringStable composition identifier.
widthnumberOutput width in pixels.
heightnumberOutput height in pixels.
fpsnumberFrames per second.
durationInFramesnumberTimeline length after duration parsing.
layersLayerIR[]Ordered visual layers.
audioTracksAudioIR[]Optional audio tracks.
transitionsTransitionIR[]Optional clip transitions.
\n

Layers contain clips. Clips define startFrame, endFrame, renderType, renderProps, and optional animation metadata.

\n

TypeScript SDK

\n

Use the SDK when composition data comes from code:

\n
import { composition, tween, Easing } from \"@cuitty/video\";\nimport { render } from \"@cuitty/video-render\";\n\nconst video = composition({\n  id: \"status-report\",\n  width: 1920,\n  height: 1080,\n  fps: 30,\n  durationInFrames: 180,\n});\n\nvideo.layer(\"title\").clip({\n  startFrame: 0,\n  endFrame: 120,\n  render: (ctx) => {\n    const opacity = tween(ctx.frame, [0, 30], [0, 1], {\n      clamp: true,\n      easing: Easing.out(Easing.cubic),\n    });\n\n    return `<h1 style=\"opacity:${opacity}\">Weekly status</h1>`;\n  },\n});\n\nawait render({\n  composition: video,\n  outputPath: \"./output/status-report.mp4\",\n  codec: \"h264\",\n  crf: 18,\n});
\n

YAML DSL

\n

Use the DSL when a composition should be editable as data:

\n
composition:\n  id: status-report\n  width: 1920\n  height: 1080\n  fps: 30\n  duration: 6s\n\nlayers:\n  - id: title\n    clips:\n      - id: headline\n        start: 0s\n        end: 4s\n        render:\n          type: text\n          text: \"Weekly status\"\n          fontSize: 72\n          color: \"#ffffff\"\n        animate:\n          - property: opacity\n            from: 0\n            to: 1\n            start: 0s\n            duration: 1s\n            easing: cubic-out
\n

The DSL accepts YAML or JSON. duration, start, and end can be frame numbers or time strings such as 500ms, 2s, or 00:00:02.

\n

Render options

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDefaultNotes
outputPathRequiredFinal output file path.
codech264Supports h264, h265, vp9, prores, and gif.
crf18Lower is higher quality for CRF-based codecs.
concurrencyCPU-dependentParallel frame rendering.
onProgressNoneReceives frame count, total frames, and render FPS.
\n

Server workflow

\n

The render server accepts composition payloads, creates jobs, reports status, and runs the same render pipeline behind an HTTP boundary. Use it when renders should be queued or called by another service instead of run directly in the CLI.

\n

Observe integration

\n

Video render jobs can emit progress, failure, and encoding metadata into Observe. The standalone Video product owns authoring and rendering; the existing Video module remains the Observe module for browser-session recording job metadata.

", "links_out": [ "/docs/modules/video" ] }