Requirements Specification

This document captures JellyTau's user requirements, software requirements, traceability matrix, test traceability, and known technical debt.

For a narrative overview of the system design, see docs/architecture/. For development workflows, see the README and scripts/README.md.

1. User Requirements

2. Software Requirements

2.1 Integration Requirements

External system integrations and platform-specific implementations.

Where a UR is met by a different mechanism than its IR anticipated. Several integration requirements were written when libmpv was expected to be the single playback backend. It is not: MpvBackend is the audio-only backend, Linux plays video through a WebKitGTK HTML5 <video> element (HLS/h264), and Android plays through ExoPlayer. So:

• UR-020 / UR-021 (subtitle and audio track selection) are Done, but not by MPV — MpvBackend overrides neither PlayerBackend::set_subtitle_track nor set_audio_track, leaving the trait's not_implemented() default. IR-018 and IR-019 have been re-scoped to the backends that actually deliver them (ExoPlayer sideloaded SubtitleConfigurations and native track switching; HTML5 <track> children and stream re-open at the chosen AudioStreamIndex) and marked Done on that basis. IT-008 / IT-009 were re-worded to match.
• UR-006 (lockscreen / BLE headset control) is Done on Android only, via MediaSessionCompat (IR-006) and ExoPlayer/AudioManager focus (IR-008). IR-005 (MPRIS) remains Planned because it genuinely does not exist — there is no MPRIS/D-Bus code or dependency in the project, and player::update_lockscreen_metadata is a no-op off Android. UR-006's status was corrected rather than IR-005's.

2.2 Jellyfin API Requirements

API endpoints and data contracts required for Jellyfin integration.

2.3 Development Requirements

Internal architecture, components, and application logic.

3. Traceability Matrix

User Requirements to Software Requirements

4. Test Traceability

Unit Tests to Software Requirements

Integration Tests

5. Technical Debt

Open items carried over from the v0.6.0 codebase audit

The 2026-08-16 audit (v0.6.0, commit be907b49) was a point-in-time snapshot with no status markers, and by v0.8.2 most of it had been either fixed or overtaken. It was retired rather than left to rot into a document that half-describes the code: what survived it is the table below, which is now the record. Each row is self-contained — the audit is not needed to act on it.

What was dropped as demonstrably closed, so it is not re-raised: the CSP and asset-protocol scope findings (now DR-198), cloud backup and credential restore, the WebView mixed-content override (DR-199), POST_NOTIFICATIONS and the media-session exemption (DR-200), the jvmTarget 1.8 pin (now 17), the half-declared Android TV leanback category (removed), the untraced-but-Done requirements and the contradictory UR/IR statuses (re-scoped in §2.1), the 50% traceability gate (ratcheted, and gated on a live denominator by DR-093), the flaky offlineCatalog test, the clippy warning backlog (cleared, and cargo fmt --check plus clippy now run in CI), and the "820 production unwrap()s" figure — a measurement error that counted test modules, corrected in the audit itself to ~19 and standing at 27 today, none of them in a command handler. The three Runtime::new().unwrap() sites that genuinely matter survive as row 5.

Ordered by what would hurt most if left.

Closed 2026-08-17: the R8-minified release APK was validated on device. That was the last item gating confidence in the v0.8.0 release itself; R8 stripping JNI-loaded classes has broken release builds here before, and v0.8.0 added a new Kotlin path (onFastForward/onRewind) that the unminified debug pass did not cover.

Linux Keyring Integration Workaround

Issue: The keyring-rs crate (v3.x) has issues with retrieving credentials from the Linux Secret Service API, despite successfully saving them.

Symptoms:

• Credentials are saved to the system keyring successfully (verified with secret-tool search)
• Retrieval via the keyring-rs library fails with NoEntry error
• Session restoration fails on app restart even though credentials exist

Root Cause: The keyring-rs library's Linux backend doesn't correctly retrieve entries from the Secret Service that it previously stored. This appears to be a bug in how the library interfaces with the Secret Service D-Bus API.

Current Workaround: We bypass the keyring-rs library on Linux and use direct system calls to secret-tool:

• Save: secret-tool store --label <label> service <service> username <username>
• Retrieve: secret-tool lookup service <service> username <username>
• Delete: secret-tool clear service <service> username <username>

Implementation: See src-tauri/src/credentials.rs for the Linux-specific secret-tool save/get/delete paths.

Future Fix:

• Monitor keyring-rs for bug fixes in future versions
• Consider alternative secure storage libraries
• Test if newer versions of keyring-rs (v4.x+) resolve the issue
• Once fixed, remove the Linux-specific workaround and use the cross-platform keyring-rs API

Impact:

• Low - The workaround is functionally equivalent to proper keyring integration
• Credentials are stored securely in the system keyring
• Session restoration works correctly
• Only affects Linux; macOS and Windows use the standard keyring-rs implementation

Dependencies:

• Requires secret-tool to be installed on Linux systems (part of libsecret-tools package)
• Already available on most Linux distributions by default

Platform Playback Backend Parity (Linux vs Android)

Issue: The Linux (MPV) and Android (ExoPlayer) playback backends have diverged in feature implementation and architecture patterns.

Symptoms (as first recorded; the audio half is now closed — see Status):

• Audio settings (gapless playback, volume normalization, equalizer) worked on Linux but not on Android
• Position update frequency differs between platforms (Linux: 250ms polling, Android: on-demand callbacks)
• Thread safety models differ (Linux: Arc<Mutex<>>, Android: global OnceLock statics)

Root Cause: The PlayerBackend trait defines optional audio settings methods with default empty implementations. MpvBackend overrode these with MPV property commands; ExoPlayerBackend took the silent defaults, so the Settings › Audio panel rendered controls that did nothing on Android. ExoPlayerBackend now overrides them too, but the trait default is still a silent Ok(()) — a backend that omits the method still reports success rather than failing loudly.

Affected Files:

• src-tauri/src/player/backend.rs - Trait; defaults still return Ok(()) silently
• src-tauri/src/player/mpv_backend.rs - Full audio settings support
• src-tauri/src/player/android/mod.rs - Audio settings carried to Kotlin as JSON over JNI

Feature Parity Matrix:

Status (see docs/architecture/05-platform-backends.md, "Audio settings on ExoPlayer"):

1. ✅ set_audio_settings() implemented in ExoPlayerBackend (JSON over JNI)
2. ✅ Gapless via ExoPlayer's pauseAtEndOfMediaItems
3. ✅ Volume normalization via LoudnessEnhancer
4. ✅ Equalizer via android.media.audiofx.Equalizer, canonical 10 bands resampled onto the device's band centres
5. ⬜ Not yet verified on a physical device — the EQ/normalization effects depend on device-specific AudioEffect availability and band layouts
6. ⬜ Flip the trait's set_audio_settings default from Ok(()) to Err(not_implemented()) so a backend that omits it fails loudly instead of silently reporting success. Deferred until (5) confirms the Android path works
7. ⬜ Standardize position update frequency across platforms

Crossfade is deliberately absent: it is unimplemented on every platform and architecturally blocked on MPV, so building it on Android alone would invert the parity gap. (The previously suggested ConcatenatingMediaSource is also deprecated in current Media3.)

Impact:

• Medium - Android users lack audio enhancement features advertised in requirements
• User experience differs between platforms
• UR-032 (Gapless), UR-033 (Normalization) and UR-027 (Equalizer) are now implemented on Android as well as Linux, pending on-device verification
• UR-031 (Crossfade) works nowhere — see DR-034

Traces To: IR-004, UR-031, UR-032, UR-033, DR-034, DR-035, DR-036

Frontend Playback Code Duplication

Issue: Playback control handlers and state derivations are duplicated between AudioPlayer.svelte and MiniPlayer.svelte.

Symptoms:

• Identical try-catch wrapped handler functions in both components (~44 lines duplicated)
• Same $derived state merging logic for local/remote playback in both components
• Position conversion (ticks ↔ seconds) scattered across multiple files

Affected Files:

• src/lib/components/player/AudioPlayer.svelte - Duplicate handlers
• src/lib/components/player/MiniPlayer.svelte - Duplicate handlers
• src/lib/utils/playbackUnits.ts - Position conversion (the shared helper the "Future Fix" below called for; playbackControl.ts, previously listed here, has since been removed)
• src/lib/stores/playbackMode.ts - Position conversion
• src/lib/services/playbackReporting.ts - Position conversion

Duplicated Code:

// These handlers are identical in both AudioPlayer and MiniPlayer:
handlePlayPause(), handleNext(), handlePrevious(),
handleToggleShuffle(), handleCycleRepeat(), handleVolumeChange()

// These derived states use identical logic:
displayMedia, displayIsPlaying, displayPosition, displayDuration

Future Fix:

1. Create src/lib/utils/playbackUnits.ts:

   export const TICKS_PER_SECOND = 10_000_000;
   export const secondsToTicks = (s: number) => Math.floor(s * TICKS_PER_SECOND);
   export const ticksToSeconds = (t: number) => t / TICKS_PER_SECOND;
   

2. Create src/lib/composables/useMergedPlaybackState.svelte.ts:

   • Export displayMedia, displayIsPlaying, displayPosition, displayDuration
   • Single source of truth for merged local/remote state

3. Simplify handler wrappers using a utility:

   export const withErrorHandler = (fn: () => Promise<void>, context: string) =>
     async () => { try { await fn(); } catch (e) { console.error(`${context}:`, e); } };
   

Impact:

• Low - Code works correctly but violates DRY principle
• Maintenance burden when logic needs to change
• Risk of handlers diverging over time

Traces To: DR-009