HLS Streaming

Overview

HTTP Live Streaming (HLS) is an adaptive bitrate streaming protocol developed by Apple. Jellyfin generates dynamic HLS playlists and serves media segments for smooth, adaptive streaming across diverse network conditions and devices.

HLS Architecture

HLS streaming consists of:

Master Playlist (.m3u8) - Lists available quality variants
Media Playlists (.m3u8) - Lists segments for a specific quality
Media Segments (.ts or .mp4) - Actual video/audio data chunks

Video HLS Endpoints

Get Master HLS Video Playlist

Retrieves the master playlist containing all available video stream variants.

GET /Videos/{itemId}/master.m3u8

Authentication: Required

string

required

The unique identifier of the video item

string

required

The media source identifier

string

The device id of the client requesting

string

The play session identifier for tracking

string

The segment container format:

ts - MPEG-TS (default, more compatible)
fmp4 - Fragmented MP4 (better compression, requires modern clients)

integer

The length of each segment in seconds (typically 3-10 seconds)

integer

The minimum number of segments to generate before starting playback

string

Specify the video codec: h264, hevc, vp9, av1

string

Specify the audio codec: aac, mp3, opus, ac3

integer

The video bitrate in bits per second

integer

The audio bitrate in bits per second

integer

Maximum video width in pixels

integer

Maximum video height in pixels

boolean

default:"false"

Enable adaptive bitrate streaming with multiple quality variants

boolean

default:"true"

Enable trickplay image playlists being added to master playlist for thumbnail previews

integer

Starting position in ticks

string

M3U8 master playlist with available stream variants

Response Codes:

200 OK - Master playlist returned
401 Unauthorized - Authentication required
404 Not Found - Item not found

Example Request

curl -X GET "https://your-jellyfin-server/Videos/12345678-1234-1234-1234-123456789abc/master.m3u8?mediaSourceId=12345678-1234-1234-1234-123456789abc&enableAdaptiveBitrateStreaming=true" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Example Response

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-STREAM-INF:BANDWIDTH=2400000,RESOLUTION=1280x720,CODECS="avc1.64001f,mp4a.40.2"
main.m3u8?videoBitRate=2000000&audioBitRate=192000&maxWidth=1280&maxHeight=720
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.640028,mp4a.40.2"
main.m3u8?videoBitRate=4500000&audioBitRate=192000&maxWidth=1920&maxHeight=1080

Get Live HLS Video Stream

Generates a live HLS stream with on-demand transcoding.

GET /Videos/{itemId}/live.m3u8

Authentication: Required

string

required

The unique identifier of the video item

string

The output container format

string

The media source identifier

string

The device id of the client

string

The play session identifier

string

The segment container: ts or fmp4

integer

Length of each segment in seconds (default: 6)

integer

Minimum number of segments before playback starts (default: 2)

string

Video codec to use

string

Audio codec to use

integer

Video bitrate in bits per second

integer

Maximum width in pixels

integer

Maximum height in pixels

boolean

default:"true"

Whether to include subtitle streams in the manifest

boolean

default:"false"

Whether to always burn in subtitles when transcoding

string

M3U8 media playlist with segment URLs

Response Codes:

200 OK - HLS live stream playlist returned
401 Unauthorized - Authentication required

Example Request

curl -X GET "https://your-jellyfin-server/Videos/12345678-1234-1234-1234-123456789abc/live.m3u8?segmentContainer=ts&segmentLength=6&videoCodec=h264&audioCodec=aac" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

Get Variant HLS Video Playlist

Retrieves a specific quality variant playlist.

GET /Videos/{itemId}/main.m3u8

Authentication: Required Parameters are similar to the live stream endpoint. This generates a media playlist for a specific quality level. Response Codes:

200 OK - Variant playlist returned
401 Unauthorized - Authentication required

Audio HLS Endpoints

Get Master HLS Audio Playlist

Retrieves the master playlist for audio streaming.

GET /Audio/{itemId}/master.m3u8

Authentication: Required

string

required

The unique identifier of the audio item

string

required

The media source identifier

string

The device id of the client

string

The play session identifier

string

The segment container format

integer

Length of each segment in seconds

string

Audio codec to use: aac, mp3, opus

integer

Audio bitrate in bits per second

integer

Maximum streaming bitrate

integer

Maximum number of audio channels

boolean

default:"false"

Enable adaptive bitrate streaming

string

M3U8 master playlist for audio streaming

Response Codes:

200 OK - Master playlist returned
401 Unauthorized - Authentication required

Example Request

curl -X GET "https://your-jellyfin-server/Audio/12345678-1234-1234-1234-123456789abc/master.m3u8?mediaSourceId=12345678-1234-1234-1234-123456789abc&audioCodec=aac&audioBitRate=192000" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

HLS Segment Endpoints

Get HLS Video Segment

Retrieves a specific video segment.

GET /Videos/{itemId}/hls/{playlistId}/{segmentId}.{segmentContainer}

string

required

The video item identifier

string

required

The playlist identifier

string

required

The segment identifier

string

required

The segment container extension: ts or mp4

Response Codes:

200 OK - Segment returned
404 Not Found - Segment not found

Get HLS Audio Segment (Legacy)

Retrieves a specific audio segment.

GET /Audio/{itemId}/hls/{segmentId}/stream.{extension}

string

required

The audio item identifier

string

required

The segment identifier

string

required

The file extension: mp3 or aac

Response Codes:

200 OK - Segment returned
400 Bad Request - Invalid segment

Stopping Active Encoding

Stop Encoding Process

Stops an active encoding/transcoding process.

DELETE /Videos/ActiveEncodings

Authentication: Required

string

required

The device id of the client

string

required

The play session identifier

Response Codes:

204 No Content - Encoding stopped successfully
401 Unauthorized - Authentication required

Example Request

curl -X DELETE "https://your-jellyfin-server/Videos/ActiveEncodings?deviceId=my-device&playSessionId=abc123def456" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

HLS Best Practices

Segment Length

Recommended Values:

Low Latency: 2-3 seconds
Standard: 6 seconds (Jellyfin default)
High Efficiency: 10 seconds

Trade-offs:

Shorter segments: Lower latency, faster quality switching, higher overhead
Longer segments: Better compression, less overhead, slower adaptation

Segment Container

MPEG-TS (ts)

✅ Maximum compatibility
✅ Works with older devices
❌ Less efficient compression
❌ Larger file sizes

Fragmented MP4 (fmp4)

✅ Better compression
✅ Smaller file sizes
✅ Supports more codecs (including FLAC)
❌ Requires FFmpeg 7.0+ for certain features
❌ May not work with older clients

Adaptive Bitrate Streaming

When enableAdaptiveBitrateStreaming=true, Jellyfin generates multiple quality variants:

#EXTM3U
#EXT-X-VERSION:3
# Low quality - mobile/poor connection
#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=640x360
main.m3u8?videoBitRate=600000&maxWidth=640&maxHeight=360

# Medium quality - standard broadband
#EXT-X-STREAM-INF:BANDWIDTH=2400000,RESOLUTION=1280x720
main.m3u8?videoBitRate=2000000&maxWidth=1280&maxHeight=720

# High quality - fast connection
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080
main.m3u8?videoBitRate=4500000&maxWidth=1920&maxHeight=1080

The client automatically switches between variants based on available bandwidth.

Playlist Types

VOD (Video on Demand)

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:6.0,
segment0.ts
#EXTINF:6.0,
segment1.ts
#EXT-X-ENDLIST

Live/Event

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:42
#EXTINF:6.0,
segment42.ts
#EXTINF:6.0,
segment43.ts
# Playlist updates as new segments become available

Trickplay Thumbnails

When enableTrickplay=true, the master playlist includes thumbnail image playlists for seek previews:

#EXT-X-IMAGE-STREAM-INF:BANDWIDTH=50000,RESOLUTION=320x180,CODECS="jpeg"
trickplay/index.m3u8

Client Implementation Tips

Segment Buffering: Buffer at least 3 segments ahead of playback position
Quality Switching: Switch quality variants at segment boundaries
Error Handling: Retry failed segments with exponential backoff
Bandwidth Estimation: Track download speed to predict optimal quality
Playlist Refresh: Refresh live playlists periodically (every target duration)

Server Configuration

Transcoding Path: Ensure adequate disk space in the transcoding directory for temporary segments Cleanup: Jellyfin automatically removes old segment files, but monitor disk usage during active streams Hardware Acceleration: Enable for better performance with multiple concurrent HLS streams

Authentication

Media Management

Playback

User Management

System

Live TV

Overview

HLS Architecture

Video HLS Endpoints

Get Master HLS Video Playlist

Example Request

Example Response

Get Live HLS Video Stream

Example Request

Get Variant HLS Video Playlist

Audio HLS Endpoints

Get Master HLS Audio Playlist

Example Request

HLS Segment Endpoints

Get HLS Video Segment

Get HLS Audio Segment (Legacy)

Stopping Active Encoding

Stop Encoding Process

Example Request

HLS Best Practices

Segment Length

Segment Container

Adaptive Bitrate Streaming

Playlist Types

Trickplay Thumbnails

Client Implementation Tips

Server Configuration

​Overview

​HLS Architecture

​Video HLS Endpoints

​Get Master HLS Video Playlist

​Example Request

​Example Response

​Get Live HLS Video Stream

​Example Request

​Get Variant HLS Video Playlist

​Audio HLS Endpoints

​Get Master HLS Audio Playlist

​Example Request

​HLS Segment Endpoints

​Get HLS Video Segment

​Get HLS Audio Segment (Legacy)

​Stopping Active Encoding

​Stop Encoding Process

​Example Request

​HLS Best Practices

​Segment Length

​Segment Container

​Adaptive Bitrate Streaming

​Playlist Types

​Trickplay Thumbnails

​Client Implementation Tips

​Server Configuration

Overview

HLS Architecture

Video HLS Endpoints

Get Master HLS Video Playlist

Example Request

Example Response

Get Live HLS Video Stream

Example Request

Get Variant HLS Video Playlist

Audio HLS Endpoints

Get Master HLS Audio Playlist

Example Request

HLS Segment Endpoints

Get HLS Video Segment

Get HLS Audio Segment (Legacy)

Stopping Active Encoding

Stop Encoding Process

Example Request

HLS Best Practices

Segment Length

Segment Container

Adaptive Bitrate Streaming

Playlist Types

Trickplay Thumbnails

Client Implementation Tips

Server Configuration