Library topic

Browse sections and items, filter them, edit collections and metadata, and find similar and sonically close tracks.

Sections

final sections = await plex.library.sections();
for (final s in sections) {
  print('${s.type.name}: ${s.title} (id=${s.id})');
}

PlexLibraryType is music, movie, show, photo or unknown. id is the section key that every section call takes as sectionId. sectionDetails(sectionId:) returns the section's views (all, by genre, search, …) as PlexSectionDetails, and folder(sectionId:) its folders as on disk: a folder's key carries the parent value that opens it. Each section also carries agent, scanner, language, locations, scannedAt and createdAt.

Items by type

final page = await plex.library.allByType(
  sectionId: musicLib.id,
  type: PlexMetadataType.album,
  start: 100,
  size: 100,
  sort: PlexSort.titleSort.asc,
);
print('Got ${page.items.length} of ${page.totalSize}');

final count = await plex.library.countByType(
  sectionId: musicLib.id,
  type: PlexMetadataType.album,
);

allByType() returns a PlexMediaContainer page (50 rows from start by default) with items, totalSize and the envelope's other fields in raw. countByType() sends the same request with an empty page, so the count always matches what allByType() would list; it takes the same filters.

PlexMetadataType carries the server's numeric values:

Type Value Type Value
movie 1 album 9
show 2 track 10
season 3 photoAlbum 13
episode 4 photo 14
trailer 5 playlist 15
artist 8 collection 18

sort takes a PlexSort: PlexSort.titleSort, PlexSort.addedAt.desc, PlexSort.lastViewedAt.desc, PlexSort.originallyAvailableAt.desc, PlexSort.random, and then() for ties (PlexSort.year.desc.then(PlexSort.titleSort)). asc and desc on a combined sort change its last field only. The constants are the sorts PMS 1.43.2 offers on music and movie sections; any other is PlexSort('field'), since PlexSort is an extension type over the wire string. The same type goes to children(), firstCharacters(), playlists.list(), sessions.history() and account.watchlist().

Filters

filters narrows allByType(), countByType() and the playlist list. Each condition is a PlexFilter, sent as its own query parameter:

final page = await plex.library.allByType(
  sectionId: musicLib.id,
  type: PlexMetadataType.album,
  filters: [PlexFilter.genre(6), PlexFilter.yearAfter(2009)],
);
// GET /library/sections/3/all?type=9&genre=6&year>>=2009

A Plex filter is a query parameter named after the field, with the operator in the name, so the operator comes from the constructor you pick:

Constructor Sends
PlexFilter.genre(6) genre=6
PlexFilter.genre(6, exclude: true) genre!=6
PlexFilter.tag('mood', [3, 7]) mood=3,7 (any of)
PlexFilter.of(tag) the tag's own field and id (see Genres and other facets below)
PlexFilter.year(1994) year=1994
PlexFilter.yearAfter(2009) year>>=2009
PlexFilter.yearBefore(2000) year<<=2000
PlexFilter.ratingAbove(9) userRating>>=9
PlexFilter.rated() userRating>>=0
PlexFilter.unplayed() unwatched=1
PlexFilter.played() unwatched=0
PlexFilter.titleContains('abbey') title=abbey
PlexFilter.titleIs('Abbey Road') title==Abbey Road
PlexFilter.firstCharacter('A') firstCharacter=A
PlexFilter.studio('A24') studio=A24
PlexFilter.contentRating('PG') contentRating=PG
PlexFilter.resolution('4k') resolution=4k
PlexFilter.hdr(), dolbyVision(), atmos() hdr=1, dovi=1, atmos=1
PlexFilter.videoCodec(['hevc', 'av1']) videoCodec=hevc,av1
PlexFilter.audioCodec(['truehd']), subtitleCodec(['pgs']) audioCodec=truehd, subtitleCodec=pgs
PlexFilter.audioLayout(['5.1']) audioLayout=5.1
PlexFilter.audioLanguage(['ita']), subtitleLanguage(['eng']) audioLanguage=ita, subtitleLanguage=eng
PlexFilter.inProgress(), duplicate() inProgress=1, duplicate=1

The media fields (hdr onwards) are those of PMS 1.43.2's movie and show sections; each narrowed a section on that version. Their values are what the section lists (filterValues()), e.g. h264 for a video codec.

Conditions in the list are ANDed; several values in one condition are ORed. Tag fields (genre, mood, style) take the numeric tag id, never the name. Two conditions on the same parameter throw a PlexException of type state, since one would overwrite the other.

The server ignores a parameter it does not know and answers unfiltered, so ask each section which fields it accepts with filters(), described in the next section. For a field without a named constructor, use PlexFilter(field: ..., values: [...], operator: PlexFilterOperator...), or PlexFilter.number, PlexFilter.text and PlexFilter.flag.

Genres and other facets

final genres = await plex.library.genres(
  sectionId: musicLib.id,
  type: PlexMetadataType.album,
);
final rock = genres.firstWhere((g) => g.title == 'Rock');
final rockAlbums = await plex.library.allByType(
  sectionId: musicLib.id,
  type: PlexMetadataType.album,
  filters: [PlexFilter.of(rock)],
);

Each PlexTag carries the numeric id the server filters by and the field it belongs to, so PlexFilter.of() builds the condition with nothing spelled by hand. id is null when the server sent nothing usable, and PlexFilter.of() then throws instead of sending a query that would come back unfiltered.

filters() lists the facets a section can be filtered on, and filterValues() lists the values of one:

final facets = await plex.library.filters(sectionId: musicLib.id);
for (final f in facets) {
  print('${f.title}: field=${f.field} type=${f.valueType}');
}

final moodFacet = facets.firstWhere((f) => f.field == 'mood');
final moods = await plex.library.filterValues(
  filter: moodFacet,
  type: PlexMetadataType.track,
);
final mellow = moods.firstWhere((m) => m.title == 'Mellow');
final mellowTracks = await plex.library.allByType(
  sectionId: musicLib.id,
  type: PlexMetadataType.track,
  filters: [PlexFilter.of(mellow)],
);

PlexLibraryFilter.field is the query parameter to use. A flag facet such as unwatched has no values, and filterValues() throws a PlexException of type state for it. sectionSorts() lists the sorts a section offers.

Single item

final item = await plex.library.item(ratingKey: '12345');
if (item != null) {
  print(item.title);
  print(item.media.first.audioCodec); // e.g. 'flac'
}

item() returns null when the answer holds no item; a rating key the server does not know throws a PlexException whose isNotFound is true. The full item is the place for media with its parts and streams (audioStream, and the loudness and lyrics described in Streaming), librarySectionId and leafCount; list responses usually leave them out.

PlexMetadata carries the item's titles, its parent and grandparent (parentTitle, grandparentRatingKey and so on), genres, moods, styles, roles (a track's performers when it has more than one), counts (leafCount, childCount, viewedLeafCount, viewCount, skipCount), dates (addedAt, lastViewedAt, originallyAvailableAt, lastRatedAt), userRating, durationMs, editionTitle (a movie's or show's edition), images with squareArt and logo, and raw.

Markers and chapters

final episode = await plex.library.item(
  ratingKey: key,
  includeMarkers: true,
  includeChapters: true,
);
final intro = episode!.markersOf(PlexMarkerType.intro).firstOrNull;
if (intro != null) skipButton(from: intro.start, to: intro.end);
for (final c in episode.chapters) {
  print('${c.index}. ${c.title} at ${c.start}');
}

The server sends markers and chapters only when asked. A PlexMarker has a type (PlexMarkerType.intro, credits, commercial, bookmark, resume, or any other the server sends), start, end and, for credits, isFinal. PMS sends credits; the API document's credit reads as the same type. createMarker() and editMarker() take the same type.

Children and leaves

// An album's tracks, an artist's albums, a season's episodes.
final tracks = await plex.library.children(ratingKey: album.ratingKey);

// Sorted and paged.
final newestAlbums = await plex.library.children(
  ratingKey: artist.ratingKey,
  sort: PlexSort.year.desc,
  size: 20,
);

// How many, without transferring them.
final albumCount = await plex.library.countChildren(ratingKey: artist.ratingKey);

// Every track of an artist in album order.
final artistTracks = await plex.library.grandchildren(
  ratingKey: artist.ratingKey,
  size: 100,
);

// Every leaf under an item: an artist's tracks, a show's episodes.
final leaves = await plex.library.allLeaves(ratingKey: artist.ratingKey);

Without size these calls return every row; with size they return one page (see the page parameters in Errors and paging). children() takes the section sort syntax. allLeaves() has no sort: the server ignores it and answers in library order. sectionAllLeaves(sectionId:) returns every leaf of a section.

Recently added, A-Z index and autocomplete

// Newest first, of one section or of the whole server.
final newInMusic = await plex.library.recentlyAdded(
  sectionId: musicLib.id,
  size: 20,
);
final newAnywhere = await plex.library.recentlyAdded(size: 20);

// The letters a section's titles start with, for an A-Z scrubber.
final letters = await plex.library.firstCharacters(
  sectionId: musicLib.id,
  type: PlexMetadataType.album,
);

// Suggestions while the user types.
final suggestions = await plex.library.autocomplete(
  sectionId: musicLib.id,
  type: PlexMetadataType.album,
  fieldQuery: {'title.query': 'Abb'},
);

In a music section recentlyAdded() returns albums: the server ignores a type there, so the call takes none. Jump to a letter of the index with PlexFilter.firstCharacter('A') on allByType(). autocomplete() needs type: the server answers 400 without it. It returns the server's map. sectionCommon() needs a type too.

Albums, folders and categories

final albums = await plex.library.albums(sectionId: musicLib.id, size: 100);
final folders = await plex.library.folderLocations(sectionId: musicLib.id);
final categories = await plex.library.categories(sectionId: photoLib.id);

albums() pages a music section's albums without the sort and filter parameters of allByType(). folderLocations() returns the section's scanned folders and categories() the server's categories, mostly for photo libraries. sectionArts(), sectionClusters() and sectionMoments() return a section's backdrops and its photo clusters and moments, sectionCollections() its collections and all() every item of every section.

Collections

A collection is a metadata item with its own rating key, so item() and children() work on it. plex.collections creates and edits them:

final machineId = (await plex.server.identity()).machineIdentifier;
final seed = PlexPlayQueuesApi.seedFromItems(
  machineIdentifier: machineId,
  ratingKeys: const ['12345', '12346'],
);

final collection = await plex.collections.create(
  sectionId: musicLib.id,
  title: 'Road trip',
  type: PlexMetadataType.album,
  seedUri: seed,
);
final items = await plex.collections.items(collectionId: collection.ratingKey);

await plex.collections.moveItem(
  collectionId: collection.ratingKey,
  itemId: items.last.ratingKey,
  afterItemId: '0', // to the start
);
await plex.collections.removeItem(
  collectionId: collection.ratingKey,
  itemId: items.first.ratingKey,
);

addItems(collectionId:, uri:) adds more items from a seed URI. A smart collection (smart: true) needs a seedUri. compositeImageUrl() builds the URL of the collection's composite cover, and library.deleteSectionCollection() deletes one.

Editing and maintenance

plex.library also edits metadata and runs library maintenance. These calls need an admin token. Most take ids, one rating key or several joined by commas.

await plex.library.editItem(
  ids: album.ratingKey,
  type: PlexMetadataType.album,
  args: {'title.value': 'New title', 'title.locked': 1},
);
await plex.library.refreshSection(sectionId: musicLib.id);

<field>.value sets a field and <field>.locked keeps the agent from overwriting it. updateSectionItems() edits every item matching a filterExpression in one call.

The editing and maintenance calls:

Area Calls
Items editItem, deleteMetadataItem, deleteMediaItem, refreshItems, analyzeItem, matchItem, listMatches, unmatch, mergeItems, splitItem, setItemPreferences
Detection detectIntros, detectCredits, detectAds, detectVoiceActivity, generateChapterThumbs, startBifGeneration
Markers createMarker, editMarker, deleteMarker
Artwork and extras itemArtworkUrl, setItemArtwork, extras, addExtra, addSubtitles, chapterImageUrl, itemFileUrl
Item reads relatedItems, itemTree, topUsers, person (PlexPerson), personMedia
Streams and parts streamUrl, setStreamOffset, deleteStream, streamLoudness, streamLevels, setPartStreamSelection, partFileUrl, partIndex, partBifThumbUrl
Sections addSection (with a PlexLibraryType), editSection, deleteSection, sectionDetails, folder, sectionPreferences, setSectionPreferences, defaultSectionPrefs, sectionCommon, sectionsAll, sectionCompositeImageUrl
Scanning refreshSection, cancelSectionRefresh, analyzeSection, refreshAllSections, stopAllRefreshes, emptyTrash
Housekeeping deleteSectionIndexes, deleteSectionIntros, deleteCaches, cleanBundles, optimizeDatabase, ingestTransientItem
Index reads tags (PlexTag, ready for PlexFilter.of), randomArtwork, matches (PlexMetadata)

Similar items and sonic radio

similar() returns what the server judges similar. The other two calls read the sonic analysis the server keeps for music, so they need it enabled (PlexServerInfo.musicAnalysis).

Similar items

final picks = await plex.library.similar(ratingKey: album.ratingKey, count: 12);

Works for albums, artists, movies and shows.

Sonically nearest tracks

final nearest = await plex.library.nearestToTrack(
  ratingKey: track.ratingKey,
  limit: 25,
  maxDistance: 0.25,
  excludeGrandparentRatingKey: track.grandparentRatingKey,
);

excludeParentRatingKey and excludeGrandparentRatingKey leave out the album or the artist of the seed. Each result carries its distance from the seed; smaller is closer.

Nearest tracks in a section

// A track analysed by the server carries its sonic vector in raw.
final seed = (track.raw['musicAnalysis']! as List).cast<num>();
final radio = await plex.library.nearestInSection(
  sectionId: musicLib.id,
  values: seed,
  limit: 50,
);

// Tracks that bridge two songs.
final path = await plex.library.sonicPath(
  sectionId: musicLib.id,
  startId: track.ratingKey,
  endId: otherTrack.ratingKey,
);

nearestInSection() seeds the search from a sonic vector instead of a track. Average the vectors of several tracks to build a radio for a mood. sonicPath() returns tracks that lead from one song to another.

Classes

PlexChapter Library
A chapter of a video (Chapter).
PlexCollectionsApi Library
/library/collections/* — hand-curated groupings of metadata items.
PlexFilter Library
One condition in a library filter.
PlexLibraryApi Library
Browse /library/sections and /library/metadata/{id}.
PlexLibraryFilter Library
One facet a section can be filtered on, from /library/sections/{id}/filters.
PlexLibrarySection Library
One library section from /library/sections.
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.
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.
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, …
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}).
PlexStream Library
streamType: 1 video, 2 audio, 3 subtitle, 4 lyrics.
PlexTag Library
One value of a filterable field — a genre, mood, style, decade, collection or label row.

Enums

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.