dtourolleandClaude Opus 5
b1844f673e
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>
6.7 KiB
6.7 KiB
Specs index
Feature specs for JellyTau. Start a new one from SPEC-TEMPLATE.md and run it past SPEC-REVIEW-CHECKLIST.md before accepting it.
What lives here
Only work that has not shipped. Once a spec is fully implemented its design is folded into the architecture docs — which are the maintained description of the build — and the spec file is deleted. Git history keeps the original, including its rejected alternatives and acceptance criteria; the architecture docs keep the reasoning that a future change still needs.
So: a file in this directory is a promise, not a description. If you want to know how something works, read docs/architecture/. If you want to know what is planned, read here.
Status vocabulary
| Status | Meaning |
|---|---|
| Proposed | Written, not accepted. Nothing built. |
| Accepted | Agreed as the design; implementation not started or not finished. |
| Partially implemented | Some parts shipped; the spec names what is left. |
| Design authority | No code of its own — it records a decision later specs act on. |
Next free requirement ids (always re-check 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 | Catalog surface: MediaKind, from_jellyfin isolated, ticks → ms |
primaryImageTag → imageId (~30 sites); player/session/reporting tick math; stream.type |
| 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 | LICENSE |
The libmpv → libmpv2 crate swap |
| 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 | Stage 1: SearchScope owned by Rust (DR-063…067) |
Stage 2: result-side grouping (GROUP_ITEM_TYPES still in searchScope.ts) |
Not started
| Spec | Blocked on / note |
|---|---|
| desktop-native-video.md | mpv draws video on every desktop platform, then the webview <video> path and hls.js are deleted. Converts a measured 7% direct-play rate toward Android's 85%. Stacked on backend-owned stream selection. |
| backend-owned-stream-selection.md | Rust owns direct-play-vs-transcode, transport and quality; players consume one StreamSelection. Partly built — StreamSelection, Transport and the .m3u8 sniff removal have landed. |
| build-provenance.md | build.rs is still bare. ⚠️ suggested id DR-093 is taken. |
| player-facade-enforcement.md | ~60 commands.player* sites still outside the facade; no lint rule. ⚠️ suggested id DR-095 is taken. |
| windows-native-audio-backend.md | Blocked on the libmpv2 swap. ⚠️ suggested id IR-030 is taken. |
| linux-native-video-spike.md | Spike run 2026-08-21: compositing works on Linux, X11 and Wayland. G1-G6 green bar the Tauri default_vbox() half of G1. The adaptive-bitrate question it was waiting on is answered: the server publishes one EXT-X-STREAM-INF, so there is no ladder for mpv to lose (DR-229). StreamSelection (DR-225) is the contract to consume. |
Design authority
| Spec | Role |
|---|---|
| playback-backend-unification.md | Why video cannot unify onto one native engine and audio can. The audio half has since shipped on Android; Windows has not. |
| scoped-search-boundary.md | The boundary design the check:boundary rule came from. Stage 1 built. |
| scoped-search.md | Superseded in part — its "frontend only, no Rust changes" decision is the leak the boundary spec reversed. UX still current. |
Where the shipped specs went
Sixteen specs were folded into the architecture docs and deleted (2026-08-21). Where to look for each:
| Shipped work | Now documented in |
|---|---|
| Account menu & global chrome | 02-svelte-frontend.md — App Shell and Chrome |
| Library mosaic | 02-svelte-frontend.md — Library Mosaic |
| Series current-episode navigation | 02-svelte-frontend.md — Series and Episode Navigation |
| Downloads as an offline library | 02-svelte-frontend.md — Downloaded Browse |
| Favourites browsing | 01-rust-backend.md — Favorites System |
| Streaming bitrate cap | 01-rust-backend.md — Streaming quality ladder |
| Locally-indexed search | 03-data-flow.md — Search Flow; 01-rust-backend.md — Background workers |
| Offline downloaded-only filter | 06-downloads-and-offline.md — Offline Catalog Visibility |
| Audio equalizer · Android audio settings parity | 05-platform-backends.md — Audio settings on ExoPlayer |
| Android native video spike | 05-platform-backends.md — Native Video Compositing |
| Video background audio | 05-platform-backends.md — Background Audio Handoff |
| Traceability gate repair | traceability-ci.md |
| Boundary tripwire hardening | scripts/check-frontend-boundary.sh (its header is the spec) |
| Playback docs corrections · req-coverage script removal | Nothing to document — both were corrections that have been applied |