feat(player): the controller talks to one contract

DR-245. PlayerController now holds a MediaPlayer instead of a PlayerBackend,
and every engine reaches it through that contract.

Deliberately a seam swap, not four rewrites: the existing backends are carried
across by LegacyPlayer, so MPV keeps its EQ and normalisation, ExoPlayer keeps
its media session, and nothing loses a feature to the migration. MpvPlayer
stays available for conformance until it grows the audio-settings half.

The substantive change is at the load site. Where the controller used to call
load() and then play(), it now issues one open() carrying the item and where
to begin — so the window a start position could be lost in is gone from the
controller as well as from the engines.

`state()` maps the engine's Phase back onto PlayerState using the queue, which
is what knows the item. External behaviour is unchanged.

Supporting pieces:

  - The contract gains set_audio_settings/audio_settings as *provided*
    methods. Engines that cannot honour them say so through Capabilities and
    inherit a no-op, rather than every implementation carrying an Ok(()) it
    does not mean.
  - PlayerBackend is implemented for Box<dyn PlayerBackend>, without which the
    boxed engine built at the composition root cannot be handed to anything
    generic over the trait.
  - StreamSelection::for_queued_item rebuilds a selection for an item already
    in the queue, without re-negotiating. The transport falls back rather than
    being sniffed out of the URL — that substring check is what DR-230 removed
    — and needs_transcoding is an exact stand-in because every transcode this
    app requests is HLS (DR-140).
  - default-run = "jellytau". The conformance binary made a bare `cargo run`
    ambiguous, which broke `tauri dev` outright. Caught by running the app
    rather than by any suite, which is the argument for doing both.

789 tests, clippy -D warnings clean with and without the feature.

src-tauri/src/player/backend.rs

@@ -249,6 +249,56 @@ impl PlayerBackend for NullBackend {
 }
 
 // TRACES: UR-003, UR-004 | DR-004 | UT-026, UT-027, UT-028, UT-029, UT-030, UT-031, UT-032, UT-033
+/// Forward the trait through a box.
+///
+/// `Box<dyn PlayerBackend>` does not implement `PlayerBackend` on its own, so
+/// without this the boxed engine built at the composition root cannot be handed
+/// to anything generic over the trait — `LegacyPlayer` in particular.
+impl PlayerBackend for Box<dyn PlayerBackend> {
+    fn load(&mut self, media: &MediaItem) -> Result<(), PlayerError> {
+        (**self).load(media)
+    }
+    fn play(&mut self) -> Result<(), PlayerError> {
+        (**self).play()
+    }
+    fn pause(&mut self) -> Result<(), PlayerError> {
+        (**self).pause()
+    }
+    fn stop(&mut self) -> Result<(), PlayerError> {
+        (**self).stop()
+    }
+    fn seek(&mut self, position: f64) -> Result<(), PlayerError> {
+        (**self).seek(position)
+    }
+    fn set_volume(&mut self, volume: f32) -> Result<(), PlayerError> {
+        (**self).set_volume(volume)
+    }
+    fn position(&self) -> f64 {
+        (**self).position()
+    }
+    fn duration(&self) -> Option<f64> {
+        (**self).duration()
+    }
+    fn state(&self) -> PlayerState {
+        (**self).state()
+    }
+    fn volume(&self) -> f32 {
+        (**self).volume()
+    }
+    fn set_audio_settings(&mut self, settings: &AudioSettings) -> Result<(), PlayerError> {
+        (**self).set_audio_settings(settings)
+    }
+    fn audio_settings(&self) -> AudioSettings {
+        (**self).audio_settings()
+    }
+    fn set_audio_track(&mut self, stream_index: i32) -> Result<(), PlayerError> {
+        (**self).set_audio_track(stream_index)
+    }
+    fn set_subtitle_track(&mut self, stream_index: Option<i32>) -> Result<(), PlayerError> {
+        (**self).set_subtitle_track(stream_index)
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src-tauri/src/player/legacy_player.rs

@@ -18,8 +18,6 @@
 //!
 //! TRACES: UR-081 | DR-245
 
-#![allow(dead_code)] // Consumed when PlayerController is ported (DR-245).
-
 use std::time::Duration;
 
 use super::backend::{PlayerBackend, PlayerError};
@@ -41,10 +39,6 @@ impl<B: PlayerBackend> LegacyPlayer<B> {
             has_item: false,
         }
     }
-
-    pub fn inner_mut(&mut self) -> &mut B {
-        &mut self.inner
-    }
 }
 
 impl<B: PlayerBackend + Send> MediaPlayer for LegacyPlayer<B> {
@@ -135,6 +129,17 @@ impl<B: PlayerBackend + Send> MediaPlayer for LegacyPlayer<B> {
         }
     }
 
+    fn set_audio_settings(
+        &mut self,
+        settings: &crate::settings::AudioSettings,
+    ) -> Result<(), PlayerError> {
+        self.inner.set_audio_settings(settings)
+    }
+
+    fn audio_settings(&self) -> crate::settings::AudioSettings {
+        self.inner.audio_settings()
+    }
+
     fn capabilities(&self) -> Capabilities {
         Capabilities {
             video: false,

src-tauri/src/player/media.rs

@@ -171,6 +171,19 @@ pub enum MediaSource {
     DirectUrl { url: String },
 }
 
+impl MediaItem {
+    /// The URL or path an engine should open.
+    ///
+    /// TRACES: UR-081 | DR-245
+    pub fn playable_url(&self) -> String {
+        match &self.source {
+            MediaSource::Remote { stream_url, .. } => stream_url.clone(),
+            MediaSource::Local { file_path, .. } => file_path.to_string_lossy().into_owned(),
+            MediaSource::DirectUrl { url } => url.clone(),
+        }
+    }
+}
+
 impl MediaItem {
     /// Get the Jellyfin item ID if available
     pub fn jellyfin_id(&self) -> Option<&str> {

src-tauri/src/player/media_player.rs

@@ -32,6 +32,7 @@ use std::time::Duration;
 use super::backend::PlayerError;
 use super::media::MediaItem;
 use crate::repository::stream_selection::StreamSelection;
+use crate::settings::AudioSettings;
 
 /// What an engine is doing right now.
 ///
@@ -203,4 +204,17 @@ pub trait MediaPlayer: Send {
     fn snapshot(&self) -> PlaybackSnapshot;
 
     fn capabilities(&self) -> Capabilities;
+
+    /// Apply EQ, normalisation and gapless settings.
+    ///
+    /// Provided rather than required: engines that cannot honour them say so
+    /// through [`Capabilities::audio_settings`] and inherit this no-op, instead
+    /// of every implementation carrying an `Ok(())` it does not mean.
+    fn set_audio_settings(&mut self, _settings: &AudioSettings) -> Result<(), PlayerError> {
+        Ok(())
+    }
+
+    fn audio_settings(&self) -> AudioSettings {
+        AudioSettings::default()
+    }
 }

src-tauri/src/player/mod.rs

@@ -12,7 +12,6 @@ pub mod events;
 pub mod fake_player;
 #[cfg(test)]
 mod fake_player_conformance;
-#[cfg(any(test, feature = "conformance"))]
 pub mod legacy_player;
 pub mod media;
 pub mod media_player;
@@ -60,10 +59,13 @@ pub mod video_surface;
 pub mod webview_audio_backend;
 
 // Re-export commonly used types
+use crate::repository::stream_selection::StreamSelection;
 pub use autoplay::{AutoplayDecision, AutoplaySettings};
 pub use backend::{NullBackend, PlayerBackend, PlayerError};
 pub use events::{PlayerEventEmitter, PlayerStatusEvent, TauriEventEmitter};
+pub use legacy_player::LegacyPlayer;
 pub use media::{MediaItem, MediaSource, MediaType, QueueContext, SubtitleTrack};
+pub use media_player::{MediaPlayer, OpenRequest, Phase};
 pub use queue::{QueueManager, RepeatMode};
 pub use seek::{determine_video_seek_strategy, VideoSeekStrategy};
 pub use session::{MediaSessionManager, MediaSessionType};
@@ -238,7 +240,9 @@ use crate::utils::conversions::seconds_to_ticks;
 
 /// Central player controller that coordinates playback
 pub struct PlayerController {
-    backend: Arc<Mutex<Box<dyn PlayerBackend>>>,
+    /// The engine. One contract, so the controller stops branching on which
+    /// platform it is running on — see docs/specs/media-player-controller.md.
+    backend: Arc<Mutex<Box<dyn MediaPlayer>>>,
     queue: Arc<Mutex<QueueManager>>,
     jellyfin_client: Arc<Mutex<Option<JellyfinClient>>>,
     muted: bool,
@@ -337,7 +341,7 @@ pub struct PlayerController {
 
 impl PlayerController {
     pub fn new(
-        backend: Box<dyn PlayerBackend>,
+        backend: Box<dyn MediaPlayer>,
         playback_reporter: Arc<TokioMutex<Option<PlaybackReporter>>>,
         position_throttler: Arc<EventThrottler>,
     ) -> Self {
@@ -568,8 +572,16 @@ impl PlayerController {
         *self.html5_playing.lock_safe() = None;
 
         let mut backend = self.backend.lock_safe();
-        backend.load(item)?;
-        backend.play()?;
+        // One operation: the engine is handed the item and where to begin, so
+        // there is no window between them for a position to be lost in.
+        backend.open(OpenRequest::new(
+            item.clone(),
+            StreamSelection::for_queued_item(
+                item.playable_url(),
+                item.transport,
+                item.needs_transcoding,
+            ),
+        ))?;
         drop(backend);
 
         // A different item is loading; the last one's reported position must not
@@ -743,7 +755,7 @@ impl PlayerController {
             return Ok(());
         }
         let mut backend = self.backend.lock_safe();
-        if backend.state().is_playing() {
+        if backend.snapshot().phase.is_active() {
             backend.pause()
         } else {
             backend.play()
@@ -768,7 +780,7 @@ impl PlayerController {
         let position = self.absolute_position();
 
         let mut backend = self.backend.lock_safe();
-        backend.stop()?;
+        backend.close()?;
         drop(backend);
         self.clear_reported_time();
 
@@ -849,7 +861,7 @@ impl PlayerController {
         // If we're more than 3 seconds in, restart current track
         {
             let backend = self.backend.lock_safe();
-            if backend.position() > 3.0 {
+            if backend.snapshot().position.as_secs_f64() > 3.0 {
                 debug!("[PlayerController] previous: restarting current track (position > 3s)");
                 drop(backend);
                 return self.seek(0.0);
@@ -881,7 +893,7 @@ impl PlayerController {
     /// timeline and is what every caller outside the player itself means.
     pub fn seek(&self, position: f64) -> Result<(), PlayerError> {
         let mut backend = self.backend.lock_safe();
-        backend.seek(position)
+        backend.seek(Duration::from_secs_f64(position.max(0.0)))
     }
 
     /// Seek to an **absolute** position on the item's own timeline.
@@ -932,23 +944,41 @@ impl PlayerController {
     /// Set the active audio track by stream index
     pub fn set_audio_track(&self, stream_index: i32) -> Result<(), PlayerError> {
         let mut backend = self.backend.lock_safe();
-        backend.set_audio_track(stream_index)
+        backend.select_audio_track(Some(stream_index))
     }
 
     /// Set the active subtitle track by stream index (None to disable subtitles)
     pub fn set_subtitle_track(&self, stream_index: Option<i32>) -> Result<(), PlayerError> {
         let mut backend = self.backend.lock_safe();
-        backend.set_subtitle_track(stream_index)
+        backend.select_subtitle_track(stream_index)
     }
 
     /// Get current state
     pub fn state(&self) -> PlayerState {
-        self.backend.lock_safe().state()
+        let phase = self.backend.lock_safe().snapshot().phase;
+        let media = self.queue.lock_safe().current().cloned();
+        match (phase, media) {
+            (Phase::Playing, Some(media)) => PlayerState::Playing {
+                media,
+                position: self.position(),
+                duration: self.duration().unwrap_or(0.0),
+            },
+            (Phase::Paused, Some(media)) => PlayerState::Paused {
+                media,
+                position: self.position(),
+                duration: self.duration().unwrap_or(0.0),
+            },
+            (Phase::Opening, Some(media)) => PlayerState::Loading { media },
+            (Phase::Failed(error), media) => PlayerState::Error { media, error },
+            // Ready without an item, or anything terminal, reads as idle: the
+            // queue is what says whether there is something to resume.
+            _ => PlayerState::Idle,
+        }
     }
 
     /// Get current position
     pub fn position(&self) -> f64 {
-        self.backend.lock_safe().position()
+        self.backend.lock_safe().snapshot().position.as_secs_f64()
     }
 
     /// The position on the **item's own timeline**, whatever is rendering it.
@@ -974,7 +1004,7 @@ impl PlayerController {
     ///
     /// TRACES: UR-040, UR-005, UR-025 | DR-178 | UT-176, UT-177
     pub fn absolute_position(&self) -> f64 {
-        let native = self.backend.lock_safe().position().max(0.0);
+        let native = self.backend.lock_safe().snapshot().position.as_secs_f64();
         let reported = self.reported_time.lock_safe().last_position();
         let base = if self.is_background_audio_active() {
             *self.background_audio_base.lock_safe()
@@ -1040,7 +1070,9 @@ impl PlayerController {
     pub fn duration(&self) -> Option<f64> {
         self.backend
             .lock_safe()
-            .duration()
+            .snapshot()
+            .duration
+            .map(|d| d.as_secs_f64())
             .or_else(|| self.observed_duration())
     }
 
@@ -1096,7 +1128,7 @@ impl PlayerController {
 
     /// Get current volume (0.0 - 1.0)
     pub fn volume(&self) -> f32 {
-        self.backend.lock_safe().volume()
+        self.backend.lock_safe().snapshot().volume
     }
 
     /// Check if muted
@@ -1197,7 +1229,7 @@ impl PlayerController {
                         drop(timer);
 
                         // Stop the backend
-                        if let Err(e) = backend.lock_safe().stop() {
+                        if let Err(e) = backend.lock_safe().close() {
                             error!("[SleepTimer] Failed to stop playback: {}", e);
                         }
                         continue;
@@ -2212,7 +2244,7 @@ impl Default for PlayerController {
         let playback_reporter = Arc::new(TokioMutex::new(None));
         let position_throttler = Arc::new(EventThrottler::new());
         Self::new(
-            Box::new(NullBackend::new()),
+            Box::new(LegacyPlayer::new(NullBackend::new())),
             playback_reporter,
             position_throttler,
         )