Library topic
Browse the libraries: items, kinds, fields and filters, artists, genres, people, facets, collections and plugin channels.
Library browsing
Libraries
final views = await jellyfin.library.userViews();
for (final v in views) {
print('${v.collectionType ?? '?'}: ${v.name}');
}
final music = views.firstWhere((v) => v.isMusic);
A view's id is the parentId that scopes the calls below to one
library. collectionType is one of music, movies, tvshows,
musicvideos, photos, books, livetv, homevideos, boxsets,
playlists or folders; isMusic, isMovies, isTvShows and
isPhotos test the common ones.
userViews.list() reads the same views with options: hidden libraries,
channel and plugin content, and preset views. groupingOptions() lists
the ways the server offers to group them.
final all = await jellyfin.userViews.list(
includeHidden: true,
includeExternalContent: false,
presetViews: const ['music', 'tvshows'],
);
final options = await jellyfin.userViews.groupingOptions();
Listing items
items.list() is the general browse call. It takes the /Items
parameters and returns a JellyfinQueryResult<JellyfinItem> with
items, totalRecordCount and startIndex:
final page = await jellyfin.items.list(
parentId: music.id,
includeItemTypes: const [JellyfinItemKind.musicAlbum],
sortBy: const [JellyfinSortField.productionYear, JellyfinSortField.sortName],
descending: true,
startIndex: 50, // the second page
limit: 50,
searchTerm: 'pink',
filters: const [JellyfinItemFilter.isFavorite],
genreIds: [genreId],
fields: JellyfinItemsApi.browseFields,
);
print('${page.items.length} of ${page.totalRecordCount}');
Every filter that takes several values is a list: ids,
excludeItemIds, genreIds, artistIds, albumArtistIds,
contributingArtistIds, albumIds, studioIds, personIds, tags,
officialRatings, the name-based genres, artists, albums and
studios, and years (a List<int>). Pass the list as it is: each
value travels as its own query parameter, so a genre or tag that holds a
comma or a pipe arrives intact. Prefer the id filters to the name
filters: ids come from filter.facets() (see Filter facets below) and
survive a rename.
A few rules of the route:
descendingapplies only together withsortBy.parentIdscopes albums and tracks to a library, but not artists: withJellyfinItemKind.musicArtistand a library's id,/Itemsanswers the artists of every library. List one library's artists withartists, or itsMusicArtistitems withartists.musicArtists()(see Artists below).enableTotalRecordCount(on by default) makes the server count the whole result. Passfalsewhen you page until a short page and never show a total;totalRecordCountthen counts only the page.
Item kinds, sort keys and filters
includeItemTypes, excludeItemTypes, fields, sortBy, mediaTypes
and filters take typed values instead of strings:
| Type | Parameter | Examples |
|---|---|---|
JellyfinItemKind |
includeItemTypes, excludeItemTypes |
audio, musicAlbum, musicArtist, playlist, movie, series, episode, boxSet |
JellyfinItemField |
fields |
genres, people, mediaSources, overview, recursiveItemCount |
JellyfinSortField |
sortBy |
sortName, productionYear, dateCreated, datePlayed, random |
JellyfinMediaType |
mediaTypes |
audio, video, photo, book |
JellyfinItemFilter |
filters |
isFavorite, isPlayed, isUnplayed, isResumable |
The server ignores a value it does not know and answers a wider result, so a typo in a string would list everything. With the typed values a typo does not compile. Each type holds one constant per value of the Jellyfin API document, and reads as the wire string. A value the package does not list yet is one constructor away:
final items = await jellyfin.items.list(
includeItemTypes: const [JellyfinItemKind('NewKind')],
);
Fields
fields defaults to empty, the server's own selection. Two presets cover
the common cases:
| Preset | Fields | Use for |
|---|---|---|
JellyfinItemsApi.browseFields |
Genres, DateCreated, ChildCount, SortName, PrimaryImageAspectRatio |
Grids and lists of albums, artists, playlists, genres |
JellyfinItemsApi.musicFields |
Overview, Genres, MediaSources, MediaStreams, ProviderIds, PrimaryImageAspectRatio, SortName, DateCreated, ChildCount, ParentId, Path, OriginalTitle |
A queue or a track info sheet, where media sources and streams are read |
MediaSources and MediaStreams make most of a track's size, so ask
for musicFields only where you read them. Neither preset is a default,
because /Items also serves video and photo libraries.
Image tags are not fields: the server sends them on every item, so
covers work with either preset. enableImages: false drops ImageTags.
Some typed members of JellyfinItem need their field:
| Member | Field | Holds |
|---|---|---|
genreItems |
genres |
Each genre's id and name (JellyfinNameGuidPair), the ids genreIds and instantMix.fromItem() take |
people |
people |
JellyfinItemPersons: name, id, role, a type such as 'Composer', image tag |
recursiveItemCount |
recursiveItemCount |
Items below a folder, at any depth |
albumCount, songCount, artistCount, movieCount, seriesCount, episodeCount, … |
itemCounts |
Counts of an artist, genre or person |
Others come without a field: albumArtistItems (album artists with
ids), playlistItemId, normalizationGain and albumNormalizationGain
(in dB, from the "Audio Normalization" task), artworkItemId and
artworkVersion. The last two give the id whose cover to show, a
track's own or its album's, and the image tag to put in a cache key:
final coverId = track.artworkItemId;
if (coverId != null) {
final url = jellyfin.images.url(
itemId: coverId,
tag: track.artworkVersion, // changes when the cover does
maxWidth: 512,
maxHeight: 512,
);
}
Counting items
count() takes the narrowing parameters of list(), without paging,
sorting and fields, and returns the total without the items:
final albumCount = await jellyfin.items.count(
parentId: music.id,
includeItemTypes: const [JellyfinItemKind.musicAlbum],
genreIds: [genreId],
);
Single item and related items
final item = await jellyfin.items.byId(itemId: '12345');
if (item != null) {
print('${item.name} ${item.mediaSources.firstOrNull?.bitrate}');
}
// Continue listening or watching, and recently added.
final resume = await jellyfin.items.resume(
mediaTypes: const [JellyfinMediaType.audio],
limit: 10,
);
final latest = await jellyfin.items.latest(
parentId: music.id,
includeItemTypes: const [JellyfinItemKind.musicAlbum],
limit: 10,
);
// Related items.
final similar = await jellyfin.library.similarAlbums(itemId: album.id, limit: 12);
final path = await jellyfin.library.ancestors(itemId: track.id);
byId() returns null when the server answers 404. resume() returns a
JellyfinQueryResult<JellyfinItem>, latest() a plain
List<JellyfinItem>.
library has similarItems(), similarAlbums(), similarArtists(),
similarMovies(), similarShows() and similarTrailers(), plus
themeSongs(), themeVideos() and themeMedia(). items has
specialFeatures(), localTrailers() and intros(), and
downloadUrl() and fileUrl() for the original file.
Artists
Jellyfin 12 stores music artists as people, and marks the /Artists
routes obsolete. artists asks /Persons, as Jellyfin Web does for its
Artists and Album Artists tabs. Each artist comes once, by name, and
parentId scopes the list to a library:
// Artists credited on at least one album: the Artists tab.
final albumArtists = await jellyfin.artists.albumArtists(
parentId: musicLibraryId,
nameStartsWith: 'A',
limit: 100,
);
// Artists credited on a track.
final trackArtists = await jellyfin.artists.list(
parentId: musicLibraryId,
searchTerm: 'beat',
limit: 50,
);
// Null when no artist or album artist has that name.
final aphex = await jellyfin.artists.byName(name: 'Aphex Twin');
// The artist's albums: a person id filters like an artist id.
final albums = await jellyfin.items.list(
includeItemTypes: const [JellyfinItemKind.musicAlbum],
albumArtistIds: [aphex!.id],
);
artists.byName() answers only artists and album artists, matching the
name whatever its case. persons.byName() answers any person, an actor
too.
totalRecordCount counts every match, not the page. User data belongs to
the Person item: isFavorite: and filters: read the person's
favourite and played state, and an artist marked favourite through its
MusicArtist id does not show up.
The answers are Person items. Their ids filter items.list(), but seed
an empty instant mix, and carry no MusicBrainz id. For those, use the
MusicArtist item: a track's artistItems and albumArtistItems, or
artists.musicArtists() and artists.musicAlbumArtists(). They ask the
obsolete GET /Artists and /Artists/AlbumArtists, which Jellyfin 12.4
still answers and which are the only routes that list one library's
MusicArtist items: items.list(includeItemTypes: [JellyfinItemKind.musicArtist]) ignores parentId. They sort with
sortBy, narrow by genreIds, genres and years, and isFavorite:
and filters: read the artist's own user data:
final musicArtists = await jellyfin.artists.musicArtists(
parentId: musicLibraryId,
sortBy: const [JellyfinSortField.sortName],
isFavorite: true,
limit: 100,
);
final mix = await jellyfin.instantMix.fromArtist(
artistId: musicArtists.items.first.id,
);
A later Jellyfin may drop /Artists; the call then fails with a
notFound error.
Genres
Jellyfin keeps two items for each genre name: a generic Genre and, for
music, a MusicGenre, with different ids. Both ids filter
items.list(genreIds:), but only the music-genre id seeds an
instant mix. See the Search and lyrics topic.
Scope genres.list() with the music library's parentId: those ids are
the ones an instant mix accepts. Without parentId it answers the
generic genres, whatever includeItemTypes says.
final musicGenres = await jellyfin.genres.list(
parentId: musicLibraryId,
sortBy: const [JellyfinSortField.sortName],
);
// Name lookups: the music genre, and the generic one.
final ambient = await jellyfin.genres.musicGenre(
name: 'Ambient',
parentId: musicLibraryId,
);
final action = await jellyfin.genres.byName(name: 'Action');
genres.musicGenre() finds a music genre by its name, ignoring case, in
a music library; it replaces /MusicGenres/{name}, which
Jellyfin 12 marks obsolete. genres.byName() takes no parentId and
answers the generic genre.
People, studios and years
persons, studios and years list one kind of entity each, as
JellyfinItems, and look one up by name or year:
final actors = await jellyfin.persons.list(
personTypes: const ['Actor'],
searchTerm: 'cumberbatch',
limit: 20,
);
final one = await jellyfin.persons.byName(name: 'Benedict Cumberbatch');
final studios = await jellyfin.studios.list(parentId: movieLibraryId);
final pixar = await jellyfin.studios.byName(name: 'Pixar');
final years = await jellyfin.years.list(
parentId: musicLibraryId,
includeItemTypes: const [JellyfinItemKind.musicAlbum],
sortBy: const [JellyfinSortField.productionYear],
descending: true,
);
final y1999 = await jellyfin.years.byYear(year: 1999);
persons.list(appearsInItemId:) lists the people credited on one item,
such as a movie's cast. nameStartsWith, nameStartsWithOrGreater and
nameLessThan drive an alphabet picker on persons, studios and
genres.
Filter facets
Ask the server which values exist in a library, to fill filter chips:
final facets = await jellyfin.filter.facets(
parentId: musicLibraryId,
includeItemTypes: const [JellyfinItemKind.musicAlbum],
);
for (final g in facets.genres) {
print('${g.id} ${g.name}');
}
final legacy = await jellyfin.filter.legacy(
parentId: movieLibraryId,
includeItemTypes: const [JellyfinItemKind.movie],
);
print(legacy.years); // [1999, 2001, 2024, ...]
print(legacy.officialRatings); // ['PG-13', 'R', ...]
facets() answers genres with ids and tags. Pass the chosen ids to
items.list(genreIds:). legacy() answers genres and tags by name, plus
the years and official ratings that facets() leaves out.
Collections
Collections are BoxSet items, so items.list(includeItemTypes: [JellyfinItemKind.boxSet]) lists them. collection edits them:
final created = await jellyfin.collection.create(
name: 'Best of 2024',
ids: [albumA, albumB],
);
final collectionId = created.id;
await jellyfin.collection.addItems(collectionId: collectionId, ids: [albumC]);
await jellyfin.collection.removeItems(collectionId: collectionId, ids: [albumA]);
// Every collection an item belongs to, for an "Included in" row.
final includedIn = await jellyfin.library.collections(itemId: album.id);
create() throws a parse error when the answer holds no id. Removing
an item from a collection leaves the item in the library.
Channels
Channels are content sources that plugins provide, such as podcasts or online radio; for TV channels, see the TV, movies and live TV topic. Each channel holds a tree of items, browsed like a library.
Listing channels
final channels = await jellyfin.channels.list(supportsLatestItems: true);
Items, latest and features
final episodes = await jellyfin.channels.items(
channelId: channelId,
sortBy: const [JellyfinSortField.dateCreated],
descending: true,
limit: 50,
);
final latest = await jellyfin.channels.latest(channelIds: [channelA, channelB], limit: 20);
final features = await jellyfin.channels.features(channelId: channelId);
print(features.supportsContentDownloading);
final allFeatures = await jellyfin.channels.allFeatures();
items(folderId:) opens a folder of the channel. allFeatures()
answers the features of every channel in one call.
Classes
- JellyfinArtistsApi Library
- Music artists, through the people routes.
- JellyfinChannelsApi Library
-
/Channels— plugin-provided IPTV / online-source channels. - JellyfinCollectionApi Library
-
/Collections— manage Jellyfin's "Collection" item type. - JellyfinFilterApi Library
-
/Items/Filters*— dynamic facet endpoints. - JellyfinGenresApi Library
-
/Genres*— generic genres across the library. - JellyfinItem Library
-
Subset of
BaseItemDto. Hand-rolled — the full DTO has 153 fields, here we lift only what music apps use today. Anything else lives in JellyfinItem.raw. - JellyfinItemsApi Library
-
/Items— the backbone of Jellyfin browsing. - JellyfinLibraryApi Library
-
/UserViewsand library-level helpers. - JellyfinPersonsApi Library
-
/Persons*— actors, directors, composers, artists, etc. - JellyfinStudiosApi Library
-
/Studios*— production studios and labels. - JellyfinUserViewsApi Library
-
/UserViews— alternate "views" endpoints. - JellyfinYearsApi Library
-
/Years*— release-year browse buckets.