feat: integrate Miruro playback and episode progress

src/miruro.rs

@@ -1,10 +1,15 @@
 //! Blocking access to the deployed Miruro catalog and source API.
 //!
-//! See `docs/miruro-api.md`. Source URLs are ephemeral; retain server headers and
-//! provider configuration for playback. This module does not select a provider,
-//! bypass protection, decode iframe embeds, or integrate with a player.
-use std::{io, mem::size_of, time::Duration};
+//! See `docs/miruro-api.md`. Source URLs are ephemeral. Playback projection is
+//! limited to direct Sun soft-subtitle sources; no proxy, iframe or retry fallback.
+use std::{
+    collections::{BTreeMap, HashSet},
+    io,
+    mem::size_of,
+    time::Duration,
+};
 
+use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value};
 
 const BASE: &str = "https://barelystarted.miruro.tv";
@@ -20,6 +25,262 @@ pub struct Detail {
     pub episodes: Vec<Value>,
 }
 
+/// Stable catalog identity, never a CDN address or playback-provider name.
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(deny_unknown_fields)]
+pub struct Identity {
+    pub provider: String,
+    pub media_id: String,
+    pub episode: u32,
+}
+
+impl Identity {
+    pub fn new(media_id: String, episode: u32) -> io::Result<Self> {
+        let identity = Self {
+            provider: "miruro".into(),
+            media_id,
+            episode,
+        };
+        identity.validate()?;
+        Ok(identity)
+    }
+
+    pub fn validate(&self) -> io::Result<()> {
+        if self.provider != "miruro"
+            || self.media_id.len() > 512
+            || self.episode == 0
+            || self.episode > i32::MAX as u32
+        {
+            return Err(invalid("Invalid Miruro episode identity"));
+        }
+        validate_segment(&self.media_id)
+    }
+
+    pub fn key(&self) -> String {
+        format!("miruro:{}:{}", self.media_id, self.episode)
+    }
+
+    pub fn from_key(key: &str) -> io::Result<Self> {
+        let (media_id, episode) = key
+            .strip_prefix("miruro:")
+            .and_then(|rest| rest.split_once(':'))
+            .ok_or_else(|| invalid("Invalid Miruro episode key"))?;
+        if episode.starts_with('0') || !episode.bytes().all(|byte| byte.is_ascii_digit()) {
+            return Err(invalid("Noncanonical Miruro episode key"));
+        }
+        Self::new(
+            media_id.into(),
+            episode
+                .parse()
+                .map_err(|_| invalid("Invalid Miruro episode number"))?,
+        )
+    }
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub struct Subtitle {
+    pub url: String,
+    pub format: String,
+    pub language: String,
+    pub label: String,
+    pub default: bool,
+    pub headers: BTreeMap<String, String>,
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub struct SourceDocument {
+    pub version: u32,
+    pub url: String,
+    pub headers: BTreeMap<String, String>,
+    pub identity: Identity,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub title: Option<String>,
+    pub subtitles: Vec<Subtitle>,
+}
+
+impl SourceDocument {
+    pub fn validate(&self) -> io::Result<()> {
+        if self.version != 1
+            || self.subtitles.len() > 32
+            || self.subtitles.iter().filter(|track| track.default).count() > 1
+        {
+            return Err(invalid(
+                "Invalid source document version or subtitle limits",
+            ));
+        }
+        if self
+            .title
+            .as_ref()
+            .is_some_and(|title| title.chars().any(char::is_control))
+        {
+            return Err(invalid("Invalid source title"));
+        }
+        self.identity.validate()?;
+        validate_url(&self.url)?;
+        validate_headers(&self.headers)?;
+        for track in &self.subtitles {
+            if track.format != "vtt" {
+                return Err(invalid("Only external VTT subtitles are supported"));
+            }
+            if track.label.chars().any(char::is_control)
+                || track.language.chars().any(char::is_control)
+            {
+                return Err(invalid("Invalid subtitle label or language"));
+            }
+            validate_url(&track.url)?;
+            validate_headers(&track.headers)?;
+        }
+        Ok(())
+    }
+
+    /// No provider/language fallback: take the first direct ssub/Sun server.
+    pub fn from_sources(sources: &Value, identity: Identity, title: &str) -> io::Result<Self> {
+        identity.validate()?;
+        if sources["episodeNumber"].as_u64() != Some(u64::from(identity.episode)) {
+            return Err(invalid(
+                "Resolved source episode does not match its identity",
+            ));
+        }
+        let config = &sources["config"]["sun"];
+        if config["player"] != "native"
+            || config["proxy"] != false
+            || config["hls"]["segments"]["enabled"] == true
+            || config["hls"]["query"]["enabled"] == true
+        {
+            return Err(invalid("Sun requires unsupported proxy or HLS rewriting"));
+        }
+        let provider = sources["tracks"]
+            .as_array()
+            .and_then(|tracks| tracks.iter().find(|track| track["track"] == "ssub"))
+            .and_then(|track| track["providers"].as_array())
+            .and_then(|providers| {
+                providers
+                    .iter()
+                    .find(|provider| provider["provider"] == "sun")
+            })
+            .ok_or_else(|| invalid("Direct Sun soft-subtitle source is unavailable"))?;
+        let server = provider["servers"]
+            .as_array()
+            .and_then(|servers| {
+                servers.iter().find(|server| {
+                    server["streams"]
+                        .as_array()
+                        .is_some_and(|streams| !streams.is_empty())
+                })
+            })
+            .ok_or_else(|| invalid("Direct Sun stream is unavailable"))?;
+        let stream = &server["streams"][0];
+        if !matches!(
+            stream["format"].as_str(),
+            Some("hls" | "m3u8" | "application/vnd.apple.mpegurl" | "application/x-mpegurl")
+        ) || !stream["embed"].is_null()
+        {
+            return Err(invalid("Selected Sun stream is not direct HLS"));
+        }
+        let headers = source_headers(&server["headers"])?;
+        let mut subtitles = Vec::new();
+        for subtitle in provider["subtitles"]
+            .as_array()
+            .ok_or_else(|| invalid("Missing Sun subtitle array"))?
+        {
+            if subtitle["format"] != "vtt" {
+                continue;
+            }
+            if subtitles.len() == 32 {
+                return Err(invalid("Source subtitle limit exceeded"));
+            }
+            subtitles.push(Subtitle {
+                url: source_string(subtitle, "file")?,
+                format: "vtt".into(),
+                language: source_string(subtitle, "language")?,
+                label: source_string(subtitle, "label")?,
+                default: subtitle["default"]
+                    .as_bool()
+                    .ok_or_else(|| invalid("Invalid subtitle default flag"))?,
+                // Verified for direct Sun only. These are explicit resource headers,
+                // not an inheritance rule for other providers.
+                headers: headers.clone(),
+            });
+        }
+        let document = Self {
+            version: 1,
+            url: source_string(stream, "url")?,
+            headers,
+            identity,
+            title: Some(title.into()),
+            subtitles,
+        };
+        document.validate()?;
+        Ok(document)
+    }
+}
+
+fn source_string(value: &Value, field: &str) -> io::Result<String> {
+    value
+        .get(field)
+        .and_then(Value::as_str)
+        .map(str::to_owned)
+        .ok_or_else(|| invalid("Missing or invalid resolved source field"))
+}
+
+fn source_headers(value: &Value) -> io::Result<BTreeMap<String, String>> {
+    if value.is_null() {
+        return Ok(BTreeMap::new());
+    }
+    let headers = value
+        .as_object()
+        .ok_or_else(|| invalid("Invalid source header map"))?;
+    if headers.len() > 64 {
+        return Err(invalid("Source header limit exceeded"));
+    }
+    headers
+        .iter()
+        .map(|(key, value)| {
+            Ok((
+                key.clone(),
+                value
+                    .as_str()
+                    .ok_or_else(|| invalid("Invalid source header value"))?
+                    .into(),
+            ))
+        })
+        .collect()
+}
+
+fn validate_url(url: &str) -> io::Result<()> {
+    let uri: ureq::http::Uri = url.parse().map_err(|_| invalid("Invalid source URL"))?;
+    if !matches!(uri.scheme_str(), Some("http" | "https"))
+        || uri.host().is_none_or(str::is_empty)
+        || uri
+            .authority()
+            .is_some_and(|authority| authority.as_str().contains('@'))
+        || url.chars().any(char::is_control)
+    {
+        return Err(invalid(
+            "Source URLs must be absolute HTTP(S) without credentials",
+        ));
+    }
+    Ok(())
+}
+
+fn validate_headers(headers: &BTreeMap<String, String>) -> io::Result<()> {
+    if headers.len() > 64 {
+        return Err(invalid("Source header limit exceeded"));
+    }
+    let mut names = HashSet::with_capacity(headers.len());
+    for (name, value) in headers {
+        let name = ureq::http::HeaderName::from_bytes(name.as_bytes())
+            .map_err(|_| invalid("Invalid source header name"))?;
+        if !names.insert(name)
+            || value.chars().any(char::is_control)
+            || ureq::http::HeaderValue::from_str(value).is_err()
+        {
+            return Err(invalid("Invalid or duplicate source header"));
+        }
+    }
+    Ok(())
+}
+
 impl Default for Client {
     fn default() -> Self {
         Self {
@@ -98,6 +359,16 @@ impl Client {
         Ok(value)
     }
 
+    pub fn source_document(
+        &self,
+        id: &str,
+        episode: u32,
+        title: &str,
+    ) -> io::Result<SourceDocument> {
+        let identity = Identity::new(id.into(), episode)?;
+        SourceDocument::from_sources(&self.sources(id, episode)?, identity, title)
+    }
+
     fn get(&self, path: &str, query: &[(&str, &str)], types: &[&str]) -> io::Result<String> {
         let mut response = self
             .agent
@@ -277,6 +548,80 @@ fn expand(table: &[Value], index: usize, depth: usize, budget: &mut usize) -> io
 mod tests {
     use super::*;
 
+    #[test]
+    fn source_projection_rejects_unsafe_or_unsupported_playback_contracts() {
+        let sources = serde_json::json!({
+            "episodeNumber": 1,
+            "config": { "sun": { "player": "native", "proxy": false } },
+            "tracks": [{ "track": "ssub", "providers": [{
+                "provider": "sun",
+                "servers": [{
+                    "headers": { "Origin": "https://ultracloud.cc", "Referer": "https://ultracloud.cc/" },
+                    "streams": [{ "url": "https://vault.keeply.top/master.m3u8?token=secret", "format": "hls", "embed": null }]
+                }],
+                "subtitles": [{
+                    "file": "https://vault.keeply.top/english.jpeg", "format": "vtt",
+                    "language": "en", "label": "English", "default": true
+                }]
+            }] }]
+        });
+        let identity = Identity::new("catalog".into(), 1).unwrap();
+        let source = SourceDocument::from_sources(&sources, identity.clone(), "Episode 1").unwrap();
+        assert_eq!(Identity::from_key(&identity.key()).unwrap(), identity);
+        assert_ne!(
+            Identity::new("catalog".into(), 2).unwrap().key(),
+            source.identity.key()
+        );
+        for key in [
+            "miruro:catalog:01",
+            "miruro:catalog:0",
+            "miruro:catalog:2147483648",
+            "miruro:catalog/:1",
+        ] {
+            assert!(Identity::from_key(key).is_err());
+        }
+        for (pointer, value) in [
+            ("/episodeNumber", serde_json::json!(49)),
+            ("/config/sun/proxy", serde_json::json!({"segments": true})),
+            (
+                "/tracks/0/providers/0/servers/0/streams/0/url",
+                serde_json::json!("file:///secret"),
+            ),
+            (
+                "/tracks/0/providers/0/servers/0/streams/0/embed",
+                serde_json::json!({"url": "https://embed.example"}),
+            ),
+            (
+                "/tracks/0/providers/0/servers/0/headers/origin",
+                serde_json::json!("secret"),
+            ),
+            (
+                "/tracks/0/providers/0/servers/0/headers/Referer",
+                serde_json::json!("secret\r\nX-Injected: true"),
+            ),
+        ] {
+            let mut invalid_sources = sources.clone();
+            if let Some(field) = invalid_sources.pointer_mut(pointer) {
+                *field = value;
+            } else {
+                invalid_sources["tracks"][0]["providers"][0]["servers"][0]["headers"]["origin"] =
+                    value;
+            }
+            let error =
+                SourceDocument::from_sources(&invalid_sources, identity.clone(), "Episode 1")
+                    .unwrap_err();
+            assert!(!error.to_string().contains("secret"));
+        }
+        let mut invalid_source = source;
+        invalid_source
+            .subtitles
+            .push(invalid_source.subtitles[0].clone());
+        assert!(invalid_source.validate().is_err());
+        invalid_source.subtitles[1].default = false;
+        invalid_source.subtitles[1].format = "srt".into();
+        assert!(invalid_source.validate().is_err());
+    }
+
     #[test]
     fn episodes_resolve_by_promise_id_with_independent_tables_or_fail_explicitly() {
         let initial = r#"{"type":"data","nodes":[null,{"type":"data","data":[{"detail":1,"episodes":4},{"id":2,"episode_count":3},"series",12,["Promise",5],9]}]}"#;

src/miruro_browser.rs

@@ -0,0 +1,276 @@
+use crate::youtube::Video;
+use serde_json::Value;
+use std::{
+    io,
+    sync::mpsc::{self, Receiver, SyncSender},
+    thread,
+};
+use tubular::miruro::{Client, Detail, Identity, SourceDocument};
+use unicode_normalization::UnicodeNormalization;
+
+pub enum Request {
+    Search(String),
+    Episodes { media_id: String, slug: String },
+    Source(Video),
+}
+pub enum Response {
+    Rows(Vec<(Video, String)>),
+    Source(Video, Box<SourceDocument>),
+}
+
+// One running request, no queued network requests. The UI retains only its newest intent.
+pub struct Worker {
+    sender: SyncSender<(u64, Request)>,
+    receiver: Receiver<(u64, io::Result<Response>)>,
+    pub busy: bool,
+    generation: u64,
+}
+impl Worker {
+    pub fn new() -> Self {
+        let (sender, requests) = mpsc::sync_channel::<(u64, Request)>(1);
+        let (results, receiver) = mpsc::sync_channel(1);
+        thread::spawn(move || {
+            let client = Client::default();
+            while let Ok((generation, request)) = requests.recv() {
+                let result = match request {
+                    Request::Search(query) => client
+                        .search(&query)
+                        .and_then(catalog_rows)
+                        .map(Response::Rows),
+                    Request::Episodes { media_id, slug } => client
+                        .detail(&media_id, &slug)
+                        .and_then(|detail| episode_rows(&media_id, detail))
+                        .map(Response::Rows),
+                    Request::Source(video) => Identity::from_key(&video.id)
+                        .and_then(|id| {
+                            client.source_document(&id.media_id, id.episode, &video.title)
+                        })
+                        .map(|source| Response::Source(video, Box::new(source))),
+                };
+                if results.send((generation, result)).is_err() {
+                    break;
+                }
+            }
+        });
+        Self {
+            sender,
+            receiver,
+            busy: false,
+            generation: 0,
+        }
+    }
+    pub fn submit(&mut self, generation: u64, request: Request) -> io::Result<()> {
+        if self.busy {
+            return Err(io::Error::other("Miruro worker is busy"));
+        }
+        self.sender
+            .try_send((generation, request))
+            .map_err(|_| io::Error::other("Miruro worker unavailable"))?;
+        self.busy = true;
+        self.generation = generation;
+        Ok(())
+    }
+    pub fn poll(&mut self) -> Option<(u64, io::Result<Response>)> {
+        match self.receiver.try_recv() {
+            Ok(result) => {
+                self.busy = false;
+                Some(result)
+            }
+            Err(mpsc::TryRecvError::Empty) => None,
+            Err(mpsc::TryRecvError::Disconnected) if self.busy => {
+                self.busy = false;
+                Some((
+                    self.generation,
+                    Err(io::Error::other("Miruro worker stopped")),
+                ))
+            }
+            Err(_) => None,
+        }
+    }
+}
+
+pub fn is_miruro(video: &Video) -> bool {
+    video.id.starts_with("miruro:") || video.id.starts_with("miruro-series:")
+}
+fn invalid(message: &str) -> io::Error {
+    io::Error::new(io::ErrorKind::InvalidData, message)
+}
+fn title(media: &Value) -> io::Result<String> {
+    let get = |language| {
+        media
+            .get("title")
+            .and_then(|v| v.get(language))
+            .and_then(Value::as_str)
+            .map(|text| text.trim_matches(js_whitespace))
+            .filter(|s| !s.is_empty())
+    };
+    let selected = match (get("english"), get("romaji")) {
+        (Some(a), Some(b)) => {
+            if a.encode_utf16().count() <= b.encode_utf16().count() {
+                a
+            } else {
+                b
+            }
+        }
+        (Some(a), None) | (None, Some(a)) => a,
+        _ => media
+            .get("title")
+            .and_then(|value| value.get("native"))
+            .and_then(Value::as_str)
+            .or_else(|| media.get("id").and_then(Value::as_str))
+            .ok_or_else(|| invalid("Miruro title is missing"))?,
+    };
+    Ok(selected.to_owned())
+}
+// ECMAScript \s/trim, not Rust's Unicode whitespace (which includes U+0085).
+fn js_whitespace(ch: char) -> bool {
+    matches!(ch, '\u{0009}'..='\u{000d}' | ' ' | '\u{00a0}' | '\u{1680}'
+        | '\u{2000}'..='\u{200a}' | '\u{2028}' | '\u{2029}' | '\u{202f}'
+        | '\u{205f}' | '\u{3000}' | '\u{feff}')
+}
+pub fn slug(title: &str) -> io::Result<String> {
+    let cleaned: String = title
+        .nfd()
+        .filter(|ch| !('\u{0300}'..='\u{036f}').contains(ch))
+        .flat_map(char::to_lowercase)
+        .filter(|ch| {
+            ch.is_ascii_lowercase() || ch.is_ascii_digit() || js_whitespace(*ch) || *ch == '-'
+        })
+        .collect();
+    let mut slug = String::new();
+    for ch in cleaned.trim_matches(js_whitespace).chars() {
+        if ch.is_ascii_alphanumeric() {
+            slug.push(ch);
+        } else if (js_whitespace(ch) || ch == '-') && !slug.ends_with('-') {
+            slug.push('-');
+        }
+    }
+    if slug.is_empty() {
+        Err(invalid("Miruro title has no representable route slug"))
+    } else {
+        Ok(slug)
+    }
+}
+fn video(id: String, title: String, date: Option<String>) -> Video {
+    Video {
+        id,
+        title,
+        channel: Some("Miruro".into()),
+        channel_id: None,
+        uploader_id: None,
+        timestamp: None,
+        publication_date: date,
+    }
+}
+pub fn catalog_rows(items: Vec<Value>) -> io::Result<Vec<(Video, String)>> {
+    items
+        .into_iter()
+        .map(|media| {
+            let id = media
+                .get("id")
+                .and_then(Value::as_str)
+                .ok_or_else(|| invalid("Miruro catalog ID is missing"))?;
+            Identity::new(id.to_owned(), 1)?;
+            let title = title(&media)?;
+            let description = media
+                .get("description")
+                .and_then(Value::as_str)
+                .unwrap_or(
+                    "Catalog title: Enter opens returned episodes; only episodes can be saved.",
+                )
+                .to_owned();
+            Ok((
+                video(format!("miruro-series:{id}"), title, None),
+                description,
+            ))
+        })
+        .collect()
+}
+pub fn episode_rows(media_id: &str, detail: Detail) -> io::Result<Vec<(Video, String)>> {
+    let series = title(&detail.media)?;
+    let mut seen = std::collections::HashSet::new();
+    detail
+        .episodes
+        .into_iter()
+        .map(|episode| {
+            let number = episode
+                .get("episode_number")
+                .and_then(Value::as_u64)
+                .and_then(|n| u32::try_from(n).ok())
+                .ok_or_else(|| invalid("Miruro episode number is invalid"))?;
+            let identity = Identity::new(media_id.to_owned(), number)?;
+            if !seen.insert(number) {
+                return Err(invalid("Miruro returned duplicate episode numbers"));
+            }
+            let label = episode.get("title").and_then(Value::as_str).unwrap_or("");
+            let title = format!(
+                "{series} · Episode {number}{}",
+                if label.is_empty() {
+                    String::new()
+                } else {
+                    format!(" · {label}")
+                }
+            );
+            let description = episode
+                .get("synopsis")
+                .and_then(Value::as_str)
+                .unwrap_or("Episode metadata unavailable.")
+                .to_owned();
+            let date = episode
+                .get("aired_on")
+                .and_then(Value::as_str)
+                .map(str::to_owned);
+            Ok((video(identity.key(), title, date), description))
+        })
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn catalog_and_actual_episode_numbers_remain_distinct() {
+        let media = serde_json::json!({"id":"opaque_ID", "title":{"english":"The Apothecary Diaries", "romaji":"Kusuriya no Hitorigoto"}});
+        let rows = catalog_rows(vec![media.clone()]).unwrap();
+        assert_eq!(rows[0].0.id, "miruro-series:opaque_ID");
+        assert!(Identity::from_key(&rows[0].0.id).is_err());
+        let episodes = episode_rows(
+            "opaque_ID",
+            Detail {
+                media,
+                episodes: vec![
+                    serde_json::json!({"episode_number":3,"absolute_number":49,"title":"Returned"}),
+                ],
+            },
+        )
+        .unwrap();
+        let identity = Identity::from_key(&episodes[0].0.id).unwrap();
+        assert_eq!(identity.episode, 3);
+        assert_eq!(identity.media_id, "opaque_ID");
+        assert!(episodes[0].0.channel_id.is_none());
+        assert!(slug("薬屋").is_err());
+        assert_eq!(slug(" A  Test!! -- Title ").unwrap(), "a-test-title");
+        assert_eq!(slug(" --Title-- ").unwrap(), "-title-");
+        assert_eq!(slug("École déjà-vu").unwrap(), "ecole-deja-vu");
+        assert_eq!(slug("Cafe\u{0301}").unwrap(), "cafe");
+        assert_eq!(slug("Ａ薬屋 KK İ").unwrap(), "kk-i");
+        assert_eq!(
+            slug("\u{feff}A\u{00a0}B\u{2003}C\u{feff}").unwrap(),
+            "a-b-c"
+        );
+        assert_eq!(slug("A\u{0085}B").unwrap(), "ab");
+        assert!(slug("!!薬屋!!").is_err());
+        assert_eq!(
+            title(&serde_json::json!({"id":"id","title":{"english":"AB","romaji":"CD"}})).unwrap(),
+            "AB"
+        );
+        assert_eq!(
+            title(&serde_json::json!({"id":"id","title":{"english":"𐀀A","romaji":"BC"}})).unwrap(),
+            "BC"
+        );
+        assert_eq!(
+            title(&serde_json::json!({"id":"id","title":{"native":""}})).unwrap(),
+            ""
+        );
+    }
+}

src/video_state.rs

@@ -10,11 +10,14 @@ use serde::Deserialize;
 use toml_edit::{Array, ArrayOfTables, DocumentMut, Table, value};
 
 use crate::youtube::{Video, valid_video_id, validate_video};
+use tubular::miruro::{Identity, SourceDocument};
 
 const MAX_STATE_BYTES: u64 = 8 * 1024 * 1024;
 const MAX_LINE: usize = 16 * 1024;
 const STREAM_BYTES: usize = 16 * 1024;
 const MAX_STREAMS: usize = 4096;
+const MAX_SOURCE_BYTES: usize = 1024 * 1024;
+const MAX_IDENTITY_BYTES: u64 = 7 + 512 + 1 + 10;
 static NEXT_NAME: AtomicU64 = AtomicU64::new(0);
 
 fn invalid(message: impl Into<String>) -> io::Error {
@@ -239,6 +242,26 @@ impl State {
         Ok(path)
     }
 
+    pub fn miruro_session(
+        &mut self,
+        video: &Video,
+        source: &SourceDocument,
+    ) -> io::Result<(PathBuf, PathBuf)> {
+        source.validate()?;
+        if Identity::from_key(&video.id)? != source.identity {
+            return Err(invalid("Source identity must match the playback episode"));
+        }
+        let contents = serde_json::to_vec(source).map_err(|e| invalid(e.to_string()))?;
+        if contents.len() > MAX_SOURCE_BYTES {
+            return Err(invalid("Playback source exceeds the 1 MiB limit"));
+        }
+        let progress_file = self.progress_file(video)?;
+        let source_file = progress_file.with_file_name("source.json");
+        atomic_write(&source_file, None, &contents)?;
+        register_identity(&progress_file, &video.id)?;
+        Ok((source_file, progress_file))
+    }
+
     pub fn poll_progress(&mut self) -> io::Result<bool> {
         let mut error = self.discover().err();
         let count = self.streams.len().min(16);
@@ -372,6 +395,23 @@ fn validate_snapshot(video: &mut Video, require_channel: bool) -> io::Result<()>
             ));
         }
     }
+    if video.id.starts_with("miruro:") {
+        Identity::from_key(&video.id)?;
+        if video.title.trim().is_empty() || video.title.chars().any(char::is_control) {
+            return Err(invalid(
+                "Miruro episode title must be nonempty and contain no controls",
+            ));
+        }
+        if video.channel.as_deref() != Some("Miruro")
+            || video.channel_id.is_some()
+            || video.uploader_id.is_some()
+        {
+            return Err(invalid(
+                "Miruro episodes must not contain YouTube channel identities",
+            ));
+        }
+        return Ok(());
+    }
     validate_video(video).map_err(invalid)?;
     video.publication_date = date;
     if let Some(handle) = &video.uploader_id
@@ -448,13 +488,13 @@ fn load_watched(document: &DocumentMut) -> io::Result<BTreeSet<String>> {
         return Ok(BTreeSet::new());
     };
     item.as_array()
-        .ok_or_else(|| invalid("watched must be an array of YouTube IDs"))?
+        .ok_or_else(|| invalid("watched must be an array of playback identities"))?
         .iter()
         .map(|v| {
             let id = v
                 .as_str()
-                .filter(|id| valid_video_id(id))
-                .ok_or_else(|| invalid("Invalid watched YouTube ID"))?;
+                .filter(|id| valid_identity(id))
+                .ok_or_else(|| invalid("Invalid watched playback identity"))?;
             Ok(id.to_owned())
         })
         .collect()
@@ -641,8 +681,12 @@ fn private_directory(path: &Path, create: bool) -> io::Result<()> {
     Ok(())
 }
 
+fn valid_identity(id: &str) -> bool {
+    valid_video_id(id) || Identity::from_key(id).is_ok()
+}
+
 pub(crate) fn register_identity(progress_file: &Path, id: &str) -> io::Result<()> {
-    if !valid_video_id(id)
+    if !valid_identity(id)
         || progress_file
             .file_name()
             .is_none_or(|name| name != "progress.jsonl")
@@ -674,7 +718,14 @@ pub(crate) fn register_identity(progress_file: &Path, id: &str) -> io::Result<()
 }
 
 #[derive(Deserialize)]
-struct ProgressRecord {
+#[serde(untagged)]
+enum ProgressRecord {
+    YouTube(YouTubeProgress),
+    Miruro(MiruroProgress),
+}
+
+#[derive(Deserialize)]
+struct YouTubeProgress {
     version: u32,
     event: String,
     media_url: String,
@@ -683,6 +734,17 @@ struct ProgressRecord {
     completion_eligible: bool,
 }
 
+#[derive(Deserialize)]
+#[serde(deny_unknown_fields)]
+struct MiruroProgress {
+    version: u32,
+    event: String,
+    media_identity: Identity,
+    position_seconds: f64,
+    duration_seconds: Option<f64>,
+    completion_eligible: bool,
+}
+
 struct ProgressStream {
     path: PathBuf,
     id: Option<String>,
@@ -722,11 +784,11 @@ impl ProgressStream {
         let marker = self.path.with_file_name("video-id");
         let mut bytes = Vec::new();
         regular_file(&marker, true)?
-            .take(65)
+            .take(MAX_IDENTITY_BYTES + 1)
             .read_to_end(&mut bytes)?;
         let id = std::str::from_utf8(&bytes)
             .ok()
-            .filter(|id| valid_video_id(id))
+            .filter(|id| id.len() as u64 <= MAX_IDENTITY_BYTES && valid_identity(id))
             .ok_or_else(|| invalid("Invalid video-id session marker"))?;
         let snapshot = self.path.with_file_name("video.toml");
         let video = match regular_file(&snapshot, true) {
@@ -739,7 +801,12 @@ impl ProgressStream {
                 }
                 collection.videos.pop()
             }
-            Err(e) if e.kind() == io::ErrorKind::NotFound => None,
+            Err(e) if e.kind() == io::ErrorKind::NotFound && valid_video_id(id) => None,
+            Err(e) if e.kind() == io::ErrorKind::NotFound => {
+                return Err(invalid(
+                    "Miruro sessions require their bound video metadata",
+                ));
+            }
             Err(e) => return Err(e),
         };
         let seen_path = self.path.with_file_name("watching-seen.toml");
@@ -856,22 +923,48 @@ impl ProgressStream {
     ) -> io::Result<()> {
         let record: ProgressRecord =
             serde_json::from_slice(&self.partial).map_err(|e| self.record_error(e))?;
-        if record.version != 1 || !matches!(record.event.as_str(), "progress" | "ended" | "closed")
-        {
-            return Err(
-                self.record_error("expected version 1 and progress, ended, or closed event")
-            );
+        let miruro_key;
+        let (id, event, position, duration, eligible) = match &record {
+            ProgressRecord::YouTube(record) if record.version == 1 => {
+                let id = record
+                    .media_url
+                    .strip_prefix("https://www.youtube.com/watch?v=")
+                    .filter(|id| valid_video_id(id))
+                    .ok_or_else(|| self.record_error("expected canonical YouTube video URL"))?;
+                (
+                    id,
+                    record.event.as_str(),
+                    record.position_seconds,
+                    record.duration_seconds,
+                    record.completion_eligible,
+                )
+            }
+            ProgressRecord::Miruro(record) if record.version == 2 => {
+                record
+                    .media_identity
+                    .validate()
+                    .map_err(|e| self.record_error(e))?;
+                miruro_key = record.media_identity.key();
+                (
+                    miruro_key.as_str(),
+                    record.event.as_str(),
+                    record.position_seconds,
+                    record.duration_seconds,
+                    record.completion_eligible,
+                )
+            }
+            _ => {
+                return Err(self.record_error(
+                    "expected version 1 with media_url or version 2 with media_identity",
+                ));
+            }
+        };
+        if !matches!(event, "progress" | "ended" | "closed") {
+            return Err(self.record_error("expected progress, ended, or closed event"));
         }
-        let id = record
-            .media_url
-            .strip_prefix("https://www.youtube.com/watch?v=")
-            .filter(|id| valid_video_id(id))
-            .ok_or_else(|| self.record_error("expected canonical YouTube video URL"))?;
-        if !record.position_seconds.is_finite()
-            || record.position_seconds < 0.0
-            || record
-                .duration_seconds
-                .is_some_and(|d| !d.is_finite() || d <= 0.0)
+        if !position.is_finite()
+            || position < 0.0
+            || duration.is_some_and(|d| !d.is_finite() || d <= 0.0)
         {
             return Err(self.record_error(
                 "position must be finite/nonnegative and duration positive/finite or null",
@@ -880,13 +973,11 @@ impl ProgressStream {
         if self.id.as_deref() != Some(id) {
             return Ok(());
         }
-        if record.position_seconds > 0.0 && !self.seen && !watched.contains(id) {
+        if position > 0.0 && !self.seen && !watched.contains(id) {
             self.started = true;
         }
-        if record.completion_eligible
-            && record
-                .duration_seconds
-                .is_some_and(|d| record.position_seconds / d >= 0.95)
+        if eligible
+            && duration.is_some_and(|d| position / d >= 0.95)
             && !watched.contains(id)
             && !pending.contains(id)
         {
@@ -955,6 +1046,50 @@ mod tests {
         )
     }
 
+    fn miruro_video(episode: u32) -> Video {
+        Video {
+            id: Identity::new("opaque_Show-1".into(), episode)
+                .unwrap()
+                .key(),
+            title: format!("Example show · Episode {episode}"),
+            channel: Some("Miruro".into()),
+            channel_id: None,
+            uploader_id: None,
+            timestamp: Some(1_114_300_000),
+            publication_date: Some("2005-04-23".into()),
+        }
+    }
+
+    fn miruro_source(video: &Video) -> SourceDocument {
+        SourceDocument {
+            version: 1,
+            url: "https://cdn.example/video.m3u8?token=private-token".into(),
+            headers: [("Referer".into(), "https://player.example/".into())].into(),
+            identity: Identity::from_key(&video.id).unwrap(),
+            title: Some(video.title.clone()),
+            subtitles: Vec::new(),
+        }
+    }
+
+    fn miruro_record(
+        video: &Video,
+        event: &str,
+        eligible: bool,
+        position: f64,
+        duration: Option<f64>,
+    ) -> String {
+        serde_json::json!({
+            "version": 2,
+            "event": event,
+            "media_identity": Identity::from_key(&video.id).unwrap(),
+            "position_seconds": position,
+            "duration_seconds": duration,
+            "completion_eligible": eligible,
+        })
+        .to_string()
+            + "\n"
+    }
+
     #[test]
     fn collections_are_independent_and_preserve_metadata_and_watched_on_restart() {
         let directory = TestDirectory::new();
@@ -1565,4 +1700,348 @@ mod tests {
             .unwrap();
         assert!(State::open(&directory.config()).is_err());
     }
+
+    #[test]
+    fn miruro_sessions_recover_collections_and_watching_without_persisting_sources_in_state() {
+        let directory = TestDirectory::new();
+        let video = miruro_video(1);
+        let mut state = State::open(&directory.config()).unwrap();
+        for kind in [CollectionKind::WatchLater, CollectionKind::Saved] {
+            state.save(kind, &video).unwrap();
+        }
+        let source = miruro_source(&video);
+        let (source_file, report) = state.miruro_session(&video, &source).unwrap();
+        let source_bytes = fs::read(&source_file).unwrap();
+        assert_eq!(source_bytes, serde_json::to_vec(&source).unwrap());
+        assert!(!report.exists());
+        assert_eq!(
+            fs::read_to_string(report.with_file_name("video-id")).unwrap(),
+            video.id
+        );
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            for path in [
+                &source_file,
+                &report.with_file_name("video-id"),
+                &report.with_file_name("video.toml"),
+            ] {
+                assert_eq!(
+                    fs::metadata(path).unwrap().permissions().mode() & 0o777,
+                    0o600
+                );
+            }
+            for path in [
+                report.parent().unwrap(),
+                &directory.0.join("playback-sessions"),
+            ] {
+                assert_eq!(
+                    fs::metadata(path).unwrap().permissions().mode() & 0o777,
+                    0o700
+                );
+            }
+        }
+        assert!(!state.poll_progress().unwrap());
+        assert!(state.videos(CollectionKind::Watching).is_empty());
+        drop(state);
+        // A GUI can acknowledge its final snapshot after Tubular has quit.
+        append(
+            &report,
+            miruro_record(&video, "closed", false, 10.0, None).as_bytes(),
+        );
+        let mut state = State::open(&directory.config()).unwrap();
+        assert!(state.poll_progress().unwrap());
+        let stored = &state.videos(CollectionKind::Watching)[0];
+        assert_eq!(stored.id, video.id);
+        assert_eq!(stored.title, video.title);
+        assert_eq!(stored.channel, video.channel);
+        assert_eq!(stored.timestamp, video.timestamp);
+        assert_eq!(stored.publication_date, video.publication_date);
+        drop(state);
+        let mut state = State::open(&directory.config()).unwrap();
+        assert!(state.contains(CollectionKind::Watching, &video.id));
+        assert!(!state.poll_progress().unwrap());
+        append(
+            &report,
+            miruro_record(&video, "ended", true, 95.0, Some(100.0)).as_bytes(),
+        );
+        assert!(state.poll_progress().unwrap());
+        assert!(state.is_watched(&video.id));
+        assert!(state.videos(CollectionKind::Watching).is_empty());
+        drop(state);
+        let mut state = State::open(&directory.config()).unwrap();
+        assert!(state.is_watched(&video.id));
+        assert!(!state.poll_progress().unwrap());
+        for kind in [CollectionKind::WatchLater, CollectionKind::Saved] {
+            let stored = &state.videos(kind)[0];
+            assert_eq!(stored.id, video.id);
+            assert_eq!(stored.title, video.title);
+            assert_eq!(stored.channel, video.channel);
+            assert_eq!(stored.channel_id, None);
+            assert_eq!(stored.uploader_id, None);
+            assert_eq!(stored.timestamp, video.timestamp);
+            assert_eq!(stored.publication_date, video.publication_date);
+        }
+        for path in [
+            directory.0.join("watch-later.toml"),
+            directory.0.join("saved-videos.toml"),
+            directory.0.join("currently-watching.toml"),
+            directory.0.join("watch-state.toml"),
+            report.with_file_name("video.toml"),
+        ] {
+            let contents = fs::read_to_string(path).unwrap();
+            assert!(!contents.contains("private-token"));
+            assert!(!contents.contains("cdn.example"));
+        }
+        assert_eq!(fs::read(source_file).unwrap(), source_bytes);
+        assert!(report.exists());
+    }
+
+    #[test]
+    fn miruro_v2_requires_matching_episode_eligible_known_duration_and_threshold() {
+        for event in ["progress", "ended", "closed"] {
+            let directory = TestDirectory::new();
+            let mut state = State::open(&directory.config()).unwrap();
+            let video = miruro_video(1);
+            let (_, report) = state
+                .miruro_session(&video, &miruro_source(&video))
+                .unwrap();
+            append(
+                &report,
+                miruro_record(&miruro_video(2), event, true, 100.0, Some(100.0)).as_bytes(),
+            );
+            assert!(!state.poll_progress().unwrap());
+            assert!(state.videos(CollectionKind::Watching).is_empty());
+            assert!(!state.is_watched(&miruro_video(2).id));
+            for (eligible, position, duration) in [
+                (true, 0.0, Some(100.0)),
+                (true, 94.9, Some(100.0)),
+                (false, 100.0, Some(100.0)),
+                (true, 100.0, None),
+            ] {
+                append(
+                    &report,
+                    miruro_record(&video, event, eligible, position, duration).as_bytes(),
+                );
+                state.poll_progress().unwrap();
+                assert!(!state.is_watched(&video.id));
+            }
+            assert!(state.contains(CollectionKind::Watching, &video.id));
+            let completion = miruro_record(&video, event, true, 95.0, Some(100.0));
+            append(&report, completion.as_bytes());
+            append(&report, completion.as_bytes());
+            assert!(state.poll_progress().unwrap());
+            assert!(state.is_watched(&video.id));
+            assert!(state.videos(CollectionKind::Watching).is_empty());
+            assert!(!state.poll_progress().unwrap());
+        }
+    }
+
+    #[test]
+    fn miruro_v2_rejects_invalid_wire_schemas_numbers_and_namespaces() {
+        let directory = TestDirectory::new();
+        let mut state = State::open(&directory.config()).unwrap();
+        let video = miruro_video(1);
+        let (_, report) = state
+            .miruro_session(&video, &miruro_source(&video))
+            .unwrap();
+        let valid = miruro_record(&video, "progress", true, 100.0, Some(100.0));
+        for line in [
+            valid.replace("\"version\":2", "\"version\":1"),
+            valid.replace("\"version\":2", "\"version\":3"),
+            valid.replace("\"provider\":\"miruro\"", "\"provider\":\"youtube\""),
+            valid.replace("\"episode\":1", "\"episode\":0"),
+            valid.replace("\"episode\":1", "\"episode\":2147483648"),
+            valid.replace("\"position_seconds\":100.0", "\"position_seconds\":-1"),
+            valid.replace("\"position_seconds\":100.0", "\"position_seconds\":1e999"),
+            valid.replace("\"duration_seconds\":100.0", "\"duration_seconds\":0"),
+            valid.replace("\"duration_seconds\":100.0", "\"duration_seconds\":-1"),
+            valid.replace("\"duration_seconds\":100.0", "\"duration_seconds\":1e999"),
+            valid.replace("\"event\":\"progress\"", "\"event\":\"other\""),
+            valid.replacen('{', "{\"media_url\":null,", 1),
+            record(&self::video().id, "ended", true, 100.0)
+                .replace("\"version\":1", "\"version\":2"),
+        ] {
+            append(&report, line.as_bytes());
+            assert!(state.poll_progress().is_err(), "{line}");
+            assert!(state.videos(CollectionKind::Watching).is_empty());
+            assert!(!state.is_watched(&video.id));
+            assert!(!state.poll_progress().unwrap());
+        }
+    }
+
+    #[test]
+    fn miruro_partial_reports_and_bad_siblings_recover_after_restart() {
+        let directory = TestDirectory::new();
+        let mut state = State::open(&directory.config()).unwrap();
+        let video = miruro_video(1);
+        let (source, report) = state
+            .miruro_session(&video, &miruro_source(&video))
+            .unwrap();
+        let completion = miruro_record(&video, "closed", true, 95.0, Some(100.0));
+        append(&report, &completion.as_bytes()[..completion.len() - 1]);
+        assert!(!state.poll_progress().unwrap());
+        drop(state);
+        let mut state = State::open(&directory.config()).unwrap();
+        assert!(!state.poll_progress().unwrap());
+        let other = miruro_video(2);
+        let (_, bad) = state
+            .miruro_session(&other, &miruro_source(&other))
+            .unwrap();
+        append(&bad, b"not json\n");
+        append(&report, b"\n");
+        assert!(state.poll_progress().is_err());
+        assert!(state.is_watched(&video.id));
+        assert!(!state.is_watched(&other.id));
+        assert!(state.poll_progress().unwrap());
+        assert!(!state.poll_progress().unwrap());
+        drop(state);
+        assert!(source.exists());
+        assert!(report.exists());
+        let state = State::open(&directory.config()).unwrap();
+        assert!(state.is_watched(&video.id));
+    }
+
+    #[test]
+    fn miruro_state_rejects_catalog_rows_bad_titles_and_youtube_metadata() {
+        let directory = TestDirectory::new();
+        let mut state = State::open(&directory.config()).unwrap();
+        for field in [
+            "series",
+            "noncanonical",
+            "empty-title",
+            "control-title",
+            "channel",
+            "channel-id",
+            "uploader",
+        ] {
+            let mut video = miruro_video(1);
+            match field {
+                "series" => video.id = "miruro-series:opaque_Show-1".into(),
+                "noncanonical" => video.id = "miruro:opaque_Show-1:01".into(),
+                "empty-title" => video.title = " ".into(),
+                "control-title" => video.title.push('\n'),
+                "channel" => video.channel = Some("YouTube".into()),
+                "channel-id" => video.channel_id = self::video().channel_id,
+                "uploader" => video.uploader_id = Some("@jawed".into()),
+                _ => unreachable!(),
+            }
+            for kind in [
+                CollectionKind::WatchLater,
+                CollectionKind::Saved,
+                CollectionKind::Watching,
+            ] {
+                assert!(state.save(kind, &video).is_err(), "{field}");
+            }
+            assert!(state.progress_file(&video).is_err(), "{field}");
+        }
+        for id in [
+            "miruro-series:opaque_Show-1",
+            "miruro:opaque_Show-1:01",
+            "other:opaque_Show-1:1",
+        ] {
+            let mut watched = DocumentMut::new();
+            watched["version"] = value(1);
+            let mut ids = Array::new();
+            ids.push(id);
+            watched["watched"] = value(ids);
+            assert!(load_watched(&watched).is_err());
+        }
+    }
+
+    #[test]
+    fn miruro_source_sessions_validate_binding_size_and_maximum_identity_marker() {
+        let directory = TestDirectory::new();
+        let mut state = State::open(&directory.config()).unwrap();
+        let mut video = miruro_video(i32::MAX as u32);
+        video.id = Identity::new("a".repeat(512), i32::MAX as u32)
+            .unwrap()
+            .key();
+        let mut source = miruro_source(&video);
+        source.identity.episode -= 1;
+        assert!(state.miruro_session(&video, &source).is_err());
+        assert!(state.streams.is_empty());
+        source.identity = Identity::from_key(&video.id).unwrap();
+        source.title = Some("x".repeat(MAX_SOURCE_BYTES));
+        assert!(state.miruro_session(&video, &source).is_err());
+        assert!(state.streams.is_empty());
+        source.title = None;
+        let (_, report) = state.miruro_session(&video, &source).unwrap();
+        append(
+            &report,
+            miruro_record(&video, "ended", true, 95.0, Some(100.0)).as_bytes(),
+        );
+        drop(state);
+        let mut state = State::open(&directory.config()).unwrap();
+        assert!(state.poll_progress().unwrap());
+        assert!(state.is_watched(&video.id));
+        drop(state);
+        let state = State::open(&directory.config()).unwrap();
+        assert!(state.is_watched(&video.id));
+    }
+
+    #[test]
+    fn miruro_recovery_rejects_missing_snapshots_and_overlong_identity_markers() {
+        for missing_snapshot in [true, false] {
+            let directory = TestDirectory::new();
+            let mut state = State::open(&directory.config()).unwrap();
+            let video = miruro_video(1);
+            let (_, report) = state
+                .miruro_session(&video, &miruro_source(&video))
+                .unwrap();
+            if missing_snapshot {
+                fs::remove_file(report.with_file_name("video.toml")).unwrap();
+            } else {
+                append(
+                    &report.with_file_name("video-id"),
+                    &vec![b'x'; MAX_IDENTITY_BYTES as usize],
+                );
+            }
+            append(
+                &report,
+                miruro_record(&video, "ended", true, 100.0, Some(100.0)).as_bytes(),
+            );
+            drop(state);
+            let mut state = State::open(&directory.config()).unwrap();
+            assert!(state.poll_progress().is_err());
+            assert!(!state.is_watched(&video.id));
+            assert!(state.videos(CollectionKind::Watching).is_empty());
+        }
+    }
+
+    #[test]
+    fn youtube_v1_reports_keep_canonical_urls_and_unknown_field_tolerance() {
+        let directory = TestDirectory::new();
+        let mut state = State::open(&directory.config()).unwrap();
+        let video = video();
+        let report = state.progress_file(&video).unwrap();
+        register_identity(&report, &video.id).unwrap();
+        let valid = record(&video.id, "ended", true, 95.0);
+        for url in [
+            format!("https://youtu.be/{}", video.id),
+            format!("https://www.youtube.com/watch?v={}&t=1", video.id),
+            format!("http://www.youtube.com/watch?v={}", video.id),
+        ] {
+            append(
+                &report,
+                valid
+                    .replace(
+                        &format!("https://www.youtube.com/watch?v={}", video.id),
+                        &url,
+                    )
+                    .as_bytes(),
+            );
+            assert!(state.poll_progress().is_err());
+            assert!(!state.is_watched(&video.id));
+            assert!(state.videos(CollectionKind::Watching).is_empty());
+        }
+        append(
+            &report,
+            valid
+                .replacen('{', "{\"legacy_extension\":true,", 1)
+                .as_bytes(),
+        );
+        assert!(state.poll_progress().unwrap());
+        assert!(state.is_watched(&video.id));
+    }
 }

src/youtube.rs

@@ -819,14 +819,67 @@ impl PlayerLaunch {
             ));
         }
         crate::video_state::register_identity(progress_file, id)?;
-        let mut player = isolated_command(player)
+        let mut command = isolated_command(player);
+        command
             .args([
                 "--new-instance",
                 "--url",
                 &format!("https://www.youtube.com/watch?v={id}"),
             ])
             .arg("--progress-file")
-            .arg(progress_file)
+            .arg(progress_file);
+        Self::launch(command)
+    }
+
+    /// Session files are owned and retained by video_state, not by this launcher.
+    pub fn start_source(
+        source_file: &Path,
+        player: &OsStr,
+        progress_file: &Path,
+    ) -> io::Result<Self> {
+        if !std::fs::symlink_metadata(source_file)?.is_file() {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "Source document must be a regular file",
+            ));
+        }
+        let source_file = std::fs::canonicalize(source_file)?;
+        let parent = std::fs::canonicalize(progress_file.parent().ok_or_else(|| {
+            io::Error::new(io::ErrorKind::InvalidInput, "Missing progress directory")
+        })?)?;
+        if source_file.parent() != Some(parent.as_path())
+            || progress_file
+                .file_name()
+                .is_none_or(|name| name != "progress.jsonl")
+        {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "Source and progress must share their private session directory",
+            ));
+        }
+        let progress_file = parent.join("progress.jsonl");
+        match std::fs::symlink_metadata(&progress_file) {
+            Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+            Err(error) => return Err(error),
+            Ok(_) => {
+                return Err(io::Error::new(
+                    io::ErrorKind::AlreadyExists,
+                    "Progress destination must not exist",
+                ));
+            }
+        }
+        let mut command = isolated_command(player);
+        command
+            .arg("--new-instance")
+            .arg("--source-file")
+            .arg(source_file)
+            .arg("--progress-file")
+            .arg(progress_file);
+        Self::launch(command)
+    }
+
+    fn launch(mut command: Command) -> io::Result<Self> {
+        let mut player = command
             .stdin(Stdio::null())
             .stdout(Stdio::null())
             .stderr(Stdio::piped())