PlexLibraryApi class

Browse /library/sections and /library/metadata/{id}.

Constructors

PlexLibraryApi(PlexConnection _http)
Construct from a PlexConnection. Typically obtained via PlexClient.library.

Properties

hashCode → int
The hash code for this object.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

addExtra({required String ids, required String extraType, required String url}) → Future<void>
POST /library/metadata/{ids}/extras?extraType=...&url=... — attach a new extra item.
addSection({required String name, required String type, required String scanner, required String agent, required List<String> locations, String? metadataAgentProviderGroupId, String? language, Map<String, dynamic>? prefs, bool? relative, bool? importFromiTunes}) → Future<void>
POST /library/sections — add a new section to the server. The spec lists this as /library/sections/all, but in practice the server only accepts POST at /library/sections (the /all suffix is for GET reads). Verified against PMS 1.43.x.
addSubtitles({required String ids, required String title, required String language, required String url, String? format, String? mediaItemID, bool? forced, bool? hearingImpaired}) → Future<void>
GET /library/metadata/{ids}/subtitles?title=...&language=...&url=... — attach an external subtitle file.
albums({required String sectionId, int start = 0, int size = 50}) → Future<PlexMediaContainer<PlexMetadata>>
/library/sections/{sectionId}/albums — every album in a music section. Cheaper than allByType(type: album) when no sort or filter is needed.
all() → Future<List<PlexMetadata>>
GET /library/all — every item across every section. Heavy query; use sections / allByType for normal browsing.
allByType({required String sectionId, required PlexMetadataType type, int start = 0, int size = 50, String? sort, List<PlexFilter> filters = const []}) → Future<PlexMediaContainer<PlexMetadata>>
Paged list of items inside a section, filtered by type.
allLeaves(String ratingKey) → Future<List<PlexMetadata>>
All leaves under an item — every track under an artist, every episode under a show. Useful for "play artist" / "play show".
analyzeItem({required String ids, int? thumbOffset, int? artOffset}) → Future<void>
PUT /library/metadata/{ids}/analyze — re-run media analysis.
analyzeSection({required String sectionId}) → Future<void>
PUT /library/sections/{sectionId}/analyze — re-analyze every item in a section (loudness, intros, etc.).
autocomplete({required String sectionId, String? type, Map<String, dynamic>? fieldQuery}) → Future<Map<String, dynamic>>
GET /library/sections/{sectionId}/autocomplete?type=...&field.query=... — autocomplete suggestions for a search field.
cancelSectionRefresh({required String sectionId}) → Future<void>
DELETE /library/sections/{sectionId}/refresh — abort a running refresh.
categories({required String sectionId}) → Future<List<PlexMetadata>>
/library/sections/{sectionId}/categories — server-defined categories for the section (mostly used by photo libraries).
chapterImageUrl({required String mediaId, required int chapter}) → String
GET /library/media/{mediaId}/chapterImages/{chapter} — URL for a chapter thumbnail.
children(String ratingKey) → Future<List<PlexMetadata>>
Children of an item — album tracks, artist albums, season episodes.
cleanBundles() → Future<void>
PUT /library/clean/bundles — clean orphaned metadata bundles on disk.
countByType({required String sectionId, required PlexMetadataType type, List<PlexFilter> filters = const []}) → Future<int>
Count-only variant of allByType — returns the section's totalSize without paying the cost of streaming the items down.
createMarker({required String ids, required String type, required int startTimeOffset, required int endTimeOffset, Map<String, dynamic>? attributes}) → Future<void>
POST /library/metadata/{ids}/marker?type=...&startTimeOffset=...&endTimeOffset=... — create a marker.
defaultSectionPrefs({String? type, String? agent}) → Future<Map<String, dynamic>>
GET /library/sections/prefs?type={t}&agent={a} — default section preferences for a media type + agent combination.
deleteCaches() → Future<void>
DELETE /library/caches — drop the library caches.
deleteMarker({required String ids, required String marker}) → Future<void>
DELETE /library/metadata/{ids}/marker/{marker} — delete a marker.
deleteMediaItem({required String ids, required String mediaItem, bool? proxy}) → Future<void>
DELETE /library/metadata/{ids}/media/{mediaItem} — delete one media item (file) from an item, keeping the metadata.
deleteMetadataItem({required String ids, bool? proxy}) → Future<void>
DELETE /library/metadata/{ids} — delete a metadata item from the library, removing its underlying media as well. Distinct from deleteMediaItem, which only removes one media version.
deleteSection({required String sectionId, bool asyncMode = false}) → Future<void>
DELETE /library/sections/{sectionId}?async={bool} — delete a section.
deleteSectionCollection({required String sectionId, required String collectionId}) → Future<void>
DELETE /library/sections/{sectionId}/collection/{collectionId} — delete a collection from a section.
deleteSectionIndexes({required String sectionId}) → Future<void>
DELETE /library/sections/{sectionId}/indexes — drop the section's indexes (forces a rebuild on next access).
deleteSectionIntros({required String sectionId}) → Future<void>
DELETE /library/sections/{sectionId}/intros — drop intro markers in a section so they can be regenerated.
deleteStream({required String streamId, required String ext}) → Future<void>
DELETE /library/streams/{streamId}.{ext} — delete a stream.
detectAds({required String ids}) → Future<void>
PUT /library/metadata/{ids}/addetect — ad detection (on recorded TV).
detectCredits({required String ids, bool force = false, bool manual = false}) → Future<void>
PUT /library/metadata/{ids}/credits?force={b}&manual={b} — credits detection.
detectIntros({required String ids, bool force = false, double? threshold}) → Future<void>
PUT /library/metadata/{ids}/intro?force={b}&threshold={n} — intro detection.
detectVoiceActivity({required String ids, bool force = false, bool manual = false}) → Future<void>
PUT /library/metadata/{ids}/voiceActivity?force={b}&manual={b} — voice-activity detection.
editItem({required String ids, required Map<String, dynamic> args, PlexMetadataType? type}) → Future<void>
PUT /library/metadata/{ids} — edit metadata fields on one item (or a comma-joined list of ids). Admin-token only.
editMarker({required String ids, required String marker, String? type, int? startTimeOffset, int? endTimeOffset, Map<String, dynamic>? attributes}) → Future<void>
PUT /library/metadata/{ids}/marker/{marker} — edit a marker.
editSection({required String sectionId, String? name, String? scanner, String? agent, String? metadataAgentProviderGroupId, String? language, List<String>? locations, Map<String, dynamic>? prefs}) → Future<void>
PUT /library/sections/{sectionId} — edit a section.
emptyTrash({required String sectionId}) → Future<void>
PUT /library/sections/{sectionId}/emptyTrash — empty the section's recycle bin.
extras({required String ids}) → Future<List<PlexMetadata>>
GET /library/metadata/{ids}/extras — bonus content (interviews, trailers) attached to an item.
filters({required String sectionId}) → Future<List<PlexLibraryFilter>>
/library/sections/{sectionId}/filters — the facets this section can be filtered on (genre, year, decade, …).
filterValues({required PlexLibraryFilter filter, PlexMetadataType? type}) → Future<List<PlexTag>>
Values a facet can take — the moods, styles, decades or labels behind a PlexLibraryFilter returned by filters.
firstCharacters({required String sectionId, String? type, String? sort}) → Future<List<PlexMetadata>>
GET /library/sections/{sectionId}/firstCharacters?type=...&sort=... — A-Z scrubber index.
folderLocations({required String sectionId}) → Future<List<PlexMetadata>>
/library/sections/{sectionId}/location — folder roots configured for the section (one entry per scanned directory).
generateChapterThumbs({required String ids, bool force = false}) → Future<void>
PUT /library/metadata/{ids}/chapterThumbs?force={b} — generate chapter thumbnails.
genres({required String sectionId, required PlexMetadataType type}) → Future<List<PlexTag>>
Browse the genres index of a section (/library/sections/{id}/genre).
ingestTransientItem({required String url, String? virtualFilePath, bool? computeHashes, bool? ingestNonMatches}) → Future<Map<String, dynamic>>
POST /library/file?url={path}&virtualFilePath={...} — ingest a file from disk without first scanning it via a section.
item(String ratingKey) → Future<PlexMetadata?>
Full metadata for one item (/library/metadata/{ratingKey}).
itemArtworkUrl({required String ids, required String element, required int timestamp}) → String
GET /library/metadata/{ids}/{element}/{timestamp} — URL for an item's artwork, theme, or other typed asset.
itemFileUrl({required String ids, required String url}) → String
GET /library/metadata/{ids}/file?url={inBundlePath} — fetch a file inside the item's metadata bundle.
itemTree({required String ids}) → Future<Map<String, dynamic>>
GET /library/metadata/{ids}/tree — items as a hierarchical tree (parents → children).
listMatches({required String ids, String? title, String? parentTitle, String? agent, String? language, int? year, bool? manual}) → Future<Map<String, dynamic>>
PUT /library/metadata/{ids}/matches?title=...&year=...&... — list candidate matches for an item.
matches(Map<String, dynamic> filters) → Future<Map<String, dynamic>>
GET /library/matches — query the metadata-agent match cache.
matchItem({required String ids, String? guid, String? name, int? year}) → Future<void>
PUT /library/metadata/{ids}/match?guid=...&name=...&year=... — pin an item to a specific upstream guid.
mergeItems({required String primaryId, required List<String> otherIds}) → Future<void>
PUT /library/metadata/{ids}/merge?ids={otherIds} — merge multiple items into one (handy for de-duping artists).
nearestInSection({required String sectionId, required List<num> values, int type = 10, int? limit, double? maxDistance}) → Future<List<PlexMetadata>>
/library/sections/{sectionId}/nearest — sonically nearest tracks inside a section, seeded by a vector of music-analysis values (typically musicAnalysis from another track or an average across recently played).
nearestToTrack({required String ratingKey, int? limit, double? maxDistance, int? excludeParentID, int? excludeGrandparentID}) → Future<List<PlexMetadata>>
/library/metadata/{ratingKey}/nearest — sonically nearest tracks to a seed track (requires music sonic analysis on the server). Used to build "sonic radio".
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
optimizeDatabase({bool asyncMode = false}) → Future<void>
PUT /library/optimize?async={bool} — re-optimize the SQLite database.
partBifThumbUrl({required String partId, required String index, required int offset}) → String
GET /library/parts/{partId}/indexes/{index}/{offset} — URL for a single BIF thumbnail at an offset.
partFileUrl({required String partId, required int changestamp, required String filename, bool? download}) → String
GET /library/parts/{partId}/{changestamp}/{filename} — URL for a media part file (direct file download).
partIndex({required String partId, required String index, int? interval}) → Future<Map<String, dynamic>>
GET /library/parts/{partId}/indexes/{index} — BIF index metadata for a media part.
person(String personId) → Future<Map<String, dynamic>>
GET /library/people/{personId} — person details.
personMedia(String personId) → Future<List<PlexMetadata>>
GET /library/people/{personId}/media — items credited to a person.
randomArtwork({String? sections}) → Future<Map<String, dynamic>>
GET /library/randomArtwork?sections={ids} — random backdrop across the supplied sections. Useful as a screensaver source.
refreshAllSections({bool force = false}) → Future<void>
POST /library/sections/refresh?force={bool} — refresh every section.
refreshItems({required String ids, String? agent, bool? markUpdated}) → Future<void>
PUT /library/metadata/{ids}/refresh?agent=... — refresh metadata on a single item or a comma-joined list.
refreshSection({required String sectionId, bool force = false, String? path}) → Future<void>
POST /library/sections/{sectionId}/refresh — kick off a section refresh.
relatedItems({required String ids}) → Future<List<PlexHub>>
GET /library/metadata/{ids}/related — related-items hub for a metadata item.
sectionAllLeaves({required String sectionId}) → Future<List<PlexMetadata>>
/library/sections/{sectionId}/allLeaves — every leaf-level item in a section (e.g. every episode of every show).
sectionArts({required String sectionId}) → Future<List<PlexMetadata>>
/library/sections/{sectionId}/arts — backdrop artwork (Directory entries with art paths).
sectionClusters({required String sectionId}) → Future<List<PlexMetadata>>
/library/sections/{sectionId}/cluster — clusters used to group photo libraries (proximity / similarity buckets).
sectionCollections({required String sectionId}) → Future<List<PlexMetadata>>
GET /library/sections/{sectionId}/collections — collections inside a section.
sectionCommon({required String sectionId, String? type}) → Future<Map<String, dynamic>>
GET /library/sections/{sectionId}/common?type=... — common fields across items (shared genres, ratings, etc.).
sectionCompositeImageUrl({required String sectionId, required int updatedAt}) → String
GET /library/sections/{sectionId}/composite/{updatedAt} — URL for the section's auto-composed cover image.
sectionDetails({required String sectionId, bool? includeDetails}) → Future<Map<String, dynamic>>
GET /library/sections/{sectionId}?includeDetails={bool} — full section details.
sectionMoments({required String sectionId}) → Future<List<PlexMetadata>>
/library/sections/{sectionId}/moment — moments index for a photo library (notable moments grouped by date/place).
sectionPreferences({required String sectionId, String? agent}) → Future<Map<String, dynamic>>
GET /library/sections/{sectionId}/prefs — section preferences.
sections() → Future<List<PlexLibrarySection>>
List every library section on the server (/library/sections).
sectionsAll() → Future<List<PlexLibrarySection>>
GET /library/sections/all — every section's metadata (Media Provider Only view). Lighter than sections; useful for the "primary library" entry point.
sectionSorts({required String sectionId}) → Future<List<PlexMetadata>>
GET /library/sections/{sectionId}/sorts — sorts available on the section.
setItemArtwork({required String ids, required String element, String? url, List<int>? data, bool update = false}) → Future<void>
POST|PUT /library/metadata/{ids}/{element}?url={url} — set a custom artwork/theme asset on an item (e.g. change its poster). Generally admin-only, except for playlists owned by the user.
setItemPreferences({required String ids, required Map<String, dynamic> args}) → Future<void>
PUT /library/metadata/{ids}/prefs — set metadata-edit locks/overrides.
setPartStreamSelection({required String partId, String? audioStreamID, String? subtitleStreamID, bool? allParts}) → Future<void>
PUT /library/parts/{partId}?audioStreamID=...&subtitleStreamID=...&allParts={b} — set the active audio/subtitle stream selection on a media part.
setSectionPreferences({required String sectionId, required Map<String, dynamic> prefs}) → Future<void>
PUT /library/sections/{sectionId}/prefs — replace the section preferences.
setStreamOffset({required String streamId, required String ext, required int offsetMs}) → Future<void>
PUT /library/streams/{streamId}.{ext}?offset={ms} — adjust a stream's offset (subtitle sync).
similar({required String ratingKey, int? count}) → Future<List<PlexMetadata>>
/library/metadata/{ratingKey}/similar — items the server considers similar to this one (works for albums, artists, movies, shows).
sonicPath({required String sectionId, required String startId, required String endId, double? maxDistance}) → Future<List<PlexMetadata>>
/library/sections/{sectionId}/computePath?startID=...&endID=...&maxDistance=... — sonic transition path between two tracks. Used to bridge two songs with intermediate tracks for smooth crossfade compilations.
splitItem({required String ids}) → Future<void>
PUT /library/metadata/{ids}/split — undo a merge.
startBifGeneration({required String ids, bool force = false}) → Future<void>
PUT /library/metadata/{ids}/index?force={b} — start BIF (Base Index File) generation for scrubbing thumbnails.
stopAllRefreshes() → Future<void>
DELETE /library/sections/all/refresh — stop every running section refresh.
streamLevels({required String streamId, int? subsample}) → Future<Map<String, dynamic>>
GET /library/streams/{streamId}/levels?subsample={n} — level samples (used for the waveform display).
streamLoudness({required String streamId, int? subsample}) → Future<Map<String, dynamic>>
GET /library/streams/{streamId}/loudness?subsample={n} — loudness curve for an audio stream.
streamUrl({required String streamId, required String ext, String? encoding, String? format, bool? autoAdjustSubtitle}) → String
GET /library/streams/{streamId}.{ext} — URL for a media stream file (subtitle text, etc.).
tags() → Future<Map<String, dynamic>>
GET /library/tags — every tag value across the library.
topUsers({required String ids}) → Future<Map<String, dynamic>>
GET /library/metadata/{ids}/users/top — top listeners / viewers for this item.
toString() → String
A string representation of this object.
inherited
unmatch({required String ids}) → Future<void>
PUT /library/metadata/{ids}/unmatch — clear the upstream guid match.
updateSectionItems({required String sectionId, int? type, String? filterExpression, required Map<String, dynamic> changes}) → Future<void>
PUT /library/sections/{sectionId}/all — bulk-edit the fields and tags of every item matching a filter, in a single call (cheaper than N per-item editItem calls for batch tagging or curation).

Operators

operator ==(Object other) → bool
The equality operator.
inherited