feat(emby): add Emby as a MediaBrowser backend alongside Jellyfin

Emby is Jellyfin's upstream ancestor and speaks a near-identical MediaBrowser API, so the existing Jellyfin stack is parameterised by a `MediaBrowserDialect` rather than forked. `JellyfinClient`, its auth service, endpoint discovery, LAN discovery, and the add/edit connection screens all take the dialect and keep one implementation; `MediaBackend.emby` and `ConnectionKind.emby` carry it through the neutral models, the Drift `kind` discriminator, downloads, and caches. Every divergence below was measured against a live Emby 4.9.5 server, not inferred from documentation, and each is documented at its capability getter. Jellyfin's request strings stay byte-identical so nothing about its behaviour changes. Routes and auth - Emby only accepts the pre-10.9 user-scoped item routes (`/Users/{id}/Items/…`, `/Users/{id}/PlayedItems/…`, `/Users/{id}/FavoriteItems/…`); the unprefixed forms Jellyfin 10.11 added return 404. - The API is also served under a legacy `/emby` prefix, and both dialects accept the token as `X-Emby-Token` or `api_key=`. - Emby answers only its own LAN discovery datagram ("who is EmbyServer?") and ignores Jellyfin's; its default HTTPS port is 8920. - No `/QuickConnect` route exists, so Quick Connect stays Jellyfin-only. Row fields Emby withholds - `ProductionYear`, `OfficialRating`, `PremiereDate` and `DateCreated` are absent from list rows unless named in `Fields`, which would otherwise strip the year and age-rating badge from every card in the app. - `UserData.LastPlayedDate` never appears on a list row under `Fields=UserData`, `EnableUserData=true` or the user-scoped `Ids=` form — only on the single-item detail route, or when the Emby-specific `UserDataLastPlayedDate` token is requested. Without it every recency-ordered surface silently degrades to library-add time, and `JellyfinApiCache.applyWatchState` stamps `DateTime.now()` on watched rows, so an offline watch-state pull would rewrite the cached play time of everything it walked. Continue Watching and Next Up - Emby computes Next Up per series only: the library-wide `/Shows/NextUp` query returns nothing under every parameter combination tried. The shelf is therefore reconstructed from a played-episode recency scan plus one `/Shows/NextUp?SeriesId=` per distinct series, bounded by a shared wall clock that covers the scan as well — per-request timeouts cannot bound the pass because `MediaServerHttpClient` times the connect and receive phases independently. Rows are stamped with their series' newest play from the same response that ordered them, so no per-series enrichment request is needed. - `/Shows/NextUp` ignores `NextUpDateCutoff`, and no server-side played-date filter exists to delegate to (`MinDatePlayed` and `MinDateLastPlayed` are ignored; `MinDateLastSaved`, `MinDateCreated` and `MinPremiereDate` filter unrelated dates), so the 365-day window is applied to the scanned dates. - The resume route returns items with no saved position, including plain next episodes, so the Emby resume leg reads from `/Items?Filters=IsResumable`. - Emby is ahead of Jellyfin in one place: `/Users/{id}/Items/{id}/HideFromResume` makes Continue Watching removal a real capability. Everything else - `/Sessions/Playing` and `/Sessions/Playing/Progress` reject a body with no `PlaySessionId` (HTTP 400), so playback reporting always sends one. - Passing any `MediaTypes` value to the playlist query returns an empty list. - There is no aggregate `/Items/Filters` route; the four filter facets are reassembled from `/Genres`, `/OfficialRatings`, `/Studios` and `/Tags`. - Metadata writes take name-pair lists (`Genres: [{'Name': 'Action'}]`); the plain string array is accepted and then silently discarded. - Custom artwork uploads must be base64 text, not raw bytes — which was broken for Jellyfin too and is fixed for both. - Trickplay, media segments and lyrics 404 on Emby, so scrub previews are absent and intro/credit markers fall back to chapter names. Verified against a local Emby 4.9.5 and a Jellyfin 10.11.11 control server: onboarding, browse, detail, playable stream URLs serving real bytes, subtitle sidecars, watch-state write and restore, hubs, cross-server aggregation and search across both backends simultaneously.
2026-08-05 06:09:26 +02:00
parent f36e20bcad
commit 05fd622968
128 changed files with 4917 additions and 1429 deletions
@@ -0,0 +1,140 @@
+import 'package:flutter_test/flutter_test.dart';
+import 'package:plezy/media/media_backend.dart';
+import 'package:plezy/media/media_browser_dialect.dart';
+
+/// Contract tests for the Jellyfin/Emby dialect discriminator.
+///
+/// The detection fixtures are verbatim `/System/Info/Public` bodies captured
+/// from Jellyfin 10.10.7 and Emby 4.9.5, so a shape change on either server
+/// surfaces here rather than as a mis-labelled connection.
+void main() {
+  group('MediaBrowserDialect ids', () {
+    test('id round-trips through fromId', () {
+      for (final dialect in MediaBrowserDialect.values) {
+        expect(MediaBrowserDialect.fromId(dialect.id), dialect);
+      }
+    });
+
+    test('fromId throws on an unknown id', () {
+      expect(() => MediaBrowserDialect.fromId('plex'), throwsA(isA<ArgumentError>()));
+    });
+
+    test('ids match the MediaBackend ids they map to', () {
+      for (final dialect in MediaBrowserDialect.values) {
+        expect(dialect.backend.id, dialect.id);
+        expect(dialect.backend.dialect, dialect);
+      }
+    });
+
+    test('fromIdOrJellyfin tolerates legacy rows that carry no dialect', () {
+      expect(MediaBrowserDialect.fromIdOrJellyfin(null), MediaBrowserDialect.jellyfin);
+      expect(MediaBrowserDialect.fromIdOrJellyfin(''), MediaBrowserDialect.jellyfin);
+      expect(MediaBrowserDialect.fromIdOrJellyfin('nonsense'), MediaBrowserDialect.jellyfin);
+      expect(MediaBrowserDialect.fromIdOrJellyfin('emby'), MediaBrowserDialect.emby);
+    });
+  });
+
+  group('MediaBrowserDialect capabilities', () {
+    test('Jellyfin-only features are off for Emby', () {
+      expect(MediaBrowserDialect.jellyfin.supportsQuickConnect, isTrue);
+      expect(MediaBrowserDialect.emby.supportsQuickConnect, isFalse);
+
+      expect(MediaBrowserDialect.jellyfin.supportsTrickplay, isTrue);
+      expect(MediaBrowserDialect.emby.supportsTrickplay, isFalse);
+
+      expect(MediaBrowserDialect.jellyfin.supportsMediaSegments, isTrue);
+      expect(MediaBrowserDialect.emby.supportsMediaSegments, isFalse);
+
+      // Emby resolves /Audio/{id}/Lyrics to audio streaming with `Lyrics` as
+      // the container and starts a failing ffmpeg process, so this gate is
+      // load-bearing rather than cosmetic.
+      expect(MediaBrowserDialect.jellyfin.supportsLyrics, isTrue);
+      expect(MediaBrowserDialect.emby.supportsLyrics, isFalse);
+
+      expect(MediaBrowserDialect.jellyfin.supportsAggregateItemFilters, isTrue);
+      expect(MediaBrowserDialect.emby.supportsAggregateItemFilters, isFalse);
+    });
+
+    test('only Emby needs the pre-10.9 user-scoped item routes', () {
+      expect(MediaBrowserDialect.emby.requiresUserScopedItemRoutes, isTrue);
+      expect(MediaBrowserDialect.jellyfin.requiresUserScopedItemRoutes, isFalse);
+    });
+
+    test('LAN discovery payloads are distinct so the datagram identifies the dialect', () {
+      expect(MediaBrowserDialect.jellyfin.lanDiscoveryMessage, 'who is JellyfinServer?');
+      expect(MediaBrowserDialect.emby.lanDiscoveryMessage, 'who is EmbyServer?');
+    });
+
+    test('Emby adds its 8920 HTTPS default to the port guesses', () {
+      expect(MediaBrowserDialect.jellyfin.httpsPortGuesses, [8096]);
+      expect(MediaBrowserDialect.emby.httpsPortGuesses, contains(8920));
+      expect(MediaBrowserDialect.emby.httpsPortGuesses, contains(8096));
+    });
+
+    test('product names are the untranslated brand names', () {
+      expect(MediaBrowserDialect.jellyfin.productName, 'Jellyfin');
+      expect(MediaBrowserDialect.emby.productName, 'Emby');
+    });
+  });
+
+  group('MediaBrowserDialect.detectFromPublicSystemInfo', () {
+    test('identifies a real Jellyfin 10.10.7 body by ProductName', () {
+      expect(
+        MediaBrowserDialect.detectFromPublicSystemInfo(const {
+          'LocalAddress': 'http://172.17.0.3:8096',
+          'ServerName': '0c1d332b2f44',
+          'Version': '10.10.7',
+          'ProductName': 'Jellyfin Server',
+          'OperatingSystem': '',
+          'Id': 'c88f271ded7e42cf87e6b12c287906ac',
+          'StartupWizardCompleted': true,
+        }),
+        MediaBrowserDialect.jellyfin,
+      );
+    });
+
+    test('identifies a real Emby 4.9.5 body by its RemoteAddresses array', () {
+      expect(
+        MediaBrowserDialect.detectFromPublicSystemInfo(const {
+          'LocalAddresses': <String>[],
+          'RemoteAddresses': <String>[],
+          'ServerName': '7befeeb2e8c9',
+          'Version': '4.9.5.0',
+          'Id': '9b6b1ea5ad4c4409a89f0f5e40607022',
+        }),
+        MediaBrowserDialect.emby,
+      );
+    });
+
+    test('an explicit Emby ProductName wins over shape sniffing', () {
+      expect(
+        MediaBrowserDialect.detectFromPublicSystemInfo(const {'ProductName': 'Emby Server', 'Id': 'x'}),
+        MediaBrowserDialect.emby,
+      );
+    });
+
+    test('returns null when neither signal is present so the caller keeps the user choice', () {
+      expect(MediaBrowserDialect.detectFromPublicSystemInfo(const {'ServerName': 'x', 'Id': 'y'}), isNull);
+      expect(MediaBrowserDialect.detectFromPublicSystemInfo(const {'ProductName': ''}), isNull);
+    });
+  });
+
+  group('MediaBackend MediaBrowser predicate', () {
+    test('usesMediaBrowserApi covers Jellyfin and Emby but not Plex', () {
+      expect(MediaBackend.plex.usesMediaBrowserApi, isFalse);
+      expect(MediaBackend.jellyfin.usesMediaBrowserApi, isTrue);
+      expect(MediaBackend.emby.usesMediaBrowserApi, isTrue);
+      expect(MediaBackend.plex.dialect, isNull);
+    });
+
+    test('emby round-trips through the persisted id helpers', () {
+      expect(MediaBackend.emby.id, 'emby');
+      expect(MediaBackend.fromId('emby'), MediaBackend.emby);
+      expect(MediaBackend.fromString('emby'), MediaBackend.emby);
+    });
+
+    test('a missing backend id still falls back to Plex for pre-Jellyfin cache rows', () {
+      expect(MediaBackend.fromString(null), MediaBackend.plex);
+    });
+  });
+}
@@ -1,5 +1,6 @@
 import 'package:flutter_test/flutter_test.dart';
 import 'package:plezy/media/media_backend.dart';
+import 'package:plezy/media/media_browser_dialect.dart';
 import 'package:plezy/media/media_item.dart';
 import 'package:plezy/media/media_kind.dart';
 import 'package:plezy/media/media_part.dart';
@@ -639,6 +640,46 @@ void main() {
      expect(decoded.id, 'legacy');
      expect(decoded.kind, MediaKind.movie);
    });
+
+    test('an Emby item persists its own backend id and restores the dialect', () {
+      const original = JellyfinMediaItem(
+        dialect: MediaBrowserDialect.emby,
+        // Emby item ids are short numeric strings, not GUIDs.
+        id: '7330',
+        kind: MediaKind.movie,
+        title: 'Movie 001',
+        playlistItemId: 'entry-1',
+      );
+
+      final json = original.toJson();
+      final decoded = MediaItem.fromJson(json);
+
+      // One discriminator on the wire: the union key carries the resolved
+      // backend and the dialect is rebuilt from it.
+      expect(json['backend'], 'emby');
+      expect(json.containsKey('dialect'), isFalse);
+      expect(decoded, isA<JellyfinMediaItem>());
+      expect(decoded.backend, MediaBackend.emby);
+      expect((decoded as JellyfinMediaItem).dialect, MediaBrowserDialect.emby);
+      expect(decoded.playlistItemId, 'entry-1');
+      expect(decoded.id, '7330');
+    });
+
+    test('the compat factory routes both MediaBrowser backends to one variant', () {
+      final emby = MediaItem(id: 'e1', backend: MediaBackend.emby, kind: MediaKind.movie);
+      final jellyfin = MediaItem(id: 'j1', backend: MediaBackend.jellyfin, kind: MediaKind.movie);
+
+      expect(emby, isA<JellyfinMediaItem>());
+      expect(jellyfin, isA<JellyfinMediaItem>());
+      expect(emby.backend, MediaBackend.emby);
+      expect(jellyfin.backend, MediaBackend.jellyfin);
+    });
+
+    test('copyWith preserves the Emby dialect', () {
+      final emby = MediaItem(id: 'e1', backend: MediaBackend.emby, kind: MediaKind.movie) as JellyfinMediaItem;
+
+      expect(emby.copyWith(title: 'renamed').backend, MediaBackend.emby);
+    });
  });

  group('MediaItem.displayTitle', () {