dart_jellyfin 0.4.1
dart_jellyfin: ^0.4.1 copied to clipboard
Dart client for Jellyfin 12.4 (12.0 or later). Authentication, library browsing, playlists, streaming, search, live events and more, on every Dart platform including the web.
dart_jellyfin #
Jellyfin client for Flutter and Dart.
![]() |
dart_jellyfin is a Dart client for Jellyfin 12.4, for servers from 12.0 on. It covers libraries, playlists, streaming, lyrics, playback reporting, remote control and search through typed Dart objects, and keeps the session for you. |
Installation #
It needs Dart 3.10 or later, and a Jellyfin server from 12.0 on.
Add dart_jellyfin to your pubspec.yaml:
dependencies:
dart_jellyfin: ^0.4.0
Features #
| Pure Dart no native plugin and no Flutter dependency. The main library also runs on the web; only downloadToFile() in io.dart needs dart:io. |
Typed models every answer is a typed Dart object with a raw map, and item kinds, fields, sort keys and filters are typed values. |
||
| Both sign-in flows username and password, and Quick Connect with a code approved on another device. |
Authorization header the MediaBrowser header with client, device, version and token, rebuilt when the token changes (see Client and sign-in). |
||
| One client a JellyfinClient holds the identity, server, token and user, and every sub-API works through it. |
Follows the OpenAPI document routes, parameter names and casing match the contract at api.jellyfin.org. |
||
Lyrics with timingJellyfinLyrics with line and word timing, rendered to LRC or enhanced LRC with toLrc(). |
Audio streaming URL builders for the server's choice between direct play and transcoding, the original file, a transcoded file and HLS. |
||
| Typed errors every failure is a JellyfinException with a type to branch on: auth, not found, timeout, connection, cancelled. |
Escape hatchrequest(), requestBytes() and requestStream() for routes the sub-APIs do not cover. |
||
| Any HTTP stack built on package:http: any http.Client, such as a CupertinoClient or CronetClient for HTTP/2 and the system proxy, or a MockClient in tests. |
Off the caller's isolate large answers are inflated, decoded and parsed on a background isolate, so the UI keeps its frames. |
||
Cancellation and retrieswithCancelToken() makes every call of a view cancellable, and a JellyfinRetryPolicy resends idempotent requests after transient failures. |
Streaming downloadsdownloadToFile() writes a body to disk as it arrives, with progress, and never leaves a partial file. |
Quick start #
import 'package:dart_jellyfin/dart_jellyfin.dart';
Future<void> main() async {
final jellyfin = JellyfinClient(
baseUrl: 'https://jellyfin.example.com',
credentials: const JellyfinCredentials(
client: 'MyApp',
device: 'iPhone',
deviceId: 'PUT-YOUR-UUID-HERE', // stable per install
version: '1.0.0',
),
);
// Sign in.
final auth = await jellyfin.user.authenticateByName(
username: 'me',
password: 'hunter2',
);
jellyfin.setSession(token: auth.accessToken, userId: auth.user.id);
// Find the music library and list its albums.
final views = await jellyfin.library.userViews();
final music = views.firstWhere((v) => v.isMusic);
final albums = await jellyfin.items.list(
parentId: music.id,
includeItemTypes: const [JellyfinItemKind.musicAlbum],
sortBy: const [JellyfinSortField.sortName],
limit: 50,
);
// List the first album's tracks and build a stream URL for one.
final tracks = await jellyfin.items.list(
parentId: albums.items.first.id,
includeItemTypes: const [JellyfinItemKind.audio],
);
final url = jellyfin.audio.universalStreamUrl(
itemId: tracks.items.first.id,
maxStreamingBitrate: 320000,
audioCodec: 'aac',
playSessionId: 'my-session-uuid',
);
print(url); // hand it to your audio engine
// Release the HTTP client when the app is done with the server.
jellyfin.close();
}
How it works #
JellyfinClient holds the identity of your app, the server, the token and the user. Each part of the Jellyfin API is a sub-API on it (jellyfin.items, jellyfin.playlists, jellyfin.audio and so on), and every call goes through one connection, the same transport dart_plex uses. Ids, names and keys are always named parameters.
Working with the client #
Signing in with Quick Connect #
final init = await jellyfin.quickConnect.initiate();
print('Enter ${init.code} in Jellyfin, under Settings, Quick Connect');
while (!(await jellyfin.quickConnect.state(secret: init.secret)).authenticated) {
await Future<void>.delayed(const Duration(seconds: 2));
}
final auth = await jellyfin.user.authenticateWithQuickConnect(secret: init.secret);
jellyfin.setSession(token: auth.accessToken, userId: auth.user.id);
See Client and sign-in for the credentials, the session, the HTTP stack and the users.
Browsing a library #
final page = await jellyfin.items.list(
parentId: music.id,
includeItemTypes: const [JellyfinItemKind.musicAlbum],
sortBy: const [JellyfinSortField.sortName],
fields: JellyfinItemsApi.browseFields,
limit: 50,
);
print('${page.items.length} of ${page.totalRecordCount}');
See Library for the typed kinds, fields and filters, and for artists, genres, people and collections.
Streaming and reporting a track #
final url = jellyfin.audio.universalStreamUrl(
itemId: track.id,
maxStreamingBitrate: 320000,
audioCodec: 'aac',
playSessionId: 'my-uuid',
);
await jellyfin.playback.start(itemId: track.id, playSessionId: 'my-uuid');
See Audio streaming and HLS for direct, transcoded and HLS URLs, and Playback negotiation and reporting for device profiles and the progress reports.
A playlist #
final playlist = await jellyfin.playlists.create(
name: 'My Mix',
mediaType: 'Audio',
itemIds: const ['12345', '12346'],
);
await jellyfin.playlists.addItems(playlistId: playlist.id, itemIds: const ['99999']);
See Playlists for entry ids, moving and removing entries, renames and sharing.
Lyrics #
final lyrics = await jellyfin.audio.lyrics(itemId: track.id);
if (lyrics != null && lyrics.isSynced) {
print(lyrics.toLrc());
}
See Search and lyrics for word timing, uploads, remote lyrics, search and instant mixes.
Covers #
final url = jellyfin.images.url(
itemId: track.artworkItemId ?? track.id,
tag: track.artworkVersion,
maxWidth: 512,
maxHeight: 512,
);
See User data and images for the sizing, the formats, favorites and display preferences.
Errors and cancellation #
final token = JellyfinCancelToken();
try {
await jellyfin.withCancelToken(token).items.list(parentId: music.id);
} on JellyfinException catch (e) {
if (e.isCancelled) return;
if (e.isAuthError) await signInAgain();
}
See Errors and paging for every error type, retries and paging.
Events #
final socket = await jellyfin.notifications.connect();
socket.events().listen((event) {
if (event case JellyfinUserDataChangedEvent(:final changes)) {
print('${changes.length} items changed');
}
});
See Events and downloads for every event and downloads to disk. Raw requests reach the routes the sub-APIs do not cover.
Documentation #
- API reference, with these guides:
- Client and sign-in: creating the client, credentials, the session, the HTTP stack, passwords, Quick Connect and users
- System: server info, counts, the clock, administration and localization
- Library: libraries, items, typed kinds, fields and filters, artists, genres, people, facets, collections and channels
- Playlists: creating, editing, reordering and sharing playlists
- Search and lyrics: search hints, suggestions, instant mixes and lyrics
- Audio streaming and HLS: universal, direct and transcoded URLs, and the HLS playlists
- Playback negotiation and reporting: playback info, device profiles, live streams, the bitrate probe and play reports
- Sessions and SyncPlay: sessions, cast targets, remote control and SyncPlay groups
- User data and images: favorites, played state, ratings, images and display preferences
- Video and subtitles: video URLs, direct play or transcoding, subtitles, trickplay and media segments
- TV, movies and live TV: seasons, episodes, next up, recommendations, trailers, channels, recordings and timers
- Errors and paging: exceptions, classifying a failure, cancellation, retries and paging
- Events and downloads: notifications, typed events and downloads to a file
- Raw requests:
request(),requestBytes()andrequestStream()
- Example
- CHANGELOG and MIGRATION
Project background #
I wrote the typed models, the sub-APIs and the transport with Claude Code.
Jellyfin is a trademark of the Jellyfin project. dart_jellyfin is not affiliated with it.
Developed by Alessandro Di Ronza
