Recipes

Updated

A recipe describes the video you want. It sits under recipe in a run submission (see Runs and results) and contains exactly one object, either delivery or highlights.

Recipes are strict. Every field listed below is required unless it says optional, and any unknown field gets the whole submission rejected. Every media reference is a source ID that you created with the same credential and that is already ready (see Sources). Raw object keys and URLs are not accepted.

Shared fields

Field	Values
`transitions`	Must be `{"type": "fade", "duration": 1.0}`. This one-second cross-fade is the only transition Slate supports.
`quality_tier`	`delivery` or `intermediate`. `delivery` is a compact H.264 file for viewers. `intermediate` is encoded at four times the bits per pixel, for footage you plan to edit further.

The output is an MP4 with H.264 video and AAC audio.

`delivery`: pages into a video

A delivery turns an ordered list of pages into a video. Each page is a still image shown for a set time over its own audio track.

{
  "delivery": {
    "pages": [
      {
        "image": "11111111-1111-4111-8111-111111111111",
        "audio": "22222222-2222-4222-8222-222222222222",
        "duration": 6.5,
        "captions": {
          "font": "33333333-3333-4333-8333-333333333333",
          "words": [
            {"text": "Once", "x": 120, "y": 860, "start": 0.2, "end": 0.7},
            {"text": "upon", "x": 300, "y": 860, "start": 0.7, "end": 1.1}
          ]
        }
      },
      {
        "image": "44444444-4444-4444-8444-444444444444",
        "audio": "55555555-5555-4555-8555-555555555555",
        "duration": 5.0
      }
    ],
    "transitions": {"type": "fade", "duration": 1.0},
    "quality_tier": "delivery",
    "width": 1536,
    "height": 1024
  }
}

Field	Rules
`pages`	An ordered list of at least two pages.
`pages[].image`	A `ready` PNG or JPEG source.
`pages[].audio`	A `ready` audio source.
`pages[].duration`	How long the page lasts, in seconds. Must be positive.
`pages[].captions`	Optional. Words drawn on top of the page.
`width`, `height`	Must be `1536` × `1024` (landscape) or `1024` × `1536` (portrait). These are the only two canvases Slate supports.

Images do not have to match the canvas. Slate scales each image to fit inside the canvas and fills the remaining space with black. Pages render at 24 frames per second with 192 kbps audio.

Each one-second fade overlaps two neighbouring pages, so the finished video is the sum of the page durations minus one second per transition. Two three-second pages give a five-second video.

Captions

captions places individual words on the page at set times:

Field	Rules
`font`	A `ready` font source, such as a TTF or OTF file you uploaded.
`words`	1 to 64 words, in order.
`words[].text`	The word to draw.
`words[].x`, `words[].y`	Pixel position on the canvas. Must be inside the canvas width and height.
`words[].start`, `words[].end`	When the word appears and disappears, in seconds from the start of the page. `end` must be after `start` and no later than the page's `duration`.

Slate draws captions only with the font you supply. If the font cannot be loaded, the render fails. Slate never swaps in a system font.

`highlights`: clips into a cut

A highlights recipe cuts ranges out of one video and joins them.

{
  "highlights": {
    "source": "77777777-7777-4777-8777-777777777777",
    "clips": [
      {"start": 12.0, "end": 19.5},
      {"start": 63.0, "end": 71.0}
    ],
    "transitions": {"type": "fade", "duration": 1.0},
    "quality_tier": "delivery"
  }
}

Field	Rules
`source`	One `ready` video source.
`clips`	An ordered list of at least two ranges.
`clips[].start`, `clips[].end`	Seconds into the source. `start` must be zero or more, and `end` must be after `start`.

A highlights recipe has no width or height. Slate first cuts the source roughly into pieces in your bucket, then re-encodes each clip precisely, then joins them. Nothing in the finished video is copied straight from your source file. Every frame is re-encoded.

If a clip's end is past the end of the source, the run is accepted but fails with clip_range_invalid, because the source's length is only checked during the render.

Size limits for a run

Slate checks the size of a recipe when you submit it. Each limit has its own 422 reason:

Reason	What it limits
`operation_count_exceeded`	At most 49 pages or clips in one run.
`total_output_duration_exceeded`	The total length of output one run may produce. The error message gives the limit in seconds.
`render_job_count_exceeded`	The number of queue jobs a run may need, which is 100.

These limits come from how Slate spreads one run across up to ten parallel workers on the managed queue. They are not configurable.

Shared fields

delivery: pages into a video

Captions

highlights: clips into a cut

Size limits for a run

`delivery`: pages into a video

`highlights`: clips into a cut