dart_jellyfin

Jellyfin client for Flutter and Dart.

logo 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.

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 timing
JellyfinLyrics 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 hatch
request(), 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 retries
withCancelToken() makes every call of a view cancellable, and a JellyfinRetryPolicy resends idempotent requests after transient failures.
Streaming downloads
downloadToFile() writes a body to disk as it arrives, with progress, and never leaves a partial file.

Getting started

dependencies:
  dart_jellyfin: ^0.4.3

The package needs Dart 3.10 or later, and a Jellyfin server from 12.0 on.

Stream a track

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.

Architecture: your code calls JellyfinClient; JellyfinConnection sends through an http.Client and parses large answers on a background isolate into typed models

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

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

Libraries

dart_jellyfin
A Dart client for Jellyfin 12.4, for servers from 12.0 on.
io
File helpers for dart:io platforms (everything but the web).