From f0fe90f0fed86f6628fb11adb7a2dfda38ca44e6 Mon Sep 17 00:00:00 2001
From: Nils Pukropp <nils@narl.io>
Date: Tue, 13 Oct 2026 21:11:20 +0200
Subject: [PATCH] feat(core,app,cli): pair subtitle files with their video and
 play them

A crawl now keeps .srt/.ass/.ssa/.vtt files and pairs each with a video by
name: the video's name followed by a dot or nothing, the same inside a
Subs folder, the Subs/<video>/ layout, and failing those the only video in
the folder. The words past the video's name give the language and the
picker's title. They go in a new sidecars table (schema v12), rebuilt by
every crawl.

The desktop opens them while mpv opens the video and adds them with
sub-add through the stream registry once the file has loaded. One in the
preferred language is turned on when subtitles are on and the file has
none of its own playing; the rest wait in the subtitle menu.
---
 crates/pstr-app/src/engine.rs    |  54 +++-
 crates/pstr-app/src/playback.rs  |  59 ++++-
 crates/pstr-cli/src/main.rs      |   5 +-
 crates/pstr-core/src/catalog.rs  | 421 ++++++++++++++++++++++++++++++-
 crates/pstr-core/src/naming.rs   |   9 +
 crates/pstr-player/src/player.rs |  22 ++
 6 files changed, 564 insertions(+), 6 deletions(-)

diff --git a/crates/pstr-app/src/engine.rs b/crates/pstr-app/src/engine.rs
index 5e3a98d..e036f22 100644
--- a/crates/pstr-app/src/engine.rs
+++ b/crates/pstr-app/src/engine.rs
@@ -28,7 +28,7 @@ use parking_lot::Mutex;
 use pstr_core::account::{DriveEntry, DrivePlace, PendingSignIn, SignIn};
 use pstr_core::appearance::Appearance;
 use pstr_core::catalog::{
-    Catalog, CatalogNode, OfflineFile, TitleTrackPrefs, WatchState, build_rows,
+    Catalog, CatalogNode, OfflineFile, TitleTrackPrefs, WatchState, build_rows, build_sidecars,
 };
 use pstr_core::config::AppDirs;
 use pstr_core::library::{Library, Title, TitleKind};
@@ -1513,6 +1513,7 @@ impl Engine {
             }
         };
         let rows = build_rows(&share_id, &nodes);
+        let sidecars = build_sidecars(&share_id, &nodes);
         let files = rows.len();
 
         // A writer opened before the crawl may be producing the revision
@@ -1574,7 +1575,7 @@ impl Engine {
                     for (link_id, _) in &stale {
                         catalog.remove_offline_file(&share_id, link_id)?;
                     }
-                    Ok(())
+                    catalog.replace_sidecars(&share_id, &sidecars)
                 })
         };
         if let Err(error) = stored {
@@ -1718,6 +1719,55 @@ impl Engine {
         });
     }
 
+    /// Open the subtitle files paired with `target`, for the player to add
+    /// once mpv has the video.
+    ///
+    /// Through the session already open: a local copy played without one goes
+    /// without its subtitles rather than waiting on a handshake. Each is
+    /// warmed — most are one block — so mpv reads it from the cache. One that
+    /// fails is left out quietly; the video plays either way.
+    pub async fn open_sidecars(
+        &self,
+        target: &PlaybackTarget,
+    ) -> Vec<(pstr_core::catalog::Sidecar, VideoStream)> {
+        let sidecars = self
+            .catalog
+            .lock()
+            .sidecars(&target.share_id, &target.link_id)
+            .unwrap_or_default();
+        if sidecars.is_empty() {
+            return Vec::new();
+        }
+        let Some((library, source)) = self.opened() else {
+            return Vec::new();
+        };
+        let opening = sidecars.into_iter().map(|sidecar| {
+            let library = Arc::clone(&library);
+            let source = source.clone();
+            async move {
+                let uid = node_uid(&sidecar.volume_id, &sidecar.link_id);
+                match library
+                    .reauthenticating(&sidecar.share_id, || source.open(&sidecar.share_id, &uid))
+                    .await
+                {
+                    Ok(stream) => {
+                        stream.warm_edges();
+                        Some((sidecar, stream))
+                    }
+                    Err(error) => {
+                        tracing::warn!(%error, "open subtitle {}", sidecar.name);
+                        None
+                    }
+                }
+            }
+        });
+        futures::future::join_all(opening)
+            .await
+            .into_iter()
+            .flatten()
+            .collect()
+    }
+
     /// How far into the file `target` resumes, as a fraction of its running
     /// time — known from the last time it played.
     fn resume_fraction(&self, target: &PlaybackTarget) -> Option<f64> {
diff --git a/crates/pstr-app/src/playback.rs b/crates/pstr-app/src/playback.rs
index 101e19b..c80c504 100644
--- a/crates/pstr-app/src/playback.rs
+++ b/crates/pstr-app/src/playback.rs
@@ -35,8 +35,8 @@ use pstr_core::catalog::CatalogNode;
 use pstr_core::library::{Episode, Title};
 use pstr_core::prefs::PlaybackPrefs;
 use pstr_player::{
-    Chapter, ChapterRole, EndReason, Player, PlayerConfig, PlayerEvent, Track, TrackKind,
-    VideoOutput,
+    Chapter, ChapterRole, EndReason, Player, PlayerConfig, PlayerEvent, StreamHandle, Track,
+    TrackKind, VideoOutput,
 };
 use pstr_stream::VideoStream;
 
@@ -530,6 +530,15 @@ fn run(
         }
     };
 
+    // Opened while mpv opens the video, and added once it has: an external
+    // track belongs to the file loaded at the time.
+    let mut sidecars = Some(engine.runtime().spawn({
+        let engine = engine.clone();
+        let target = target.clone();
+        async move { engine.open_sidecars(&target).await }
+    }));
+    let mut subtitles: Vec<StreamHandle> = Vec::new();
+
     let mut position = target.resume_at.unwrap_or(0.0);
     let mut duration: Option<f64> = None;
     let mut watched = false;
@@ -558,6 +567,10 @@ fn run(
         match &event {
             PlayerEvent::FileLoaded => {
                 duration = player.duration();
+                if let Some(opening) = sidecars.take() {
+                    let opened = engine.runtime().block_on(opening).unwrap_or_default();
+                    subtitles = add_sidecars(&engine, &target, &player, opened);
+                }
                 // The first moment there is a track list to read: mpv has
                 // demuxed the file and made its own default selection. Put the
                 // title's own choice over it before the menus are told, so they
@@ -607,6 +620,7 @@ fn run(
     // the other `Arc`, and mpv must be destroyed there, on the thread whose
     // OpenGL context its render context was built against.
     drop(handle);
+    drop(subtitles);
     drop(player);
 
     engine.release(
@@ -721,6 +735,47 @@ fn restore_tracks(player: &Player, show: &pstr_core::catalog::TitleTrackPrefs) {
     }
 }
 
+/// Hand mpv the subtitle files paired with the video it has just loaded.
+///
+/// One is turned on only when subtitles are on and the video has none of its
+/// own playing — a file's own track was chosen by name and language already,
+/// and an external one is the fallback, not an override.
+fn add_sidecars(
+    engine: &Engine,
+    target: &PlaybackTarget,
+    player: &Player,
+    opened: Vec<(pstr_core::catalog::Sidecar, VideoStream)>,
+) -> Vec<StreamHandle> {
+    let config = from_prefs(&engine.playback_prefs(), target.track_prefs.as_deref());
+    let playing = player
+        .tracks()
+        .iter()
+        .any(|track| track.kind == TrackKind::Subtitle && track.selected);
+    let (sidecars, streams): (Vec<_>, Vec<_>) = opened.into_iter().unzip();
+    let select = (config.subtitles && !playing)
+        .then(|| {
+            pstr_core::catalog::preferred_sidecar(&sidecars, config.subtitle_language.as_deref())
+        })
+        .flatten();
+    sidecars
+        .iter()
+        .zip(streams)
+        .enumerate()
+        .filter_map(|(index, (sidecar, stream))| {
+            let title = sidecar.title.as_deref().unwrap_or("External");
+            player
+                .add_subtitle(
+                    stream,
+                    title,
+                    sidecar.language.as_deref(),
+                    select == Some(index),
+                )
+                .inspect_err(|error| tracing::warn!(%error, "add subtitle {}", sidecar.name))
+                .ok()
+        })
+        .collect()
+}
+
 /// Tell the UI what the file contains and what of it is playing.
 fn emit_tracks(engine: &Engine, id: u64, player: &Player) {
     engine.emit(Event::Player {
diff --git a/crates/pstr-cli/src/main.rs b/crates/pstr-cli/src/main.rs
index 0bd8b00..99b7dd9 100644
--- a/crates/pstr-cli/src/main.rs
+++ b/crates/pstr-cli/src/main.rs
@@ -9,7 +9,7 @@ use anyhow::{Context, Result};
 use clap::{Parser, Subcommand};
 use proton_sdk::ids::{LinkId, NodeUid, VolumeId};
 use pstr_core::account::{PlaceKind, SignIn};
-use pstr_core::catalog::{Catalog, build_rows};
+use pstr_core::catalog::{Catalog, build_rows, build_sidecars};
 use pstr_core::config::AppDirs;
 use pstr_core::shares::AccountFolder;
 use pstr_core::sync::WatchSync;
@@ -425,6 +425,9 @@ async fn run(runtime: std::sync::Arc<tokio::runtime::Runtime>) -> Result<()> {
 
                 catalog
                     .replace_share(&share_id, &rows)
+                    .and_then(|()| {
+                        catalog.replace_sidecars(&share_id, &build_sidecars(&share_id, &nodes))
+                    })
                     .with_context(|| format!("store {share_id}"))?;
 
                 println!(
diff --git a/crates/pstr-core/src/catalog.rs b/crates/pstr-core/src/catalog.rs
index 097521a..774d066 100644
--- a/crates/pstr-core/src/catalog.rs
+++ b/crates/pstr-core/src/catalog.rs
@@ -24,7 +24,7 @@ use crate::metadata::{
 use crate::naming::{self, ParsedName};
 
 /// Bump when adding a migration.
-pub const SCHEMA_VERSION: i64 = 11;
+pub const SCHEMA_VERSION: i64 = 12;
 
 const MIGRATION_V1: &str = r#"
 CREATE TABLE nodes (
@@ -225,6 +225,23 @@ CREATE TABLE share_crawls (
 );
 "#;
 
+/// Subtitle files beside a video, which the crawl used to drop with the
+/// `.nfo` files. Rebuilt by every crawl, like `nodes`; a subtitle belongs to
+/// one video, the one it was paired with by name.
+const MIGRATION_V12: &str = r#"
+CREATE TABLE sidecars (
+    share_id       TEXT NOT NULL,
+    link_id        TEXT NOT NULL,
+    volume_id      TEXT NOT NULL,
+    video_link_id  TEXT NOT NULL,
+    name           TEXT NOT NULL,
+    language       TEXT,
+    title          TEXT,
+    PRIMARY KEY (share_id, link_id)
+);
+CREATE INDEX sidecars_by_video ON sidecars (share_id, video_link_id);
+"#;
+
 /// How old a share's last crawl may be before an app looks again on its own.
 /// Long enough that a launch rarely costs a crawl; short enough that a new
 /// episode turns up the same day.
@@ -329,6 +346,21 @@ pub struct CatalogNode {
     pub parsed: ParsedName,
 }
 
+/// A subtitle file paired with the video beside it. See [`build_sidecars`].
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Sidecar {
+    pub share_id: String,
+    pub link_id: String,
+    pub volume_id: String,
+    /// The video this subtitle is for.
+    pub video_link_id: String,
+    pub name: String,
+    /// The [`crate::language::LANGUAGES`] tag its name states, if any.
+    pub language: Option<String>,
+    /// What else its name says about it — "forced", "SDH" — for the picker.
+    pub title: Option<String>,
+}
+
 /// Where playback left off.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct WatchState {
@@ -459,6 +491,12 @@ impl Catalog {
             tx.pragma_update(None, "user_version", 11)?;
             tx.commit()?;
         }
+        if version < 12 {
+            let tx = self.conn.transaction()?;
+            tx.execute_batch(MIGRATION_V12)?;
+            tx.pragma_update(None, "user_version", 12)?;
+            tx.commit()?;
+        }
 
         Ok(())
     }
@@ -547,6 +585,59 @@ impl Catalog {
         Ok(())
     }
 
+    /// Replace one share's subtitle files with `sidecars`.
+    ///
+    /// Apart from [`Self::replace_share`] rather than inside it: a subtitle
+    /// left over from the crawl before is one that fails to open, quietly,
+    /// which is no reason to make every caller of that pass these along.
+    pub fn replace_sidecars(&mut self, share_id: &str, sidecars: &[Sidecar]) -> Result<()> {
+        let tx = self.conn.transaction()?;
+        tx.execute(
+            "DELETE FROM sidecars WHERE share_id = ?1",
+            params![share_id],
+        )?;
+        {
+            let mut insert = tx.prepare(
+                "INSERT OR REPLACE INTO sidecars (
+                     share_id, link_id, volume_id, video_link_id, name, language, title
+                 ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
+            )?;
+            for sidecar in sidecars {
+                insert.execute(params![
+                    share_id,
+                    sidecar.link_id,
+                    sidecar.volume_id,
+                    sidecar.video_link_id,
+                    sidecar.name,
+                    sidecar.language,
+                    sidecar.title,
+                ])?;
+            }
+        }
+        tx.commit()?;
+        Ok(())
+    }
+
+    /// The subtitle files paired with one video, in name order.
+    pub fn sidecars(&self, share_id: &str, video_link_id: &str) -> Result<Vec<Sidecar>> {
+        let mut select = self.conn.prepare_cached(
+            "SELECT share_id, link_id, volume_id, video_link_id, name, language, title
+             FROM sidecars WHERE share_id = ?1 AND video_link_id = ?2 ORDER BY name",
+        )?;
+        let rows = select.query_map(params![share_id, video_link_id], |row| {
+            Ok(Sidecar {
+                share_id: row.get(0)?,
+                link_id: row.get(1)?,
+                volume_id: row.get(2)?,
+                video_link_id: row.get(3)?,
+                name: row.get(4)?,
+                language: row.get(5)?,
+                title: row.get(6)?,
+            })
+        })?;
+        Ok(rows.collect::<rusqlite::Result<_>>()?)
+    }
+
     /// Record that a crawl of `share_id` failed, keeping what the last
     /// finished one stored.
     pub fn record_crawl_failure(&self, share_id: &str, error: &str) -> Result<()> {
@@ -670,6 +761,10 @@ impl Catalog {
             params![share_id],
         )?;
         tx.execute("DELETE FROM nodes WHERE share_id = ?1", params![share_id])?;
+        tx.execute(
+            "DELETE FROM sidecars WHERE share_id = ?1",
+            params![share_id],
+        )?;
         tx.execute(
             "DELETE FROM offline_files WHERE share_id = ?1",
             params![share_id],
@@ -1509,6 +1604,182 @@ pub fn build_rows(share_id: &str, nodes: &[proton_drive_rs::Node]) -> Vec<Catalo
         .collect()
 }
 
+/// Pair each subtitle file in a crawl with the video it is for.
+///
+/// By name, the way every player looks for one, in the three layouts shares
+/// actually have:
+///
+/// ```text
+/// Show/Season 01/S01E01.mkv + S01E01.srt, S01E01.en.srt, S01E01.en.forced.ass
+/// Show/Season 01/Subs/S01E01.en.srt          a subtitles folder beside the videos
+/// Film (2020)/Subs/Film (2020)/2_English.srt a folder per video inside that
+/// ```
+///
+/// A subtitle whose name starts with no video's is still paired when its
+/// folder holds one video only — `Film/film.mkv` beside `English.srt`. One
+/// that matches nothing is left out: offering it under the wrong episode is
+/// worse than not offering it.
+pub fn build_sidecars(share_id: &str, nodes: &[proton_drive_rs::Node]) -> Vec<Sidecar> {
+    use std::collections::HashMap;
+
+    let by_link: HashMap<&str, &proton_drive_rs::Node> = nodes
+        .iter()
+        .map(|node| (node.uid.link_id.as_str(), node))
+        .collect();
+    let parent_of = |node: &proton_drive_rs::Node| {
+        node.parent_uid
+            .as_ref()
+            .and_then(|uid| by_link.get(uid.link_id.as_str()).copied())
+    };
+    let mut videos: HashMap<&str, Vec<(&proton_drive_rs::Node, &str)>> = HashMap::new();
+    for node in nodes {
+        if !node.is_folder()
+            && naming::is_video_file(&node.name)
+            && let Some(parent) = &node.parent_uid
+        {
+            videos
+                .entry(parent.link_id.as_str())
+                .or_default()
+                .push((node, stem(&node.name)));
+        }
+    }
+
+    let mut sidecars: Vec<Sidecar> = nodes
+        .iter()
+        .filter(|node| !node.is_folder() && naming::is_subtitle_file(&node.name))
+        .filter_map(|node| {
+            let own = stem(&node.name);
+            let parent = parent_of(node)?;
+            let (video, rest) = if is_subtitles_folder(&parent.name) {
+                // `Subs/S01E01.en.srt`, for the videos beside `Subs`.
+                beside(
+                    videos.get(parent.parent_uid.as_ref()?.link_id.as_str())?,
+                    own,
+                )?
+            } else if let Some(holder) = parent_of(parent)
+                && is_subtitles_folder(&holder.name)
+            {
+                // `Subs/<video>/2_English.srt`: the folder is named for the video.
+                let candidates = videos.get(holder.parent_uid.as_ref()?.link_id.as_str())?;
+                let (video, _) = candidates
+                    .iter()
+                    .find(|(_, video)| video.eq_ignore_ascii_case(&parent.name))?;
+                (*video, own)
+            } else {
+                beside(videos.get(node.parent_uid.as_ref()?.link_id.as_str())?, own)?
+            };
+            let (language, title) = describe_subtitle(rest);
+            Some(Sidecar {
+                share_id: share_id.to_owned(),
+                link_id: node.uid.link_id.to_string(),
+                volume_id: node.uid.volume_id.to_string(),
+                video_link_id: video.uid.link_id.to_string(),
+                name: node.name.clone(),
+                language,
+                title,
+            })
+        })
+        .collect();
+    sidecars.sort_by(|a, b| (&a.video_link_id, &a.name).cmp(&(&b.video_link_id, &b.name)));
+    sidecars
+}
+
+/// Which of a video's subtitle files to turn on when the video itself has
+/// no subtitle playing: the first in the preferred language, or with no
+/// preference the first of all. One in no stated language is taken over
+/// nothing, since it is most often the only one there is.
+///
+/// Never one in another language: a viewer who asked for English subtitles
+/// and gets German ones has not been helped.
+pub fn preferred_sidecar(sidecars: &[Sidecar], language: Option<&str>) -> Option<usize> {
+    let Some(wanted) = language else {
+        return (!sidecars.is_empty()).then_some(0);
+    };
+    sidecars
+        .iter()
+        .position(|sidecar| {
+            sidecar
+                .language
+                .as_deref()
+                .is_some_and(|have| crate::language::same_language(wanted, have))
+        })
+        .or_else(|| {
+            sidecars
+                .iter()
+                .position(|sidecar| sidecar.language.is_none())
+        })
+}
+
+/// A file name without its extension.
+fn stem(name: &str) -> &str {
+    name.rsplit_once('.').map_or(name, |(stem, _)| stem)
+}
+
+fn is_subtitles_folder(name: &str) -> bool {
+    ["subs", "sub", "subtitles", "subtitle"]
+        .iter()
+        .any(|known| known.eq_ignore_ascii_case(name.trim()))
+}
+
+/// Which of the videos in one folder a subtitle named `own` is for, and what
+/// its name says past the video's.
+///
+/// The longest video name the subtitle's starts with, followed by a dot or
+/// nothing: `S01E1.en` is not `S01E10`'s. Failing that, the only video there.
+fn beside<'a, 'b>(
+    videos: &[(&'a proton_drive_rs::Node, &str)],
+    own: &'b str,
+) -> Option<(&'a proton_drive_rs::Node, &'b str)> {
+    let lower = own.to_lowercase();
+    let named = videos
+        .iter()
+        .filter_map(|(video, name)| {
+            let name = name.to_lowercase();
+            if lower == name {
+                Some((*video, name.len(), ""))
+            } else if lower.starts_with(&format!("{name}.")) {
+                // Lowercasing keeps the length of what these names hold;
+                // `get` covers the names where it does not.
+                Some((*video, name.len(), own.get(name.len() + 1..)?))
+            } else {
+                None
+            }
+        })
+        .max_by_key(|(_, length, _)| *length)
+        .map(|(video, _, rest)| (video, rest));
+    named.or(match videos {
+        [(video, _)] => Some((*video, own)),
+        _ => None,
+    })
+}
+
+/// The language and the rest of what a subtitle's name says past its video's:
+/// `en.forced` is English, "forced"; `2_English_SDH` is English, "SDH".
+///
+/// The last word naming a language is the language — in `Film.2020.English`
+/// the words before it are the film's. Numbers are an index, not a title.
+fn describe_subtitle(rest: &str) -> (Option<String>, Option<String>) {
+    let words: Vec<&str> = rest
+        .split(['.', '_', ' ', '-', '(', ')', '[', ']'])
+        .filter(|word| !word.is_empty())
+        .collect();
+    let found = words
+        .iter()
+        .enumerate()
+        .rev()
+        .find_map(|(index, word)| crate::language::language_tag(word).map(|tag| (index, tag)));
+    let title_words: Vec<&str> = words
+        .iter()
+        .enumerate()
+        .filter(|(index, word)| {
+            Some(*index) != found.map(|(at, _)| at) && !word.chars().all(|c| c.is_ascii_digit())
+        })
+        .map(|(_, word)| *word)
+        .collect();
+    let title = (!title_words.is_empty()).then(|| title_words.join(" "));
+    (found.map(|(_, tag)| tag.to_owned()), title)
+}
+
 /// What a file's ancestors say about it.
 #[derive(Debug, Default)]
 struct Ancestry {
@@ -2321,6 +2592,30 @@ mod tests {
         assert!(catalog.crawls().expect("read").is_empty());
     }
 
+    #[test]
+    fn migration_v12_opens_a_v11_catalog() {
+        let conn = Connection::open_in_memory().expect("open");
+        for migration in [
+            MIGRATION_V1,
+            MIGRATION_V2,
+            MIGRATION_V3,
+            MIGRATION_V4,
+            MIGRATION_V5,
+            MIGRATION_V6,
+            MIGRATION_V7,
+            MIGRATION_V8,
+            MIGRATION_V9,
+            MIGRATION_V10,
+            MIGRATION_V11,
+        ] {
+            conn.execute_batch(migration).expect("migrate");
+        }
+        conn.pragma_update(None, "user_version", 11)
+            .expect("set version");
+        let catalog = Catalog::from_connection(conn).expect("upgrade");
+        assert!(catalog.sidecars("s", "a").expect("read").is_empty());
+    }
+
     /// A file keeps the moment it first appeared across recrawls, and one
     /// that was there before this was recorded reads as 0.
     #[test]
@@ -3082,4 +3377,128 @@ mod tests {
             None
         );
     }
+
+    // ---- build_sidecars: subtitles paired by name --------------------------
+
+    fn paired(sidecars: &[Sidecar]) -> Vec<(&str, &str, Option<&str>, Option<&str>)> {
+        sidecars
+            .iter()
+            .map(|sidecar| {
+                (
+                    sidecar.name.as_str(),
+                    sidecar.video_link_id.as_str(),
+                    sidecar.language.as_deref(),
+                    sidecar.title.as_deref(),
+                )
+            })
+            .collect()
+    }
+
+    #[test]
+    fn a_subtitle_named_after_a_video_is_paired_with_it_and_says_its_language() {
+        let nodes = vec![
+            root(),
+            folder("s1", Some("root"), "Season 01"),
+            video("ep1", "s1", "S01E1.mkv"),
+            video("ep10", "s1", "S01E10.mkv"),
+            video("plain", "s1", "S01E1.srt"),
+            video("en", "s1", "S01E10.en.srt"),
+            video("forced", "s1", "S01E10.eng.forced.ass"),
+            video("nfo", "s1", "S01E10.nfo"),
+        ];
+        assert_eq!(
+            paired(&build_sidecars("share", &nodes)),
+            vec![
+                ("S01E1.srt", "ep1", None, None),
+                ("S01E10.en.srt", "ep10", Some("eng"), None),
+                ("S01E10.eng.forced.ass", "ep10", Some("eng"), Some("forced")),
+            ]
+        );
+    }
+
+    #[test]
+    fn a_subtitles_folder_beside_the_videos_holds_theirs() {
+        let nodes = vec![
+            root(),
+            folder("film", Some("root"), "Film (2020)"),
+            video("video", "film", "Film (2020).mkv"),
+            folder("subs", Some("film"), "Subs"),
+            video("de", "subs", "Film (2020).German.srt"),
+            folder("per-video", Some("subs"), "Film (2020)"),
+            video("sdh", "per-video", "3_English_SDH.srt"),
+        ];
+        assert_eq!(
+            paired(&build_sidecars("share", &nodes)),
+            vec![
+                ("3_English_SDH.srt", "video", Some("eng"), Some("SDH")),
+                ("Film (2020).German.srt", "video", Some("ger"), None),
+            ]
+        );
+    }
+
+    /// One video in the folder can only be the one; two leave a subtitle
+    /// named after neither unpaired rather than guessed.
+    #[test]
+    fn a_subtitle_named_after_no_video_is_paired_only_when_its_folder_has_one() {
+        let nodes = vec![
+            root(),
+            folder("film", Some("root"), "Film"),
+            video("video", "film", "film.1080p.mkv"),
+            video("english", "film", "English.srt"),
+            folder("s1", Some("root"), "Season 01"),
+            video("ep1", "s1", "S01E01.mkv"),
+            video("ep2", "s1", "S01E02.mkv"),
+            video("stray", "s1", "English.srt"),
+        ];
+        assert_eq!(
+            paired(&build_sidecars("share", &nodes)),
+            vec![("English.srt", "video", Some("eng"), None)]
+        );
+    }
+
+    #[test]
+    fn a_recrawl_replaces_a_shares_subtitles_and_removing_the_share_drops_them() {
+        let mut catalog = Catalog::in_memory().expect("open");
+        let sidecar = |link: &str| Sidecar {
+            share_id: "s".into(),
+            link_id: link.into(),
+            volume_id: "vol".into(),
+            video_link_id: "a".into(),
+            name: format!("{link}.srt"),
+            language: Some("eng".into()),
+            title: None,
+        };
+        catalog
+            .replace_sidecars("s", &[sidecar("old")])
+            .expect("crawl");
+        catalog
+            .replace_sidecars("s", &[sidecar("new")])
+            .expect("recrawl");
+        assert_eq!(
+            catalog.sidecars("s", "a").expect("read"),
+            vec![sidecar("new")]
+        );
+        catalog.remove_share("s").expect("remove");
+        assert!(catalog.sidecars("s", "a").expect("read").is_empty());
+    }
+
+    #[test]
+    fn the_subtitle_turned_on_is_one_in_the_preferred_language_and_never_another() {
+        let sidecar = |language: Option<&str>| Sidecar {
+            share_id: "s".into(),
+            link_id: "l".into(),
+            volume_id: "v".into(),
+            video_link_id: "a".into(),
+            name: "a.srt".into(),
+            language: language.map(str::to_owned),
+            title: None,
+        };
+        let ger_eng = [sidecar(Some("ger")), sidecar(Some("eng"))];
+        assert_eq!(preferred_sidecar(&ger_eng, Some("en")), Some(1));
+        assert_eq!(preferred_sidecar(&ger_eng, None), Some(0));
+        assert_eq!(preferred_sidecar(&ger_eng, Some("jpn")), None);
+        let ger_unknown = [sidecar(Some("ger")), sidecar(None)];
+        assert_eq!(preferred_sidecar(&ger_unknown, Some("eng")), Some(1));
+        assert_eq!(preferred_sidecar(&[], None), None);
+    }
 }
diff --git a/crates/pstr-core/src/naming.rs b/crates/pstr-core/src/naming.rs
index f9deee9..b770f93 100644
--- a/crates/pstr-core/src/naming.rs
+++ b/crates/pstr-core/src/naming.rs
@@ -813,6 +813,15 @@ pub fn is_video_file(name: &str) -> bool {
         .is_some_and(|(_, ext)| VIDEO_EXTENSIONS.contains(&ext.to_ascii_lowercase().as_str()))
 }
 
+/// Subtitle formats mpv reads from a file of their own.
+const SUBTITLE_EXTENSIONS: &[&str] = &["srt", "ass", "ssa", "vtt"];
+
+/// Whether a filename names a subtitle file a video can be paired with.
+pub fn is_subtitle_file(name: &str) -> bool {
+    name.rsplit_once('.')
+        .is_some_and(|(_, ext)| SUBTITLE_EXTENSIONS.contains(&ext.to_ascii_lowercase().as_str()))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/crates/pstr-player/src/player.rs b/crates/pstr-player/src/player.rs
index 5c7792b..6e1c611 100644
--- a/crates/pstr-player/src/player.rs
+++ b/crates/pstr-player/src/player.rs
@@ -342,6 +342,28 @@ impl Player {
         Ok(handle)
     }
 
+    /// Add a subtitle file to the one playing, read through the same
+    /// registry as the video, so mpv never learns where either came from.
+    ///
+    /// Only once the video has loaded: mpv attaches an external track to the
+    /// file open now. `select` turns it on; otherwise it waits in the list.
+    /// The handle keeps it readable, like [`Self::play`]'s.
+    pub fn add_subtitle(
+        &self,
+        stream: VideoStream,
+        title: &str,
+        language: Option<&str>,
+        select: bool,
+    ) -> Result<StreamHandle> {
+        let handle = self.registry.publish(stream);
+        let url = handle.url();
+        let flag = if select { "select" } else { "auto" };
+        let mut args = vec![url.as_str(), flag, title];
+        args.extend(language);
+        self.mpv.command("sub-add", &args)?;
+        Ok(handle)
+    }
+
     /// Start playing a stream `seconds` in.
     ///
     /// Through mpv's `start` option rather than a seek once the file has