# 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:

```mermaid
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"]
```

<steps>
    <step title="Add a Source">
        A **Source** identifies the original video. Add one from a hosted URL, an object in connected storage, or an upload.

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

    </step>

    <step title="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](/docs/video-streaming/quickstart) for a quick tutorial.
        You can also configure a [Workflow](/docs/video-streaming/asset-workflow) to define static renditions and captions for your video.
    </step>

    <step title="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](/docs/integration/webhooks) to configure your notifications.
    </step>

    <step title="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](/docs/video-streaming/storage), then use its `cdn_url` in your player.
    </step>
</steps>

## 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](/docs/video-streaming/asset-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](/docs/api-reference/assets/retrieve-an-asset) for the current playback status. Read [Asset outputs](/docs/video-streaming/outputs) for captions, static renditions, and additional thumbnails.

The video asset response exposes playback paths and URLs as they become available. [CDN delivery](/docs/video-streaming/storage/cdn-delivery) explains which URL to use for viewers.

To see the API contract, visit [Create a video asset](/docs/api-reference/assets/create-an-asset) and [Retrieve a video asset](/docs/api-reference/assets/retrieve-an-asset).