dart_jellyfin 0.3.2
dart_jellyfin: ^0.3.2 copied to clipboard
Dart client for Jellyfin. Supports authentication, library browsing, playlists, streaming, search and more. Targets macOS, Windows, Linux, iOS and Android.
dart_jellyfin #
Jellyfin client for Flutter and Dart.
![]() |
dart_jellyfin is a Dart client for Jellyfin 12.2. It covers libraries, playlists, streaming, lyrics, playback reporting, remote control and search through typed Dart objects, and keeps the session for you. |
Installation #
Add dart_jellyfin to your pubspec.yaml:
dependencies:
dart_jellyfin: ^0.3.2
Features #
| Pure Dart no native plugin and no Flutter dependency, so it runs on every Dart platform, the web included. |
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: pass 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 the same connection. 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
