dart_plex 0.2.0
dart_plex: ^0.2.0 copied to clipboard
Dart client for Plex Media Server. Supports authentication, library browsing, playlists, streaming, search and more. Targets macOS, Windows, Linux, iOS and Android.
0.2.0 11-10-2026 #
A revision of the whole package. See MIGRATION.md for the changes to make in an app.
Breaking #
- The transport is
package:http, not Dio. Pass anyhttp.ClientashttpClient:(dio:is gone).request()and its siblings return aPlexResponse<T>and take aPlexResponseTypeand aPlexCancelToken.PlexException.fromDioandfetchBytes()are gone. - Every id is a named parameter:
library.item(ratingKey: …),playlists.items(playlistId: …),playback.scrobble(ratingKey: …)and so on. server.identity(),server.info(),sessions.history(),activities.list(),butler.tasks()andpreferences.all()return typed models instead of maps.preferences.byId()returnsnullfor an unknown id.- The API exposes
Object?instead ofdynamicin its maps and lists. - Models,
PlexException,PlexCredentials,PlexFilter,PlexNotificationandPlexTranscodeDecisionarefinal.PlexClientand the sub-APIs gained members, so a fake that implements one must add them. PlexMediaContainer.rawholds the envelope's own fields, without the entry array.playback.timeline()takes exactly one ofplayState:and the deprecatedstate:, and throwsArgumentErrorfor a duration of zero or less, a negative time orPlexPlayState.unknown.playlists.items(),library.children()andallLeaves()throwArgumentErrorfor astartwithout asize.library.autocomplete()requires aPlexMetadataType type.streaming.stopUniversal()returns normally when the session is already gone.- An empty answer without a JSON content type is
nullinPlexResponse.data, not"". Query values that are not strings are form-encoded, and aList<int>body is sent as bytes.
Added #
PlexClient.withCancelToken(), a view of the client whose calls one token cancels, andPlexClient.close().PlexRetryPolicy: opt-in resend ofGETandHEADafter a network failure,502,503,504or429, with backoff andRetry-After.PlexException.isNetworkFailure,isTransient,isNotFound,isCancelledandretryAfter.requestStream(), anddownloadToFile()in the newpackage:dart_plex/io.dart.library.children()with paging and sort,countChildren(),allLeaves()with paging,grandchildren(),recentlyAdded()andsearch.section().playlists.list()andcount()takefilters:andsort:.streaming.startAudioTranscode(), which makes the decision and caps the bitrate the way the server accepts, andPlexStreamingApi.musicProfileExtra().- Typed notification events:
PlexEventwithPlexPlaySessionEvent,PlexLibraryItemEvent,PlexActivityEvent,PlexStatusEventandPlexUnknownEvent, throughnotification.eventsorstream.events(). timeline(playState:, playQueueItemID:).PlexMetadata.roles,playlistItemId,playQueueItemId,audioStream,originallyAvailableAt,parentYear,leafCount,viewedLeafCount,childCount,skipCount,lastRatedAt,librarySectionId,librarySectionTitle,parentGuid,grandparentGuid,distance,scoreandultraBlurColors.PlexMetadata.thumbVersion,artVersion,parentThumbVersion,grandparentThumbVersionandPlexArtwork.versionOf(), for artwork cache keys.PlexStream.gain,albumGain,peak,albumPeak,loudnessandlra.PlexPaging.pages()anditems().
Changed #
- Large responses are decoded, inflated and parsed into models on a background isolate, above
jsonIsolateThreshold(50 KB by default). scrobble(),unscrobble(),rate()andsetFavorite()are sent asPUT.timeline()sends a time past the duration as the duration.PlexDVRsApiisPlexDvrsApi; the old name is a deprecated typedef.streaming.universalAudioUrl()is deprecated: usestartAudioTranscode().timeline(state: String)and thePlexPlaybackApi.state*constants are deprecated: useplayState:.timeline(playQueueItemId: String)is deprecated: useplayQueueItemID: int.nearestToTrack(excludeParentID:, excludeGrandparentID:)are deprecated: useexcludeParentRatingKeyandexcludeGrandparentRatingKey.isRetriableis deprecated: useisNetworkFailure, orisTransientto include 5xx and 429.- The pinned API document is LukeHagar/plex-api-spec@3f0fb272b29c, and a contract test checks every request against it.
Fixed #
library.firstCharacters()calls/firstCharacter: the old route answered 404.library.setItemArtwork(data:)uploads the bytes instead of their text.notifications.connectEventSource()keeps a quiet stream open, and closing it before the server answers cancels the request.- A gzip body cut short fails instead of coming back short.
- Two
createcalls throw aPlexExceptionof typeparse, not a bareException, when the server answers no item.
0.1.3 22-09-2026 #
0.1.2 09-09-2026 #
Fixed #
streaming.lyrics()returns readable text whatever the file's encoding: accented characters in a UTF-8.lrccame back mangled, and a UTF-16 one full of NUL.notifications.connectEventSource()decodes the event stream as a whole, so a multi-byte character split across two network chunks no longer becomes U+FFFD.
0.1.1 12-08-2026 #
Breaking #
library.allByType()andcountByType()takefilters, a list ofPlexFilter, instead offilter: writefilters: [PlexFilter.genre(6)]forfilter: 'genre=6'. Several filters are combined with AND.library.allByType()loses itstitleargument: usePlexFilter.titleContains()orPlexFilter.titleIs().library.genres()returnsList<PlexTag>instead ofList<PlexMetadata>. Pass a tag toPlexFilter.of(tag); usetag.titlefor its name.library.filters()returnsList<PlexLibraryFilter>:field,valueTypeandvaluesKeyreplaceraw['filter'],raw['filterType']andkey.library.updateSectionItems()names its argumentfilterExpressioninstead offilters. The request is unchanged.
Added #
PlexFilter, a typed library filter:genre(),tag(),year(),yearAfter(),yearBefore(),ratingAbove(),rated(),unplayed(),played(),titleContains(),titleIs(),firstCharacter(),studio(),contentRating(),resolution(), andnumber(),text(),flag()and a plain constructor for other fields.PlexFilter.of(tag), the filter for a genre, mood or style the server returned.library.filterValues(): the values a facet can take.PlexTag,PlexLibraryFilterandPlexFilterValueType.
Fixed #
- Filtering a library section works.
filter: ...was sent as a parameter namedfilter, which Plex ignores, so every filtered call returned the whole section. Filters travel as one parameter per condition, with the operator in the name:?genre=6,?year>>=2009,?unwatched=1. library.countByType()sends the same request asallByType()with a page size of zero, so a count matches the page it counts, filters included.
0.1.0 30-06-2026 #
Breaking #
liveTv.history(),liveTv.subscriptions()andliveTv.cancelSubscription()are gone: their routes do not exist. Usesessions.history()andPlexClient.subscriptions.streaming.directFileUrl()takes the item's file key instead of a part id and container.server.securityResources()requires asource.server.transientToken()takes notypeorscopeand returns the token string.transcoder.imageUrl():chromaSubsamplingis a number from 0 to 3.devices.setChannelMap()sends the mapping and the enabled channels the way Plex reads them.epg.bestLineup()requiresdeviceandlineupGroup.epg.lineupChannels()takes a list of lineups.playlists.moveItem(),playQueues.moveItem()andsubscriptions.reorder()move an item to the front whenafteris left out.PlexStream.selectedmeans the user picked the stream; the file default isPlexStream.isDefault.PlexHub.keyfetches a hub's content;hubKeyis the optional re-fetch key.subscriptions.create():typeis a number.notifications.connectWebSocket()returns aFuturethat completes once the socket is open, and a failed connection throws.
Added #
library.editItem(),deleteMetadataItem(),setItemArtwork()andupdateSectionItems().hubs.forMetadata(): the related rows of one item.sessions.historyItem(): one playback history entry.playlists.upload(): import an m3u playlist from a path on the server.PlexClient.clearSession(): drop the token and stay connected.
Changed #
collections.create()makes empty, named, typed and smart collections.playQueues.create()takes akeyfor the starting item.search.voice()takes atype.streaming.decisionUniversal()takes atranscodeType.PlexCredentialsaccepts the optionalX-Plex-Model,X-Plex-Device-VendorandX-Plex-Marketplaceheaders.request()andrequestBytes()take aCancelToken; a cancelled request isPlexErrorType.cancelled.PlexExceptionkeeps the original stack trace.PlexClient.fetchBytesis deprecated: userequestBytes.
Fixed #
addSection()andeditSection()apply the library settings they are given.- The transcode decision reads error codes as errors, so
isPlayable,isDirectandisTranscodeare right. playlists.generators()reads the right field.preferences.byId()returns the setting in the same shape asall().sessions.history()includes the start and end dates it is given.transcoder.imageUrl(),subtitlesUrl()andstartUrl()throw before connecting instead of returning a broken URL.subscriptions.editPreferences()sends the settings in the form Plex reads.- A body that cannot be decoded is a
parseerror. PlexResource.providesis empty when a resource advertises nothing.PlexMetadataType.photoAlbumuses the value Plex sends.
0.0.1 25-05-2026 #
Added #
- Initial release, for Plex Media Server
v1.43.x. - Sign-in with username and password, and the PIN link flow.
- The PMS HTTP client with the
X-Plex-*identity headers. PlexExceptionwith a semanticPlexErrorType.- Music endpoints: libraries, sections, items by type, playlists, artwork, audio streaming, playback reporting, search and favourites.
- Play queues, with
PlexPlayQueue. - Notifications over WebSocket and Server-Sent Events.
- Typed models, each with a
rawmap.