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
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
A user the account shares servers with, or is in a Home with (plex.tv/api/users/, python-plexapi's MyPlexUser).
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 as PlexActivityEvents.
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 Raw requests
Stateful façade over the Plex API.
PlexCollectionsApi Library
/library/collections/* — hand-curated groupings of metadata items.
PlexCredentials
Identity of the client app talking to Plex.
PlexDevice
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
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
A friend of the account (plex.tv/api/v2/friends).
PlexGeoLocation
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
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 /hubs or /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
A token plex.tv issued, with what its claims say about its lifetime.
PlexJwtSession
A device's plex.tv sign-in: its key and current token, kept fresh.
PlexLibraryApi Library
Browse /library/sections and /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.lyrics reads 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 MediaContainer envelope 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/notifications and /:/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
PIN flow state returned by POST /api/v2/pins and GET /api/v2/pins/{id}.
PlexPlaybackApi Playback and play queues
/:/timeline, /:/scrobble, /:/unscrobble, /:/rate.
PlexPlaylistsApi Playlists
Playlist endpoints — /playlists and /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 with PlexPlaybackApi.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
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 (Directory of /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
One candidate URI to reach a PlexResource. Roughly: https://192-168-0-2.{uuid}.plex.direct:32400 for local-https https://1-2-3-4.{uuid}.plex.direct:32400 for remote-https https://relay-…plex.tv for relay http://[2001:db8::2]:32400 for 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.
PlexServerShare
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 with User, Player and (when transcoding) TranscodeSession sub-nodes describing who is playing and how.
PlexSessionPlayer Playback and play queues
Player sub-node of a PlexSession — identifies the device that's driving playback.
PlexSessionsApi Playback and play queues
/status/sessions and /status/sessions/history/* — "what's playing on the server right now" and "what was played in the past".
PlexSessionUser Playback and play queues
User sub-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/:/transcode and /{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/image for 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
User profile returned by /api/v2/user, /users/sign_in.json and a Plex Home switch.
PlexVideoTranscode Streaming
A started video transcode: the server's decision and the url to play (see PlexStreamingApi.startVideoTranscode).

Enums

PlexConnectionKind
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 filterType attribute.
PlexLibraryType Library
Top-level library category (the type field 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 protocol on the universal transcoder (PlexStreamingApi.startVideoTranscode, PlexStreamingApi.startAudioTranscode).
PlexWatchlistFilter
Which part of the watchlist PlexAccountApi.watchlist lists.

Extension Types

PlexMarkerType Library
The kind of a PlexMarker, as in Marker.type and the marker endpoints' type.
PlexMediaType Playlists
A media type, as sent in a playlist's or play queue's type and playlistType: audio, video or photo.
PlexSort Library
A sort order, as sent in sort: a field, optionally with :asc or :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)
Renews a refused token; see PlexClient.tokenRenewer.

Exceptions / Errors

PlexException Errors and paging
Exception thrown by PlexClient for any failed operation.