Skip to main content

​
Overview

The Streaming API provides endpoints for direct playback of audio and video content. These endpoints support both static streaming (direct file access) and dynamic transcoding based on client capabilities.

​
Audio Stream

Stream audio content with optional transcoding.

​
Get Audio Stream

GET /Audio/{itemId}/stream
GET /Audio/{itemId}/stream.{container}
Authentication: Required
​
itemId
string
required
The unique identifier of the audio item
​
container
string
The audio container format (e.g., mp3, aac, flac, opus)
​
static
boolean
default:"false"
If true, streams the original file without encoding. Use either no extension or the original file extension
​
mediaSourceId
string
The media version id, if playing an alternate version
​
deviceId
string
The device id of the client requesting. Used to stop encoding processes when needed
​
audioCodec
string
Specify an audio codec to encode to (e.g., mp3, aac, opus). If omitted, the server will auto-select using the URL’s extension
​
audioBitRate
integer
Specify an audio bitrate to encode to (e.g., 128000). If omitted, this will be left to encoder defaults
​
audioChannels
integer
Specify a specific number of audio channels to encode to (e.g., 2)
​
maxAudioChannels
integer
Specify a maximum number of audio channels to encode to (e.g., 2)
​
audioSampleRate
integer
Specify a specific audio sample rate (e.g., 44100)
​
maxAudioBitDepth
integer
The maximum audio bit depth
​
startTimeTicks
integer
Specify a starting offset, in ticks. 1 tick = 10000 ms (0.01ms)
​
enableAutoStreamCopy
boolean
default:"true"
Whether to allow automatic stream copy if requested values match the original source
​
allowAudioStreamCopy
boolean
default:"true"
Whether to allow copying of the audio stream URL
​
enableAudioVbrEncoding
boolean
default:"true"
Whether to enable Audio VBR (Variable Bit Rate) Encoding
​
Stream
binary
Audio file stream with appropriate MIME type
Response Codes:
  • 200 OK - Audio stream returned successfully
  • 401 Unauthorized - Authentication required
  • 404 Not Found - Item not found

​
Example Request

curl -X GET "https://your-jellyfin-server/Audio/12345678-1234-1234-1234-123456789abc/stream.mp3?audioBitRate=128000&audioChannels=2" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

​
Video Stream

Stream video content with optional transcoding.

​
Get Video Stream

GET /Videos/{itemId}/stream
GET /Videos/{itemId}/stream.{container}
Authentication: Required
​
itemId
string
required
The unique identifier of the video item
​
container
string
The video container. Possible values: ts, webm, asf, wmv, ogv, mp4, m4v, mkv, mpeg, mpg, avi, 3gp, wtv, m2ts, mov, iso, flv
​
static
boolean
default:"false"
If true, streams the original file without encoding
​
mediaSourceId
string
The media version id, if playing an alternate version
​
deviceId
string
The device id of the client requesting
​
videoCodec
string
Specify a video codec to encode to (e.g., h264, hevc, vp9). If omitted, the server will auto-select
​
audioCodec
string
Specify an audio codec to encode to (e.g., aac, mp3, opus)
​
videoBitRate
integer
Specify a video bitrate to encode to (e.g., 5000000). If omitted, left to encoder defaults
​
audioBitRate
integer
Specify an audio bitrate to encode to (e.g., 128000)
​
width
integer
The fixed horizontal resolution of the encoded video
​
height
integer
The fixed vertical resolution of the encoded video
​
maxWidth
integer
The maximum horizontal resolution of the encoded video
​
maxHeight
integer
The maximum vertical resolution of the encoded video
​
framerate
number
A specific video framerate to encode to (e.g., 23.976). Generally should be omitted unless device has specific requirements
​
maxFramerate
number
A specific maximum video framerate to encode to
​
startTimeTicks
integer
Specify a starting offset, in ticks. 1 tick = 10000 ms
​
subtitleStreamIndex
integer
The index of the subtitle stream to use. If omitted, no subtitles will be used
​
subtitleMethod
string
Specify the subtitle delivery method: Encode, Embed, External, Hls
​
Stream
binary
Video file stream with appropriate MIME type
Response Codes:
  • 200 OK - Video stream returned successfully
  • 400 Bad Request - Invalid parameters or unsupported protocol
  • 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/stream.mp4?videoBitRate=5000000&width=1920&height=1080" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

​
Universal Audio Stream

Intelligent audio streaming endpoint that automatically selects the best streaming method based on device capabilities.

​
Get Universal Audio Stream

GET /Audio/{itemId}/universal
Authentication: Required
​
itemId
string
required
The unique identifier of the audio item
​
container
array
Comma-delimited list of supported containers (e.g., “mp3,aac,flac”)
​
mediaSourceId
string
The media version id, if playing an alternate version
​
deviceId
string
The device id of the client requesting
​
userId
string
The user id (optional, defaults to authenticated user)
​
audioCodec
string
The audio codec to transcode to
​
maxAudioChannels
integer
The maximum number of audio channels
​
transcodingAudioChannels
integer
The number of audio channels to transcode to
​
maxStreamingBitrate
integer
The maximum streaming bitrate
​
audioBitRate
integer
Specify an audio bitrate to encode to (e.g., 128000)
​
startTimeTicks
integer
Specify a starting offset, in ticks
​
transcodingContainer
string
The container to transcode to
​
transcodingProtocol
string
The transcoding protocol: http or hls
​
maxAudioSampleRate
integer
The maximum audio sample rate
​
maxAudioBitDepth
integer
The maximum audio bit depth
​
enableRemoteMedia
boolean
Whether to enable remote media
​
enableAudioVbrEncoding
boolean
default:"true"
Whether to enable Audio VBR Encoding
​
enableRedirection
boolean
default:"true"
Whether to enable redirection for remote streams
Response Codes:
  • 200 OK - Audio stream returned
  • 302 Found - Redirected to remote audio stream
  • 404 Not Found - Item not found

​
Example Request

curl -X GET "https://your-jellyfin-server/Audio/12345678-1234-1234-1234-123456789abc/universal?container=mp3,aac&maxStreamingBitrate=192000" \
  -H "Authorization: MediaBrowser Token=YOUR_API_KEY"

​
Notes

​
Ticks

Jellyfin uses “ticks” as a time unit where 1 tick = 0.01 milliseconds = 10000 ticks per millisecond. This allows for high-precision timing. Conversion:
  • Milliseconds to Ticks: milliseconds * 10000
  • Seconds to Ticks: seconds * 10000000
  • Ticks to Milliseconds: ticks / 10000

​
Static vs Dynamic Streaming

Static Streaming:
  • Serves the original file without modification
  • Requires client to support the native format
  • Lower server resource usage
  • Faster startup time
Dynamic Streaming:
  • Transcodes content on-the-fly
  • Adapts to client capabilities and network conditions
  • Higher server resource usage
  • More compatible with diverse clients

​
HTTP Methods

Most streaming endpoints support both:
  • GET - Returns the actual stream
  • HEAD - Returns headers only (useful for checking availability and getting metadata)