Streaming topic
Build stream URLs for audio and video, manage transcode sessions, and read lyrics and loudness.
The streaming calls return URLs; none of them fetches the media. Hand the
URL to your player (mpv, AVPlayer, ExoPlayer). The URL carries
X-Plex-Token in its query, so segment requests need no headers.
PlexStreamingProtocol names the protocol: hls (an .m3u8 of MPEG-TS
segments), dash (an .mpd of fragmented MP4) or http (one stream).
Audio transcode
final transcode = await plex.streaming.startAudioTranscode(
ratingKey: track.ratingKey,
session: 'my-uuid', // one per playback session
protocol: PlexStreamingProtocol.dash, // hls (default) or dash
maxAudioBitrateKbps: 128,
);
if (transcode.decision.isPlayable) {
print(transcode.url); // hand to the player
}
startAudioTranscode() asks the server for a decision for session,
then builds the start URL from the same parameters. It names a client
profile (clientProfileName, 'Generic' by default), so it works from
any platform, and sends the transcode target and the bitrate cap the
server expects. audioCodec is 'aac' by default; offsetSeconds,
mediaIndex and partIndex pick where and what to play. The cap cannot
go above the profile's own ceiling, 256 kbps AAC for Generic.
When decision.isPlayable is false the URL does not play either. Stop
each session you stop playing (see Transcode sessions below): while
other transcodes of the same client stay open, a new session's bitrate
cap may not apply. To make the decision yourself,
PlexStreamingApi.musicProfileExtra() builds the same profile value for
decisionUniversal().
Direct file URL
final (url, ext) = plex.streaming.directFileUrl(
partKey: track.media.first.parts.first.key!,
);
The original file, with no transcode. Use it for downloads (see
Events and downloads)
and for players that decode whatever the file contains. ext is the
file's extension.
The server sends an MP3 without its ID3v2 tag, so a downloaded MP3 has no
embedded tags or cover and is a little shorter than PlexPart.size. Take
metadata and artwork from the server.
Transcode sessions
await plex.streaming.pingUniversal(session: sessionId); // keep alive
await plex.streaming.stopUniversal(session: sessionId); // tear down
The same calls serve audio and video sessions. The server drops a
session after about 2 minutes without requests: ping every 30 s while
the player is paused, and stop the session when the user leaves.
pingUniversal() throws a PlexException of type notFound once the
session is gone. stopUniversal() returns normally when the session no
longer exists, or never started: the server creates a DASH session with
its first segment.
Video transcode
final transcode = await plex.streaming.startVideoTranscode(
ratingKey: movie.ratingKey,
session: 'my-uuid',
protocol: PlexStreamingProtocol.hls, // hls, dash or http
maxVideoBitrateKbps: 8000,
videoResolution: '1920x1080',
);
if (transcode.decision.isPlayable) {
print(transcode.url); // start.m3u8, start.mpd or start.mkv
}
The video counterpart of startAudioTranscode(): a decision for
session, then the start URL with the same parameters. PMS 1.43.2
answers "no conversion profile found" (decision code 4005) unless the
client profile names a target, so the call sends
X-Plex-Client-Profile-Name (Generic by default) and a videoProfile
target for the protocol (PlexStreamingApi.videoProfileExtra():
videoCodec h264 and audioCodec aac by default, in MPEG-TS, MP4 or
Matroska). Verified for all three protocols on PMS 1.43.2.
directStream (on by default) lets the server copy what it need not
re-encode.
Video decision
To make the decision yourself, call decisionUniversal(). The server
weighs the source against your client profile and answers with
generalDecisionCode: 1xxx means playback can succeed; 2xxx (general),
3xxx (direct play) and 4xxx (transcode) are errors.
final decision = await plex.streaming.decisionUniversal(
params: {
'path': '/library/metadata/$ratingKey',
'mediaIndex': 0,
'partIndex': 0,
'protocol': PlexStreamingProtocol.hls.wire,
'directPlay': 0,
'directStream': 1,
'videoResolution': '1920x1080',
'maxVideoBitrate': 8000,
'session': 'my-uuid',
'X-Plex-Client-Profile-Name': 'Generic',
},
extraHeaders: {
'X-Plex-Client-Profile-Extra': PlexStreamingApi.videoProfileExtra(
protocol: PlexStreamingProtocol.hls,
),
},
);
if (decision.isDirect) {
// direct play or direct stream
} else if (decision.isTranscode) {
// the server transcodes
} else {
print(decision.text); // why not: bandwidth, codec, the remote pass
}
transcodeType is 'video' by default; 'music' and 'photo' reach
the other transcoders. isDirect and isTranscode read
directPlayDecisionCode and transcodeDecisionCode; text is the
server's own explanation and the whole answer is in raw.
Remote playback and the pass
Since April 2025 Plex requires a Plex Pass (on the server owner's
account) or a Remote Watch Pass (on the viewer's) to stream personal
video to a device outside the server's network. plex.connectionKind
says how the client reaches the server (local, remote or relay,
known after connectToResource or connectTo).
A refusal for that reason is a PlexException of type
PlexErrorType.passRequired (isPassRequired), with the server's whole
answer in body. It is not an auth error: the token works, do not sign
the user out. PMS documents no code for it, so the decision calls
(decisionUniversal, startVideoTranscode, startAudioTranscode)
recognise it from:
- the text of a 4xx error answer other than
401,404and498, or of a decision'sgeneralDecisionText,transcodeDecisionTextordirectPlayDecisionText, naming "Plex Pass" or "Remote Watch", or remote playback as requiring a subscription or not allowed. An HTML page does not count: a site's pages can name the Plex Pass anywhere.
startAudioTranscode() and startVideoTranscode() throw for such a
decision; decisionUniversal() returns it, with isPassRequired true.
A bare 403 stays an auth error on any connection: it is also how a
server refuses a token. The rule could not be checked against a real
refusal for this release.
A refusal they miss stays the error it was (an auth or bad-request
error, or an unplayable decision): when in doubt, read connectionKind
and body. Music is not covered by the requirement.
Transcoder URLs
plex.transcoder builds the raw transcoder URLs:
final cover = plex.transcoder.imageUrl(
sourceUrl: album.thumb!,
width: 600,
height: 600,
blur: 20,
format: 'png',
);
final subtitles = plex.transcoder.subtitlesUrl(
transcodeType: 'video',
params: {'session': 'my-uuid'},
);
imageUrl() exposes every option of the photo transcoder (quality,
blur, saturation, opacity, rotate, background, blendColor).
triggerFallback() asks the server for a full transcode after direct
play failed. startUrl() and streaming.universalVideoUrl() are
deprecated: PMS refuses a start without a decision, which
startVideoTranscode() and startAudioTranscode() make first.
Do not log these URLs. Every URL built here (a transcode url,
directFileUrl(), the transcoder URLs) carries the X-Plex-Token in its
query, because the player opens it without this client's headers:
whoever reads one can use the server as you. Building one before
connect() throws a state PlexException.
Lyrics
final full = await plex.library.item(ratingKey: track.ratingKey);
final lyricsStream = full!.media.first.parts.first.streams
.firstWhere((s) => s.isLyrics);
final lyrics = await plex.streaming.lyrics(streamKey: lyricsStream.key!);
for (final line in lyrics?.lines ?? const <PlexLyricLine>[]) {
print('${line.start} ${line.text}');
}
The lyrics are a stream of the full item (isLyrics, stream type 4).
lyrics() returns PlexLyrics, or null when there is none: text is
the file as decoded, lines its lines read as LRC. A line has start
(null when unsynced), text and, for enhanced LRC, word cues
(position, endPosition, start, end), the shape of dart_jellyfin's
JellyfinLyricLine. Several [mm:ss.xx] on one line repeat it, the LRC
ID tags (ar, ti, al, au, by, length, offset, re, ve,
#) go to metadata, and [offset:±ms] is applied to every time. Any
other bracketed line, such as [Chorus: Jay-Z], is text.
toLrc() (with enhanced: true for word times) and toPlainText() write
it back.
The file is decoded whatever its encoding: a byte-order mark first
(removed, so the first [mm:ss.xx] still starts its line), then the
response's charset, then UTF-8 with Latin-1 as the fallback.
Loudness
final full = await plex.library.item(ratingKey: track.ratingKey);
final audio = full?.audioStream;
if (audio != null && audio.hasLoudness) {
print('track gain ${audio.gain} dB, album gain ${audio.albumGain} dB, '
'peak ${audio.peak}, ${audio.loudness} LUFS');
}
An analysed audio stream carries gain, albumGain, peak,
albumPeak, albumRange, loudness (LUFS), lra (LU), startRamp and
endRamp, from the server's own analysis, and canNormalizeLoudness
says whether the server can level it. They survive a transcode that drops the file's ReplayGain tags:
read them from the original stream and apply the gain to the transcoded
audio. audioStream is the selected audio stream of the first part.
Classes
- PlexAudioTranscode Streaming
- A started audio transcode: the server's decision and the url to play (see PlexStreamingApi.startAudioTranscode).
- PlexLyricCue Streaming
- A word of an enhanced LRC PlexLyricLine: where it sits in the line's text and when it is sung.
- PlexLyricLine Streaming
-
One line of PlexLyrics, shaped like dart_jellyfin's
JellyfinLyricLine. - PlexLyrics Streaming
-
A track's lyrics as
PlexStreamingApi.lyricsreads them: the text as the server sent it, and its lines. - PlexStreamingApi Streaming
- Transcode decisions and streaming URLs.
- PlexTranscodeDecision Streaming
- Outcome of PlexStreamingApi.decisionUniversal.
- PlexTranscoderApi Streaming
-
/photo/:/transcodeand/{audio|video|photo}/:/transcode/...— universal transcode URL builders. - PlexVideoTranscode Streaming
- A started video transcode: the server's decision and the url to play (see PlexStreamingApi.startVideoTranscode).
Enums
- PlexStreamingProtocol Streaming
-
How a transcode reaches the player, as in
protocolon the universal transcoder (PlexStreamingApi.startVideoTranscode, PlexStreamingApi.startAudioTranscode).