dart_plex library
A Dart client for Plex Media Server 1.43 and plex.tv.
PlexClient holds the client identity, the server and the tokens, and exposes one sub-API per domain:
final plex = PlexClient(
credentials: const PlexCredentials(
clientIdentifier: 'a-stable-id-per-install',
product: 'MyApp',
version: '1.0.0',
device: 'iPhone',
deviceName: 'My iPhone',
platform: 'iOS',
),
);
// Sign in with a device key: the user approves the pin in a browser.
final key = await PlexDeviceKey.generate();
var pin = await plex.account.createJwtPin(key: key);
openBrowser(plex.account.authAppUrl(pin));
while (!pin.isAuthenticated) {
await Future<void>.delayed(const Duration(seconds: 1));
pin = await plex.account.pollJwtPin(id: pin.id, key: key);
}
await plex.useJwt(
PlexJwtSession(key: key, token: PlexJwt.parse(pin.authToken!)),
);
final servers = await plex.account.fetchResources();
final server = servers.firstWhere((s) => s.owned);
await plex.connectToResource(server);
final sections = await plex.library.sections();
final music = sections.firstWhere((s) => s.type == PlexLibraryType.music);
final albums = await plex.library.allByType(
sectionId: music.id,
type: PlexMetadataType.album,
size: 50,
);
Classes
- PlexAccountApi Client and sign-in
- Talks to plex.tv for everything that lives outside a specific Plex Media Server: sign-in (PIN, JWT, password), server discovery, the user's profile, Plex Home, friends, the watchlist.
- PlexAccountUser Client and sign-in
-
A user the account shares servers with, or is in a Home with
(
plex.tv/api/users/, python-plexapi'sMyPlexUser). - PlexActivitiesApi Server
-
/activities— long-running server activities (scan progress, transcoding sessions, etc.). - PlexActivity Server
-
A running background activity (
/activities→Activity), e.g. a library scan. The same activities arrive live asPlexActivityEvents. - PlexActivityEvent Events and downloads
-
A background activity started, progressed or ended (frame type
activity) — library scans above all. - PlexArtwork Images and hubs
- Helpers for PMS artwork paths.
- PlexAudioTranscode Streaming
- A started audio transcode: the server's decision and the url to play (see PlexStreamingApi.startAudioTranscode).
- PlexButlerApi Server
-
/butler— Plex's nightly maintenance task runner. - PlexButlerTask Server
-
A scheduled maintenance task (
/butler→ButlerTask). - PlexCancelToken Errors and paging
- Cancels requests that are still in flight.
- PlexChannelMapping Live TV
-
How a device channel maps to a lineup channel (
ChannelMapping). - PlexChapter Library
-
A chapter of a video (
Chapter). - PlexClient Client and sign-in Raw requests
- Stateful façade over the Plex API.
- PlexCollectionsApi Library
-
/library/collections/*— hand-curated groupings of metadata items. - PlexCredentials Client and sign-in
- Identity of the client app talking to Plex.
- PlexDevice Client and sign-in
-
A device signed in to the account (
plex.tv/api/v2/devices). - PlexDeviceChannel Live TV
-
A channel a tuner device can receive
(
/media/grabbers/devices/{id}/channels). - PlexDeviceKey Client and sign-in
- The Ed25519 key pair a device signs in to plex.tv with.
- PlexDevicesApi Live TV
-
/media/grabbers/*— DVR/IPTV grabber device management. - PlexDownloadQueue Events and downloads
-
A download queue (
/downloadQueue): one per client and user. - PlexDownloadQueueApi Events and downloads
-
/downloadQueue/*— legacy mobile-sync download queue. - PlexDownloadQueueItem Events and downloads
-
An item of a download queue (
DownloadQueueItem). - PlexDvr Live TV
-
A DVR: a lineup with the tuners that record from it (
/livetv/dvrs). - PlexDvrsApi Live TV
-
/livetv/dvrs/*— Plex DVR backend configuration. - PlexEpgApi Live TV
-
/livetv/epg/*— Electronic Program Guide. - PlexEpgChannel Live TV
-
A channel of a lineup (
Channel). - PlexEpgCountry Live TV
-
A country (or a region of one) with program guide data
(
/livetv/epg/countries,…/regions). - PlexEpgLanguage Live TV
-
A guide language (
/livetv/epg/languages). - PlexEvent Events and downloads
- One event from the notification stream. Switch over the subtypes:
- PlexFilter Library
- One condition in a library filter.
- PlexFriend Client and sign-in
-
A friend of the account (
plex.tv/api/v2/friends). - PlexGeoLocation Client and sign-in
-
Where an IP address is, by plex.tv's GeoIP database
(
plex.tv/api/v2/geoip). - PlexHistoryEntry Playback and play queues
-
One play in
/status/sessions/history/all. - PlexHomeUser Client and sign-in
-
A member of the account's Plex Home (
plex.tv/api/home/users): the admin, other full accounts, and managed users. - PlexHub Images and hubs
-
One
<Hub>entry from/hubsor/hubs/search— a titled, optionally paginated bucket of PlexMetadata items grouped by Plex. - PlexHubsApi Images and hubs
-
/hubs/*— global and per-section discovery rails. - PlexImage Images and hubs
- One entry of PlexMetadata.images.
- PlexImagesApi Images and hubs
-
Build & fetch artwork URLs through the server's image transcoder
(
/photo/:/transcode). - PlexJwt Client and sign-in
- A token plex.tv issued, with what its claims say about its lifetime.
- PlexJwtSession Client and sign-in
- A device's plex.tv sign-in: its key and current token, kept fresh.
- PlexLibraryApi Library
-
Browse
/library/sectionsand/library/metadata/{id}. - PlexLibraryFilter Library
-
One facet a section can be filtered on, from
/library/sections/{id}/filters. - PlexLibraryItemEvent Events and downloads
-
A library item was created, changed, analysed or deleted (frame type
timeline). - PlexLibrarySection Library
-
One library section from
/library/sections. - PlexLineup Live TV
-
A channel lineup (
/livetv/epg/…/lineups,lineupchannels). - PlexLiveTvApi Live TV
-
/livetv/*— Plex Live TV and DVR. - PlexLogApi Server
-
/log— send log entries to the server. - 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. - PlexMarker Library
-
A span of a video the server marked (
Marker): an intro or credits to skip, a commercial break. - PlexMedia Library
-
One
<Media>node under a PlexMetadata. Tracks/movies usually have exactly one; some items have alternate versions and produce several. -
PlexMediaContainer<
T> Library -
Every PMS endpoint returns a
MediaContainerenvelope wrapping the payload. This helper unwraps it and validates the basic shape. - PlexMediaGrabber Live TV
-
A grabber type the server supports (
/media/grabbers). - PlexMediaGrabOperation Live TV
-
A recording, in progress or planned (
MediaGrabOperation). - PlexMediaProvider Server
-
A media provider registered on the server (
/media/providers): the library itself, or an online source. - PlexMediaSubscription Live TV
-
A recording rule (
/media/subscriptions): "record this show", "record this airing". - PlexMetadata Library
-
A single item under
/library/metadata/{ratingKey}(or as an entry in any list response). Generic across types — the type tag tells you which fields are meaningful. - PlexNotification Events and downloads
- One frame received from the Plex notifications stream.
- PlexNotificationsApi Events and downloads
-
/:/websockets/notificationsand/:/eventsource/notifications— server-push notifications. - PlexPaging Errors and paging
- Walk a paged endpoint page by page.
- PlexPart Library
-
One
<Part>node — a single file backing a PlexMedia. - PlexPerson Library
-
A person in the library (
/library/people/{id}): an actor, a director, … - PlexPin Client and sign-in
-
PIN flow state returned by
POST /api/v2/pinsandGET /api/v2/pins/{id}. - PlexPlaybackApi Playback and play queues
-
/:/timeline,/:/scrobble,/:/unscrobble,/:/rate. - PlexPlaylistsApi Playlists
-
Playlist endpoints —
/playlistsand/playlists/{id}/items. - PlexPlayQueue Playback and play queues
-
Wraps the response of
POST /playQueues(and friends). - PlexPlayQueueGenerator Playlists
-
What feeds a smart playlist (
PlayQueueGenerator). - PlexPlayQueuesApi Playback and play queues
-
/playQueues/*— Plex's canonical playback queue model. - PlexPlaySessionEvent Events and downloads
-
A player's play state changed (frame type
playing): playing, paused, stopped or buffering — the same reports a client sends withPlexPlaybackApi.timeline, as the server saw them. - PlexPreferencesApi Server
-
/:/prefs— server preferences (setting names and values). - PlexProviderFeature Server
-
One feature of a PlexMediaProvider (
Feature). - PlexProvidersApi Server
-
/media/providers— third-party media providers (TIDAL, internal channels, external streaming sources). - PlexRelease Server
-
A server release on offer (
Release). - PlexResource Client and sign-in
-
One server entry from
plex.tv/api/v2/resources. -
PlexResponse<
T> Raw requests - A completed response with a decoded body.
- PlexRetryPolicy Errors and paging
- When and how often to resend a request that failed transiently.
- PlexSearchApi Search
- Search endpoints.
- PlexSectionDetails Library
-
A section's details (
/library/sections/{id}): its views, as directories to browse. - PlexSectionView Library
-
A view of a section (
Directoryof/library/sections/{id}). - PlexSecurityResource Server
-
How to reach a source and with which token (
/security/resources). - PlexServerApi Server
-
Top-level server endpoints —
/,/identity,/capabilities. - PlexServerConnection Client and sign-in
-
One candidate URI to reach a PlexResource. Roughly:
https://192-168-0-2.{uuid}.plex.direct:32400for local-httpshttps://1-2-3-4.{uuid}.plex.direct:32400for remote-httpshttps://relay-…plex.tvfor relayhttp://[2001:db8::2]:32400for an IPv6 address - PlexServerIdentity Server
-
GET /identity— who the server is. Answers without a token. - PlexServerInfo Server
-
GET /— the server's capabilities and account state. -
One server shared with a PlexAccountUser (python-plexapi's
MyPlexServerShare). - PlexSession Playback and play queues
-
One entry from
/status/sessions— a Plex metadata item enriched withUser,Playerand (when transcoding)TranscodeSessionsub-nodes describing who is playing and how. - PlexSessionPlayer Playback and play queues
-
Playersub-node of a PlexSession — identifies the device that's driving playback. - PlexSessionsApi Playback and play queues
-
/status/sessionsand/status/sessions/history/*— "what's playing on the server right now" and "what was played in the past". - PlexSessionUser Playback and play queues
-
Usersub-node of a PlexSession — identifies the account streaming the item. - PlexSetting Server
-
One server preference (
/:/prefs→Setting). - PlexStatusEvent Events and downloads
-
A server status message (frame type
status), e.g. a scan starting. - PlexStream Library
-
streamType: 1 video, 2 audio, 3 subtitle, 4 lyrics. - PlexStreamedResponse Raw requests
- A response whose body is still arriving, for downloads too large to hold in memory.
- PlexStreamingApi Streaming
- Transcode decisions and streaming URLs.
- PlexSubscriptionsApi Live TV
-
/media/subscriptions/*— DVR recording subscriptions. - PlexTag Library
- One value of a filterable field — a genre, mood, style, decade, collection or label row.
- PlexTranscodeDecision Streaming
- Outcome of PlexStreamingApi.decisionUniversal.
- PlexTranscodeJob Server
-
A background transcode job — an optimize or a sync conversion
(
/status/sessions/background,TranscodeJob). - PlexTranscoderApi Streaming
-
/photo/:/transcodeand/{audio|video|photo}/:/transcode/...— universal transcode URL builders. - PlexTunerDevice Live TV
-
A tuner or other grabber device (
/media/grabbers/devices). - PlexUltraBlurApi Images and hubs
-
/services/ultrablur/*— server-side palette extraction and gradient backdrop rendering. - PlexUltraBlurColors Images and hubs
-
Four hex colours extracted from an image by the Plex server. Use
the same four values to ask
/services/ultrablur/imagefor a server-rendered gradient backdrop. - PlexUnknownEvent Events and downloads
-
A frame type without a typed event (
progress,reachability,transcodeSession.update,preference, …). raw is the whole frame. - PlexUpdaterApi Server
-
/updater/*— server software update lifecycle. - PlexUpdaterStatus Server
-
The server's update state (
/updater/status). - PlexUser Client and sign-in
-
User profile returned by
/api/v2/user,/users/sign_in.jsonand a Plex Home switch. - PlexVideoTranscode Streaming
- A started video transcode: the server's decision and the url to play (see PlexStreamingApi.startVideoTranscode).
Enums
- PlexConnectionKind Client and sign-in
- How a PlexServerConnection reaches the server, from what plex.tv says about it.
- PlexErrorType Errors and paging
- Semantic categories for failures coming out of PlexClient.
- PlexFilterOperator Library
- How a PlexFilter compares its values against its field.
- PlexFilterValueType Library
-
Kind of value a PlexLibraryFilter compares against, from the
filterTypeattribute. - PlexLibraryType Library
-
Top-level library category (the
typefield on a<Directory>returned from/library/sections). - PlexMetadataType Library
-
The integer type tag used on every
/library/metadata/{id}response. - PlexPlayState Playback and play queues
- Play state of a session.
- PlexResponseType Raw requests
- How PlexClient.request decodes a response body.
- PlexStreamingProtocol Streaming
-
How a transcode reaches the player, as in
protocolon the universal transcoder (PlexStreamingApi.startVideoTranscode, PlexStreamingApi.startAudioTranscode). - PlexWatchlistFilter Client and sign-in
-
Which part of the watchlist
PlexAccountApi.watchlistlists.
Extension Types
- PlexMarkerType Library
-
The kind of a PlexMarker, as in
Marker.typeand the marker endpoints'type. - PlexMediaType Playlists
-
A media type, as sent in a playlist's or play queue's
typeandplaylistType:audio,videoorphoto. - PlexSort Library
-
A sort order, as sent in
sort: a field, optionally with:ascor:desc, several joined with,.
Extensions
-
PlexNotificationEvents
on Stream<
PlexNotification> Events and downloads - Typed events from a notification stream.
Typedefs
-
PlexTokenRenewer
= Future<
String?> Function(String? rejected) Client and sign-in - Renews a refused token; see PlexClient.tokenRenewer.
Exceptions / Errors
- PlexException Errors and paging
- Exception thrown by PlexClient for any failed operation.