@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-domain/src/naming/marker.rs

@@ -0,0 +1,215 @@
+//! Season/episode marker detection (`S01E02`, `s1e2`, `S01E02-E03`, `1x02`) and
+//! season-folder recognition the cues that classify a file as a TV episode.
+
+/// A season/episode marker found in a filename stem, plus the byte span it
+/// occupies (so the caller can split the stem into show-vs-episode-title parts).
+#[derive(Debug, PartialEq, Eq)]
+pub(super) struct Marker {
+    pub(super) season: u32,
+    pub(super) episode: u32,
+    pub(super) episode_end: Option<u32>,
+    pub(super) start: usize,
+    pub(super) end: usize,
+}
+
+/// Find the first plausible season/episode marker in a filename stem.
+pub(super) fn find_marker(stem: &str) -> Option<Marker> {
+    let lower = stem.to_ascii_lowercase();
+    let b = lower.as_bytes();
+
+    // Form 1: SxxEyy [(-|E)zz]
+    for i in 0..b.len() {
+        if let Some(m) = match_sxxeyy(b, i) {
+            return Some(m);
+        }
+    }
+
+    // Form 2: NxNN (e.g. 1x02). Bounded season to avoid matching resolutions.
+    for i in 0..b.len() {
+        if let Some(m) = match_nxnn(b, i) {
+            return Some(m);
+        }
+    }
+
+    None
+}
+
+// Try to match Form 1 (`SxxEyy` with an optional multi-episode tail) starting
+// at byte `i`. Returns the marker when the bytes at `i` form a valid one.
+fn match_sxxeyy(b: &[u8], i: usize) -> Option<Marker> {
+    if b[i] != b's' {
+        return None;
+    }
+    let (sd, sn) = read_digits(b, i + 1);
+    if sd == 0 {
+        return None;
+    }
+    let j = i + 1 + sd;
+    if j >= b.len() || b[j] != b'e' {
+        return None;
+    }
+    let (ed, en) = read_digits(b, j + 1);
+    if ed == 0 || !plausible(sn, en) {
+        return None;
+    }
+
+    let mut k = j + 1 + ed;
+    let mut episode_end = None;
+    // Optional multi-episode tail: "-E03", "-03", "E03".
+    let mut m = k;
+    if m < b.len() && b[m] == b'-' {
+        m += 1;
+    }
+    if m < b.len() && b[m] == b'e' {
+        m += 1;
+    }
+    if m > k {
+        let (ed2, en2) = read_digits(b, m);
+        if ed2 > 0 {
+            episode_end = Some(en2);
+            k = m + ed2;
+        }
+    }
+    Some(Marker {
+        season: sn,
+        episode: en,
+        episode_end,
+        start: i,
+        end: k,
+    })
+}
+
+// Try to match Form 2 (`NxNN`, e.g. `1x02`) starting at byte `i`. The season is
+// bounded and must not be preceded by an alphanumeric (to avoid resolutions).
+fn match_nxnn(b: &[u8], i: usize) -> Option<Marker> {
+    if !b[i].is_ascii_digit() {
+        return None;
+    }
+    let (sd, sn) = read_digits(b, i);
+    let before_ok = i == 0 || !b[i - 1].is_ascii_alphanumeric();
+    if !before_ok || sd < 1 || sn > 50 {
+        return None;
+    }
+    let xpos = i + sd;
+    if xpos >= b.len() || b[xpos] != b'x' {
+        return None;
+    }
+    let (ed, en) = read_digits(b, xpos + 1);
+    if ed < 1 || !plausible(sn, en) {
+        return None;
+    }
+    Some(Marker {
+        season: sn,
+        episode: en,
+        episode_end: None,
+        start: i,
+        end: xpos + 1 + ed,
+    })
+}
+
+// Guard against resolutions / wild numbers being read as season/episode.
+fn plausible(season: u32, episode: u32) -> bool {
+    season <= 100 && episode <= 9999
+}
+
+// Read a run of ASCII digits from `start`; returns (count, parsed value).
+fn read_digits(b: &[u8], start: usize) -> (usize, u32) {
+    let mut n = 0;
+    while start + n < b.len() && b[start + n].is_ascii_digit() {
+        n += 1;
+    }
+    if n == 0 {
+        return (0, 0);
+    }
+    let value: u32 = std::str::from_utf8(&b[start..start + n])
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(0);
+    (n, value)
+}
+
+/// "Season 01", "Saison 1", "Specials", "S01" → a season folder, not a show.
+pub(super) fn is_season_folder(name: &str) -> bool {
+    let l = name.trim().to_ascii_lowercase();
+    l == "specials"
+        || l.starts_with("season")
+        || l.starts_with("saison")
+        || (l.starts_with('s') && l.len() <= 4 && l[1..].bytes().all(|c| c.is_ascii_digit()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sxxeyy_basic() {
+        let m = find_marker("Show.S01E02").unwrap();
+        assert_eq!((m.season, m.episode, m.episode_end), (1, 2, None));
+        // The reported span exactly covers the marker text.
+        assert_eq!(&"Show.S01E02"[m.start..m.end], "S01E02");
+    }
+
+    #[test]
+    fn multi_episode_dash_concatenated_and_bare() {
+        let dash = find_marker("Show.S01E02-E03").unwrap();
+        assert_eq!(
+            (dash.season, dash.episode, dash.episode_end),
+            (1, 2, Some(3))
+        );
+        // "S01E02E03" (no separator) still yields the second episode.
+        let cat = find_marker("Show.S01E02E03").unwrap();
+        assert_eq!(cat.episode_end, Some(3));
+        // "S01E02-03": a bare trailing number after the dash.
+        let bare = find_marker("Show.S01E02-03").unwrap();
+        assert_eq!(bare.episode_end, Some(3));
+    }
+
+    #[test]
+    fn nxnn_form() {
+        let m = find_marker("Firefly 1x02 The Train Job").unwrap();
+        assert_eq!((m.season, m.episode, m.episode_end), (1, 2, None));
+    }
+
+    #[test]
+    fn resolution_is_not_a_marker() {
+        // 1920x1080: season 1920 is out of the NxNN bound, so no marker.
+        assert!(find_marker("Heat 1995 1920x1080").is_none());
+    }
+
+    #[test]
+    fn implausible_season_rejected() {
+        // s200e01: season 200 > 100 fails the plausibility guard.
+        assert!(find_marker("Thing.S200E01").is_none());
+    }
+
+    #[test]
+    fn half_a_marker_is_not_a_marker() {
+        assert!(find_marker("Show S01 Complete").is_none());
+        assert!(find_marker("Kill Bill Vol 2").is_none());
+        assert!(find_marker("Show 1x").is_none());
+    }
+
+    #[test]
+    fn no_marker_returns_none() {
+        assert!(find_marker("The Matrix 1999").is_none());
+    }
+
+    #[test]
+    fn nxnn_rejected_after_alphanumeric() {
+        // The digit run must sit at a boundary; "abc1x02" is part of a token.
+        assert!(find_marker("abc1x02").is_none());
+    }
+
+    #[test]
+    fn season_folder_recognition() {
+        assert!(is_season_folder("Season 01"));
+        assert!(is_season_folder("season 1"));
+        assert!(is_season_folder("Saison 2"));
+        assert!(is_season_folder("Specials"));
+        assert!(is_season_folder("S01"));
+        assert!(is_season_folder("s3"));
+        assert!(!is_season_folder("The Office"));
+        // Too long for the bare-S form.
+        assert!(!is_season_folder("s2000"));
+    }
+}

package/rust/kroma-domain/src/naming/mod.rs

@@ -0,0 +1,283 @@
+//! Plex-style filename / folder parsing.
+//!
+//! Decides whether a file is a movie or a TV episode, and pulls out the show
+//! name, season, episode (incl. multi-episode files), titles and year using
+//! the same cues Plex/Jellyfin rely on:
+//!   * `S01E02`, `s1e2`, `S01E02-E03`, `1x02` season/episode markers
+//!   * the top-level folder under a library root as the *show* identity
+//!     (`Library/Show Name/Season 01/Show - S01E02.mkv`)
+//!   * `Movie Title (2017)` movie folders / filenames
+//!   * release-junk stripping for clean titles (resolution, source, codec, group)
+//!
+//! This is pure domain logic: filename → parsed identity, no I/O.
+
+mod marker;
+mod title;
+
+use std::path::Path;
+
+use marker::{find_marker, is_season_folder};
+use title::clean_episode_title;
+pub use title::{clean_title, parse_year};
+
+/// Outcome of parsing one media file path.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Parsed {
+    Movie {
+        title: String,
+        year: Option<u32>,
+    },
+    Episode {
+        show_title: String,
+        show_year: Option<u32>,
+        season: u32,
+        episode: u32,
+        episode_end: Option<u32>,
+        episode_title: Option<String>,
+    },
+}
+
+/// Parse a media file located at `path`, relative to its library `root`.
+pub fn parse(root: &Path, path: &Path) -> Parsed {
+    let stem = path
+        .file_stem()
+        .and_then(std::ffi::OsStr::to_str)
+        .unwrap_or("Untitled");
+
+    // Directory components between the library root and the file.
+    let dirs: Vec<String> = path
+        .parent()
+        .and_then(|p| p.strip_prefix(root).ok())
+        .map(|rel| {
+            rel.components()
+                .filter_map(|c| c.as_os_str().to_str())
+                .map(ToString::to_string)
+                .collect()
+        })
+        .unwrap_or_default();
+
+    if let Some(m) = find_marker(stem) {
+        // Show identity: the top-level folder under the library root, else the
+        // text before the marker in the filename (flat layout).
+        let (show_title, show_year) = match dirs.first() {
+            Some(folder) if !is_season_folder(folder) => (clean_title(folder), parse_year(folder)),
+            _ => {
+                let before = &stem[..m.start];
+                (clean_title(before), parse_year(before))
+            }
+        };
+        let show_title = if show_title.is_empty() {
+            clean_title(stem)
+        } else {
+            show_title
+        };
+
+        let after = stem.get(m.end..).unwrap_or("");
+        let episode_title = {
+            let t = clean_episode_title(after);
+            if t.is_empty() {
+                None
+            } else {
+                Some(t)
+            }
+        };
+
+        Parsed::Episode {
+            show_title,
+            show_year,
+            season: m.season,
+            episode: m.episode,
+            episode_end: m.episode_end,
+            episode_title,
+        }
+    } else {
+        // Movie: prefer the filename when it carries a year, else fall back to a
+        // `Title (Year)` parent folder (the canonical Plex movie layout).
+        let parent = dirs.last().map(String::as_str);
+        let (title, year) = if let Some(y) = parse_year(stem) {
+            (clean_title(stem), Some(y))
+        } else if let Some((p, y)) = parent.and_then(|p| parse_year(p).map(|y| (p, y))) {
+            (clean_title(p), Some(y))
+        } else {
+            (clean_title(stem), None)
+        };
+        Parsed::Movie { title, year }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::Path;
+
+    fn p(root: &str, path: &str) -> Parsed {
+        parse(Path::new(root), Path::new(path))
+    }
+
+    #[test]
+    fn an_episode_under_a_bare_season_folder_falls_back_to_the_filename() {
+        assert_eq!(
+            p("/tv", "/tv/Season 01/S01E02.mkv"),
+            Parsed::Episode {
+                show_title: "S01E02".into(),
+                show_year: None,
+                season: 1,
+                episode: 2,
+                episode_end: None,
+                episode_title: None,
+            }
+        );
+    }
+
+    #[test]
+    fn a_movie_with_no_year_anywhere_keeps_the_filename_title() {
+        assert_eq!(
+            p("/m", "/m/Movies/Inception.mkv"),
+            Parsed::Movie {
+                title: "Inception".into(),
+                year: None
+            }
+        );
+    }
+
+    #[test]
+    fn movie_in_year_folder() {
+        assert_eq!(
+            p(
+                "/m",
+                "/m/Blade Runner 2049 (2017)/Blade Runner 2049 (2017) 2160p BluRay x265.mkv"
+            ),
+            Parsed::Movie {
+                title: "Blade Runner 2049".into(),
+                year: Some(2017)
+            }
+        );
+    }
+
+    #[test]
+    fn movie_flat_dotted() {
+        assert_eq!(
+            p("/m", "/m/The.Matrix.1999.1080p.BluRay.x264-GROUP.mp4"),
+            Parsed::Movie {
+                title: "The Matrix".into(),
+                year: Some(1999)
+            }
+        );
+    }
+
+    #[test]
+    fn movie_title_from_folder_when_file_is_generic() {
+        assert_eq!(
+            p("/m", "/m/Inception (2010)/movie.mkv"),
+            Parsed::Movie {
+                title: "Inception".into(),
+                year: Some(2010)
+            }
+        );
+    }
+
+    #[test]
+    fn episode_show_season_layout() {
+        assert_eq!(
+            p(
+                "/tv",
+                "/tv/The Office (2005)/Season 02/The Office - S02E01 - The Dundies.mkv"
+            ),
+            Parsed::Episode {
+                show_title: "The Office".into(),
+                show_year: Some(2005),
+                season: 2,
+                episode: 1,
+                episode_end: None,
+                episode_title: Some("The Dundies".into()),
+            }
+        );
+    }
+
+    #[test]
+    fn episode_multi() {
+        match p("/tv", "/tv/Show/Season 1/Show.S01E02-E03.mkv") {
+            Parsed::Episode {
+                season,
+                episode,
+                episode_end,
+                ..
+            } => {
+                assert_eq!((season, episode, episode_end), (1, 2, Some(3)));
+            }
+            other => panic!("expected episode, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn episode_nxnn_flat() {
+        match p("/tv", "/tv/Firefly - 1x02 - The Train Job.mkv") {
+            Parsed::Episode {
+                show_title,
+                season,
+                episode,
+                ..
+            } => {
+                assert_eq!((show_title.as_str(), season, episode), ("Firefly", 1, 2));
+            }
+            other => panic!("expected episode, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn resolution_not_mistaken_for_episode() {
+        // 1920x1080 must NOT parse as season 1920 / episode 1080.
+        assert!(matches!(
+            p("/m", "/m/Heat 1995 1920x1080.mkv"),
+            Parsed::Movie { .. }
+        ));
+    }
+
+    #[test]
+    fn dictionary_words_survive_in_titles() {
+        // "french"/"uncut" are release tags AND real words; the authoritative
+        // `(YYYY)` boundary must win so the title is not clipped at them.
+        assert_eq!(
+            clean_title("The French Dispatch (2021) [EN+FR] Bluray-1080p"),
+            "The French Dispatch"
+        );
+        assert_eq!(clean_title("Uncut Gems (2019) WEBDL-1080p"), "Uncut Gems");
+        // Bare-year layout, still must keep the dictionary word.
+        assert_eq!(
+            clean_title("The French Connection 1971 1080p BluRay"),
+            "The French Connection"
+        );
+    }
+
+    #[test]
+    fn french_dub_tag_stripped_when_adjacent_to_junk() {
+        // No year: FRENCH sits right before a hard marker → both drop.
+        assert_eq!(
+            clean_title("Le Fabuleux Destin FRENCH DVDRip XviD"),
+            "Le Fabuleux Destin"
+        );
+    }
+
+    #[test]
+    fn leading_year_recovers_title() {
+        // A year at the start must not wipe the whole title to "".
+        assert_eq!(
+            clean_title("2018 - LaserGame - Indian Forest"),
+            "LaserGame - Indian Forest"
+        );
+    }
+
+    #[test]
+    fn the_french_dispatch_parses_with_year() {
+        assert_eq!(
+            p(
+                "/m",
+                "/m/The French Dispatch (2021)/The French Dispatch (2021) [EN+FR] Bluray-1080p.mkv"
+            ),
+            Parsed::Movie {
+                title: "The French Dispatch".into(),
+                year: Some(2021)
+            }
+        );
+    }
+}