Video edits

Transitions

Applied at a clip’s edges. Append Fast or Slow to any name to scale its duration — fadeFast, carouselLeftSlow. A slide travels the width of the whole frame unless you tell it otherwise.

"transition": { "in": "slideUp", "out": "fadeFast" }

// fade, reveal
// wipeLeft, wipeRight, wipeUp, wipeDown
// slideLeft, slideRight, slideUp, slideDown
// carouselLeft, carouselRight, carouselUp, carouselDown
// shuffleTopRight, shuffleRightBottom, shuffleBottomLeft, …
// zoom, zoomIn, zoomOut
// blur, glitch, whipLeft, whipRight

Effects

Continuous motion for the clip’s whole life. Every one of these is evaluated by the render graph rather than painted frame by frame, so none of them costs anything extra. The oscillating ones are sized against the frame unless you tell them otherwise.

"effect": "zoomInSlow"

// Ken Burns — a slow push, pull or drift
// zoomIn, zoomOut
// slideLeft, slideRight, slideUp, slideDown
// panLeft, panRight, panUp, panDown

// Rotation about the clip's own centre
// rotateCW, rotateCCW

// Oscillations that loop while the clip is on screen
// shake   handheld jitter
// float   a slow vertical bob
// pulse   a breathing scale

// Focus pulls
// blurIn, blurOut

// each accepts a Fast or Slow suffix

Text animations

A text or titleasset can arrive rather than simply appear — typed out, a word at a time, flipping in letter by letter, or as one line rising into place. This is an animation of the clip’s content rather than of its position, so it is set on the asset and not on the clip.

"asset": {
  "type": "text",
  "text": "LUXURY APARTMENT",
  "font": { "family": "Montserrat", "size": 88, "weight": 500 },
  "animation": {
    "type": "wordByWord",
    "staggerSec": 0.2,
    "durationSec": 0.45
  }
}

// type        any name from the table below, or none
// unit        block, line, word, letter — overrides what the animation counts
// staggerSec  gap between two parts starting. 0 reveals everything at once
// durationSec how long one part takes to arrive
// delaySec    hold before the first part moves
// easing      the curve each part travels on
// intensity   0-3. Scales the travel, the turn and the blur. 1 is as designed
// reverse     run the parts back to front

Every name carries its own unit, its own pace and its own curve, and unit overrides the first of those — so flipIn flips letters, and { "type": "flipIn", "unit": "word" } flips whole words. The four Loop animations never settle: they run for as long as the clip does, and their durationSec is one cycle rather than one arrival.

Both values are absolute seconds, so a reveal runs at the same pace whatever the clip does — a two-word headline on a length: "end" clip assembles in the first second, not spread across the whole timeline. Parts are also kept at least one output frame apart, so they can never quantise onto the same frame and arrive together. If a line genuinely cannot fit at the requested pace, the whole schedule compresses into the first 70% of the clip rather than overrunning it.

The durationSec default is deliberately longer than the stagger: parts overlap, which is what makes a line flow rather than tick over one word at a time.

Fitting type to its box

Type that does not fit its box is cut — the clip is painted at exactly the box the layout gives it, and anything past that edge is clipped. Two things make that easy to run into: a text asset with no font.size is sized against its box, and a title is sized against the frame, so dragging one into a lower third keeps its full size in a box a fifth as tall.

"asset": {
  "type": "title",
  "text": "An Extremely Long Title That Will Not Fit",
  "style": "chunk",
  "autoFit": true
}

// Shrinks the type until it fits — measured in the renderer
// with the real font loaded, so where the lines break is the
// truth rather than an estimate.
//
// autoFit is a CEILING, not a target: type that already fits
// is left at exactly the size it asked for, never grown.

The fit is measured against the box after padding, borders and the plate, so it accounts for everything you have put around the text. It will not shrink type below a quarter of its stated size — past that the answer is a bigger box or fewer words, not smaller type. A countdown needs no switch: its row of tiles is scaled to its box always, since there is no design in which the last unit is meant to be cut off.

Text transforms

A warp sets the line on a shape instead of a straight baseline. It is static geometry, baked into the frame the clip was already drawing, so unlike an animation it costs nothing at all to use and composes freely with one.

"asset": {
  "type": "title",
  "text": "SUMMER SALE",
  "style": "chunk",
  "warp": { "type": "arcUp", "intensity": 1.4 }
}

// A bare name is the same as intensity 1:
"warp": "leftUplift"

The warps that tilt, shear or turn the whole line leave it a single flowing run, so it keeps its wrapping, its kerning and its justification. The ones that place each letter individually cannot — a line set on an arc does not wrap — so give those a box wide enough for the line, or shorten the line.

Padding, borders and corners

Anywhere a plate sits behind text — a text or title background, a caption’s, a ticker’s, a countdown’s tiles — the same three fields describe it, and each takes a shorthand or a long form.

"background": {
  "color": "#101014",
  "opacity": 0.9,

  // One number pads every side...
  "padding": 16,
  // ...or state them separately.
  "padding": { "top": 8, "right": 20, "bottom": 24, "left": 20 },

  // One radius rounds every corner...
  "borderRadius": 12,
  // ...or one corner at a time.
  "borderRadius": { "topLeft": 12, "topRight": 12 },

  // A rule round the box, or along one edge of it.
  "border": {
    "width": 1,
    "style": "solid",
    "color": "#2A2A32",
    "left": { "width": 6, "color": "#8B3DFF" }
  }
}

A side left out of the long form is zero, not the shorthand’s value — there is no shorthand present to inherit from. A border edge is the exception and inherits every part it does not state from the border’s own width/style/color, so one accent edge does not mean restating the other three. An edge that ends at zero width is not drawn, which is why a border naming only a colour draws nothing.

style takes the CSS keywords: solid, dashed, dotted, double, groove, ridge, inset, outset, none. Padding and border are drawn inside the box the clip declares, so adding either never changes the size you asked for.

Marquee

A news-channel ticker. The strip is painted once at its natural width and scrolled by the render graph, so a ten-minute ticker costs one browser paint. The text repeats end to end and the scroll wraps on the repeat boundary, which is what keeps the loop seamless.

{
  "asset": {
    "type": "marquee",
    "text": "Markets close higher as tech leads the rally",
    "direction": "left",
    "speed": 220,
    "separator": " • ",
    "background": { "color": "#B00020" },
    "label": { "text": "Breaking", "background": "#FFFFFF", "color": "#B00020" },
    "font": { "family": "Inter", "weight": 700 }
  },
  "start": 0,
  "length": 30,
  "position": "bottom"
}

// direction  left (default), right, up, down
// speed      output pixels per second
// cycles     complete passes over the clip — overrides speed
// label      a fixed chip that stays put while the text runs under it

// With no width/height the ticker is a full-width bar 9% of the frame tall.

Keyframes

Animate a numeric property with explicit stops and easing. Times are relative to the clip’sstart, not the timeline’s.

"keyframes": {
  "opacity": [
    { "at": 0,   "value": 0 },
    { "at": 0.6, "value": 1, "easing": "easeOutCubic" }
  ],
  "offsetY": [
    { "at": 0, "value": -0.05 },
    { "at": 5, "value": 0.05, "easing": "linear" }
  ],
  "scale": [
    { "at": 0, "value": 1 },
    { "at": 4, "value": 1.15, "easing": "easeInOutQuad" }
  ]
}

Animatable: opacity, scale, rotate, offsetX, offsetY, volume, blur, brightness. Easing covers the usual quad/cubic/quart/expo/back curves plus spring and bounce.

Drawing on

With "animation": { "type": "drawOn" } the chart arrives rather than cutting in: bars grow from the baseline, a line draws itself left to right, a pie sweeps once round, a widget counts up to its number, and table rows land in turn. Values printed next to the marks count with the geometry, so the number always states what the mark is showing — and they count in whole numbers when the target is whole, rather than flickering through decimals.

The draw-on takes durationSec— 1.2s by default — measured from the clip’s start, and the chart then holds for the rest of the clip. It does not stretch to fill a long clip.

What a data field accepts

A list may be separated by newlines, pipes or commas — in that order of precedence, which is what lets "1,200\n980" keep its thousands separators. Currency symbols, separators and trailing per-cent signs are stripped from numbers, because a spreadsheet column is where these usually come from.

Type: nine roles, one scale

Every label a chart draws is derived from font.size— a title is that plus three, an axis tick one less, a category label exactly it. That is a sensible default and a poor ceiling: a chart is laid out on a monitor and watched on a phone, so the answer to “the legend is too small to read” used to be a single number that moved every label at once, including the ones already the right size.

fontScaleis the one-field answer — it multiplies every piece of type in the chart, a table’s rows and a widget’s readout included. text is the precise one: it addresses each label by role, so one moves and the rest stay.

"asset": {
  "type": "chart",
  "chart": "bar",
  "data": { "labels": ["Jun", "Jul"], "values": [18, 34] },
  "fontScale": 1.5
}

// Everything grows together and stays in proportion:
// the labels, the ticks, the legend and its swatches,
// and the left gutter widens to fit the bigger ticks.
//
// 1 is the chart as drawn. Start at 1.4-1.8 for a
// 9:16 frame, where the chart is watched at phone size.

font.sizedefaults to 13, and a table’s to 12. A role a given chart does not draw is simply never asked for, so one text block can be shared by every chart in a template.

Moving the legend

A legend used to go wherever the renderer put it — under an axis plot, to the right of a pie — and nothing in the payload could move it. legend sets the edge it sits on, the direction it runs, and what its marks look like. The plot gives up the room rather than being drawn over, so moving a legend re-lays the chart around it.

"asset": {
  "type": "chart",
  "chart": "bar",
  "data": {
    "labels": ["Jun", "Jul", "Aug"],
    "series": [
      { "name": "Rentals", "values": [12, 19, 24] },
      { "name": "Sales",   "values": [8, 11, 9] }
    ]
  },
  "showLegend": true,
  "legend": { "position": "right", "swatch": "circle" }
}

// The plot narrows by the legend's band and the
// legend stacks down its side. On a wide frame that
// reads better than a row of names under the bars.

Room, gridlines and where a value sits

Date and time

A datetimeclip resolves its value when the video is rendered, not when the template is written. That is what lets one template keep working: a “posted on” stamp, a session time, an offer’s expiry date — the same clip, saying something different every day it runs.

{
  "asset": {
    "type": "datetime",
    "mode": "date",
    "value": "now",
    "format": "long",
    "timezone": "Asia/Kolkata",
    "font": { "family": "Inter", "size": 64, "weight": 700, "color": "#FFFFFF" }
  },
  "start": 0,
  "length": 5
}

// mode     date | time | datetime (default) | relative
// value    "now" (default), an ISO 8601 date, or a Unix timestamp
// format   a preset name, or your own token pattern
// timezone an IANA zone. Defaults to the render worker's own.
// locale   a BCP-47 tag driving month and weekday names. Defaults to "en".

// `date` and `time` also work as asset types on their own, and set the
// matching mode: { "type": "date", "format": "long" }

Format presets. short, medium (the default), long, full, iso, us, compact, and ordinal for dates. Anything that is not a preset name is read as a token pattern.

Countdown

A timer counting toward — or away from — a moment. The asset owns the whole widget, not just the number: segment tiles, unit captions, an urgency palette that takes over as the deadline closes in, and what happens once the clock runs out.

{
  "asset": {
    "type": "countdown",
    "to": "2026-12-25T09:00:00Z",
    "layout": "segments",
    "units": ["days", "hours", "minutes", "seconds"],
    "labels": { "show": true, "style": "long", "position": "below" },
    "segment": { "background": "rgba(255,255,255,0.10)", "borderRadius": 16, "gap": 18 },
    "font": { "family": "Inter", "size": 84, "weight": 800, "color": "#FFFFFF" }
  },
  "start": 0,
  "length": 10,
  "position": "center"
}

// layout   inline (default) · segments · stacked · flip · ring
// units    largest to smallest. Omit and they are chosen from the actual span.
// padStart leading zeros. Default true.

// The LARGEST unit you show absorbs everything above it: a three-day
// countdown showing only hours reads "78h", never a silently missing 3 days.

Timing against the voice, with no transcript

A generated voice-over rarely comes with a transcript, so there is nothing to align the words to — only your script and the audio itself. Speech is separated by pauses, and those can be located exactly, so the engine finds the phrases the speaker actually uttered and lays your script into them, each word taking time in proportion to its length.

Captions then land on the voice rather than on a stopwatch: a pause in the delivery is a pause in the captions, and no caption is ever drawn over silence. No transcription service is involved, nothing is sent anywhere, and the result is identical on every render.

For word-perfect timings without writing them by hand, transcribe the recording instead. That reads the words rather than the pauses, works on a video as well as on a voice-over, and returns cues carrying per-word offsets.

One template, a different voice-over per render

Both of a caption’s URLs are ordinary strings, so both take merge fields: audio for the voice-over it times against, and src for a subtitle file. That is what makes captions work in a personalised video — every render sends its own recording, and the captions follow that file rather than the one the template was built with.

{
  "merge": [
    { "find": "VOICEOVER_URL", "replace": "https://cdn.acme.com/vo/priya.mp3" }
  ],
  "timeline": {
    "tracks": [{ "clips": [{
      "asset": {
        "type": "caption",
        "audio": "{{VOICEOVER_URL}}",
        "script": "Hi Priya, your order is on its way.",
        "karaoke": { "enabled": true }
      }
    }] }]
  }
}

Marking the spoken word

karaoke.stylepicks one of ten markings. Every one of them is layout-neutral — the line keeps its exact metrics as the highlight moves along it — because a marking that changed a word’s box would shift every word after it at the moment the eye is tracking one of them. That is why box and underlineare drawn as inset shadows rather than as borders, and why every word carries the chip’s padding whether it is lit or not.

flow decides how much of a cue is on screen at once, which is a separate question from marking: all shows the whole caption and holds it, progressive reveals words as they are spoken and keeps them, and active shows only the word being said — one word at a time, very large, which is the look built for a 9:16 frame. inactiveOpacity dims words not yet spoken.

background is separate and independent from all of it: it is the plate behind the whole cue. Use either, both, or neither — and nullremoves a preset’s plate outright, which is not the same as leaving it out.

Checking a family before you render

Google answers a request for a family it does not publish with a success and no font. The render then completes in a system fallback face — no error, no warning in the response, just the wrong typeface in a finished video. If you generate edits programmatically, check the name first:

curl "https://pixbix.app/api/v1/fonts?family=Playfair%20Display"

{
  "success": true,
  "data": {
    "query": "Playfair Display",
    "supported": true,
    "generic": false,
    "font": {
      "family": "Playfair Display",
      "category": "serif",
      "weights": [400, 500, 600, 700, 800, 900],
      "italic": true,
      "variable": true
    }
  }
}

GET /v1/fonts needs no API key. Browse it with search, category and limit, or pass family to check one exact string. The full endpoint reference is under Endpoints below.

Fonts you host yourself

For anything not in the catalogue — a brand face, a licensed cut — add it to timeline.fonts as an https URL to a .ttf, .otf, .woff or .woff2 file. The engine reads the real family name out of the file itself, so font.family is whatever the font calls itself rather than whatever the file is called. Set family on the declaration to override that.

A declared family is never also requested from Google, so a self-hosted font of the same name as a Google one wins rather than being quietly replaced by a different cut of it.