dtourolle/jellytau
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 45 Wiki Activity

docs(specs): Jellyfin server version compatibility, and what research found

Browse Source 
Adds the spec for running one build against two Jellyfin generations, plus the
research report that establishes what actually differs — with a source URL per
claim, and an explicit section for what could NOT be established.

The framing the spec started from was wrong, which is the most useful thing here:

  Jellyfin 11.0 does not exist and never did. With 12.0 the project dropped the
  leading "10" from its scheme, so what would have been 10.12.0 shipped as 12.0
  and the server reports Version: "12.0.0". The two live generations are 10.11.x
  and 12.x — one release-branch step apart, not two majors. 12.0 became stable
  on 2026-09-08.

The delta turned out far smaller than assumed, and almost none of it is a
version branch:

  - X-Emby-Authorization and the api_key query parameter are disabled by default
    in 12.0, including on upgraded servers via a migration. This is the one
    genuinely breaking change, and the fix is a rename: Authorization and ApiKey
    are ungated on both generations.
  - GetItems now defaults recursive to true for a library parent with
    IncludeItemTypes, so the same request returns a different result set. Fixed
    by stating Recursive explicitly.
  - The /Users/{userId}/... family survives. Six routes were removed in total;
    none are ones this client calls.
  - BaseItemDto is purely additive. DeviceProfile, PlaybackInfo and
    PublicSystemInfo are byte-identical between the two tags.

The generalisable lesson, recorded in the spec: most of a version delta is fixed
by writing the request correctly for both generations rather than by branching
on the version. A flag is a silent branch that outlives the reason it was added.

Allocates UR-085, IR-035, JA-037, DR-279..DR-288 and IT-019..IT-026. DR-287 and
DR-288 did not exist when the spec was written — they are what the research
turned up.

Also corrects docs/specs/README.md, whose "next free requirement ids" line was
stale by five, two and forty-seven.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
dtourolle
2026-09-08 20:09:11 +02:00
co-authored by Claude Opus 5
parent 4bce81a800
commit b1844f673e
4 changed files with 1054 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/specs/README.md
+6 -3
View File
@@ -27,15 +27,18 @@ know how something *works*, read
| Design authority | No code of its own — it records a decision later specs act on. |
**Next free requirement ids** (always re-check
[requirements.md](../requirements.md) before allocating): **UR-079**,
**IR-033**, **DR-232**. Three specs below suggested ids that have since been
taken by other work; each carries a ⚠️ note at the top.
[requirements.md](../requirements.md) before allocating): **UR-086**,
**IR-036**, **JA-038**, **DR-289**. Three specs below suggested ids that have
since been taken by other work; each carries a ⚠️ note at the top — this line
was itself stale by five, two and forty-seven until 2026-09-08, which is why the
re-check is not optional.
## Partially implemented
| Spec | What landed | What is left |
|---|---|---|
| [frontend-domain-model.md](frontend-domain-model.md) | Catalog surface: `MediaKind`, `from_jellyfin` isolated, ticks → ms | `primaryImageTag` → `imageId` (~30 sites); player/session/reporting tick math; `stream.type` |
| [jellyfin-server-version-compatibility.md](jellyfin-server-version-compatibility.md) | Route table, `ServerCapabilities`, the auth-spelling fix (the one thing 12.0 actually breaks), explicit `Recursive`, cache generation stamping, the frontend route leak, the unsupported-server state, and an HTTP-level harness that runs the repository against both generations | DR-283: two resolved flags are not consumed yet, and `honours_directplay_audio_codec` is unestablished for 12.x — both need a running 12.x server. Nothing has been tested against a real server of either generation |
| [libmpv2-migration.md](libmpv2-migration.md) | `LICENSE` | The `libmpv` → `libmpv2` crate swap |
| [read-through-media-cache.md](read-through-media-cache.md) | DR-126…128, DR-133…138 — cache entries *are* download rows; local playback of downloads | DR-122/124/125 — the read-through capture. DR-121 shipped as backend-owned stream selection and left this spec |
| [scoped-search-boundary-implementation.md](scoped-search-boundary-implementation.md) | Stage 1: `SearchScope` owned by Rust (DR-063…067) | Stage 2: result-side grouping (`GROUP_ITEM_TYPES` still in `searchScope.ts`) |
docs/specs/jellyfin-12-api-delta.md
+732
View File
@@ -0,0 +1,732 @@
<!--
Companion to jellyfin-server-version-compatibility.md — the evidence base for
every decision in it. Kept in the repo because the *reasoning* is what a future
change needs: which differences were verified, which were looked for and could
NOT be established, and which URL each claim came from.
Delete this alongside the spec when the last of it ships and the design is
folded into docs/architecture/.
-->
# Jellyfin server API delta: 10.11.x → next major
Research date: **2026-09-08**. All claims verified against live sources; no claim below is
from model memory. Method: GitHub Releases/Tags API, the official release blog, the published
OpenAPI spec, and a **byte-level diff of the actual C# source trees** at tags `v10.11.5` and
`v12.0` (downloaded from `codeload.github.com`, extracted locally).
---
## Section 1 — Version reality check
### 🔴 Jellyfin 11.0 does not exist and never did.
The complete tag list of `jellyfin/jellyfin` contains **zero** `v11.*` tags. The project went
directly from the `10.11.x` branch to `12.0`.
Source: `https://api.github.com/repos/jellyfin/jellyfin/tags` (all 8 pages; 116 tags total).
Major-version histogram: `v10` × 107, `v12` × 8, `v3` × 1. `11.x tags: []`.
### What actually exists today (2026-09-08)
| Version | Status | Published | Source |
|---|---|---|---|
| **12.0** | **Current stable / `releases/latest`** | **2026-09-08T01:38:39Z** (today) | `https://api.github.com/repos/jellyfin/jellyfin/releases/latest` |
| 12.0-rc1 … rc7 | prereleases | 2026-06 → 2026-08-31 | `https://api.github.com/repos/jellyfin/jellyfin/releases` |
| 10.11.11 | last release on the 10.11 branch | 2026-06-06T16:18:54Z | `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v10.11.11` |
| 10.11.5 | **what JellyTau targets** | 2025-12-15 (file mtime in tag tarball) | `https://codeload.github.com/jellyfin/jellyfin/tar.gz/refs/tags/v10.11.5` |
| 10.11.0 | 10.11 branch opened | 2025-10-20 | `https://jellyfin.org/posts/jellyfin-release-10.11.0` |
**v12.0 was released roughly 18 hours before this research was performed.** Treat "12.0 in the
wild" as approximately zero installs today, rising over the coming months.
### Why the number jumped 10.11 → 12.0
Official rationale, quoted from the release blog:
> "The most visible change in this release is the one in its name: we are dropping the major
> version '10' from our naming scheme. What would have been 10.12.0 is simply 12.0, and the
> server reports its version as `12.0.0`. 10.11.x was the last release branch to use the old
> scheme. […] Jumping to 11.0 would still look like a minor increment […]"
> "**If you maintain anything that parses Jellyfin version strings** — a client, a monitoring
> check, a deployment script, a container tag pin — **this is the item to look at before
> upgrading.**"
Source: `https://jellyfin.org/posts/jellyfin-release-12.0` (dated September 7, 2026)
So: `12.0` *is* `10.12` under the old scheme. It is one release-branch step from 10.11, not two.
**"Two server generations from one build" means 10.11.x and 12.x.** There is no third thing.
⚠️ Direct consequence for JellyTau: `/System/Info/Public` returns `Version: "12.0.0"` on the new
generation and `"10.11.5"` on the old. Any version comparison must not assume a leading `10.`.
---
## Section 2 — Confirmed changes
### 2.1 Routes: the legacy user-scoped family SURVIVES intact
**The `/Users/{userId}/…` route family that JellyTau depends on in ~17 call sites is NOT removed
in 12.0.** Every route the task listed still exists and still functions.
Verified by diffing every `[HttpGet|Post|Delete|Put|Patch|Head]` attribute across
`Jellyfin.Api/Controllers/` in both tags (369 routes in 10.11.5, 364 in 12.0).
**Complete list of routes removed in 12.0 — all six:**
| Route | Handler |
|---|---|
| `POST /Users/{userId}/EasyPassword` | `UpdateUserEasyPassword` |
| `GET /Items/{itemId}/CriticReviews` | `GetCriticReviews` |
| `GET /Environment/NetworkShares` | `GetNetworkShares` |
| `POST /System/MediaEncoder/Path` | `UpdateMediaEncoderPath` |
| `GET /LiveTv/Recordings/Groups/{groupId}` | `GetRecordingGroup` |
| `GET /QuickConnect/Initiate` | `InitiateQuickConnectLegacy` |
**Complete list of routes added in 12.0 — one:** `GET /Items/{itemId}/Collections`
(`GetItemCollections`).
Sources:
- Route diff computed from `https://codeload.github.com/jellyfin/jellyfin/tar.gz/refs/tags/v10.11.5`
and `.../v12.0`, directory `Jellyfin.Api/Controllers/`.
- Corroborated verbatim by the release notes: "Removed obsolete API routes: `POST
/Users/{userId}/EasyPassword` (the EasyPassword feature is gone), `GET
/Items/{itemId}/CriticReviews`, `GET /Environment/NetworkShares`, `POST
/System/MediaEncoder/Path`, `GET /LiveTv/Recordings/Groups/{groupId}`, and `GET
/QuickConnect/Initiate`" — `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v12.0`
**Confirmed present and functional in v12.0** (`Jellyfin.Api/Controllers/`, tag `v12.0`):
| Route | File:line in v12.0 |
|---|---|
| `GET /Users/{userId}/Items` | `ItemsController.cs:721` |
| `GET /Users/{userId}/Items/Resume` | `ItemsController.cs:1027` |
| `GET /Users/{userId}/Items/Latest` | `UserLibraryController.cs:619` |
| `GET /Users/{userId}/Views` | `UserViewsController.cs:107` |
| `GET /Users/{userId}/Items/{itemId}` | `UserLibraryController.cs:117` |
| `POST /Users/{userId}/FavoriteItems/{itemId}` | `UserLibraryController.cs:252` |
| `DELETE /Users/{userId}/FavoriteItems/{itemId}` | `UserLibraryController.cs:300` |
| `POST /Users/{userId}/PlayedItems/{itemId}` | `PlaystateController.cs:120` |
| `DELETE /Users/{userId}/PlayedItems/{itemId}` | `PlaystateController.cs:185` |
### 2.2 …but the whole family was ALREADY deprecated in 10.11.5, and 12.0 hardens the policy
This is **not a new deprecation**. Every one of those methods already carried
`[Obsolete("Kept for backwards compatibility")]` **and** `[ApiExplorerSettings(IgnoreApi = true)]`
in 10.11.5, at the same positions. Nothing changed about their status between the two versions.
Confirmed: the 12.0 OpenAPI spec contains only these `/Users` paths — `/Users`,
`/Users/AuthenticateByName`, `/Users/AuthenticateWithQuickConnect`, `/Users/Configuration`,
`/Users/ForgotPassword`, `/Users/ForgotPassword/Pin`, `/Users/Me`, `/Users/New`,
`/Users/Password`, `/Users/Public`, `/Users/{userId}`, `/Users/{userId}/Policy`.
**None of the item/view/favorite/played routes appear.**
Source: `https://api.jellyfin.org/openapi/jellyfin-openapi-stable.json`
(`info.version` = `"12.0.0"`, `x-jellyfin-version` = `"12.0.0"`, 294 paths).
What *is* new in 12.0 is the written removal policy:
> "If an endpoint isn't listed in the OpenAPI specification it should not be used by clients.
> There are certain endpoints that are still exposed for legacy reasons despite being excluded
> from the OpenAPI spec. **These can be removed in any major release without warning.**"
> "As a general rule, any deprecations will be marked as such for an entire (major) release cycle
> before the deprecated endpoint or parameter is liable for removal."
Source: `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v12.0`
**Assessment:** the user-scoped family needs no migration to run on 12.0, but it is now formally
removable without notice in 13.0. The replacements (`/Items?userId=`, `/UserViews?userId=`,
`/UserFavoriteItems/{itemId}`, `/UserPlayedItems/{itemId}`) **already exist in 10.11.5**, so
migrating is a one-generation-compatible change, not a branch.
Verified: `GET /Items` accepts `[FromQuery] Guid? userId` in v12.0
(`ItemsController.cs:171-174`), and non-user-scoped twins exist in *both* trees
(`UserLibraryController.cs`: `UserFavoriteItems/{itemId}`, `UserItems/{itemId}/Rating`).
### 2.3 🔴 AUTHENTICATION — the one genuinely breaking change for JellyTau
**`X-Emby-Authorization` is disabled by default in 12.0, including on upgraded servers.
`api_key` as a query parameter is disabled by default in 12.0.**
The authoritative accepted/deprecated table, from the Jellyfin core team's canonical
client-developer gist (last updated 2026-09-08):
| Type | Name | Method | Deprecated |
|---|---|---|---|
| Header | `Authorization` | Schema | **No** |
| Query | `ApiKey` | Token only | **No**, but discouraged |
| Query | `api_key` | Token only | **yes** |
| Header | `X-Emby-Token` | Token only | **yes** |
| Header | `X-MediaBrowser-Token` | Token only | **yes** |
| Header | `X-Emby-Authorization` | Schema | **yes** |
Source: `https://gist.github.com/nielsvanvelzen/ea047d9028f676185832e51ffaf12a6f`
(referenced from PR #13306 and from the 12.0 release notes)
**Verified in source.** `Jellyfin.Server.Implementations/Security/AuthorizationContext.cs` is
**byte-identical between v10.11.5 and v12.0** except one whitespace change
(`authorizationHeader[start.. i]` → `[start..i]`). The gating logic in **both** versions:
```csharp
// always read, no gate:
var auth = httpReq.Headers[HeaderNames.Authorization];
if (_configurationManager.Configuration.EnableLegacyAuthorization && string.IsNullOrEmpty(auth))
{
auth = httpReq.Headers["X-Emby-Authorization"];
}
...
var validName = name.Equals("MediaBrowser", StringComparison.OrdinalIgnoreCase); // always OK
validName = validName || (…EnableLegacyAuthorization && name.Equals("Emby", …)); // gated
...
if (…EnableLegacyAuthorization && string.IsNullOrEmpty(token)) { token = headers["X-Emby-Token"]; }
if (…EnableLegacyAuthorization && string.IsNullOrEmpty(token)) { token = headers["X-MediaBrowser-Token"]; }
if (string.IsNullOrEmpty(token)) { token = queryString["ApiKey"]; } // NOT gated
if (…EnableLegacyAuthorization && string.IsNullOrEmpty(token)) { token = queryString["api_key"]; } // gated
```
Source: `https://raw.githubusercontent.com/jellyfin/jellyfin/v12.0/Jellyfin.Server.Implementations/Security/AuthorizationContext.cs`
(and the `v10.11.5` path of the same file)
**The only difference between the two versions is the default of the gate:**
- `v10.11.5` — `MediaBrowser.Model/Configuration/ServerConfiguration.cs:290`:
`public bool EnableLegacyAuthorization { get; set; } = true;`
- `v12.0` — same file, same line: `public bool EnableLegacyAuthorization { get; set; }`
(no initializer → C# default `false`)
Source: `https://raw.githubusercontent.com/jellyfin/jellyfin/v10.11.5/MediaBrowser.Model/Configuration/ServerConfiguration.cs`
and `.../v12.0/...`
**Existing installs are flipped too**, by a migration that runs on first boot:
```csharp
[JellyfinMigration("2026-05-31T16:00:00", nameof(DisableLegacyAuthorization), …)]
public class DisableLegacyAuthorization : IAsyncMigrationRoutine
{
public Task PerformAsync(CancellationToken cancellationToken)
{
_serverConfigurationManager.Configuration.EnableLegacyAuthorization = false;
_serverConfigurationManager.SaveConfiguration();
```
Source: `tree/jellyfin-12.0/Jellyfin.Server/Migrations/Routines/20260531160000_DisableLegacyAuthorization.cs`
(from `https://codeload.github.com/jellyfin/jellyfin/tar.gz/refs/tags/v12.0`)
Release-note wording: "Legacy authorization is now disabled by default, and a migration disables
it on existing installs as well."
Source: `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v12.0`
Blog wording: "the deprecated way of signing in is now disabled, including on existing servers."
Source: `https://jellyfin.org/posts/jellyfin-release-12.0`
Change history (all merged):
- PR #13306 "Add option to disable deprecated legacy authorization options", merged
2025-01-11, shipped in 10.11 with default `true`. Body: *"The only method we'll allow is the
`Authorization` header with `MediaBrowser` scheme and the `ApiKey` query parameter. The other
headers (`X-Emby-Authorization`, `X-Emby-Token`, `X-MediaBrowser-Token`), query parameter
(`api_key`) and authorization scheme (`Emby`) are all deprecated."*
`https://api.github.com/repos/jellyfin/jellyfin/pulls/13306`
- PR #15559 "Disable legacy authorization methods by default", merged 2025-11-27. Body:
*"We'll remove this configuration option (and the authorization methods) in a future release,
likely 10.13."* `https://api.github.com/repos/jellyfin/jellyfin/pulls/15559`
- PR #16754 "Keep legacy authorization enabled" (temporary revert), merged 2026-05-05.
`https://api.github.com/repos/jellyfin/jellyfin/pulls/16754`
- PR #16992 "Re-disable legacy authorization methods by default", merged 2026-06-01 — the
state that shipped. `https://api.github.com/repos/jellyfin/jellyfin/pulls/16992`
#### 🟢 The critical good news: query-param auth for media players is SAFE
`ApiKey` (capital A, capital K, no underscore) as a **query parameter** is **not** deprecated and
**not** gated in either version. The server itself generates it — identically in both trees:
- `v10.11.5` `MediaBrowser.Model/Dlna/StreamInfo.cs:1042` → `sb.Append("&ApiKey=");`
- `v12.0` `MediaBrowser.Model/Dlna/StreamInfo.cs:1034` → `sb.Append("&ApiKey=");`
- `v12.0` `StreamInfo.cs:1279-1280` → `// Use "?ApiKey=" as seen in HEAD and other parts of the code`
So the load-bearing requirement — handing stream URLs to mpv / ExoPlayer / HTML5 `<video>`, which
cannot set headers — **remains satisfied on both generations by one code path**, provided the
parameter is spelled `ApiKey` rather than `api_key`.
#### 🔴 JellyTau uses the disabled spellings today
Grep of `/home/dtourolle/Development/JellyTau/src-tauri/src`:
- **21 occurrences of `.header("X-Emby-Authorization", …)`** across
`auth/mod.rs` (3), `jellyfin/client.rs` (5), `repository/online.rs` (13).
- **28 non-test occurrences of `api_key`**, including every stream URL:
`repository/online.rs:1046, 2314` (`/Videos/{}/stream?…&api_key={}`),
`online.rs:2338` (`/Audio/{}/stream?…&api_key={}`),
`online.rs:2464` (`/Videos/{}/master.m3u8?api_key={}&…`),
`online.rs:633, 727, 2626`, plus `player/stream_end.rs`, `player/mod.rs`,
`jellyfin/http_client.rs`, `repository/device_profile.rs`, `utils/diagnostics.rs`.
The header **value** JellyTau already builds is correct — `jellyfin/client.rs:60` emits
`MediaBrowser Client="…", Version="…", Device="…", DeviceId="…", Token="…"`, which is exactly the
`MediaBrowser` scheme the non-deprecated `Authorization` header expects.
**Therefore the fix is a rename, not a branch:**
- `X-Emby-Authorization` → `Authorization` (value unchanged)
- `api_key=` → `ApiKey=`
Both work on 10.11.5 **and** 12.0. **No capability flag is needed for authentication.**
### 2.4 `POST /Users/AuthenticateByName` — unchanged
Request DTO `Jellyfin.Api/Models/UserDtos/AuthenticateUserByName.cs` and response
`MediaBrowser.Controller/Authentication/AuthenticationResult.cs` are **byte-identical** between
v10.11.5 and v12.0 (`diff` exit 0, no output). The controller method differs only by an added
`[Tags("Authentication")]` OpenAPI annotation.
Note the endpoint still reads the auth context from the request, so the client-identifying
`Authorization: MediaBrowser Client=…, DeviceId=…` header must be present on the login call too.
`UserDto` (returned inside `AuthenticationResult`) has three fields whose **type widened to
nullable**, all annotated obsolete:
`HasPassword` `bool` → `bool? = true` `[Obsolete("This information is no longer provided")]`;
`HasConfiguredPassword` `bool` → `bool? = true` `[Obsolete("This is always true")]`;
`HasConfiguredEasyPassword` `bool` → `bool? = false`.
Source: `MediaBrowser.Model/Dto/UserDto.cs` diff between the two tags; corroborated by release
notes "`UserDto.HasPassword` is marked obsolete and no longer provides useful information".
### 2.5 `/System/Info/Public` — unchanged endpoint, changed version string
`MediaBrowser.Model/System/PublicSystemInfo.cs` is **byte-identical** between v10.11.5 and v12.0
(`diff` produced no output). Fields in v12.0: `LocalAddress`, `ServerName`, `Version`,
`ProductName`, `OperatingSystem`, `Id`, `StartupWizardCompleted`.
The route `[HttpGet("Info/Public")]` sits at `SystemController.cs:92` in **both** versions, with
no `[Authorize]` attribute (anonymous), and is present in the 12.0 OpenAPI spec as
`/System/Info/Public`.
Sources: source diff of both tags; `https://api.jellyfin.org/openapi/jellyfin-openapi-stable.json`
**The only delta is the value of `Version`:** `"12.0.0"` instead of `"10.11.x"`. Confirmed by the
blog: "the server reports its version as `12.0.0`" —
`https://jellyfin.org/posts/jellyfin-release-12.0`
Both uses JellyTau makes of this endpoint (version detection, offline-recovery probe) remain valid.
Version *parsing* is the thing to fix.
### 2.6 `/emby/*` and `/mediabrowser/*` route prefixes removed
`Jellyfin.Api/Middleware/LegacyEmbyRouteRewriteMiddleware.cs` **exists in v10.11.5 and is deleted
in v12.0**. Verified by `grep -rln '/emby' --include='*.cs'` over both trees: the file is listed
for 10.11.5 and absent for 12.0.
Release note: "Legacy route prefixes removed (`/emby/*` and `/mediabrowser/*`). Old third-party
clients that rely on them will stop working."
Source: `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v12.0`
**Not applicable to JellyTau** — grep found no `/emby/` or `/mediabrowser/` prefix usage.
### 2.7 BaseItemDto — purely additive, nothing removed or renamed
`MediaBrowser.Model/Dto/BaseItemDto.cs` diff between v10.11.5 and v12.0 is **two added fields and
nothing else**:
```diff
+ public float? AlbumNormalizationGain { get; set; }
+ public string OriginalLanguage { get; set; }
```
Every field the task called out is **declared identically in both versions** (verified by
extracting the property declarations from both files):
| Field | Type (identical in 10.11.5 and 12.0) |
|---|---|
| `ImageTags` | `Dictionary<ImageType, string>` |
| `BackdropImageTags` | `string[]` |
| `ParentBackdropImageTags` | `string[]` |
| `ParentBackdropItemId` | `Guid?` |
| `ParentThumbImageTag` / `ParentPrimaryImageTag` | `string` |
| `UserData` | `UserItemDataDto` |
| `MediaStreams` | `MediaStream[]` |
| `MediaSources` | `MediaSourceInfo[]` |
| `RunTimeTicks` | `long?` |
| `IndexNumber` | `int?` |
| `ParentIndexNumber` | `int?` |
| `SeriesId` | `Guid?` |
| `SeasonId` | `Guid?` |
`MediaBrowser.Model/Dto/UserItemDataDto.cs` and `MediaBrowser.Model/Dto/MediaSourceInfo.cs` are
**byte-identical** between the two tags.
`MediaBrowser.Model/Entities/MediaStream.cs` adds two fields — `LocalizedLanguage`,
`LocalizedOriginal` — and rewrites the computed `DisplayTitle` to use pre-resolved localized names
(this is the `Accept-Language` header support). **No field removed, no type changed.**
Source: source diff of `v10.11.5` vs `v12.0`.
### 2.8 PlaybackInfo — request and response shape unchanged; behaviour changed
`Jellyfin.Api/Models/MediaInfoDtos/PlaybackInfoDto.cs` (the POST body, carrying `DeviceProfile`)
is **byte-identical** between v10.11.5 and v12.0. `/Items/{itemId}/PlaybackInfo` is present in the
12.0 OpenAPI spec.
`MediaInfoController.cs` diff is 28 lines, all plumbing:
`GetPlaybackInfo(item, user)` → `GetPlaybackInfo(item, user, Request)` (to read `Accept-Language`),
and `SortMediaSources(info, maxStreamingBitrate)` → `SortMediaSources(info, maxStreamingBitrate, item.Id)`.
Source: source diff of `Jellyfin.Api/Controllers/MediaInfoController.cs` and
`Jellyfin.Api/Helpers/MediaInfoHelper.cs`.
### 2.9 DeviceProfile schema — near-identical, two changes
`MediaBrowser.Model/Dlna/` diff between v10.11.5 and v12.0:
| File | Result |
|---|---|
| `DeviceProfile.cs` | **byte-identical** |
| `DirectPlayProfile.cs` | **byte-identical** |
| `CodecProfile.cs` | **byte-identical** |
| `SubtitleProfile.cs` | **byte-identical** |
| `ProfileCondition.cs` | **byte-identical** |
| `TranscodingProfile.cs` | one change (below) |
| `ProfileConditionValue.cs` | one added enum member (below) |
**Change 1 — `TranscodingProfile.BreakOnNonKeyFrames` retired:**
```diff
[DefaultValue(false)]
+ [XmlIgnore]
[XmlAttribute("breakOnNonKeyFrames")]
- public bool BreakOnNonKeyFrames { get; set; }
+ [Obsolete("This is always false")]
+ public bool? BreakOnNonKeyFrames { get; set; }
```
**Type widened `bool` → `bool?`.** Also dropped from the copy constructor, dropped from
`StreamInfo`, and the `breakOnNonKeyFrames` **query parameter is removed from every streaming
endpoint** (`DynamicHlsController`, `VideosController`, `AudioController`,
`UniversalAudioController` — 8 method signatures total). Unknown query params are ignored by
ASP.NET Core, so a client still sending it is harmless.
**Change 2 — `ProfileConditionValue` gains `VideoRotation = 26`**, with a matching
`TranscodeReason.VideoRotationNotSupported = 1 << 27`. Additive; existing enum values are
unchanged (`NumStreams` is still `25`). Release note: "Add VideoRotation profile condition for
Android TVs that do not support rotation metadata."
Source: source diff of both tags; `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v12.0`
### 2.10 🟠 New: HLS/DASH-container sources are no longer eligible for direct play
New in `MediaBrowser.Model/Dlna/StreamBuilder.cs` (v12.0):
```csharp
private const string ManifestContainers = "hls,applehttp,dash";
…
// A manifest is not a byte stream, so it cannot be handed to the client as one. The variant
// and segment URIs inside it are relative to the origin and do not resolve against the
// Jellyfin url the client would fetch it from.
if (ContainerHelper.ContainsContainer(ManifestContainers, item.Container))
{
isEligibleForDirectPlay = false;
}
```
A source whose container is `hls`/`applehttp`/`dash` that direct-played on 10.11.5 will now be
transcoded/remuxed. Source: `StreamBuilder.cs` diff, hunk `@@ -714,6 +720,14 @@`.
### 2.11 🟠 TranscodeReasons now reports codec mismatches that 10.11.5 silently omitted
New in v12.0 `StreamBuilder.cs`:
```csharp
playlistItem.VideoCodecs = videoCodecs;
if (videoStream is not null && !ContainerHelper.ContainsContainer(videoCodecs, false, videoStream.Codec))
{
playlistItem.TranscodeReasons |= TranscodeReason.VideoCodecNotSupported;
}
…
if (audioStream is not null && audioStreamWithSupportedCodec is null)
{
playlistItem.TranscodeReasons |= TranscodeReason.AudioCodecNotSupported;
}
```
Source: `StreamBuilder.cs` diff, hunks `@@ -944,6 +958,10 @@` and `@@ -992,6 +1010,10 @@`.
This is a **reporting** improvement: PlaybackInfo responses now carry `VideoCodecNotSupported` /
`AudioCodecNotSupported` in cases where 10.11.5 returned an empty or partial reason set. If any
JellyTau workaround keys off "TranscodeReasons was empty so the profile must have been honoured",
that inference changes. See §3 for what this does **not** establish.
### 2.12 🔴 `GetItems` now defaults `recursive` to true for library folders with `includeItemTypes`
New in v12.0 `ItemsController.cs`:
```csharp
else if (folder is ICollectionFolder && includeItemTypes.Length == 0)
{
includeItemTypes = collectionType switch { CollectionType.boxsets => [BaseItemKind.BoxSet], _ => [] };
}
// includeItemTypes on a library lists its contents recursively rather than just its
// immediate children, so default to a recursive query when the client didn't choose.
if (folder is ICollectionFolder && includeItemTypes.Length > 0)
{
recursive ??= true;
}
```
and, at the user root, filtered requests now take the query path:
```diff
-if ((recursive.HasValue && recursive.Value) || ids.Length != 0 || item is not UserRootFolder)
+if ((recursive.HasValue && recursive.Value) || ids.Length != 0 || item is not UserRootFolder || query.HasFilters)
```
Source: `Jellyfin.Api/Controllers/ItemsController.cs` diff (703 lines), hunks `@@ -294,7 +321,22 @@`
and `@@ -307,220 +349,273 @@`.
Release-note wording: "`GetItems` is now asynchronous and applies `recursive` when filters are
requested, limited to requests that include `includeItemTypes`. **The same query can return a
different result set than it did on 10.11.**"
Source: `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v12.0`; also
`https://jellyfin.org/posts/jellyfin-release-12.0`
This applies equally to the deprecated `/Users/{userId}/Items` alias, which routes to the same
handler.
**JellyTau audit item:** any request that sends `ParentId=<library>` **plus** `IncludeItemTypes`
**without** an explicit `Recursive` will change behaviour. The hard-coded query strings in
`repository/online.rs` all pair `IncludeItemTypes` with `Recursive=true`, but the dynamically
appended ones do not obviously do so — check `repository/endpoints.rs:172, 263, 315, 353, 367` and
`repository/online.rs:1259, 1492, 2246, 2947`. **Sending `Recursive` explicitly makes the
behaviour identical on both generations** — again a rename-class fix, not a capability branch.
### 2.13 🟠 HLS controllers removed from the OpenAPI spec (routes still live)
`Jellyfin.Api/Controllers/DynamicHlsController.cs` gains a class-level
`[ApiExplorerSettings(IgnoreApi = true)]` in v12.0 (it had none in 10.11.5), as does
`HlsSegmentController.cs`. Release note: "The HLS controllers are hidden from the specification."
**The routes still exist and still work in v12.0**, confirmed in source:
| Route | v12.0 location |
|---|---|
| `GET/HEAD /Videos/{itemId}/master.m3u8` | `DynamicHlsController.cs:404-405` |
| `GET/HEAD /Audio/{itemId}/master.m3u8` | `DynamicHlsController.cs:577-578` |
| `GET /Videos/{itemId}/main.m3u8` | `DynamicHlsController.cs:745` |
| `GET /Videos/{itemId}/live.m3u8` | `DynamicHlsController.cs:164` |
| `GET /Videos/{itemId}/hls1/{playlistId}/{segmentId}.{container}` | `DynamicHlsController.cs:1086` |
But they are **absent from the 12.0 OpenAPI spec**. Grepping
`https://api.jellyfin.org/openapi/jellyfin-openapi-stable.json` for m3u8/stream/universal paths
returns only: `/Audio/{itemId}/stream`, `/Audio/{itemId}/stream.{container}`,
`/Audio/{itemId}/universal`, `/Videos/{itemId}/stream`, `/Videos/{itemId}/stream.{container}`,
`/Videos/{itemId}/Trickplay/{width}/tiles.m3u8`,
`/Videos/{itemId}/{mediaSourceId}/Subtitles/{index}/subtitles.m3u8`, plus LiveTv paths.
**`/Videos/{itemId}/master.m3u8` is not among them.**
Combined with the stated policy ("can be removed in any major release without warning"), JellyTau's
transcoded-playback path — which depends on `master.m3u8` — is now on **unspecified-but-functional**
footing. It works on 12.0; it carries removal risk for 13.0. This is a risk to track, not a
behavioural difference to branch on.
`GET/HEAD /Audio/{itemId}/universal` (`UniversalAudioController.cs:92-93`) and
`/Videos/{itemId}/stream` remain **in** the spec.
### 2.14 `StartTimeTicks` — unchanged
`long? startTimeTicks` appears in the same **11 method signatures** across
`VideosController.cs`, `AudioController.cs` and `DynamicHlsController.cs` in **both** v10.11.5 and
v12.0. Source: grep count over both trees.
One related fix in `StreamInfo.cs`: the master.m3u8 URL builder no longer emits a stray `?`
(10.11.5 appended `"/master.m3u8?"` then later `'?'`/`'&'`; 12.0 appends `"/master.m3u8"` and
rewrites the first `&` to `?`). This only affects server-generated URLs.
### 2.15 🟠 Image endpoints no longer upscale
New in v12.0 `MediaBrowser.Model/Drawing/DrawingUtils.cs`:
```csharp
/// Scales a size down uniformly until it fits inside a bounding box.
/// Returns the original size if it already fits, so this never upscales.
public static ImageDimensions ScaleDownToFit(ImageDimensions size, ImageDimensions boundingBox)
```
Blog: "Artwork is no longer stretched past its real size. Low resolution posters now appear at
their actual size instead of being blown up to fit."
Sources: `DrawingUtils.cs` diff; `https://jellyfin.org/posts/jellyfin-release-12.0`
A request for `?fillWidth=400` against a 200px-wide source now returns a ~200px image on 12.0 and a
400px image on 10.11.5. Layouts that assume the returned image matches the requested dimensions
will see different intrinsic sizes.
### 2.16 Other confirmed API-surface changes (obsolete-but-functional)
From `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v12.0`, each verified as an
`[Obsolete]` attribute present in the v12.0 controller source (file:line from the extracted tree):
| Endpoint | Replacement | v12.0 source |
|---|---|---|
| `GetTrailers` | `GetItems` with `includeItemTypes=Trailer` | `TrailersController.cs:125` |
| `GetArtists`, `GetAlbumArtists` | `GetPersons` | `ArtistsController.cs:90, 244` |
| `GetArtistByName` | `GetPerson` | `ArtistsController.cs:368` |
| `GetMusicGenre` | `GetGenre` | `MusicGenresController.cs:154` |
| `GetInstantMixFromMusicGenreBy{Id,Name}` | `GetInstantMixFromItem` | `InstantMixController.cs:199, 363` |
| `GetStartupConfiguration`, `UpdateInitialConfiguration`, `SetRemoteAccess` | configuration endpoints | `StartupController.cs:56, 76, 95` |
Also confirmed from the release notes: "`ItemByName` responses are restricted and people are
deduplicated"; sorting by name now uses `SortName`/`CleanName` so library ordering may differ;
`.ogg` is audio-only; global subtitle configuration removed in favour of per-library settings.
---
## Section 3 — Unverified / could not establish
Everything below was actively looked for and **could not be confirmed**. Treat each as unknown.
1. **Whether 12.0 honours a submitted `DirectPlayProfile`'s declared container and video codec any
differently from 10.11.5.** This was the central question behind JellyTau's workarounds and I
**cannot answer it.** What I established is narrower: 12.0 *reports* `VideoCodecNotSupported` /
`AudioCodecNotSupported` in `TranscodeReasons` where 10.11.5 did not (§2.11), and 12.0 refuses
direct play for HLS/DASH-container sources (§2.10). Neither tells you whether the *decision*
about a declared container/codec changed. `DirectPlayProfile.cs` is byte-identical and the rest
of `StreamBuilder.cs`'s direct-play evaluation shows no relevant change across its 18 diff
hunks, which is weak evidence for "no change" — but I did not trace the full decision path, and
I did not run either server. **Do not remove any existing workaround on the strength of this
report.** Verify empirically against a real 12.0 instance.
2. **Which specific 10.11.5 profile-ignoring defect each JellyTau workaround exists for.** I did
not read the workarounds or their originating issues, so I cannot say whether any is now
unnecessary, still necessary, or actively harmful on 12.0.
3. **Whether `EnableLegacyAuthorization` will be removed entirely in 13.0.** PR #15559 said
removal was expected "likely 10.13" (i.e. 13.0 under the new scheme), but that is a 2025-11
statement about a plan, not a commitment, and the flag still exists in 12.0. The 12.0 release
notes do not restate a removal target.
4. **Whether real-world 12.0 servers will have `EnableLegacyAuthorization` re-enabled by users.**
The setting is user-editable in `system.xml` and some users will flip it back to keep older
clients working. A client cannot read this setting (it is not in `/System/Info/Public`), so
**there is no way to detect it other than attempting a request and observing 401.** Do not
assume "server is 12.0" implies "legacy auth is off".
5. **The exact HTTP status/body returned when a legacy auth method is rejected.** I did not run a
12.0 server. I assume 401 based on the authorization pipeline but **did not verify it**, and I
did not establish whether a rejected `X-Emby-Authorization` produces a distinguishable error
from an expired token — which matters if you want to auto-detect and re-auth.
6. **Whether `/Users/{userId}/…` routes emit a deprecation warning header** (e.g. `Deprecation`,
`Sunset`, `Warning`) on 12.0. I looked at the controllers and found only `[Obsolete]` /
`[ApiExplorerSettings]` compile-time and spec-time attributes. I found no evidence of a runtime
response header, but did not exhaustively search the middleware pipeline.
7. **A 10.11.x OpenAPI document for a true spec-to-spec diff.** `api.jellyfin.org` serves only one
spec and it is now `12.0.0`; both the "stable" and "unstable" URLs return the identical
1,894,898-byte 12.0 document. The `jellyfin-sdk-typescript` repo's historic `openapi.json` files
are **Git LFS pointers**, which I did not resolve. All route/DTO comparisons in this report are
therefore from **C# source**, not from two specs. Source-level results should be equivalent or
better, but the difference is worth stating.
8. **Changes to `POST /Sessions/Playing`, `/Sessions/Playing/Progress`, `/Sessions/Playing/Stopped`
payload semantics**, and to remote-control / session-polling behaviour. `PlaystateController.cs`
shows the routes intact with unchanged obsolete markers, but I did not diff the session
manager, `SessionInfo`, or the WebSocket message set. JellyTau's remote mode depends on these
and they were **not examined**.
9. **Whether the `Accept-Language` header support changes any response JellyTau parses.**
`MediaStream.DisplayTitle` is now built from server-resolved `LocalizedLanguage` rather than
client-side culture lookup, which means `DisplayTitle` **strings will differ** — but I did not
determine the default when no `Accept-Language` is sent, nor whether JellyTau parses
`DisplayTitle` anywhere.
10. **Any change to `/Items/{itemId}/Images/{type}` URL parameters** (`tag`, `maxWidth`,
`fillHeight`, `quality`). I confirmed the *upscaling* behaviour change (§2.15) but did not diff
`ImageController`'s parameter list.
11. **Download / sync / offline endpoints** (`/Items/{id}/Download`, `/Sync/*`). Not examined.
12. **`/Videos/{id}/stream` `static=true` semantics** — whether the container/`mediaSourceId`
handling changed. `VideosController.cs` has a 207-line diff dominated by the
`PrimaryVersionId` `string` → `Guid` refactor and alternate-version relinking; I did not
isolate whether any of it alters `static=true` responses.
13. **Whether 12.0 changes the `DeviceId` single-session constraint** mentioned in the auth gist.
Not investigated.
14. **Actual 12.0 runtime behaviour of anything.** Nothing in this report was tested against a
running server of either version. Everything is source, spec, and release-note analysis.
---
## Section 4 — Proposed capability flags
The strongest finding here is that **most of this needs no flag.** Four of the five headline
changes are fixed by writing the request in a way that is correct on *both* generations. Flags
should be reserved for genuine either/or behaviour, because each one is a silent branch that will
outlive the reason it was added.
### Needs no flag — fix once, works on both generations
| Change | Fix | Why no flag |
|---|---|---|
| §2.3 auth header | `X-Emby-Authorization` → `Authorization`, same value | `Authorization` + `MediaBrowser` scheme is ungated in 10.11.5 and 12.0 |
| §2.3 query auth | `api_key=` → `ApiKey=` | `ApiKey` is ungated in both; the server itself emits it in both |
| §2.12 recursive default | send `Recursive` explicitly on every `IncludeItemTypes` query | an explicit value makes both generations agree |
| §2.9 breakOnNonKeyFrames | stop sending it | ignored as an unknown query param on both |
| §2.2 user-scoped routes | optional: migrate to `/Items?userId=` etc. | replacements exist in 10.11.5 too |
Do these first. They eliminate the entire breaking surface without introducing a single branch.
### Genuinely version-dependent — flag candidates
A single detected generation, derived once from `/System/Info/Public` `Version`, should drive these:
```
ServerGeneration::V10_11 // Version major == 10
ServerGeneration::V12Plus // Version major >= 12
```
| Flag | Guards | Default 10.11.x | Default 12.x | Source |
|---|---|---|---|---|
| `supports_manifest_container_direct_play` | Whether an `hls`/`applehttp`/`dash` source may be direct-played | `true` | `false` | §2.10 |
| `reports_codec_transcode_reasons` | Whether an empty/partial `TranscodeReasons` can be read as "profile honoured" | `false` | `true` | §2.11 |
| `image_endpoint_upscales` | Whether a requested `fillWidth`/`maxWidth` is the size you get back | `true` | `false` | §2.15 |
| `hls_master_playlist_in_spec` | Whether `/Videos/{id}/master.m3u8` is a specified endpoint (removal-risk telemetry, not a behaviour switch) | `true` | `false` | §2.13 |
### Runtime-probed, not version-derived
| Flag | Why it cannot be version-derived |
|---|---|
| `legacy_auth_accepted` | A 12.0 admin can set `EnableLegacyAuthorization=true`, and a 10.11 admin can set it to `false`. Not exposed to clients (§3.4). If JellyTau keeps any legacy-auth fallback, it must be probe-and-observe-401, never version-inferred. **Better: send only non-deprecated auth and delete the concept.** |
### Version parsing
Whatever detects the generation must **not** assume a leading `10.`. `/System/Info/Public` returns
`"10.11.5"` on one generation and `"12.0.0"` on the other; under the old scheme 12.0 would have been
10.12.0, so `major >= 12` and `major == 10` are the two live cases and `major == 11` will never
occur. The Jellyfin blog explicitly flags version-string parsers as the thing to check before
upgrading (`https://jellyfin.org/posts/jellyfin-release-12.0`).
---
## Source index
| # | URL |
|---|---|
| 1 | `https://api.github.com/repos/jellyfin/jellyfin/tags` (pages 1-8) |
| 2 | `https://api.github.com/repos/jellyfin/jellyfin/releases/latest` |
| 3 | `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v12.0` |
| 4 | `https://api.github.com/repos/jellyfin/jellyfin/releases/tags/v10.11.11` |
| 5 | `https://jellyfin.org/posts/jellyfin-release-12.0` |
| 6 | `https://jellyfin.org/posts/` |
| 7 | `https://api.jellyfin.org/openapi/jellyfin-openapi-stable.json` (`info.version` = 12.0.0) |
| 8 | `https://gist.github.com/nielsvanvelzen/ea047d9028f676185832e51ffaf12a6f` (auth methods table) |
| 9 | `https://api.github.com/repos/jellyfin/jellyfin/pulls/13306` |
| 10 | `https://api.github.com/repos/jellyfin/jellyfin/pulls/15559` |
| 11 | `https://api.github.com/repos/jellyfin/jellyfin/pulls/16754` |
| 12 | `https://api.github.com/repos/jellyfin/jellyfin/pulls/16992` |
| 13 | `https://codeload.github.com/jellyfin/jellyfin/tar.gz/refs/tags/v10.11.5` (full source tree) |
| 14 | `https://codeload.github.com/jellyfin/jellyfin/tar.gz/refs/tags/v12.0` (full source tree) |
| 15 | `https://raw.githubusercontent.com/jellyfin/jellyfin/v12.0/Jellyfin.Server.Implementations/Security/AuthorizationContext.cs` |
| 16 | `https://raw.githubusercontent.com/jellyfin/jellyfin/v10.11.5/MediaBrowser.Model/Configuration/ServerConfiguration.cs` |
| 17 | `https://raw.githubusercontent.com/jellyfin/jellyfin/v12.0/MediaBrowser.Model/Configuration/ServerConfiguration.cs` |
Working files (source trees, diffs, route diff JSON) are retained in the scratchpad alongside this
report: `tree/jellyfin-10.11.5/`, `tree/jellyfin-12.0/`, `routediff.json`, `sb.diff`, `items.diff`,
`v12-body.md`, `oas-stable.json`.
docs/specs/jellyfin-server-version-compatibility.md
+294
View File
@@ -0,0 +1,294 @@
# Spec: Jellyfin server version compatibility
**Status:** Partially implemented
**Requirements:** UR-085 → IR-035, JA-037, DR-279 … DR-288 (DR-287 and DR-288
were added once research established what actually breaks).
## What is left
Everything below shipped on 2026-09-08 **except**:
- **DR-283 is partially done.** `supports_manifest_container_direct_play` and
`image_endpoint_upscales` are resolved and tested, but **nothing consumes them
yet** — and that may be correct rather than an omission: on 12.0 the *server*
enforces both (it refuses direct play for manifest containers itself, and
simply returns the smaller image), so the client learns the answer from the
`PlaybackInfo` response without needing to predict it. Decide whether to
consume them or delete them once a running 12.x server can be observed. Do not
leave them unread indefinitely: an unconsumed flag is a branch waiting to be
wired wrongly.
- **`honours_directplay_audio_codec` is unresolved for 12.x.** A source-level
diff could not establish whether the behaviour changed. The override stays on
for both generations. Flip it only against a running 12.x server — keeping it
costs an unnecessary transcode, removing it wrongly costs silent playback.
- **The user-scoped route migration (DR-282) was not performed.** It is not
needed: the whole family still works on 12.0. Both route shapes are built and
tested, so switching is a one-line change whenever it is wanted.
- **Nothing was tested against a real server of either generation.** Every
cross-generation assertion runs against a mock built from a source-level diff.
## What research established
The framing this spec was written under was wrong in a way worth recording.
**Jellyfin 11.0 does not exist and never did.** With 12.0 the project dropped the
leading `10` from its version scheme: what would have been 10.12.0 shipped as
`12.0`, and the server reports `Version: "12.0.0"`. So "two generations" means
**10.11.x and 12.x**, one release-branch step apart, not two majors. 12.0 became
stable on 2026-09-08 — the same day this work was done — so real-world 12.x
installs are currently near zero and rising.
The delta is far smaller than this spec assumed, and almost none of it is a
branch:
| Finding | Consequence |
|---|---|
| `X-Emby-Authorization` and the `api_key` query parameter are **disabled by default in 12.0**, including on upgraded servers via a migration | The one genuinely breaking change. Fixed by a **rename** — `Authorization` + `ApiKey` are ungated on both — not a flag (DR-287) |
| `GetItems` now defaults `recursive` to true for a library parent with `IncludeItemTypes` | The same request returns a different result set. Fixed by stating `Recursive` explicitly (DR-288) |
| The `/Users/{userId}/…` family **survives** in 12.0 | No migration needed. Six routes were removed in total; none are ones this client calls |
| `BaseItemDto` is **purely additive**; `DeviceProfile`, `PlaybackInfo`, `PublicSystemInfo` byte-identical | No DTO work at all |
| Manifest-container sources are no longer direct-play eligible; image endpoints no longer upscale | The only two genuine either/or differences — and both are server-enforced |
The lesson for the layer rule: **most of a version delta is fixed by writing the
request correctly for both generations, not by branching on the version.** Flags
are for genuine either/or behaviour, because each one is a silent branch that
outlives the reason it was added.
The full report, with a source URL per claim, is
[jellyfin-12-api-delta.md](jellyfin-12-api-delta.md).
**UX spec:** n/a for the bulk of it. One new user-visible state — "this server
is a version JellyTau does not know" — needs a home in the connect flow; see
DR-286.
**Supersedes / revises:** nothing. Touches
[backend-owned-stream-selection.md](backend-owned-stream-selection.md) at the
`StreamSelection` boundary and should land after it where they overlap, but
neither blocks the other.
**Destination on completion:**
[01-rust-backend.md](../architecture/01-rust-backend.md) — a new "Server
capability negotiation" section beside "Domain Vocabulary Owned by Rust", which
is where the litmus test this feature exists to satisfy already lives; and a
paragraph in [07-connectivity.md](../architecture/07-connectivity.md) noting
that the `/System/Info/Public` probe now has a second consumer. The durable half
is the capability model and *why* it is flags rather than version comparisons;
phases, ticket boundaries and acceptance criteria are disposable.
## Summary
Let one build of JellyTau talk to more than one generation of Jellyfin server.
The app already asks the server what version it is, at connect, before login —
and then throws the answer away. Instead it resolves that version into a
`ServerCapabilities` value once per connection, and every decision that depends
on the server generation reads a named flag from it.
Nothing about the app changes for a user whose server matches what the code
targets today. What changes is that the release which follows the server forward
stops silently abandoning everyone who has not upgraded, and that a server the
app does not recognise produces a sentence rather than a cascade of parse
failures.
## Motivation
The server and its clients are upgraded by different people on different
schedules. A family server can sit a major version behind for a year while the
phone updates itself weekly. Today the code has no way to express that.
**1. One server generation is hard-coded, unconditionally.** The current target
is 10.11.5 and it is written into the code as fact, not as a branch —
[device_profile.rs:336](../../src-tauri/src/repository/device_profile.rs#L336),
[online.rs:966](../../src-tauri/src/repository/online.rs#L966),
[online.rs:2271](../../src-tauri/src/repository/online.rs#L2271), and most
pointedly [online.rs:4667](../../src-tauri/src/repository/online.rs#L4667),
which is documented as "the override that exists because Jellyfin 10.11.5
ignores…". Every one of those is correct for one server and wrong for another,
and there is nowhere to say which.
**2. Endpoints are 57 inline string literals, not a route table.** They are
built with `format!` at the point of use, query string and all —
[online.rs:1957](../../src-tauri/src/repository/online.rs#L1957) is
representative. Supporting a second route shape without a table means 57
conditionals rather than one.
**3. The legacy user-scoped routes are load-bearing.** Roughly twelve sites use
`/Users/{uid}/Items`, `/Users/{uid}/Items/Resume`, `/Users/{uid}/Views`,
`/Users/{uid}/FavoriteItems/{id}` and `/Users/{uid}/PlayedItems/{id}`. These are
precisely the routes upstream has been moving away from in favour of
`/Items?userId=`. Whichever release drops them takes the app with it.
**4. There is no way to test any of this.** `src-tauri/` contains no HTTP mocking
at all — no `wiremock`, no `mockito`, no `httpmock`. Every test of the online
repository asserts on a *constructed URL string*; not one exercises a response.
So there is currently no mechanism by which "works against both generations"
could be demonstrated, and this is the single largest item in the work. It is
also worth doing on its own merits: a 4,797-line adapter with no response-level
tests is under-covered regardless of how many server versions it supports.
**5. A Jellyfin route is being built in the frontend.**
[imageCache.ts:64](../../src/lib/services/imageCache.ts#L64) constructs
`${serverUrl}/Items/${itemId}/Images/${imageType}` in Svelte. By the litmus test
in this project's own spec template — *would this have to change if Jellyfin
changed its API?* — that is domain logic in the presentation layer. It is the
only one left, and this is the feature that makes it actively wrong rather than
merely misplaced.
**What this is not.** It is not multi-server support. Profiles are users on one
server ([profiles/store.rs](../../src-tauri/src/profiles/store.rs)), and that
does not change here. "Both versions at the same time" means one binary that
adapts to whichever server it is pointed at, not two servers connected at once.
## Layer assignment
| Logic / responsibility | Layer | Why it belongs there |
|------------------------|-------|----------------------|
| Server version string → capability flags | Rust | Domain vocabulary in the strictest sense: it changes when and only when Jellyfin's API changes. The template's litmus test answers this in one word. |
| Which route shape to use for a given call | Rust | Wire format. The frontend must not know that a route exists, let alone that there are two. |
| Image URL construction (**moving** out of `imageCache.ts`) | Rust | A Jellyfin route, therefore it changes with Jellyfin's API. Currently in the frontend; this feature is what turns that from untidy into broken. |
| Device-profile / `PlaybackInfo` override selection | Rust | Already Rust and staying there. Only the *gating* is new — the overrides stop being unconditional. |
| Whether a cache written against one server generation is still valid | Rust | A storage invariant. The frontend cannot see the server version and must not learn to. |
| Deciding a server is too old / too new to use | Rust | A domain judgement about an API, expressed as an opaque state on the wire. |
| How the "unsupported server" state is worded and where it appears in the connect flow | Frontend | Pure presentation. It changes if the UI is redesigned and not otherwise. The frontend renders an opaque state; it never compares a version. |
Borderline: none. The one row that could be argued is the last, and it splits
cleanly — Rust decides *that* the server is unsupported, the frontend decides
what that looks like. The frontend never receives a version number to reason
about, for the same reason it never receives an item-type list.
## Design
### `ServerCapabilities`
Resolved once, at connect, from a version the app already has.
`AuthManager::connect_to_server` ([auth/mod.rs:147](../../src-tauri/src/auth/mod.rs#L147))
already parses `PublicSystemInfo.version` and returns it in `ServerInfo`, and the
`servers` table already has a `version TEXT` column
([schema.rs:42](../../src-tauri/src/storage/schema.rs#L42)) that is written on
insert. Detection therefore costs nothing new; the value is simply discarded
today.
The resolved value hangs on `OnlineRepository` and is passed to the route table.
`OfflineRepository` has no server and no capabilities; `HybridRepository`
delegates. No `MediaRepository` method signature changes, so no caller above
`repository/` is touched.
**Flags, not comparisons.** Every capability is named for the behaviour it
governs — `user_scoped_item_routes`, `honours_directplay_container`,
`playback_info_respects_container` — and the version → flags mapping lives in
exactly one function. A `version < 11` scattered through call sites is the same
mistake as a taxonomy in the frontend: it re-derives a domain fact at the point
of use, and it is unreadable at the second occurrence. Flags also survive the
case the comparison cannot express, which is a backport.
### Route table
The ~30 distinct endpoints move into `repository/endpoints.rs`, each a function
taking `&ServerCapabilities` and returning the path. Everything in `online.rs`
already funnels through three helpers that take `endpoint: &str` —
`get_json`, `post_json`, `post_json_response`
([online.rs:315-459](../../src-tauri/src/repository/online.rs#L315-L459)) — so
the interception point exists and there are 32 call sites, not 57 literals.
This step is behaviour-preserving on its own and lands before anything depends
on it.
### Unknown versions
An unrecognised version resolves to the newest known capability set and is
recorded, not rejected — the app should keep working against a server that is
merely newer than the release. Rejection is reserved for a version below the
floor, where the failure is certain rather than likely. Either way the outcome
crosses the IPC boundary as an opaque state, never a version number.
### Cache validity
Cached rows carry no record of which server generation wrote them. The server's
version goes on the cache alongside the existing `synced_at`, and a change
invalidates by clearing `synced_at` — the same move
[MIGRATION_018 and migration 025](../../src-tauri/src/storage/schema.rs) already
make, and for the same reason: the association was never stored, so existing rows
cannot be repaired locally and must be re-fetched.
## Out of scope
- **Multi-server support.** One server per install, as today.
- **Emby, or any non-Jellyfin server.** The capability model would carry it; the
DTO layer would not, and nothing here should be read as a step toward it.
- **The Windows/Linux/Android split.** Capabilities describe the *server*, never
the client platform. Platform differences stay in `device_profile.rs`.
- **Raising coverage of the whole online adapter.** The mock-server harness makes
that possible and the version-sensitive paths get tests; a general backfill is
separate work.
## Acceptance criteria
- [ ] The app connects, browses, plays and reports against both target server
generations, from one build, with no user-visible configuration.
- [ ] The repository suite runs against both generations' fixtures and passes.
- [ ] No `format!` endpoint literal remains in `online.rs`.
- [ ] No version comparison exists outside the single version → capabilities
function.
- [ ] A server below the supported floor produces one legible message; a server
newer than the release still works.
- [ ] `bun run check` and `bun run test` pass.
- [ ] `cargo fmt` clean, `cargo clippy --all-targets -D warnings` clean,
`bun run test:rust` passes.
- [ ] `bun run check:boundary` passes — and note it will *not* catch the
`imageCache.ts` route, which is why DR-285 is a ticket rather than a
tripwire.
- [ ] New requirement-implementing code carries `// TRACES:` comments;
`bun run traces:validate` passes and coverage does not fall.
- [ ] `bindings.ts` regenerated if Rust types changed.
## Testing
The harness is the feature's precondition, not its afterthought.
**Rust.** Add a mock HTTP server (`wiremock` — a project dependency, so no CI
image change; see the toolchain rule in CLAUDE.md) plus one recorded fixture set
per server generation. The repository suite becomes parameterised over
generations. What must be covered: route selection per capability; the
device-profile overrides firing on the generation they were written for and *not*
on the other; cache invalidation across a version change; an unknown version
resolving forward rather than failing.
**Frontend.** `imageCache.ts` loses its URL construction, so its tests assert it
calls the command rather than that it builds a string.
`repository/online_integration_test.rs` **has been deleted** (2026-09-08). It was
never declared in `repository/mod.rs` and referenced a `crate::api::jellyfin`
module that does not exist, so it had never compiled. It is worth knowing why it
was not merely dead but harmful: its mock *reimplemented* the URL builders and
then asserted against itself, and `online.rs` carries a comment recording that
this exact arrangement once shipped a `/Videos/{id}/download` endpoint that 404s
on real servers while the mock happily tested the correct one — silently breaking
every movie and TV download. Its own `test_image_url_basic` asserted `api_key=`
appears in image URLs while the mock beside it documented the opposite.
That is the anti-pattern DR-281 exists to replace: assert against a *response*
from a mock **server**, never against a mock that re-derives the thing under
test.
## TRACES
| Piece | Suggested tag |
|---|---|
| `ServerCapabilities` + version resolution | `UR-085 \| IR-035, DR-280 \| UT-xxx` |
| `repository/endpoints.rs` | `UR-085 \| DR-279` |
| Route selection for user-scoped endpoints | `UR-085 \| JA-037, DR-282` |
| Capability-gated profile overrides | `UR-085 \| DR-283` |
| Cache generation stamp + invalidation | `UR-085 \| DR-284` |
| Image URL command | `UR-012, UR-085 \| DR-285` |
| Unsupported-server state | `UR-085 \| DR-286` |
## Notes for the implementer
- **The concrete API delta is not in this spec, deliberately.** No route, field
or behaviour difference between the two generations is asserted here, because
none has been verified against an upstream changelog. The first ticket exists
to establish it. Do not let a plausible-sounding difference enter the code
without a citation — a wrong capability flag is worse than none, since it fires
silently on the generation it was not tested against.
- The route table and the capability struct are independently useful and
independently reviewable. If the feature is cut, cut from the end, not the
start.
- A parallel Claude session may be active in this repo — `git diff` before
"repairing" unexpected changes.