How it works

See how Chunkify prepares video assets for playback and creates HLS renditions on request.

Chunkify prepares your source video for on-demand playback as a video asset. Here are the main steps of this process:

flowchart LR
    source["Source"] --> prepare["Prepare video asset"]
    prepare --> playback["Video asset playback ready"]
    playback --> webhook["Webhook sent to your app<br/>with the playback URL"]
    webhook --> initial["Viewer can watch<br/>the initial stream"]
    initial --> transcode["Transcode HLS renditions<br/>when requested by the player"]
    transcode --> available["Renditions available<br/>for playback"]

    playback --> ready["Video asset ready<br/>(Poster and timeline previews done)"]
    ready -. "If configured" .-> workflow["Workflow<br/>Static renditions, captions<br/>and translations"]

Add a Source

A Source identifies the original video. Add one from a hosted URL, an object in connected storage, or an upload.

We recommend hosting source files in S3 or equivalent cloud storage for reliable access during processing.

Create a video asset and let Chunkify prepare the video

Chunkify analyzes the Source and prepares the HLS stream, poster, and timeline previews. Check Create your first video stream for a quick tutorial. You can also configure a Workflow to define static renditions and captions for your video.

Get notified when playback is available

Chunkify sends asset.playback_ready to subscribed webhooks as soon as the initial HLS stream is playable. The video asset can still be preparing, with its poster and timeline previews not yet available.

See Webhooks to configure your notifications.

Stream the video

You can stream your video using the URL provided. Use the video asset's preview_url to test playback. For ongoing playback, configure your storage and CDN, then use its cdn_url in your player.

How Chunkify prepares the video

Analyze the source video

Chunkify reads the source video's properties, including its dimensions, duration, and frame rate. It analyzes the video content to choose an HLS rendition ladder.

The ladder defines the resolutions and bitrates a player can switch between as the viewer's connection changes. These stay within the video asset's minimum and maximum streaming resolution settings.

Prepare the HLS stream

Chunkify publishes the initial HLS stream progressively. Once it can play, playback_ready becomes true and Chunkify records asset.playback_ready. The video asset can still have status preparing.

Your player uses the video asset's master playlist URL. When it first requests a rendition from the ladder, Chunkify starts transcoding that rendition. Viewers watch the initial stream while that rendition is transcoded.

Once transcoding finishes, that HLS rendition is available for playback. You keep using the same master playlist URL.

Prepare the poster and timeline previews

The poster is an image to show before playback. Timeline previews are thumbnail images and a WebVTT file that maps positions in the video to those images. A player can use them to show a preview while a viewer seeks through the video.

When playback, the poster, and timeline previews are all ready, the video asset has status ready and Chunkify records asset.ready.

This status does not mean that every HLS rendition has been transcoded or that optional outputs have finished.

Add static renditions and captions

If configured, a Workflow starts when the video asset is ready. It can request static MP4 renditions, generated captions, and caption translations. Translations start after the original captions are ready.

Set a Workflow as the Project default or select one for an individual video asset. You can also request optional outputs later.

When outputs become available

HLS playback can start before the poster and timeline previews are ready. Use playback_ready to decide when to show the player:

Video asset state	What you can use
`preparing`, with `playback_ready: false`	Playback is not yet available.
`preparing`, with `playback_ready: true`	The initial HLS stream is playable. The poster and timeline previews may still be preparing.
`ready`, with `playback_ready: true`	The initial HLS stream is playable. The poster and timeline previews are available.
An HLS rendition is `ready`	That rendition is available for playback after being requested by the player.
An optional output is `ready`	That MP4 rendition or caption track is available. Its status is independent of the video asset's status.

If required processing fails, the video asset has status failed and an error with the failed stage, code, and message. See Retrieve a video asset for the current playback status. Read Asset outputs for captions, static renditions, and additional thumbnails.

The video asset response exposes playback paths and URLs as they become available. CDN delivery explains which URL to use for viewers.

To see the API contract, visit Create a video asset and Retrieve a video asset.