Docs

HLS

Create HTTP live streaming with H.264, H.265, AV1 codecs. Learn manifest handling, keyframe configuration.

This guide documents the legacy Jobs API (/jobs). Existing Jobs API integrations remain supported during the transition. For automatic file encoding, see the transcode guides.

Use HLS (HTTP Live Streaming) to offer multiple renditions that a player can switch between as network conditions change.

HLS Job Creation Example

This example creates an HLS job with a specified video bitrate:

These examples configure the video bitrate manually. Per-title optimization is disabled when per_title is omitted, so existing HLS requests continue to use their provided bitrate. To let Chunkify select an average bitrate for each requested rendition, set per_title: true and omit video_bitrate, crf, minrate, maxrate, and bufsize. See Per-title optimization for details.

import Chunkify from '@chunkify/chunkify';

const client = new Chunkify({
    projectAccessToken: 'My Project Access Token',
});

// Transcode using h264 format with 1080 resolution
const firstJob = await client.jobs.create({
    source_id: source.id,
    format: {
        id: 'hls_h264',
        height: 1080,
        gop: 60,
        x264_keyint: 60,
        audio_bitrate: 128000,
        video_bitrate: 7000000,
    },
});

// Keep the manifest ID
const manifestId = firstJob.hls_manifest_id;

// Create a new job using the manifest ID
const job = await client.jobs.create({
    source_id: source.id,
    format: {
        id: 'hls_h264',
        height: 720,
        gop: 60,
        x264_keyint: 60,
        audio_bitrate: 128000,
        video_bitrate: 7000000,
    },
    hls_manifest_id: manifestId,
});

Encoding Parameters by Codec

A complete list of all the parameters available for each codec.

FFmpeg encoding parameters specific to HLS with H.264 encoding. When per-title optimization is disabled, either audio_bitrate or video_bitrate is required.

id
"hls_h264"
string
required
audio_bitrate
integer

AudioBitrate specifies the audio bitrate in bits per second. Must be between 32Kbps and 512Kbps.

Required range: 32000 <= x <= 512000
bufsize
integer

Bufsize specifies the video buffer size in bits. Must be between 100Kbps and 50Mbps.

Required range: 100000 <= x <= 5e+07
channels
integer

Channels specifies the number of audio channels. Valid values: 1 (mono), 2 (stereo), 5 (5.1), 7 (7.1)

Available options:
1257
crf
default: 21
integer

Crf (Constant Rate Factor) controls the quality of the output video. Lower values mean better quality but larger file size. Range: 16 to 35. Recommended values: 18-28 for high quality, 23-28 for good quality, 28-35 for acceptable quality.

Required range: 16 <= x <= 35
Examples:
23
disable_audio
boolean

DisableAudio indicates whether to disable audio processing.

disable_video
boolean

DisableVideo indicates whether to disable video processing.

duration
integer

Duration specifies the duration to process in seconds. Must be a positive value.

Required range: x >= 1
framerate
number

Framerate specifies the output video frame rate. Must be greater than zero and at most 240 fps.

Required range: x <= 240
gop
integer

Gop specifies the Group of Pictures (GOP) size. Must be between 1 and 960 frames.

Required range: 1 <= x <= 960
height
integer

Height specifies the output video height in pixels. Must be between -2 and 7680. Use -2 for automatic calculation while maintaining aspect ratio.

Required range: -2 <= x <= 7680
hls_enc
boolean

HlsEnc enables encryption for HLS segments when set to true.

Examples:
false
hls_enc_iv
string

HlsEncIv specifies the initialization vector for encryption. Maximum length: 64 characters. Required when HlsEnc is true.

Examples:
0123456789abcdef
hls_enc_key
string

HlsEncKey specifies the encryption key for HLS segments. Maximum length: 64 characters. Required when HlsEnc is true.

Examples:
0123456789abcdef
hls_enc_key_url
string

HlsEncKeyUrl specifies the URL where clients can fetch the encryption key. Required when HlsEnc is true.

Examples:
https://example.com/key
hls_segment_type
default: "fmp4"
string

HlsSegmentType specifies the type of HLS segments. Valid values:

  • mpegts: Traditional MPEG-TS segments, better compatibility
  • fmp4: Fragmented MP4 segments, better efficiency
Available options:
mpegtsfmp4
Examples:
mpegts
hls_single_file
default: true
boolean

HlsSingleFile specifies whether to store HLS segments in one file using byte ranges. Defaults to true. Set to false to create separate segment files.

Examples:
false
hls_time
default: 4
integer

HlsTime specifies the duration of each HLS segment in seconds. Range: 1 to 10. Shorter segments provide faster startup but more overhead, longer segments are more efficient.

Required range: 1 <= x <= 10
Examples:
6
level
integer

Level specifies the H.264 profile level. Valid values: 10-13 (baseline), 20-22 (main), 30-32 (high), 40-42 (high), 50-51 (high). Higher levels support higher resolutions and bitrates but require more processing power.

Available options:
101112132021223031324041425051
Examples:
41
maxrate
integer

Maxrate specifies the maximum video bitrate in bits per second. Must be between 100Kbps and 50Mbps.

Required range: 100000 <= x <= 5e+07
minrate
integer

Minrate specifies the minimum video bitrate in bits per second. Must be between 100Kbps and 50Mbps.

Required range: 100000 <= x <= 5e+07
movflags
string
per_title
default: false
boolean

Enables per-title optimization. Disabled by default. Set it to true to let Chunkify select rate control automatically. When enabled, explicit rate-control fields cannot be provided. For HLS outputs, either audio_bitrate or video_bitrate is required when per-title optimization is disabled or omitted.

pixfmt
default: "yuv420p"
string

PixFmt specifies the pixel format. Valid value: yuv420p

Available options:
yuv410pyuv411pyuv420pyuv422pyuv440pyuv444pyuvJ411pyuvJ420pyuvJ422pyuvJ440pyuvJ444pyuv420p10leyuv422p10leyuv440p10leyuv444p10leyuv420p12leyuv422p12leyuv440p12leyuv444p12leyuv420p10beyuv422p10beyuv440p10beyuv444p10beyuv420p12beyuv422p12beyuv440p12beyuv444p12be
preset
default: "veryfast"
string

Preset specifies the encoding speed preset. Valid values (from fastest to slowest):

  • ultrafast: Fastest encoding, lowest quality
  • superfast: Very fast encoding, lower quality
  • veryfast: Fast encoding, moderate quality
  • faster: Faster encoding, good quality
  • fast: Fast encoding, better quality
  • medium: Balanced preset, best quality
Available options:
ultrafastsuperfastveryfastfasterfastmedium
Examples:
medium
profilev
string

Profilev specifies the H.264 profile. Valid values:

  • baseline: Basic profile, good for mobile devices
  • main: Main profile, good for most applications
  • high: High profile, best quality but requires more processing
  • high10: High 10-bit profile, supports 10-bit color
  • high422: High 4:2:2 profile, supports 4:2:2 color sampling
  • high444: High 4:4:4 profile, supports 4:4:4 color sampling
Available options:
baselinemainhighhigh10high422high444
Examples:
high
seek
integer

Seek specifies the timestamp to start processing from (in seconds). Must be a positive value.

Required range: x >= 1
video_bitrate
integer

VideoBitrate specifies the video bitrate in bits per second. Must be between 1 bps and 100 Mbps.

Required range: 1 <= x <= 1e+08
width
integer

Width specifies the output video width in pixels. Must be between -2 and 7680. Use -2 for automatic calculation while maintaining aspect ratio.

Required range: -2 <= x <= 7680
x264_keyint
integer

X264KeyInt specifies the maximum number of frames between keyframes for H.264 encoding. Range: 1 to 960. Higher values can improve compression but may affect seeking.

Required range: 1 <= x <= 960
Examples:
60

Keyframe Interval Configuration

To ensure proper HLS segmentation, keyframe intervals must be explicitly configured. The required parameters vary by codec:

  • For the H264 codec you will need to provide the gop and x264_keyint parameters.
  • For the H265 codec you will need to provide the gop and x265_keyint parameters.
  • For the AV1 codec you will need to provide the gop parameter.

HLS Manifest Handling

The manifest is the HLS playlist file that enables adaptive streaming.

Chunkify generates a manifest ID when you create the first HLS job in a group.

Pass that ID when creating additional HLS jobs to include them in the same manifest.

You cannot provide a manifest ID that does not already exist when creating a new job.

CORS Issues

When using HLS in a web player, see Configure CORS for browser playback requirements.