dart_plex library

Pure-Dart client for Plex Media Server.

Entry point is PlexClient — a stateful façade that holds the credentials/token across calls and exposes one sub-API per domain:

final plex = PlexClient(
  credentials: const PlexCredentials(
    clientIdentifier: '2f5b…-uuid',
    product: 'Finova',
    version: '1.0.0',
    device: 'iPhone',
    deviceName: "Alex's iPhone",
    platform: 'iOS',
  ),
);

// 1. Authenticate against plex.tv
final user = await plex.account.signInWithPassword('alex', 'hunter2');

// 2. Discover the user's servers and connect to one
final resources = await plex.account.fetchResources();
final server = resources.firstWhere((r) => r.owned);
await plex.connect(server.bestConnection().uri, accessToken: server.accessToken);

// 3. Browse libraries
final libs = await plex.library.sections();
final musicLib = libs.firstWhere((l) => l.type == PlexLibraryType.music);
final albums = await plex.library.allByType(
  sectionId: musicLib.id,
  type: PlexMetadataType.album,
  limit: 50,
);

Higher-level use cases (artwork URLs, transcode session URLs, playback reporting) are exposed through dedicated sub-APIs: PlexClient.artwork, PlexClient.streaming, PlexClient.playback.

Classes

PlexAccountApi: Talks to plex.tv/api/v2 for everything that lives outside a specific Plex Media Server: authentication, server discovery, user profile.
PlexActivitiesApi: /activities — long-running server activities (scan progress, transcoding sessions, etc.).
PlexButlerApi: /butler — Plex's nightly maintenance task runner.
PlexClient: Stateful façade over the Plex API.
PlexCollectionsApi: /library/collections/* — hand-curated groupings of metadata items.
PlexCredentials: Identity of the client app talking to Plex.
PlexDevicesApi: /media/grabbers/* — DVR/IPTV grabber device management.
PlexDownloadQueueApi: /downloadQueue/* — legacy mobile-sync download queue.
PlexDVRsApi: /livetv/dvrs/* — Plex DVR backend configuration.
PlexEpgApi: /livetv/epg/* — Electronic Program Guide.
PlexHub: One <Hub> entry from /hubs or /hubs/search — a titled, optionally paginated bucket of PlexMetadata items grouped by Plex.
PlexHubsApi: /hubs/* — global and per-section discovery rails.
PlexImagesApi: Build & fetch artwork URLs through the server's image transcoder (/photo/:/transcode).
PlexLibraryApi: Browse /library/sections and /library/metadata/{id}.
PlexLibrarySection: One library section from /library/sections.
PlexLiveTvApi: /livetv/* — Plex Live TV and DVR.
PlexLogApi: /log — send log entries to the server.
PlexMedia: One <Media> node under a PlexMetadata. Tracks/movies usually have exactly one; some items have alternate versions and produce several.
PlexMediaContainer<T>: Every PMS endpoint returns a MediaContainer envelope wrapping the payload. This helper unwraps it and validates the basic shape.
PlexMetadata: 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: One frame received from the Plex notifications stream.
PlexNotificationsApi: /:/websockets/notifications and /:/eventsource/notifications — server-push notifications.
PlexPart: One <Part> node — a single file backing a PlexMedia.
PlexPin: PIN flow state returned by POST /api/v2/pins and GET /api/v2/pins/{id}.
PlexPlaybackApi: /:/timeline, /:/scrobble, /:/unscrobble, /:/rate.
PlexPlaylistsApi: Playlist endpoints — /playlists and /playlists/{id}/items.
PlexPlayQueue: Wraps the response of POST /playQueues (and friends).
PlexPlayQueuesApi: /playQueues/* — Plex's canonical playback queue model.
PlexPreferencesApi: /:/prefs — server preferences (setting names and values).
PlexProvidersApi: /media/providers — third-party media providers (TIDAL, internal channels, external streaming sources).
PlexResource: One server entry from plex.tv/api/v2/resources.
PlexSearchApi: Search endpoints.
PlexServerApi: 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
PlexSession: 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: Player sub-node of a PlexSession — identifies the device that's driving playback.
PlexSessionsApi: /status/sessions and /status/sessions/history/* — "what's playing on the server right now" and "what was played in the past".
PlexSessionUser: User sub-node of a PlexSession — identifies the account streaming the item.
PlexStream: streamType: 1 video, 2 audio, 3 subtitle, 4 lyrics.
PlexStreamingApi: Audio (and video) streaming URL builders.
PlexSubscriptionsApi: /media/subscriptions/* — DVR recording subscriptions.
PlexTranscodeDecision: Outcome of PlexStreamingApi.decisionUniversal.
PlexTranscoderApi: /photo/:/transcode and /{audio|video|photo}/:/transcode/... — universal transcode URL builders.
PlexUltraBlurApi: /services/ultrablur/* — server-side palette extraction and gradient backdrop rendering.
PlexUltraBlurColors: 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.
PlexUpdaterApi: /updater/* — server software update lifecycle.
PlexUser: User profile returned by /api/v2/user and /users/sign_in.json.

Enums

PlexErrorType: Semantic categories for failures coming out of PlexClient.
PlexLibraryType: Top-level library category (the type field on a <Directory> returned from /library/sections).
PlexMetadataType: The integer type tag used on every /library/metadata/{id} response.

Exceptions / Errors

PlexException: Exception thrown by PlexClient for any failed operation.

dart_plex library

Classes

Enums

Exceptions / Errors

dart_plex package

dart_plex library