Compose: render from a timeline

compose renders a video from a JSON timeline. Start with one clip, then layer up: more clips, transitions, overlays, and effects. This page builds from the smallest render to the full model. Each step adds one idea.

Your simplest render

The smallest timeline is one track with one clip. This trims three seconds of a video and renders it to MP4. The whole API call:

import { createClient, outputUrl } from "@rendobar/sdk";

const client = createClient({ apiKey: "rb_YOUR_KEY" });

const job = await client.jobs.create({
  type: "compose",
  params: {
    schemaVersion: 1,
    output: { format: "mp4", resolution: { width: 1280, height: 720 }, fps: 30 },
    timeline: {
      tracks: [
        { clips: [
          { asset: { type: "video", src: "https://cdn.rendobar.com/assets/examples/a.mp4", trim: { from: 0, to: 3 } }, start: 0, length: 3 },
        ] },
      ],
    },
  },
});

const result = await client.jobs.wait(job.id);
console.log(outputUrl(result));

import requests

res = requests.post(
    "https://api.rendobar.com/jobs",
    headers={"Authorization": "Bearer rb_YOUR_KEY"},
    json={
        "type": "compose",
        "params": {
            "schemaVersion": 1,
            "output": {"format": "mp4", "resolution": {"width": 1280, "height": 720}, "fps": 30},
            "timeline": {
                "tracks": [
                    {"clips": [
                        {"asset": {"type": "video", "src": "https://cdn.rendobar.com/assets/examples/a.mp4", "trim": {"from": 0, "to": 3}}, "start": 0, "length": 3}
                    ]}
                ]
            },
        },
    },
)

curl -X POST https://api.rendobar.com/jobs \
  -H "Authorization: Bearer rb_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "compose",
    "params": {
      "schemaVersion": 1,
      "output": { "format": "mp4", "resolution": { "width": 1280, "height": 720 }, "fps": 30 },
      "timeline": {
        "tracks": [
          { "clips": [
            { "asset": { "type": "video", "src": "https://cdn.rendobar.com/assets/examples/a.mp4", "trim": { "from": 0, "to": 3 } }, "start": 0, "length": 3 }
          ] }
        ]
      }
    }
  }'

Assets: video, image, text, audio, composition · Output: mp4 / webm / gif / mp3 (audio only) / jpg / png (still frame)

That is the shape of every render. Everything below is one more clip, one more track, or one more field.

Join two clips

Put a second clip on the same track and a transition between them. The clips overlap by the transition’s duration, so the second clip starts a little before the first ends.

"clips": [
  { "asset": { "type": "video", "src": "a.mp4" }, "start": 0, "length": 3 },
  { "type": "transition", "transition": "crossfade", "duration": 1 },
  { "asset": { "type": "video", "src": "b.mp4" }, "start": 2, "length": 3 }
]

slide also accepts direction: "left" | "right" | "up" | "down".

Transition	Effect
`crossfade`	A dissolves directly into B
`fade`	A dips through black, then B fades up
`slide`	B slides in over A from an edge (directional)
`zoom`	B grows in from the center

crossfade

fade

slide (left)

zoom

How the timeline works

The model is two ideas:

Tracks stack. The first track is the background. Each later track composites on top of the ones below it: overlays, titles, picture-in-picture.
Clips sit in time. Each clip has a start and a length in seconds. Two clips on the same track are joined by a transition. A gap between them plays nothing.

So a multi-track timeline is layers (tracks) of sequences (clips). That is the whole structure.

Add a layer

A second track renders over the first. This lays an animated title over the video.

"tracks": [
  { "clips": [
    { "asset": { "type": "video", "src": "a.mp4" }, "start": 0, "length": 5 }
  ] },
  { "clips": [
    { "asset": { "type": "text", "text": "Coastal Escape", "style": { "size": 84 } },
      "start": 0, "length": 5 }
  ] }
]

Effects on a clip

Any clip takes effects as fields. Add one field at a time, on the clip it applies to.

Color grade

color grades a clip. Set contrast, saturation, temperature, brightness, and gamma to set a cinematic mood, or push them to lift flat, hazy footage.

"color": { "contrast": 1.12, "saturation": 1.2, "temperature": 6800, "gamma": 0.95 }

Cinematic color grade to set a mood

Filters

filter applies a one-shot look: greyscale, negative, boost, muted, lighten, darken, or contrast.

"filter": "greyscale"

Transform and Ken Burns

transform positions and scales a clip. Add animateTo and it animates from the start values to the end values over the clip, the Ken Burns move that brings a still photo to life.

"transform": {
  "scale": 1.1,
  "position": { "x": "38%", "y": "48%" },
  "animateTo": { "scale": 1.32, "position": { "x": "62%", "y": "52%" } }
}

Bring a still photo to life for slideshows and docs

Picture-in-picture

Scale a clip down and position it on an overlay track to put a webcam over your content, for reactions and screen-shares.

"transform": { "scale": 0.3, "position": { "x": "80%", "y": "75%" } }

Speed

speed is a multiplier. Below 1 slows a clip down for a dramatic action beat, above 1 speeds a slow process into a timelapse.

"speed": 0.4

Chroma key

chromaKey removes a solid background color so you can drop a presenter onto any scene. Put the keyed clip on an overlay track above the new background.

"chromaKey": { "color": "#66DD09", "similarity": 0.28 }

Put a presenter on any background (chroma key)

Blend modes

blendMode controls how an overlay composites with the track below: screen, multiply, overlay, add, and more. A light-leak clip over your footage with screen adds a cinematic glow.

"blendMode": "screen",
"opacity": 0.7

Opacity and blur

opacity takes a number or keyframes. Keyframe it from 0 to 1 and back for a clean fade in and out. blur softens a clip, useful as a backdrop that keeps overlaid text readable.

"opacity": [
  { "time": 0, "value": 0 },
  { "time": 0.6, "value": 1 },
  { "time": 2.4, "value": 1 },
  { "time": 3, "value": 0 }
]

Text and titles

A text asset renders a styled title. Set the font, size, weight, color, position, and an animate entrance (fade, slideUp, slideDown, slideLeft, slideRight). Put one text clip on its own track for a title card, another low and left for a lower-third name tag.

"asset": {
  "type": "text",
  "text": "Coastal Escape",
  "style": {
    "font": "Inter",
    "size": 84,
    "weight": 800,
    "color": "#FFFFFF",
    "position": { "x": "50%", "y": "38%" },
    "animate": { "type": "slideUp", "duration": 0.7 }
  }
}

Add a title card and a lower-third name tag (text)

Set the canvas

output controls the resolution, frame rate, and format. A 9:16 canvas with a crop on the clip turns landscape footage into a vertical Reel that fills the frame, no black bars.

"output": { "format": "mp4", "resolution": { "width": 1080, "height": 1920 }, "fps": 30 }

Landscape footage reframed to a vertical 9:16 Reel (crop)

Scene-first authoring

Tracks give you precise multi-track control. For a sequential edit, you can instead describe a list of scenes. Each scene is a self-contained segment with its own clips and an optional transition into the next. overlays is a flat list of clips that sit over the whole composition, like a persistent logo or watermark.

{
  "scenes": [
    { "duration": 4, "transition": { "transition": "crossfade", "duration": 0.6 },
      "clips": [{ "asset": { "type": "video", "src": "a.mp4" } }] },
    { "duration": 4, "clips": [{ "asset": { "type": "video", "src": "b.mp4" } }] }
  ],
  "overlays": [
    { "asset": { "type": "image", "src": "logo.png" }, "start": 0, "length": 8,
      "transform": { "scale": 0.2, "position": { "x": "88%", "y": "12%" } } }
  ]
}

A scene’s clips can omit start and length to span the whole scene. Every clip field works the same as in tracks mode. scenes and tracks are mutually exclusive: a timeline uses one or the other.

Reference

Output

The output object controls the render target.

Field	Values
`format`	`mp4` (default), `webm`, `gif` (no audio), `mp3` (audio only), `jpg`, `png` (still frame)
`resolution`	`{ width, height }` (integer pixels)
`fps`	number
`videoCodec`	`h264`, `vp9` (optional; per-format default otherwise)
`audioCodec`	`aac`, `opus`, `mp3` (optional)
`frameTime`	second of the timeline to capture for `jpg` / `png` (default `0`)

Assets

A clip’s asset is one of:

`type`	Fields
`video`	`src`, `trim` `{ from, to }`, `volume` (default `1`)
`image`	`src`
`audio`	`src`, `trim`, `volume`, `fadeIn`, `fadeOut` (seconds)
`text`	`text`, `style`
`composition`	`timeline`, a nested `{ tracks }` rendered and composited as a single clip

Clip fields

Every clip has asset, start, length, plus any of:

Field	What it does
`opacity`	`0`..`1`, or keyframes `[{ time, value, easing: step \| linear \| smooth }]`
`transform`	`position {x,y}`, `scale`, `rotate`, `anchor` (`center` \| `topLeft`), `fit` (`contain` \| `fill`), `animateTo` (Ken Burns end state)
`crop`	`top` / `right` / `bottom` / `left`, each a percent string like `"10%"`
`speed`	playback rate (`0.5` = slow motion, `2` = fast, and pitch shifts with speed)
`color`	`brightness` (-1..1), `contrast` (0..4), `saturation` (0..3), `gamma` (0.1..10), `hue` (-180..180), `temperature` (1000..40000 K)
`filter`	`greyscale`, `negative`, `boost`, `muted`, `lighten`, `darken`, `contrast` (mutually exclusive with `color`)
`blur` / `sharpen`	gaussian blur strength / unsharp amount
`chromaKey`	`color` (hex), `similarity` (0..1)
`blendMode`	`normal`, `multiply`, `screen`, `overlay`, `darken`, `lighten`, `add`, `difference`
`pan`	stereo balance, `-1` (left) to `1` (right)
`flip`	`{ horizontal, vertical }`

Transitions

A track item { "type": "transition", "transition": <kind>, "duration": <seconds>, "direction"?: <dir> }: crossfade, fade, slide (direction: left / right / up / down), zoom, none (hard cut).

Text style

Fields on a text asset’s style: font, size, weight (100..1000), color, align (left / center / right), position {x,y}, stroke {color,width}, background, shadow {color,opacity,offsetX,offsetY}, animate {type: fade \| slideUp \| slideDown \| slideLeft \| slideRight, duration}.

Getting Started

Concepts

Jobs

Integrations

Support

Compose: render from a timeline

Your simplest render

Join two clips

How the timeline works

Add a layer

Effects on a clip

Color grade

Filters

Transform and Ken Burns

Picture-in-picture

Speed

Chroma key

Blend modes

Opacity and blur

Text and titles

Set the canvas

Scene-first authoring

Reference

Output

Assets

Clip fields

Transitions

Text style

​Your simplest render

​Join two clips

​How the timeline works

​Add a layer

​Effects on a clip

​Color grade

​Filters

​Transform and Ken Burns

​Picture-in-picture

​Speed

​Chroma key

​Blend modes

​Opacity and blur

​Text and titles

​Set the canvas

​Scene-first authoring

​Reference

​Output

​Assets

​Clip fields

​Transitions

​Text style

Your simplest render

Join two clips

How the timeline works

Add a layer

Effects on a clip

Color grade

Filters

Transform and Ken Burns

Picture-in-picture

Speed

Chroma key

Blend modes

Opacity and blur

Text and titles

Set the canvas

Scene-first authoring

Reference

Output

Assets

Clip fields

Transitions

Text style