fix: save and restore playback state across session reconnects

When SpircTask exits due to session loss, it now saves its
ConnectState, SpircPlayStatus, and play_request_id into a
SavedPlaybackState. main.rs captures this and passes it to
Spirc::with_saved_state() when creating the replacement Spirc.

The restored SpircTask starts with the saved state. On the first
connection_id_update, it updates the playback position to account for
elapsed time and re-registers with Spotify showing the correct track
and position. The Player is never interrupted.

After fix — 6 days of logs (Mar 14-20) showing 5 TCP session losses
all recovered with playback state preserved:

  Mar 18 11:49 — "Connection to server closed."
  Mar 18 11:52 — "session lost, saving playback state for recovery:
                   Playing { nominal_start_time: 1773834169899, ... }"
  Mar 18 11:52 — "Spirc shut down with saved playback state, reconnecting"
  Mar 18 11:52 — "Spirc[1] restoring saved playback state"
  Mar 18 11:52 — "re-registering with active playback state:
                   Playing { nominal_start_time: 1773834169899, ... }"
  [3 second recovery, playback never stopped]

  Mar 19 12:21-12:37 — Two session losses during active playback,
  both recovered in ~2 seconds with Playing state preserved.

Summary over 6 days post-fix (Mar 14-20):
  - 0 "Spirc shut down unexpectedly" (vs ~2-3/day before fix)
  - 0 process restarts needed
  - 5 session TCP losses, all recovered with state preserved
  - ~20 dealer reconnects, all handled in-place
  - Process running continuously (Spirc counter reached Spirc[4])

Co-authored-by: Copilot <[email protected]>

Author: antoinecellerier

connect/src/model.rs

@@ -1,5 +1,7 @@
 use crate::{
-    core::dealer::protocol::SkipTo, protocol::context_player_options::ContextPlayerOptionOverrides,
+    core::dealer::protocol::SkipTo,
+    protocol::context_player_options::ContextPlayerOptionOverrides,
+    state::ConnectState,
 };
 
 use std::ops::Deref;
@@ -165,3 +167,11 @@ pub(super) enum SpircPlayStatus {
         preloading_of_next_track_triggered: bool,
     },
 }
+
+/// Playback state saved across session reconnects so the new SpircTask
+/// can resume where the old one left off.
+pub struct SavedPlaybackState {
+    pub(super) connect_state: ConnectState,
+    pub(super) play_status: SpircPlayStatus,
+    pub(super) play_request_id: Option<u64>,
+}

connect/src/spirc.rs

@@ -11,7 +11,7 @@ use crate::{
         session::UserAttributes,
         spclient::TransferRequest,
     },
-    model::{LoadRequest, PlayingTrack, SpircPlayStatus},
+    model::{LoadRequest, PlayingTrack, SavedPlaybackState, SpircPlayStatus},
     playback::{
         mixer::Mixer,
         player::{Player, PlayerEvent, PlayerEventChannel, QueueTrack},
@@ -37,6 +37,7 @@ use librespot_protocol::context_page::ContextPage;
 use protobuf::MessageField;
 use std::{
     future::Future,
+    mem,
     sync::Arc,
     sync::atomic::{AtomicUsize, Ordering},
     time::{Duration, SystemTime, UNIX_EPOCH},
@@ -163,7 +164,23 @@ impl Spirc {
         credentials: Credentials,
         player: Arc<Player>,
         mixer: Arc<dyn Mixer>,
-    ) -> Result<(Spirc, impl Future<Output = ()>), Error> {
+    ) -> Result<(Spirc, impl Future<Output = Option<SavedPlaybackState>>), Error> {
+        Self::with_saved_state(config, session, credentials, player, mixer, None).await
+    }
+
+    /// Like [`Spirc::new`], but restores playback state from a previous session.
+    ///
+    /// When `saved_state` is provided, the new SpircTask picks up where the
+    /// old one left off — same track, position, and connect state — so the
+    /// Player can continue without interruption after a session reconnect.
+    pub async fn with_saved_state(
+        config: ConnectConfig,
+        session: Session,
+        credentials: Credentials,
+        player: Arc<Player>,
+        mixer: Arc<dyn Mixer>,
+        saved_state: Option<SavedPlaybackState>,
+    ) -> Result<(Spirc, impl Future<Output = Option<SavedPlaybackState>>), Error> {
         fn extract_connection_id(msg: Message) -> Result<String, Error> {
             let connection_id = msg
                 .headers
@@ -176,7 +193,17 @@ impl Spirc {
         debug!("new Spirc[{spirc_id}]");
 
         let emit_set_queue_events = config.emit_set_queue_events;
-        let connect_state = ConnectState::new(config, &session);
+
+        let (connect_state, play_status, play_request_id) = match saved_state {
+            Some(saved) => {
+                info!("Spirc[{spirc_id}] restoring saved playback state");
+                let mut cs = saved.connect_state;
+                // Update to the new session's ID so Spotify sees us as the same device.
+                cs.set_session_id(session.session_id());
+                (cs, saved.play_status, saved.play_request_id)
+            }
+            None => (ConnectState::new(config, &session), SpircPlayStatus::Stopped, None),
+        };
 
         let connection_id_update = session
             .dealer()
@@ -235,8 +262,8 @@ impl Spirc {
             connect_state,
             connect_established: false,
 
-            play_request_id: None,
-            play_status: SpircPlayStatus::Stopped,
+            play_request_id,
+            play_status,
 
             connection_id_update,
             connect_state_update,
@@ -438,7 +465,7 @@ impl Spirc {
 }
 
 impl SpircTask {
-    async fn run(mut self) {
+    async fn run(mut self) -> Option<SavedPlaybackState> {
         // simplify unwrapping of received item or parsed result
         macro_rules! unwrap {
             ( $next:expr, |$some:ident| $use_some:expr ) => {
@@ -463,7 +490,7 @@ impl SpircTask {
 
         if let Err(why) = self.session.dealer().start().await {
             error!("starting dealer failed: {why}");
-            return;
+            return None;
         }
 
         while !self.session.is_invalid() && !self.shutdown {
@@ -603,8 +630,12 @@ impl SpircTask {
             // Session TCP connection died — skip server communication that
             // would fail anyway. The Player continues playing from its
             // buffer independently; main.rs will create a new session.
-            warn!("session lost, skipping server cleanup");
-            return;
+            warn!("session lost, saving playback state for recovery: {:?}", self.play_status);
+            return Some(SavedPlaybackState {
+                connect_state: mem::take(&mut self.connect_state),
+                play_status: mem::replace(&mut self.play_status, SpircPlayStatus::Stopped),
+                play_request_id: self.play_request_id.take(),
+            });
         }
 
         if !self.shutdown && self.connect_state.is_active() {
@@ -620,6 +651,7 @@ impl SpircTask {
         };
 
         self.session.dealer().close().await;
+        None
     }
 
     fn handle_next_context(&mut self, next_context: Result<Context, Error>) -> bool {
@@ -907,6 +939,19 @@ impl SpircTask {
         trace!("Received connection ID update: {connection_id:?}");
         self.session.set_connection_id(&connection_id);
 
+        // If we have active playback (e.g. restored from saved state),
+        // update the position before registering so Spotify sees the
+        // correct track position.
+        if !matches!(self.play_status, SpircPlayStatus::Stopped) {
+            info!("re-registering with active playback state: {:?}", self.play_status);
+            self.connect_state.set_status(&self.play_status);
+            if self.connect_state.is_playing() {
+                self.connect_state
+                    .update_position_in_relation(self.now_ms());
+            }
+            self.connect_state.set_now(self.now_ms() as u64);
+        }
+
         let cluster = match self
             .connect_state
             .notify_new_device_appeared(&self.session)

examples/play_connect.rs

@@ -71,7 +71,7 @@ async fn main() -> Result<(), Error> {
     spirc.play()?;
 
     // starting the connect device and processing the previously "queued" calls
-    spirc_task.await;
+    let _ = spirc_task.await;
 
     Ok(())
 }

src/main.rs

@@ -1899,6 +1899,7 @@ async fn main() {
     let mut discovery = None;
     let mut connecting = false;
     let mut _event_handler: Option<EventHandler> = None;
+    let mut saved_playback_state = None;
 
     let mut session = Session::new(setup.session_config.clone(), setup.cache.clone());
 
@@ -2049,11 +2050,14 @@ async fn main() {
 
                 let connect_config = setup.connect_config.clone();
 
-                let (spirc_, spirc_task_) = match Spirc::new(connect_config,
-                                                                session.clone(),
-                                                                last_credentials.clone().unwrap_or_default(),
-                                                                player.clone(),
-                                                                mixer.clone()).await {
+                let (spirc_, spirc_task_) = match Spirc::with_saved_state(
+                    connect_config,
+                    session.clone(),
+                    last_credentials.clone().unwrap_or_default(),
+                    player.clone(),
+                    mixer.clone(),
+                    saved_playback_state.take(),
+                ).await {
                     Ok((spirc_, spirc_task_)) => (spirc_, spirc_task_),
                     Err(e) => {
                         error!("could not initialize spirc: {e}");
@@ -2065,14 +2069,20 @@ async fn main() {
 
                 connecting = false;
             },
-            _ = async {
-                if let Some(task) = spirc_task.as_mut() {
-                    task.await;
+            saved = async {
+                match spirc_task.as_mut() {
+                    Some(task) => task.await,
+                    None => None,
                 }
             }, if spirc_task.is_some() && !connecting => {
                 spirc_task = None;
+                saved_playback_state = saved;
 
-                warn!("Spirc shut down unexpectedly");
+                if saved_playback_state.is_some() {
+                    info!("Spirc shut down with saved playback state, reconnecting");
+                } else {
+                    warn!("Spirc shut down unexpectedly");
+                }
 
                 let mut reconnect_exceeds_rate_limit = || {
                     auto_connect_times.retain(|&t| t.elapsed() < RECONNECT_RATE_LIMIT_WINDOW);
@@ -2112,7 +2122,7 @@ async fn main() {
         }
 
         if let Some(spirc_task) = spirc_task {
-            shutdown_tasks.spawn(spirc_task);
+            shutdown_tasks.spawn(async { spirc_task.await; });
         }
     }