Skip to main content

radio_cli/
engine.rs

1pub(crate) mod artwork;
2mod persistence;
3mod playback;
4mod queue;
5mod recording;
6mod status;
7use playback::PlaybackController;
8use recording::RecordingController;
9pub use status::{PlaybackState, RecordingState};
10
11use crate::error::{DomainError, ErrorCode};
12use crate::{
13    config::Config,
14    directory::Directory,
15    model::{Filter, Station},
16    player::{Event, Player},
17    process::{Background, MediaLock},
18    recorder::{self, Recorder},
19    store::Store,
20};
21use anyhow::{Context, Result, bail};
22use std::{
23    collections::VecDeque,
24    sync::{Arc, atomic::AtomicBool},
25    time::{Duration, Instant},
26};
27
28#[derive(Debug, Clone, PartialEq)]
29pub struct Status {
30    pub episode: Option<crate::podcast::Episode>,
31    pub seekable: bool,
32    pub speed: f64,
33    pub station: Option<Station>,
34    pub title: String,
35    pub message: String,
36    pub playback_state: PlaybackState,
37    pub volume: u8,
38    pub muted: bool,
39    pub recording_state: RecordingState,
40    pub recording_ms: u64,
41    pub recording_path: String,
42    pub source_url: String,
43}
44
45impl Status {
46    pub(crate) fn control_eq(&self, other: &Self) -> bool {
47        self.episode
48            .as_ref()
49            .map(|e| (&e.id, e.completed, e.observed_duration_ms))
50            == other
51                .episode
52                .as_ref()
53                .map(|e| (&e.id, e.completed, e.observed_duration_ms))
54            && self.seekable == other.seekable
55            && self.speed == other.speed
56            && self.station == other.station
57            && self.title == other.title
58            && self.message == other.message
59            && self.playback_state == other.playback_state
60            && self.recording_state == other.recording_state
61            && self.volume == other.volume
62            && self.muted == other.muted
63            && self.recording_path == other.recording_path
64            && self.source_url == other.source_url
65    }
66    pub(crate) fn ui_eq(&self, other: &Self) -> bool {
67        self.control_eq(other)
68            && self.recording_ms / 1000 == other.recording_ms / 1000
69            && self.episode.as_ref().map(|e| e.position_ms / 1000)
70                == other.episode.as_ref().map(|e| e.position_ms / 1000)
71    }
72    pub fn playing(&self) -> bool {
73        matches!(
74            self.playback_state,
75            PlaybackState::Playing | PlaybackState::Paused
76        )
77    }
78    pub fn paused(&self) -> bool {
79        self.playback_state == PlaybackState::Paused
80    }
81    pub fn recording(&self) -> bool {
82        matches!(
83            self.recording_state,
84            RecordingState::Probing | RecordingState::Recording
85        )
86    }
87}
88
89pub struct Engine {
90    podcast_runtime: crate::podcast::Runtime,
91    session: Session,
92    playback: PlaybackController,
93    recording: RecordingController,
94}
95
96/// Shared services and published session state owned by the engine.
97pub(crate) struct Session {
98    persistence: Option<persistence::Writer>,
99    pub subtitles: crate::speech::Controller,
100    pub(crate) artwork: artwork::Controller,
101    pub config: Config,
102    pub store: Store,
103    pub directory: Directory,
104    pub status: Status,
105    // Session preferences survive playback resets and pending database writes.
106    pub podcast_speed: f64,
107    pub podcast_auto_next: bool,
108    pub stop: Arc<AtomicBool>,
109    pub(crate) _lock: Arc<MediaLock>,
110    pub(crate) background_media: bool,
111    pub(crate) diagnostics: Option<Background<(serde_json::Value, bool)>>,
112    pub(crate) library_task: Option<Background<String>>,
113    pub playback_failed: bool,
114}
115
116impl Session {
117    pub(crate) fn save_preference(&self, key: &str, value: &str) -> Result<()> {
118        if let Some(writer) = &self.persistence {
119            writer.preference(key, value)
120        } else {
121            if let Some(id) = key.strip_prefix("podcast_progress:") {
122                self.store
123                    .podcast_save_progress(id, &serde_json::from_str(value)?)
124            } else if let Some(id) = key.strip_prefix("podcast_played:") {
125                self.store.podcast_played(id)
126            } else {
127                self.store.set_meta(key, value)
128            }
129        }
130    }
131
132    fn remember_play(&self, uuid: &str) -> Result<()> {
133        if let Some(writer) = &self.persistence {
134            writer.played(uuid)?;
135            writer.preference("pref_last_media", "station")
136        } else {
137            self.store.played(uuid)?;
138            self.store.set_meta("pref_last_media", "station")?;
139            self.store.set_meta("pref_last_station", uuid)
140        }
141    }
142}
143
144impl Engine {
145    pub fn status(&self) -> &Status {
146        &self.session.status
147    }
148
149    pub fn config(&self) -> &Config {
150        &self.session.config
151    }
152
153    pub fn store(&self) -> &Store {
154        &self.session.store
155    }
156
157    pub fn subtitles(&self) -> &crate::speech::Snapshot {
158        &self.session.subtitles.snapshot
159    }
160
161    pub fn playback_failed(&self) -> bool {
162        self.session.playback_failed
163    }
164
165    /// Add, edit, remove, or change backup URLs without exposing session state.
166    pub fn change_station(
167        &mut self,
168        command: crate::service::StationCommand,
169    ) -> Result<crate::service::StationChange> {
170        crate::service::change_station(&mut self.session.store, command)
171    }
172
173    /// Atomically toggle a favorite and return its new state.
174    pub fn toggle_favorite(&mut self, uuid: &str) -> Result<bool> {
175        self.session.store.toggle_favorite(uuid)
176    }
177
178    pub(crate) fn save_preference(&self, key: &str, value: &str) -> Result<()> {
179        self.session.save_preference(key, value)
180    }
181
182    pub(crate) fn set_language(&mut self, language: String) {
183        crate::messages::init(Some(&language), None);
184        self.session.config.settings.language = Some(language.clone());
185        self.session.status.message = crate::t!("language_set", "language" => language);
186    }
187
188    pub(crate) fn request_artwork(&mut self, station: Option<String>) {
189        self.session.artwork.demand = station;
190    }
191
192    pub(crate) fn track_artwork(&self) -> &Option<artwork::TrackArtwork> {
193        &self.session.artwork.cover
194    }
195
196    pub(crate) fn start_diagnostics(&mut self) -> Result<()> {
197        if self.session.diagnostics.is_some() {
198            bail!(crate::t!("diagnostics_busy"));
199        }
200        let config = self.session.config.clone();
201        self.session.diagnostics = Some(Background::start("radio-doctor", move |cancel| {
202            crate::service::doctor_report(&config, &cancel)
203        })?);
204        Ok(())
205    }
206
207    pub(crate) fn poll_diagnostics(&mut self) -> Option<Result<(serde_json::Value, bool)>> {
208        let result = self.session.diagnostics.as_ref()?.poll()?;
209        self.session.diagnostics = None;
210        Some(result)
211    }
212
213    pub(crate) fn stop(&mut self) -> Result<()> {
214        self.stop_playback()?;
215        self.session.status.message = crate::t!("playback_stopped").into();
216        Ok(())
217    }
218
219    #[cfg(test)]
220    pub(crate) fn test_session(&mut self) -> &mut Session {
221        &mut self.session
222    }
223
224    pub fn bootstrap(&mut self) -> Result<usize> {
225        self.session.directory.bootstrap(&mut self.session.store)
226    }
227
228    /// Fetch and publish a full catalog. This call performs blocking I/O.
229    pub fn sync(&mut self, progress: impl FnMut(usize)) -> Result<usize> {
230        self.sync_with_policy(progress, false)
231    }
232
233    /// Sync with explicit permission to accept a catalog shrink over 25%.
234    /// This call performs blocking I/O.
235    pub fn sync_with_policy(
236        &mut self,
237        progress: impl FnMut(usize),
238        accept_shrink: bool,
239    ) -> Result<usize> {
240        self.session
241            .directory
242            .sync_with_policy(&mut self.session.store, progress, accept_shrink)
243    }
244
245    /// Fetch current directory metadata without persisting it. Performs I/O.
246    pub fn refresh_station(&mut self, uuid: &str) -> Result<Option<Station>> {
247        self.session.directory.refresh(uuid)
248    }
249
250    /// Report a confirmed play to the directory. This call performs blocking I/O.
251    pub fn report_click(&mut self, uuid: &str) -> Result<()> {
252        self.session.directory.click(uuid)
253    }
254    pub fn new(mut config: Config, stop: Arc<AtomicBool>) -> Result<Self> {
255        let lock = MediaLock::acquire(&config.runtime_dir)?;
256        let store = Store::open(&config.data_dir.join("radio.db"))?;
257        if let Some(volume) = store
258            .meta("pref_volume")?
259            .and_then(|v| v.parse::<u8>().ok())
260            .filter(|v| *v <= 100)
261        {
262            config.settings.volume = volume;
263        }
264        let podcast_speed = store
265            .meta("podcast_speed")?
266            .and_then(|v| v.parse().ok())
267            .unwrap_or(1.);
268        let podcast_auto_next = store.meta("podcast_auto_next")?.as_deref() == Some("on");
269        let recovery_warnings = recorder::recover(&store)?;
270        let directory = Directory::new(&config, stop.clone())?;
271        let status = Status {
272            episode: None,
273            seekable: false,
274            speed: 1.,
275            station: None,
276            title: String::new(),
277            message: if recovery_warnings.is_empty() {
278                crate::t!("status_ready").into()
279            } else {
280                recovery_warnings.join("\n")
281            },
282            playback_state: PlaybackState::Idle,
283            volume: config.settings.volume,
284            muted: false,
285            recording_state: RecordingState::Idle,
286            recording_ms: 0,
287            recording_path: String::new(),
288            source_url: String::new(),
289        };
290        Ok(Self {
291            podcast_runtime: Default::default(),
292            session: Session {
293                persistence: None,
294                subtitles: crate::speech::Controller::default(),
295                artwork: artwork::Controller::default(),
296                config,
297                store,
298                directory,
299                status,
300                podcast_speed,
301                podcast_auto_next,
302                stop,
303                _lock: Arc::new(lock),
304                background_media: false,
305                diagnostics: None,
306                library_task: None,
307                playback_failed: false,
308            },
309            playback: PlaybackController {
310                episode: None,
311                progress: Default::default(),
312                seek_request: None,
313                loaded: false,
314                resume_pending: false,
315                resume_blocked: false,
316                last_save: Instant::now(),
317                queue_mode: false,
318                auto_next: false,
319                queue_completions: Default::default(),
320                generation: 0,
321                refresh_task: None,
322                click_task: None,
323                player: None,
324                player_start: None,
325                retiring: vec![],
326                url: String::new(),
327                candidates: VecDeque::new(),
328                tried: vec![],
329                refreshed: false,
330                confirmed: false,
331                session_started: false,
332                source_kind: playback::SourceKind::Catalog,
333                local_recording_id: None,
334                reconnect_attempts: 0,
335                reconnect_due: None,
336                reconnect_window: VecDeque::new(),
337                started: Instant::now(),
338                random_filter: None,
339                random_tried: vec![],
340                failure: None,
341            },
342            recording: RecordingController {
343                recording_probe: None,
344                retiring_probes: vec![],
345                finalizing: None,
346                recorder: None,
347            },
348        })
349    }
350
351    pub fn play_episode(&mut self, id: &str, from_start: bool, speed: Option<f64>) -> Result<()> {
352        self.playback.play_episode(
353            &mut self.session,
354            &mut self.recording,
355            id,
356            from_start,
357            speed,
358        )
359    }
360    pub fn play_podcast_queue(&mut self, auto_next: bool) -> Result<()> {
361        let id = self
362            .store()
363            .podcast_queue()?
364            .first()
365            .map(|e| e.id.clone())
366            .context(crate::t!("podcast_empty_queue"))?;
367        self.play_episode(&id, false, None)?;
368        self.playback.queue_mode = true;
369        self.playback.auto_next = auto_next;
370        Ok(())
371    }
372    pub fn seek_episode(&mut self, position: u64) -> Result<()> {
373        self.playback.seek_episode(&mut self.session, position)
374    }
375    pub fn podcast_speed(&mut self, rate: f64) -> Result<()> {
376        crate::podcast::valid_speed(rate)?;
377        if let Some(p) = self.playback.player.as_mut()
378            && self.playback.episode.is_some()
379        {
380            p.request(serde_json::json!(["set_property", "speed", rate]))?;
381        }
382        self.session.podcast_speed = rate;
383        self.session.status.speed = rate;
384        self.session
385            .save_preference("podcast_speed", &rate.to_string())
386    }
387    pub fn podcast_auto_next(&mut self, on: bool) -> Result<()> {
388        self.session.podcast_auto_next = on;
389        self.playback.auto_next = on;
390        self.session
391            .save_preference("podcast_auto_next", if on { "on" } else { "off" })
392    }
393    pub fn play(&mut self, uuid: &str) -> Result<()> {
394        let result = self
395            .playback
396            .play(&mut self.session, &mut self.recording, uuid);
397        if let Err(error) = &result
398            && !self.playback_active()
399        {
400            self.session.status.playback_state = PlaybackState::Failed {
401                reason: format!("{error:#}"),
402            };
403        }
404        result
405    }
406
407    pub fn resume_last_station(&mut self) -> Result<()> {
408        self.playback
409            .resume_last_station(&mut self.session, &mut self.recording)
410    }
411
412    pub fn play_recording(&mut self, id: &str) -> Result<()> {
413        let result = self
414            .playback
415            .play_recording(&mut self.session, &mut self.recording, id);
416        if let Err(error) = &result
417            && !self.playback_active()
418        {
419            self.session.status.playback_state = PlaybackState::Failed {
420                reason: format!("{error:#}"),
421            };
422        }
423        result
424    }
425
426    pub fn random(&mut self, filter: Filter) -> Result<()> {
427        let result = self
428            .playback
429            .random(&mut self.session, &mut self.recording, filter);
430        if let Err(error) = &result
431            && !self.playback_active()
432        {
433            self.session.status.playback_state = PlaybackState::Failed {
434                reason: format!("{error:#}"),
435            };
436        }
437        result
438    }
439
440    pub fn podcast_action(&mut self, action: crate::podcast::Action) -> Result<()> {
441        use crate::podcast::{Action, DownloadAction, QueueAction};
442        match action {
443            Action::Play {
444                id,
445                from_start,
446                speed,
447            } => self.play_episode(&id, from_start, speed),
448            Action::Queue {
449                action: QueueAction::Play { auto_next },
450            } => self.play_podcast_queue(auto_next || self.session.podcast_auto_next),
451            Action::Seek { time } => self.seek_episode(crate::podcast::parse_time(&time)?),
452            Action::Speed { rate } => self.podcast_speed(rate),
453            Action::Mark { id, state } => {
454                let mut e = self.session.store.podcast_episode(&id)?;
455                if self.playback.episode.as_ref().is_some_and(|e| e.id == id) {
456                    self.stop_playback()?;
457                    self.playback.episode = None;
458                }
459                e.completed = state == "played";
460                e.position_ms = if e.completed {
461                    e.observed_duration_ms.unwrap_or(e.position_ms)
462                } else {
463                    0
464                };
465                self.playback.progress.insert(id.clone(), e.clone());
466                if self
467                    .session
468                    .status
469                    .episode
470                    .as_ref()
471                    .is_some_and(|p| p.id == id)
472                {
473                    self.session.status.episode = Some(e.clone());
474                }
475                self.session.save_preference(
476                    &format!("podcast_progress:{id}"),
477                    &serde_json::to_string(&e.progress())?,
478                )
479            }
480            Action::AutoNext { state } => self.podcast_auto_next(state == "on"),
481            Action::Downloads {
482                action: DownloadAction::Remove { ref id },
483            } if self.podcast_runtime.download_active(id) => {
484                Err(crate::podcast::error(crate::t!("podcast_download_busy")))
485            }
486            Action::Downloads {
487                action: DownloadAction::Remove { ref id },
488            } if self.playback_active()
489                && self
490                    .store()
491                    .podcast_download(id)?
492                    .is_some_and(|d| !d.path.is_empty() && d.path == self.playback.url) =>
493            {
494                Err(crate::podcast::error(crate::t!("podcast_download_in_use")))
495            }
496            action => self.podcast_runtime.action(
497                &self.session.config,
498                action,
499                self.session._lock.clone(),
500            ),
501        }
502    }
503    pub fn podcast_tasks(&self) -> (usize, bool) {
504        self.podcast_runtime.tasks()
505    }
506    pub fn poll_podcast(&mut self) -> Option<Result<serde_json::Value>> {
507        self.podcast_runtime.poll()
508    }
509    pub fn cancel_podcast(&mut self) -> bool {
510        self.podcast_runtime.cancel()
511    }
512    pub fn tick(&mut self) -> Result<()> {
513        if self.session.background_media {
514            self.podcast_runtime
515                .tick(&self.session.config, self.session._lock.clone())?;
516        }
517        self.poll_background()?;
518        self.playback.tick(&mut self.session, &mut self.recording)?;
519        self.recording
520            .recording_tick(&mut self.session, &mut self.playback)?;
521        self.subtitle_tick();
522        self.artwork_tick();
523        Ok(())
524    }
525
526    fn subtitle_tick(&mut self) {
527        if !self.session.background_media {
528            return;
529        }
530        if self.session.subtitles.snapshot.enabled && !self.session.artwork.quiescent() {
531            self.session.artwork.cancel();
532            return;
533        }
534        let playing = self.session.status.playback_state == PlaybackState::Playing;
535        let paused = self.session.status.paused();
536        let local = self.playback.source_kind == playback::SourceKind::Local;
537        let generation = self.playback.generation;
538        let session = &mut self.session;
539        let key = (generation, session.status.source_url.as_str());
540        session
541            .subtitles
542            .update(&session.config, key, playing, paused, local, &session.stop);
543    }
544
545    pub fn set_subtitles(&mut self, enabled: bool) {
546        self.session.subtitles.enabled(enabled);
547    }
548    pub fn retry_subtitles(&mut self) {
549        self.session.subtitles.retry();
550    }
551    pub fn clear_subtitles(&mut self) {
552        self.session.subtitles.clear();
553    }
554    pub fn set_subtitle_model(&mut self, id: String) -> Result<()> {
555        crate::speech::validate_model(&id)?;
556        let mut settings = self.session.config.settings.subtitles.clone();
557        settings.model = id;
558        settings.validate()?;
559        self.session.config.settings.subtitles = settings;
560        self.session.subtitles.retry();
561        self.session.subtitles.clear();
562        Ok(())
563    }
564
565    fn artwork_tick(&mut self) {
566        let request = (self.session.background_media
567            && !self.session.subtitles.snapshot.enabled
568            && self.session.subtitles.quiescent()
569            && self.session.config.settings.artwork == crate::config::ArtworkMode::Track
570            && self.session.status.playback_state == PlaybackState::Playing
571            && !matches!(
572                self.session.status.recording_state,
573                RecordingState::Probing | RecordingState::Recording | RecordingState::Finalizing
574            )
575            && self.playback.source_kind != playback::SourceKind::Local
576            && self.playback.retiring.is_empty()
577            && self.recording.retiring_probes.is_empty()
578            && !self.session.status.title.is_empty())
579        .then_some(self.session.status.station.as_ref())
580        .flatten()
581        .filter(|station| {
582            station.hls == 0
583                && self.session.artwork.demand.as_deref() == Some(station.stationuuid.as_str())
584        })
585        .filter(|_| crate::config::validate_url(&self.session.status.source_url).is_ok())
586        .map(|station| artwork::Request {
587            stationuuid: station.stationuuid.clone(),
588            source_url: self.session.status.source_url.clone(),
589            title: self.session.status.title.clone(),
590        });
591        let session = &mut self.session;
592        session.artwork.update(&session.config, request);
593    }
594
595    pub fn pause(&mut self) -> Result<()> {
596        self.playback.pause(&mut self.session, &mut self.recording)
597    }
598    pub fn mute(&mut self) -> Result<()> {
599        self.playback
600            .player
601            .as_mut()
602            .context(DomainError::new(ErrorCode::NotPlaying))?
603            .toggle_mute()
604    }
605
606    pub fn volume(&mut self, delta: i32) -> Result<()> {
607        self.playback
608            .volume(&mut self.session, &mut self.recording, delta)
609    }
610
611    pub fn stop_playback(&mut self) -> Result<()> {
612        self.playback
613            .stop_playback(&mut self.session, &mut self.recording)
614    }
615
616    pub fn toggle_recording(&mut self) -> Result<()> {
617        let result = self
618            .recording
619            .toggle_recording(&mut self.session, &mut self.playback);
620        if let Err(error) = &result
621            && self.recording.recorder.is_none()
622            && self.recording.recording_probe.is_none()
623            && self.recording.finalizing.is_none()
624        {
625            self.session.status.recording_state = RecordingState::Failed {
626                reason: format!("{error:#}"),
627            };
628        }
629        result
630    }
631
632    pub fn record_current(
633        &mut self,
634        duration: Option<Duration>,
635        dir: Option<&std::path::Path>,
636    ) -> Result<()> {
637        let result =
638            self.recording
639                .record_current(&mut self.session, &mut self.playback, duration, dir);
640        if let Err(error) = &result
641            && self.recording.recorder.is_none()
642            && self.recording.recording_probe.is_none()
643            && self.recording.finalizing.is_none()
644        {
645            self.session.status.recording_state = RecordingState::Failed {
646                reason: format!("{error:#}"),
647            };
648        }
649        result
650    }
651
652    pub fn standalone_record(
653        &mut self,
654        uuid: &str,
655        duration: Option<Duration>,
656        dir: Option<&std::path::Path>,
657    ) -> Result<()> {
658        let result = self.recording.standalone_record(
659            &mut self.session,
660            &mut self.playback,
661            uuid,
662            duration,
663            dir,
664        );
665        if let Err(error) = &result
666            && self.recording.recorder.is_none()
667            && self.recording.recording_probe.is_none()
668            && self.recording.finalizing.is_none()
669        {
670            self.session.status.recording_state = RecordingState::Failed {
671                reason: format!("{error:#}"),
672            };
673        }
674        result
675    }
676
677    pub fn stop_recording(&mut self, reason: Option<&str>) -> Result<()> {
678        self.recording
679            .stop_recording(&mut self.session, &mut self.playback, reason)
680    }
681
682    pub(crate) fn enable_background_media(&mut self) -> Result<()> {
683        if self.session.persistence.is_none() {
684            self.session.persistence = Some(persistence::Writer::start(
685                self.session.config.data_dir.join("radio.db"),
686                self.session._lock.clone(),
687            )?);
688        }
689        self.session.background_media = true;
690        let enabled = self.session.config.settings.subtitles.enabled;
691        self.session.subtitles.enabled(enabled);
692        Ok(())
693    }
694
695    pub fn delete_recording(&mut self, id: String, index_only: bool) -> Result<()> {
696        if self.session.library_task.is_some() {
697            bail!(DomainError::new(ErrorCode::RecordingBusy));
698        }
699        if self.playback.local_recording_id.as_deref() == Some(&id) {
700            self.stop_playback()?;
701        }
702        let path = self.session.config.data_dir.join("radio.db");
703        let lock = self.session._lock.clone();
704        self.session.library_task = Some(Background::start(
705            "radio-recording-delete",
706            move |cancel| {
707                let _lock = lock;
708                if cancel.load(std::sync::atomic::Ordering::Relaxed) {
709                    bail!(DomainError::new(ErrorCode::Cancelled));
710                }
711                crate::service::delete_recording(&Store::open(&path)?, &id, index_only)?;
712                Ok(crate::t!("recording_deleted", "id" => id))
713            },
714        )?);
715        Ok(())
716    }
717
718    pub fn open_recordings(&mut self) -> Result<()> {
719        if self.session.library_task.is_some() {
720            bail!(DomainError::new(ErrorCode::RecordingBusy));
721        }
722        let dir = self.session.config.recording_dir.clone();
723        self.session.library_task =
724            Some(Background::start("radio-open-recordings", move |cancel| {
725                crate::service::open_recordings(&dir, &cancel)?;
726                Ok(crate::t!("recordings_opened", "path" => dir.display()))
727            })?);
728        Ok(())
729    }
730
731    pub fn playback_active(&self) -> bool {
732        self.playback.player.is_some()
733            || self.playback.player_start.is_some()
734            || self.playback.refresh_task.is_some()
735            || self.playback.reconnect_due.is_some()
736            || self
737                .playback
738                .queue_completions
739                .active(self.playback.generation)
740    }
741
742    pub fn playback_error(&self) -> Option<&DomainError> {
743        self.playback.failure.as_ref()
744    }
745
746    pub fn shutdown(&mut self) -> Result<()> {
747        self.shutdown_with_budget(Duration::from_secs(6))
748    }
749
750    fn shutdown_with_budget(&mut self, budget: Duration) -> Result<()> {
751        self.podcast_runtime = Default::default();
752        let mut failure = self.stop_playback().err();
753        self.session.subtitles.enabled(false);
754        self.playback.click_task = None;
755        self.session.diagnostics = None;
756        self.session.library_task = None;
757        let deadline = Instant::now() + budget;
758        if let Some(writer) = &self.session.persistence {
759            writer.close(deadline);
760        }
761        // Allow normal finalization, then cancel verification if its budget
762        // expires. Outstanding HTTP results never need joining.
763        while (self.recording.finalizing.is_some()
764            || !self.playback.queue_completions.is_empty()
765            || !self.playback.retiring.is_empty()
766            || !self.recording.retiring_probes.is_empty()
767            || !self.session.artwork.quiescent()
768            || !self.session.subtitles.quiescent()
769            || self
770                .session
771                .persistence
772                .as_ref()
773                .is_some_and(|writer| !writer.finished()))
774            && Instant::now() < deadline
775        {
776            if let Err(error) = self.poll_background() {
777                failure.get_or_insert(error);
778            }
779            std::thread::sleep(Duration::from_millis(10));
780        }
781        self.recording.finalizing = None;
782        if !self.playback.queue_completions.is_empty() {
783            failure.get_or_insert_with(|| anyhow::anyhow!(crate::t!("session_save_failed")));
784        }
785        if let Some(writer) = self.session.persistence.take()
786            && let Err(error) = writer.finish().context(crate::t!("session_save_failed"))
787        {
788            failure.get_or_insert(error);
789        }
790        failure.map_or(Ok(()), Err)
791    }
792
793    fn poll_background(&mut self) -> Result<()> {
794        if let Some(writer) = &self.session.persistence {
795            writer.poll().context(crate::t!("session_save_failed"))?;
796        }
797        self.session.subtitles.poll_retiring();
798        if let Some(result) = self
799            .session
800            .library_task
801            .as_ref()
802            .and_then(Background::poll)
803        {
804            self.session.library_task = None;
805            self.session.status.message = match result {
806                Ok(message) => message,
807                Err(error) => {
808                    crate::t!("recording_operation_failed", "error" => format!("{error:#}"))
809                }
810            };
811        }
812        self.playback
813            .poll_background(&mut self.session, &mut self.recording)?;
814        self.recording
815            .record_poll_background(&mut self.session, &mut self.playback)
816    }
817}
818
819impl Drop for Engine {
820    fn drop(&mut self) {
821        let _ = self.shutdown();
822    }
823}
824
825#[cfg(test)]
826mod tests {
827    use super::*;
828
829    #[test]
830    fn queue_completion_refreshes_candidates_after_concurrent_edits() {
831        use crate::podcast::{Episode, Feed, Preview, QueueAction};
832        for edit in ["clear", "remove", "move", "readd"] {
833            let dir = tempfile::tempdir().unwrap();
834            let mut config = crate::test_support::config(dir.path());
835            config.settings.mpv = crate::test_support::fake_mpv(dir.path())
836                .to_string_lossy()
837                .into_owned();
838            let path = config.data_dir.join("radio.db");
839            let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
840            let preview = Preview {
841                feed: Feed {
842                    url: "https://example.test/feed".into(),
843                    ..Default::default()
844                },
845                episodes: ["episode-eof", "second", "third"]
846                    .into_iter()
847                    .map(|name| Episode {
848                        guid: Some(name.into()),
849                        url: format!("https://example.test/{name}"),
850                        ..Default::default()
851                    })
852                    .collect(),
853            };
854            let feed = engine
855                .store()
856                .podcast_subscribe(&preview, &preview.feed.url)
857                .unwrap();
858            let episodes = engine.store().podcast_episodes(&feed.id).unwrap();
859            let ids: Vec<_> = ["episode-eof", "second", "third"]
860                .into_iter()
861                .map(|name| {
862                    episodes
863                        .iter()
864                        .find(|e| e.guid.as_deref() == Some(name))
865                        .unwrap()
866                        .id
867                        .clone()
868                })
869                .collect();
870            engine.store().podcast_queue_set(&ids).unwrap();
871            engine.enable_background_media().unwrap();
872            engine.play_podcast_queue(true).unwrap();
873            let deadline = Instant::now() + Duration::from_secs(3);
874            while engine.playback.queue_completions.is_empty() {
875                engine.tick().unwrap();
876                assert!(Instant::now() < deadline);
877                std::thread::sleep(Duration::from_millis(5));
878            }
879            // Launch completion, then stop polling until its transaction commits.
880            engine.poll_background().unwrap();
881            let external = Store::open(&path).unwrap();
882            while external.podcast_queue().unwrap().len() != 2 {
883                assert!(Instant::now() < deadline);
884                std::thread::sleep(Duration::from_millis(5));
885            }
886            let action = match edit {
887                "clear" => QueueAction::Clear,
888                "remove" => QueueAction::Remove { id: ids[1].clone() },
889                "move" => QueueAction::Move {
890                    id: ids[2].clone(),
891                    position: 1,
892                },
893                "readd" => QueueAction::Add { id: ids[0].clone() },
894                _ => unreachable!(),
895            };
896            external.podcast_queue_update(action).unwrap();
897            let deadline = Instant::now() + Duration::from_secs(3);
898            while !engine.playback.queue_completions.is_empty() {
899                engine.tick().unwrap();
900                assert!(Instant::now() < deadline);
901                std::thread::sleep(Duration::from_millis(5));
902            }
903            match edit {
904                "clear" => {
905                    assert!(!engine.playback_active());
906                    assert_eq!(engine.status().playback_state, PlaybackState::Idle);
907                }
908                "remove" | "move" => {
909                    assert_eq!(engine.status().episode.as_ref().unwrap().id, ids[2])
910                }
911                "readd" => {
912                    assert_eq!(engine.status().episode.as_ref().unwrap().id, ids[1]);
913                    assert!(
914                        external
915                            .podcast_queue()
916                            .unwrap()
917                            .iter()
918                            .any(|e| e.id == ids[0])
919                    );
920                }
921                _ => unreachable!(),
922            }
923            engine.shutdown().unwrap();
924        }
925    }
926
927    #[test]
928    fn queue_completion_retries_without_blocking_or_overriding_controls() {
929        use crate::podcast::{Episode, Feed, Preview};
930        for control in ["advance", "stop", "switch", "off", "shutdown"] {
931            let dir = tempfile::tempdir().unwrap();
932            let mut config = crate::test_support::config(dir.path());
933            config.settings.mpv = crate::test_support::fake_mpv(dir.path())
934                .to_string_lossy()
935                .into_owned();
936            let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
937            let preview = Preview {
938                feed: Feed {
939                    url: "https://example.test/feed".into(),
940                    ..Default::default()
941                },
942                episodes: ["episode-eof", "audio"]
943                    .into_iter()
944                    .map(|name| Episode {
945                        guid: Some(name.into()),
946                        url: format!("https://example.test/{name}"),
947                        ..Default::default()
948                    })
949                    .collect(),
950            };
951            let feed = engine
952                .store()
953                .podcast_subscribe(&preview, &preview.feed.url)
954                .unwrap();
955            let episodes = engine.store().podcast_episodes(&feed.id).unwrap();
956            let first = episodes
957                .iter()
958                .find(|e| e.guid.as_deref() == Some("episode-eof"))
959                .unwrap();
960            let next = episodes
961                .iter()
962                .find(|e| e.guid.as_deref() == Some("audio"))
963                .unwrap();
964            engine
965                .store()
966                .podcast_queue_set(&[first.id.clone(), next.id.clone()])
967                .unwrap();
968            engine.enable_background_media().unwrap();
969            engine.play_podcast_queue(true).unwrap();
970            let connection = rusqlite::Connection::open(dir.path().join("radio.db")).unwrap();
971            connection.execute_batch("BEGIN IMMEDIATE").unwrap();
972            let deadline = Instant::now() + Duration::from_secs(3);
973            while engine.playback.queue_completions.is_empty() {
974                let started = Instant::now();
975                engine.tick().unwrap();
976                assert!(
977                    started.elapsed() < Duration::from_millis(250),
978                    "EOF blocked controls"
979                );
980                assert!(Instant::now() < deadline);
981                std::thread::sleep(Duration::from_millis(5));
982            }
983            let deadline = Instant::now() + Duration::from_millis(350);
984            while Instant::now() < deadline {
985                let started = Instant::now();
986                engine.tick().unwrap();
987                engine.volume(-1).unwrap();
988                assert!(
989                    started.elapsed() < Duration::from_millis(250),
990                    "queue retry blocked controls"
991                );
992                std::thread::sleep(Duration::from_millis(5));
993            }
994            assert_eq!(engine.store().podcast_queue().unwrap().len(), 2);
995            assert!(!engine.playback.queue_completions.is_empty());
996            if control == "shutdown" {
997                let release = std::thread::spawn(move || {
998                    std::thread::sleep(Duration::from_millis(200));
999                    connection.execute_batch("ROLLBACK").unwrap();
1000                });
1001                engine.shutdown().unwrap();
1002                release.join().unwrap();
1003                assert!(engine.playback.queue_completions.is_empty());
1004                assert_eq!(engine.status().playback_state, PlaybackState::Idle);
1005                assert_eq!(engine.store().podcast_queue().unwrap()[0].id, next.id);
1006                assert!(engine.store().podcast_episode(&first.id).unwrap().completed);
1007                continue;
1008            }
1009            match control {
1010                "stop" => {
1011                    engine.stop_playback().unwrap();
1012                    assert!(!engine.playback_active());
1013                }
1014                "switch" => {
1015                    engine.play("https://example.test/live").unwrap();
1016                }
1017                "off" => engine.podcast_auto_next(false).unwrap(),
1018                _ => assert!(engine.playback_active()),
1019            }
1020            connection.execute_batch("ROLLBACK").unwrap();
1021            let deadline = Instant::now() + Duration::from_secs(3);
1022            loop {
1023                engine.tick().unwrap();
1024                if engine.playback.queue_completions.is_empty()
1025                    && (matches!(control, "stop" | "off")
1026                        || engine.status().playback_state == PlaybackState::Playing)
1027                {
1028                    break;
1029                }
1030                assert!(
1031                    Instant::now() < deadline,
1032                    "{control}: {:?}",
1033                    engine.status()
1034                );
1035                std::thread::sleep(Duration::from_millis(5));
1036            }
1037            assert_eq!(
1038                engine
1039                    .store()
1040                    .podcast_queue()
1041                    .unwrap()
1042                    .iter()
1043                    .map(|e| &e.id)
1044                    .collect::<Vec<_>>(),
1045                vec![&next.id]
1046            );
1047            match control {
1048                "advance" => assert_eq!(engine.status().episode.as_ref().unwrap().id, next.id),
1049                "stop" | "off" => assert_eq!(engine.status().playback_state, PlaybackState::Idle),
1050                "switch" => {
1051                    assert!(engine.status().episode.is_none());
1052                    assert_eq!(engine.status().source_url, "https://example.test/live");
1053                }
1054                _ => unreachable!(),
1055            }
1056            engine.shutdown().unwrap();
1057            assert!(engine.store().podcast_episode(&first.id).unwrap().completed);
1058        }
1059    }
1060
1061    #[test]
1062    fn podcast_preferences_apply_before_the_background_write_finishes() {
1063        use crate::podcast::{Action, Episode, Feed, Preview, QueueAction};
1064        for (old_speed, old_auto_next, speed, auto_next) in
1065            [(1., false, 1.5, true), (1.5, true, 1.25, false)]
1066        {
1067            let dir = tempfile::tempdir().unwrap();
1068            let mut config = crate::test_support::config(dir.path());
1069            let mpv = crate::test_support::fake_mpv(dir.path());
1070            config.settings.mpv = mpv.to_string_lossy().into_owned();
1071            let store = Store::open(&config.data_dir.join("radio.db")).unwrap();
1072            store
1073                .set_meta("podcast_speed", &old_speed.to_string())
1074                .unwrap();
1075            store
1076                .set_meta(
1077                    "podcast_auto_next",
1078                    if old_auto_next { "on" } else { "off" },
1079                )
1080                .unwrap();
1081            let preview = Preview {
1082                feed: Feed {
1083                    url: "https://example.test/feed".into(),
1084                    ..Default::default()
1085                },
1086                episodes: vec![Episode {
1087                    url: "https://example.test/audio".into(),
1088                    ..Default::default()
1089                }],
1090            };
1091            let feed = store
1092                .podcast_subscribe(&preview, &preview.feed.url)
1093                .unwrap();
1094            let id = store.podcast_episodes(&feed.id).unwrap().remove(0).id;
1095            store.podcast_queue_set(std::slice::from_ref(&id)).unwrap();
1096            let mut engine = Engine::new(config.clone(), Arc::new(AtomicBool::new(false))).unwrap();
1097            engine.enable_background_media().unwrap();
1098            let connection = rusqlite::Connection::open(dir.path().join("radio.db")).unwrap();
1099            connection.execute_batch("BEGIN IMMEDIATE").unwrap();
1100            engine
1101                .podcast_action(Action::Speed { rate: speed })
1102                .unwrap();
1103            engine
1104                .podcast_action(Action::AutoNext {
1105                    state: if auto_next { "on" } else { "off" }.into(),
1106                })
1107                .unwrap();
1108            assert_eq!(
1109                store.meta("podcast_speed").unwrap(),
1110                Some(old_speed.to_string())
1111            );
1112            assert_eq!(
1113                store.meta("podcast_auto_next").unwrap().as_deref(),
1114                Some(if old_auto_next { "on" } else { "off" })
1115            );
1116            engine
1117                .podcast_action(Action::Queue {
1118                    action: QueueAction::Play { auto_next: false },
1119                })
1120                .unwrap();
1121            assert_eq!(engine.status().speed, speed);
1122            assert_eq!(engine.playback.auto_next, auto_next);
1123            let deadline = Instant::now() + Duration::from_secs(3);
1124            loop {
1125                engine.tick().unwrap();
1126                let commands =
1127                    std::fs::read_to_string(mpv.with_extension("commands")).unwrap_or_default();
1128                let speed_sent = commands
1129                    .lines()
1130                    .filter_map(|line| serde_json::from_str::<serde_json::Value>(line).ok())
1131                    .any(|value| {
1132                        value["command"] == serde_json::json!(["set_property", "speed", speed])
1133                    });
1134                if speed_sent && engine.status().playback_state == PlaybackState::Playing {
1135                    break;
1136                }
1137                assert!(Instant::now() < deadline, "{:?}", engine.status());
1138                std::thread::sleep(Duration::from_millis(5));
1139            }
1140            engine.play("https://example.test/live").unwrap();
1141            assert_eq!(engine.status().speed, 1.);
1142            engine.play_episode(&id, false, Some(2.)).unwrap();
1143            assert_eq!(engine.status().speed, 2.);
1144            assert!(engine.podcast_speed(f64::NAN).is_err());
1145            engine.play_episode(&id, false, None).unwrap();
1146            assert_eq!(engine.status().speed, speed);
1147            engine
1148                .podcast_action(Action::Queue {
1149                    action: QueueAction::Play { auto_next: true },
1150                })
1151                .unwrap();
1152            assert!(engine.playback.auto_next);
1153            connection.execute_batch("ROLLBACK").unwrap();
1154            engine.shutdown().unwrap();
1155            let lock = Arc::downgrade(&engine.session._lock);
1156            drop(engine);
1157            // Cancelled player startups finish their cleanup on detached threads.
1158            let deadline = Instant::now() + Duration::from_secs(3);
1159            while lock.strong_count() > 0 {
1160                assert!(Instant::now() < deadline);
1161                std::thread::sleep(Duration::from_millis(5));
1162            }
1163            let mut restored = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1164            restored.play_episode(&id, false, None).unwrap();
1165            assert_eq!(restored.status().speed, speed);
1166            assert_eq!(restored.playback.auto_next, auto_next);
1167            restored.shutdown().unwrap();
1168        }
1169    }
1170
1171    #[test]
1172    fn podcast_marks_apply_before_the_background_write_finishes() {
1173        use crate::podcast::{Action, Episode, Feed, Preview};
1174        for active in [false, true] {
1175            for state in ["unplayed", "played"] {
1176                let dir = tempfile::tempdir().unwrap();
1177                let mut config = crate::test_support::config(dir.path());
1178                config.settings.mpv = crate::test_support::fake_mpv(dir.path())
1179                    .to_string_lossy()
1180                    .into_owned();
1181                let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1182                let preview = Preview {
1183                    feed: Feed {
1184                        url: "https://example.test/feed".into(),
1185                        ..Default::default()
1186                    },
1187                    episodes: vec![Episode {
1188                        url: "https://example.test/audio".into(),
1189                        ..Default::default()
1190                    }],
1191                };
1192                let feed = engine
1193                    .store()
1194                    .podcast_subscribe(&preview, &preview.feed.url)
1195                    .unwrap();
1196                let episode = engine.store().podcast_episodes(&feed.id).unwrap().remove(0);
1197                let id = episode.id.clone();
1198                engine
1199                    .store()
1200                    .podcast_progress(&episode, 15000, Some(20000), false)
1201                    .unwrap();
1202                engine.enable_background_media().unwrap();
1203                if active {
1204                    engine.play_episode(&id, false, None).unwrap();
1205                }
1206                let connection = rusqlite::Connection::open(dir.path().join("radio.db")).unwrap();
1207                connection.execute_batch("BEGIN IMMEDIATE").unwrap();
1208                engine
1209                    .podcast_action(Action::Mark {
1210                        id: id.clone(),
1211                        state: state.into(),
1212                    })
1213                    .unwrap();
1214                let stored = engine.store().podcast_episode(&id).unwrap();
1215                assert_eq!(stored.position_ms, 15000);
1216                assert!(!stored.completed);
1217                engine.play_episode(&id, false, None).unwrap();
1218                let playing = engine.status().episode.as_ref().unwrap();
1219                assert_eq!(playing.position_ms, 0, "{state}, active={active}");
1220                assert!(!playing.completed);
1221                connection.execute_batch("ROLLBACK").unwrap();
1222                engine.shutdown().unwrap();
1223                assert_eq!(engine.store().podcast_episode(&id).unwrap().position_ms, 0);
1224            }
1225        }
1226    }
1227
1228    #[test]
1229    fn replay_preserves_uncommitted_progress_for_unchanged_media() {
1230        use crate::podcast::{Episode, Feed, Preview};
1231        let dir = tempfile::tempdir().unwrap();
1232        let mut config = crate::test_support::config(dir.path());
1233        config.settings.mpv = crate::test_support::fake_mpv(dir.path())
1234            .to_string_lossy()
1235            .into_owned();
1236        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1237        let preview = Preview {
1238            feed: Feed {
1239                url: "https://example.test/feed".into(),
1240                ..Default::default()
1241            },
1242            episodes: vec![Episode {
1243                url: "https://example.test/audio".into(),
1244                duration_ms: Some(20000),
1245                ..Default::default()
1246            }],
1247        };
1248        let feed = engine
1249            .store()
1250            .podcast_subscribe(&preview, &preview.feed.url)
1251            .unwrap();
1252        let mut episode = engine.store().podcast_episodes(&feed.id).unwrap().remove(0);
1253        let id = episode.id.clone();
1254        engine.enable_background_media().unwrap();
1255        let connection = rusqlite::Connection::open(dir.path().join("radio.db")).unwrap();
1256        connection.execute_batch("BEGIN IMMEDIATE").unwrap();
1257        episode.position_ms = 8000;
1258        engine.playback.episode = Some(episode);
1259        engine
1260            .playback
1261            .save_episode(&mut engine.session, false)
1262            .unwrap();
1263        engine.playback.episode = None;
1264        assert_eq!(engine.store().podcast_episode(&id).unwrap().position_ms, 0);
1265        engine.play_episode(&id, false, None).unwrap();
1266        assert_eq!(engine.status().episode.as_ref().unwrap().position_ms, 8000);
1267        connection.execute_batch("ROLLBACK").unwrap();
1268        engine.shutdown().unwrap();
1269        assert_eq!(
1270            engine.store().podcast_episode(&id).unwrap().position_ms,
1271            8000
1272        );
1273    }
1274
1275    #[test]
1276    fn download_removal_checks_the_active_input_instead_of_the_saved_episode() {
1277        use crate::podcast::{self, Action, Episode, Feed, Preview};
1278        for streaming in [false, true] {
1279            for background in [false, true] {
1280                let dir = tempfile::tempdir().unwrap();
1281                let mut config = crate::test_support::config(dir.path());
1282                config.settings.mpv = crate::test_support::fake_mpv(dir.path())
1283                    .to_string_lossy()
1284                    .into_owned();
1285                let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1286                if background {
1287                    engine.enable_background_media().unwrap();
1288                }
1289                let p = Preview {
1290                    feed: Feed {
1291                        url: "https://example.test/rss".into(),
1292                        ..Default::default()
1293                    },
1294                    episodes: vec![Episode {
1295                        guid: Some("episode".into()),
1296                        url: "https://example.test/audio".into(),
1297                        ..Default::default()
1298                    }],
1299                };
1300                let feed = engine.store().podcast_subscribe(&p, &p.feed.url).unwrap();
1301                let episode = engine.store().podcast_episodes(&feed.id).unwrap().remove(0);
1302                let path = podcast::download_path(engine.config(), &episode.id);
1303                std::fs::create_dir_all(path.parent().unwrap()).unwrap();
1304                std::fs::write(&path, b"fixture").unwrap();
1305                let download = podcast::Download {
1306                    episode_id: episode.id.clone(),
1307                    url: episode.url.clone(),
1308                    media: Some(episode.media()),
1309                    state: "complete".into(),
1310                    path: path.to_string_lossy().into_owned(),
1311                    bytes: 7,
1312                    ..Default::default()
1313                };
1314                // An online player must not reserve a download completed later.
1315                if !streaming {
1316                    engine.store().podcast_save_download(&download).unwrap();
1317                }
1318                engine.play_episode(&episode.id, false, None).unwrap();
1319                if streaming {
1320                    engine.store().podcast_save_download(&download).unwrap();
1321                }
1322                assert!(engine.playback_active());
1323                let remove = Action::Downloads {
1324                    action: podcast::DownloadAction::Remove {
1325                        id: episode.id.clone(),
1326                    },
1327                };
1328                if !streaming {
1329                    assert!(engine.podcast_action(remove.clone()).is_err());
1330                    assert!(path.exists());
1331                    engine.stop_playback().unwrap();
1332                    assert!(!engine.playback_active());
1333                    assert_eq!(engine.status().episode.as_ref().unwrap().id, episode.id);
1334                }
1335                engine.podcast_action(remove).unwrap();
1336                let deadline = Instant::now() + Duration::from_secs(3);
1337                let result = loop {
1338                    if let Some(result) = engine.poll_podcast() {
1339                        break result.unwrap();
1340                    }
1341                    assert!(Instant::now() < deadline);
1342                    std::thread::sleep(Duration::from_millis(10));
1343                };
1344                assert_eq!(result["state"], "removed");
1345                assert!(!path.exists());
1346                if streaming {
1347                    assert!(engine.playback_active());
1348                }
1349                engine.shutdown().unwrap();
1350            }
1351        }
1352    }
1353
1354    #[test]
1355    fn background_media_preserves_the_lock_budget_for_catalog_writes() {
1356        let dir = tempfile::tempdir().unwrap();
1357        let config = crate::test_support::config(dir.path());
1358        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1359        let station = crate::service::add_station(
1360            &mut engine.session.store,
1361            "Custom".into(),
1362            "https://example.test/live".into(),
1363            &[],
1364        )
1365        .unwrap();
1366        engine.enable_background_media().unwrap();
1367        // Every operation waits through a short publication transaction. The
1368        // former 20 ms owner budget failed each one while the lock was held.
1369        for operation in 0..5 {
1370            let connection = rusqlite::Connection::open(dir.path().join("radio.db")).unwrap();
1371            connection.execute_batch("BEGIN IMMEDIATE").unwrap();
1372            let release = std::thread::spawn(move || {
1373                std::thread::sleep(Duration::from_millis(100));
1374                connection.execute_batch("ROLLBACK").unwrap();
1375            });
1376            let result = match operation {
1377                0 => engine.toggle_favorite(&station.stationuuid).map(|_| ()),
1378                1 => engine
1379                    .change_station(crate::service::StationCommand::Backups {
1380                        uuid: station.stationuuid.clone(),
1381                        add: vec!["https://example.test/backup".into()],
1382                        remove: vec![],
1383                    })
1384                    .map(|_| ()),
1385                2 => engine.store().upsert(&station),
1386                3 => engine.store().save_recording(
1387                    &serde_json::from_value(serde_json::json!({
1388                        "id":"record", "stationuuid":station.stationuuid,
1389                        "station_name":station.name, "source_url_resolved":station.url,
1390                        "started_at":"2026-11-01T00:00:00Z", "codec":"mp3", "container":"mp3",
1391                        "path":"record.mp3", "size_bytes":0, "status":"recording"
1392                    }))
1393                    .unwrap(),
1394                ),
1395                4 => engine
1396                    .change_station(crate::service::StationCommand::Remove {
1397                        uuid: station.stationuuid.clone(),
1398                        keep_references: true,
1399                    })
1400                    .map(|_| ()),
1401                _ => unreachable!(),
1402            };
1403            release.join().unwrap();
1404            result.unwrap();
1405        }
1406        engine.shutdown().unwrap();
1407    }
1408
1409    #[test]
1410    fn background_session_writes_keep_controls_responsive_under_a_write_lock() {
1411        let dir = tempfile::tempdir().unwrap();
1412        let config = crate::test_support::config(dir.path());
1413        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1414        let station = Station {
1415            stationuuid: uuid::Uuid::new_v4().to_string(),
1416            name: "Remembered".into(),
1417            active: true,
1418            ..Station::default()
1419        };
1420        engine.session.store.upsert(&station).unwrap();
1421        engine.enable_background_media().unwrap();
1422        let connection = rusqlite::Connection::open(dir.path().join("radio.db")).unwrap();
1423        connection.execute_batch("BEGIN IMMEDIATE").unwrap();
1424        let started = Instant::now();
1425        for _ in 0..10 {
1426            engine.volume(-1).unwrap();
1427        }
1428        engine.save_preference("pref_source", "favorites").unwrap();
1429        engine.session.remember_play(&station.stationuuid).unwrap();
1430        engine.stop_playback().unwrap();
1431        engine.tick().unwrap();
1432        assert!(started.elapsed() < Duration::from_millis(250));
1433        assert_eq!(engine.session.status.volume, 70);
1434        // Let the writer hit contention before sending the newer value.
1435        std::thread::sleep(Duration::from_millis(150));
1436        engine.volume(-5).unwrap();
1437        connection.execute_batch("ROLLBACK").unwrap();
1438        // Closing flushes the latest value even before the debounce expires.
1439        engine.shutdown().unwrap();
1440        assert_eq!(
1441            engine.session.store.meta("pref_volume").unwrap().as_deref(),
1442            Some("65")
1443        );
1444        assert_eq!(
1445            engine.session.store.meta("pref_source").unwrap().as_deref(),
1446            Some("favorites")
1447        );
1448        assert_eq!(
1449            engine
1450                .session
1451                .store
1452                .meta("pref_last_station")
1453                .unwrap()
1454                .as_deref(),
1455            Some(station.stationuuid.as_str())
1456        );
1457        assert_eq!(
1458            engine
1459                .session
1460                .store
1461                .search_count(&Filter {
1462                    history: true,
1463                    ..Filter::default()
1464                })
1465                .unwrap(),
1466            1
1467        );
1468    }
1469
1470    #[test]
1471    fn background_session_write_failures_are_reported() {
1472        let dir = tempfile::tempdir().unwrap();
1473        let config = crate::test_support::config(dir.path());
1474        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1475        engine
1476            .session
1477            .store
1478            .test_connection()
1479            .execute_batch(
1480                "CREATE TRIGGER deny_preferences BEFORE INSERT ON meta
1481             BEGIN SELECT RAISE(ABORT,'preference denied'); END;",
1482            )
1483            .unwrap();
1484        engine.enable_background_media().unwrap();
1485        engine.volume(-1).unwrap();
1486        let deadline = Instant::now() + Duration::from_secs(3);
1487        loop {
1488            if let Err(error) = engine.tick() {
1489                assert!(format!("{error:#}").contains("preference denied"));
1490                break;
1491            }
1492            assert!(Instant::now() < deadline);
1493            std::thread::sleep(Duration::from_millis(10));
1494        }
1495        assert!(engine.shutdown().is_err());
1496        assert!(engine.session.persistence.is_none());
1497        engine.shutdown().unwrap();
1498    }
1499
1500    #[test]
1501    fn shutdown_drains_finalization_after_a_session_write_failure() {
1502        let dir = tempfile::tempdir().unwrap();
1503        let config = crate::test_support::config(dir.path());
1504        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1505        engine
1506            .store()
1507            .test_connection()
1508            .execute_batch(
1509                "CREATE TRIGGER deny_preferences BEFORE INSERT ON meta
1510             BEGIN SELECT RAISE(ABORT,'preference denied'); END;",
1511            )
1512            .unwrap();
1513        engine.enable_background_media().unwrap();
1514        engine.volume(-1).unwrap();
1515        let (completed, receive) = std::sync::mpsc::channel();
1516        engine.recording.finalizing = Some(
1517            Background::start("test-finalization", move |_| {
1518                std::thread::sleep(Duration::from_millis(150));
1519                completed.send(()).unwrap();
1520                bail!("finalization fixture");
1521            })
1522            .unwrap(),
1523        );
1524        let error = engine.shutdown().unwrap_err();
1525        assert!(format!("{error:#}").contains("preference denied"));
1526        receive
1527            .try_recv()
1528            .expect("finalization must finish before shutdown returns");
1529        assert!(engine.recording.finalizing.is_none());
1530        assert!(engine.session.persistence.is_none());
1531        assert!(matches!(
1532            engine.status().recording_state,
1533            RecordingState::Failed { .. }
1534        ));
1535        engine.shutdown().unwrap();
1536    }
1537
1538    #[test]
1539    fn shutdown_stops_pending_writes_before_reporting_a_flush_timeout() {
1540        let dir = tempfile::tempdir().unwrap();
1541        let config = crate::test_support::config(dir.path());
1542        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1543        engine.enable_background_media().unwrap();
1544        let connection = rusqlite::Connection::open(dir.path().join("radio.db")).unwrap();
1545        connection.execute_batch("BEGIN IMMEDIATE").unwrap();
1546        engine.volume(-1).unwrap();
1547        let (cancelled, receive) = std::sync::mpsc::channel();
1548        engine.recording.finalizing = Some(
1549            Background::start("test-finalization", move |cancel| {
1550                while !cancel.load(std::sync::atomic::Ordering::Relaxed) {
1551                    std::thread::sleep(Duration::from_millis(5));
1552                }
1553                cancelled.send(()).unwrap();
1554                bail!("cancelled finalization fixture");
1555            })
1556            .unwrap(),
1557        );
1558        assert!(
1559            engine
1560                .shutdown_with_budget(Duration::from_millis(150))
1561                .is_err()
1562        );
1563        assert!(engine.session.persistence.is_none());
1564        assert!(engine.recording.finalizing.is_none());
1565        receive.recv_timeout(Duration::from_secs(1)).unwrap();
1566        connection.execute_batch("ROLLBACK").unwrap();
1567        // The writer has settled, so releasing the lock cannot produce a late
1568        // successful write after the caller was told that flushing failed.
1569        assert!(engine.store().meta("pref_volume").unwrap().is_none());
1570        engine.shutdown().unwrap();
1571    }
1572
1573    #[test]
1574    fn invalid_subtitle_model_reports_id_without_changing_settings() {
1575        let dir = tempfile::tempdir().unwrap();
1576        let config = crate::test_support::config(dir.path());
1577        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1578        let original = engine.session.config.settings.subtitles.model.clone();
1579        for id in ["unknown", "silero-vad", "../../model"] {
1580            let error = engine.set_subtitle_model(id.into()).unwrap_err();
1581            let error = error.downcast_ref::<DomainError>().unwrap();
1582            assert_eq!(error.code, ErrorCode::SubtitleModel);
1583            assert_eq!(engine.session.config.settings.subtitles.model, original);
1584        }
1585    }
1586
1587    #[test]
1588    fn device_failure_skips_backups_reconnects_refresh_and_random_fallback() {
1589        use crate::test_support::{Server, fake_mpv};
1590        use std::sync::atomic::{AtomicUsize, Ordering};
1591        let requests = Arc::new(AtomicUsize::new(0));
1592        let counter = requests.clone();
1593        let server = Server::new(move |_, _| {
1594            counter.fetch_add(1, Ordering::Relaxed);
1595        });
1596        let dir = tempfile::tempdir().unwrap();
1597        let mpv = fake_mpv(dir.path());
1598        for background in [false, true] {
1599            let data = dir.path().join(background.to_string());
1600            let mut config = crate::test_support::config_with_api(&data, &server.url);
1601            config.settings.mpv = mpv.to_string_lossy().into_owned();
1602            config.settings.audio_device = Some("test/fail".into());
1603            let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1604            engine.session.background_media = background;
1605            let station = Station {
1606                stationuuid: uuid::Uuid::new_v4().to_string(),
1607                name: "Catalog station".into(),
1608                url: format!("{}/live", server.url),
1609                active: true,
1610                ..Station::default()
1611            };
1612            engine.session.store.upsert(&station).unwrap();
1613            engine
1614                .session
1615                .store
1616                .add_backup(&station.stationuuid, &format!("{}/backup", server.url))
1617                .unwrap();
1618            engine.play(&station.stationuuid).unwrap();
1619            engine.playback.random_filter = Some(Filter::default());
1620            engine.playback.session_started = true;
1621            let deadline = Instant::now() + Duration::from_secs(3);
1622            while !engine.session.playback_failed {
1623                engine.tick().unwrap();
1624                assert!(
1625                    Instant::now() < deadline,
1626                    "{}",
1627                    engine.session.status.message
1628                );
1629                std::thread::sleep(Duration::from_millis(10));
1630            }
1631            let error = engine.playback_error().unwrap();
1632            assert_eq!(error.code, ErrorCode::AudioDeviceFailed);
1633            assert_eq!(error.params["device"], "test/fail");
1634            assert_eq!(engine.playback.tried.len(), 1);
1635            assert!(!engine.playback_active());
1636            assert!(!engine.playback.refreshed);
1637            assert!(engine.playback.reconnect_window.is_empty());
1638            engine.shutdown().unwrap();
1639        }
1640        assert_eq!(requests.load(Ordering::Relaxed), 0);
1641        let commands = std::fs::read_to_string(mpv.with_extension("commands")).unwrap();
1642        assert_eq!(
1643            commands
1644                .lines()
1645                .filter(|s| s.contains("\"loadfile\""))
1646                .count(),
1647            2
1648        );
1649    }
1650
1651    #[test]
1652    fn background_player_startup_preserves_dependency_failure() {
1653        let dir = tempfile::tempdir().unwrap();
1654        let mut config = crate::test_support::config(dir.path());
1655        config.settings.mpv = dir
1656            .path()
1657            .join("missing-mpv")
1658            .to_string_lossy()
1659            .into_owned();
1660        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1661        engine.enable_background_media().unwrap();
1662        engine.play("https://example.com/live").unwrap();
1663        let deadline = Instant::now() + Duration::from_secs(3);
1664        while !engine.session.playback_failed {
1665            engine.tick().unwrap();
1666            assert!(Instant::now() < deadline);
1667            std::thread::sleep(Duration::from_millis(10));
1668        }
1669        assert_eq!(
1670            engine.playback_error().unwrap().code,
1671            ErrorCode::MissingDependency
1672        );
1673        assert!(!engine.playback_active());
1674    }
1675
1676    #[test]
1677    fn failed_recording_finalization_keeps_the_previous_playback_source_kind() {
1678        use crate::test_support::{Server, config, fixture, response};
1679        let bytes = fixture("libmp3lame", "mp3");
1680        let server = Server::new(move |_, stream| response(stream, 200, "audio/mpeg", &bytes));
1681        let dir = tempfile::tempdir().unwrap();
1682        let mut engine = Engine::new(config(dir.path()), Arc::new(AtomicBool::new(false))).unwrap();
1683        let station = Station {
1684            stationuuid: uuid::Uuid::new_v4().to_string(),
1685            name: "Saved station".into(),
1686            url: server.url.clone(),
1687            active: true,
1688            custom: true,
1689            ..Station::default()
1690        };
1691        engine.session.store.upsert(&station).unwrap();
1692        engine.session.status.station = Some(station.clone());
1693        engine.session.status.playback_state = PlaybackState::Playing;
1694        engine.playback.url = server.url.clone();
1695        engine.record_current(None, None).unwrap();
1696        let conn = rusqlite::Connection::open(dir.path().join("radio.db")).unwrap();
1697        conn.execute_batch("CREATE TRIGGER reject_recording_update BEFORE UPDATE ON recordings BEGIN SELECT RAISE(ABORT, 'test failure'); END;").unwrap();
1698        assert!(engine.play("https://example.com/audition").is_err());
1699        assert_eq!(
1700            engine.session.status.station.as_ref().unwrap().stationuuid,
1701            station.stationuuid
1702        );
1703        assert_eq!(engine.playback.source_kind, playback::SourceKind::Catalog);
1704    }
1705
1706    #[test]
1707    fn recording_track_is_snapshotted_before_probe_and_stays_stable() {
1708        use crate::test_support::{Server, config, fixture, response};
1709        let bytes = fixture("libmp3lame", "mp3");
1710        let server = Server::new(move |_, stream| response(stream, 200, "audio/mpeg", &bytes));
1711        for background in [false, true] {
1712            for title in [
1713                "Björk / 中文\x1b\n".to_owned(),
1714                String::new(),
1715                "曲".repeat(100),
1716            ] {
1717                let dir = tempfile::tempdir().unwrap();
1718                let mut engine =
1719                    Engine::new(config(dir.path()), Arc::new(AtomicBool::new(false))).unwrap();
1720                if background {
1721                    engine.enable_background_media().unwrap();
1722                }
1723                let station = Station {
1724                    stationuuid: uuid::Uuid::new_v4().to_string(),
1725                    name: if title.starts_with('曲') {
1726                        "台".repeat(60)
1727                    } else {
1728                        "Station".into()
1729                    },
1730                    url: server.url.clone(),
1731                    custom: true,
1732                    active: true,
1733                    ..Station::default()
1734                };
1735                engine.session.store.upsert(&station).unwrap();
1736                engine.session.status.station = Some(station);
1737                engine.session.status.playback_state = PlaybackState::Playing;
1738                engine.session.status.title = title.clone();
1739                engine.playback.url = server.url.clone();
1740                engine
1741                    .record_current(Some(Duration::from_secs(1)), None)
1742                    .unwrap();
1743                engine.session.status.title = "Next track".into();
1744                let deadline = Instant::now() + Duration::from_secs(8);
1745                while engine.session.status.recording_path.is_empty() {
1746                    engine.tick().unwrap();
1747                    assert!(
1748                        Instant::now() < deadline,
1749                        "{}",
1750                        engine.session.status.message
1751                    );
1752                    std::thread::sleep(Duration::from_millis(10));
1753                }
1754                let record = engine.session.store.recordings(1).unwrap().remove(0);
1755                let expected = crate::clean_text(&title).trim().to_owned();
1756                assert_eq!(
1757                    record.track.as_deref(),
1758                    (!expected.is_empty()).then_some(expected.as_str())
1759                );
1760                let final_path = record.final_path.clone().unwrap();
1761                let name = std::path::Path::new(&record.path)
1762                    .file_name()
1763                    .unwrap()
1764                    .to_str()
1765                    .unwrap();
1766                assert!(name.len() + ".json.tmp".len() <= 255);
1767                if title.starts_with("Björk") {
1768                    assert!(name.contains("-Station-Björk_中文-"));
1769                }
1770                if title.is_empty() {
1771                    assert!(name.contains("-Station-"));
1772                }
1773                while engine.session.status.recording()
1774                    || engine.session.status.recording_state == RecordingState::Finalizing
1775                {
1776                    engine.tick().unwrap();
1777                    assert!(
1778                        Instant::now() < deadline,
1779                        "{}",
1780                        engine.session.status.message
1781                    );
1782                    std::thread::sleep(Duration::from_millis(10));
1783                }
1784                let saved = engine.session.store.recording(&record.id).unwrap();
1785                assert_eq!(saved.status, "complete", "{:?}", saved.error);
1786                assert_eq!(saved.path, final_path);
1787                assert_eq!(saved.track, record.track);
1788                let sidecar: crate::model::Recording =
1789                    serde_json::from_slice(&std::fs::read(format!("{}.json", saved.path)).unwrap())
1790                        .unwrap();
1791                assert_eq!(sidecar.track, saved.track);
1792                let reopened = Store::open(&dir.path().join("radio.db")).unwrap();
1793                assert_eq!(reopened.recording(&record.id).unwrap().track, saved.track);
1794            }
1795        }
1796    }
1797
1798    #[test]
1799    fn changing_station_clears_finished_recording_status() {
1800        let dir = tempfile::tempdir().unwrap();
1801        let config = crate::test_support::config(dir.path());
1802        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1803        for state in [
1804            RecordingState::Done,
1805            RecordingState::Failed {
1806                reason: "disk".into(),
1807            },
1808        ] {
1809            engine.session.status.recording_state = state;
1810            engine.session.status.recording_path = "old.mp3".into();
1811            engine.session.status.recording_ms = 1000;
1812            // No source reaches mpv; the new station still owns clean status.
1813            assert!(
1814                engine
1815                    .playback
1816                    .play_source(
1817                        &mut engine.session,
1818                        &mut engine.recording,
1819                        Station::default(),
1820                        vec![],
1821                        playback::SourceKind::Catalog
1822                    )
1823                    .is_err()
1824            );
1825            assert_eq!(engine.session.status.recording_state, RecordingState::Idle);
1826            assert!(engine.session.status.recording_path.is_empty());
1827            assert_eq!(engine.session.status.recording_ms, 0);
1828        }
1829    }
1830
1831    #[test]
1832    fn flapping_reconnects_have_a_sliding_window_limit() {
1833        let dir = tempfile::tempdir().unwrap();
1834        let config = crate::test_support::config(dir.path());
1835        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1836        engine.session.status.station = Some(Station {
1837            custom: true,
1838            ..Station::default()
1839        });
1840        engine.playback.session_started = true;
1841        engine.playback.reconnect_window = std::iter::repeat_n(Instant::now(), 6).collect();
1842        engine
1843            .playback
1844            .stream_failed(&mut engine.session, &mut engine.recording, "EOF")
1845            .unwrap();
1846        assert!(engine.session.playback_failed);
1847        assert!(!engine.session.status.muted);
1848        assert_eq!(engine.playback.reconnect_attempts, 0);
1849        assert!(engine.playback.reconnect_window.is_empty());
1850        assert!(engine.playback.reconnect_due.is_none());
1851        let failed_state = engine.session.status.playback_state.clone();
1852        for _ in 0..3 {
1853            engine.tick().unwrap();
1854            assert!(engine.session.playback_failed);
1855            assert_eq!(engine.session.status.playback_state, failed_state);
1856            assert!(!engine.playback_active());
1857        }
1858        engine.playback.reconnect_window =
1859            std::iter::repeat_n(Instant::now() - Duration::from_secs(61), 6).collect();
1860        engine
1861            .playback
1862            .stream_failed(&mut engine.session, &mut engine.recording, "EOF")
1863            .unwrap();
1864        assert!(engine.playback.reconnect_due.is_some());
1865        assert_eq!(engine.playback.reconnect_window.len(), 1);
1866    }
1867
1868    #[test]
1869    fn reconnect_budget_is_bounded_and_stop_cancels_it() {
1870        let dir = tempfile::tempdir().unwrap();
1871        let config = crate::test_support::config(dir.path());
1872        let mut engine = Engine::new(config, Arc::new(AtomicBool::new(false))).unwrap();
1873        engine.session.status.station = Some(Station {
1874            custom: true,
1875            name: "Test".into(),
1876            ..Station::default()
1877        });
1878        engine.session.status.muted = true;
1879        engine.playback.session_started = true;
1880        for delay in [1, 3, 7] {
1881            engine
1882                .playback
1883                .stream_failed(&mut engine.session, &mut engine.recording, "EOF")
1884                .unwrap();
1885            let remaining = engine
1886                .playback
1887                .reconnect_due
1888                .unwrap()
1889                .saturating_duration_since(Instant::now());
1890            assert!(remaining <= Duration::from_secs(delay));
1891            assert!(remaining > Duration::from_millis(delay * 1000 - 100));
1892            assert!(!engine.session.playback_failed);
1893        }
1894        engine.playback.reconnect_due = None;
1895        engine
1896            .playback
1897            .stream_failed(&mut engine.session, &mut engine.recording, "EOF")
1898            .unwrap();
1899        assert!(engine.session.playback_failed);
1900        assert!(!engine.session.status.muted);
1901        assert_eq!(engine.playback.reconnect_attempts, 0);
1902        assert!(engine.playback.reconnect_window.is_empty());
1903        assert!(engine.playback.reconnect_due.is_none());
1904        engine.playback.reconnect_attempts = 0;
1905        engine
1906            .playback
1907            .stream_failed(&mut engine.session, &mut engine.recording, "EOF")
1908            .unwrap();
1909        engine.session.status.muted = true;
1910        engine.stop_playback().unwrap();
1911        assert!(!engine.session.status.muted);
1912        assert_eq!(engine.playback.reconnect_attempts, 0);
1913        assert!(engine.playback.reconnect_window.is_empty());
1914        assert!(engine.playback.reconnect_due.is_none());
1915        let generation = engine.playback.generation;
1916        engine.tick().unwrap();
1917        assert_eq!(engine.playback.generation, generation);
1918        assert!(engine.playback.player.is_none() && engine.playback.player_start.is_none());
1919    }
1920}