@kromatv/sdk 0.1.40-canary.0

package/rust/kroma-db/src/localize/test_support.rs

@@ -0,0 +1,91 @@
+use crate::testing::TempPool;
+use crate::translations::TransData;
+
+use kroma_domain::{CastMember, Kind, MediaItem, Metadata, Show};
+
+pub(super) fn pool() -> TempPool {
+    crate::testing::temp_pool("loc")
+}
+
+pub(super) fn meta(title: &str) -> Metadata {
+    Metadata {
+        provider: "tmdb",
+        tmdb_id: 1,
+        imdb_id: None,
+        title: Some(title.into()),
+        tagline: Some("orig tagline".into()),
+        overview: Some("orig overview".into()),
+        release_date: None,
+        genres: vec!["Original".into()],
+        tmdb_genre_ids: vec![878],
+        rating: None,
+        certification: None,
+        poster_url: None,
+        backdrop_url: None,
+        logo_url: None,
+        theme_url: None,
+        cast: vec![CastMember {
+            name: "Actor".into(),
+            tmdb_id: None,
+            character: Some("Orig Char".into()),
+            profile_url: None,
+        }],
+        crew: vec![],
+        keywords: vec![],
+        tvdb_id: None,
+        tmdb_url: "x".into(),
+    }
+}
+
+pub(super) fn item(id: &str, kind: Kind) -> MediaItem {
+    MediaItem {
+        id: id.into(),
+        title: "T".into(),
+        kind,
+        year: None,
+        duration_ms: None,
+        container: "mkv".into(),
+        video: None,
+        audio: None,
+        audio_tracks: Vec::new(),
+        subtitles: Vec::new(),
+        library: "lib".into(),
+        show_id: None,
+        show_title: None,
+        season: None,
+        episode: None,
+        episode_end: None,
+        episode_title: None,
+        rel_path: None,
+        added_at: "t".into(),
+        metadata: Some(meta("Original")),
+        abs_path: None,
+        files: Vec::new(),
+        default_file_id: None,
+        markers: Vec::new(),
+        audio_analysis: None,
+    }
+}
+
+pub(super) fn show(id: &str) -> Show {
+    Show {
+        id: id.into(),
+        title: "T".into(),
+        year: None,
+        library: "lib".into(),
+        season_count: 0,
+        episode_count: 0,
+        video: None,
+        added_at: "t".into(),
+        metadata: Some(meta("Show EN")),
+        progress: None,
+    }
+}
+
+pub(super) fn td(title: &str, characters: Vec<Option<String>>) -> TransData {
+    TransData {
+        title: Some(title.into()),
+        characters,
+        ..Default::default()
+    }
+}

package/rust/kroma-db/src/localize.rs

@@ -0,0 +1,105 @@
+//! Locale overlay for served catalog entities.
+//!
+//! During the transition the `metadata` blob still carries the household
+//! (primary) language; these helpers overlay the request locale's translation
+//! on top so each user sees the catalog in *their* language. The overlay only
+//! touches the localized text (title/tagline/overview/genres/character names)
+//! the invariant art/ids/people already on the blob are left untouched. Applied
+//! at the API boundary, right before serialization, keyed off `Accept-Language`.
+//!
+//! Resolution falls back requested lang -> `en` -> any (see
+//! [`super::translations::resolve_many`]); an entity with no stored translation
+//! keeps its blob text, so this is always safe to call.
+
+use super::translations::{self, TransData};
+use super::*;
+
+use kroma_domain::{CastMember, Metadata, Season, Show};
+
+mod items;
+mod shows;
+
+#[cfg(test)]
+mod test_support;
+
+pub use items::*;
+pub use shows::*;
+
+/// Overlay `locale` onto one show's metadata blob, which is where the generated
+/// poster and card routes read a show's art from.
+pub fn overlay_show_metadata(
+    pool: &Pool,
+    show_id: &str,
+    meta: &mut Metadata,
+    locale: &str,
+) -> Result<()> {
+    let conn = pool.get()?;
+    if let Some(tr) =
+        translations::resolve_many(&conn, metadata_core::SHOW, &[show_id], locale)?.get(show_id)
+    {
+        apply(Some(meta), tr);
+    }
+    Ok(())
+}
+
+// Overlay one season's cast character names from its `season_cast` translation.
+fn overlay_season_cast(
+    conn: &Connection,
+    show_id: &str,
+    season: &mut Season,
+    locale: &str,
+) -> Result<()> {
+    if season.cast.is_empty() {
+        return Ok(());
+    }
+    let sc_id = format!("{show_id}:{}", season.number);
+    if let Some(t) =
+        translations::resolve_many(conn, "season_cast", &[sc_id.as_str()], locale)?.get(&sc_id)
+    {
+        apply_characters(&mut season.cast, &t.characters);
+    }
+    Ok(())
+}
+
+// Overlay the localized text fields onto an item's metadata (no-op when the item
+// has no blob metadata yet, i.e. not enriched).
+fn apply(meta: Option<&mut Metadata>, tr: &TransData) {
+    let Some(meta) = meta else { return };
+    if tr.title.is_some() {
+        meta.title = tr.title.clone();
+    }
+    if tr.tagline.is_some() {
+        meta.tagline = tr.tagline.clone();
+    }
+    if tr.overview.is_some() {
+        meta.overview = tr.overview.clone();
+    }
+    if !tr.genres.is_empty() {
+        meta.genres = tr.genres.clone();
+    }
+    if tr.poster_url.is_some() {
+        meta.poster_url = tr.poster_url.clone();
+    }
+    if tr.logo_url.is_some() {
+        meta.logo_url = tr.logo_url.clone();
+    }
+    apply_characters(&mut meta.cast, &tr.characters);
+}
+
+// A show's metadata overlay (same fields; shows carry no per-title cast here).
+fn apply_show(show: &mut Show, tr: &TransData) {
+    apply(show.metadata.as_mut(), tr);
+    if let Some(t) = &tr.title {
+        show.title = t.clone();
+    }
+}
+
+// Overlay localized character names onto a cast list, aligned by index (the
+// translation was written in the same TMDB cast order the core was stored in).
+fn apply_characters(cast: &mut [CastMember], characters: &[Option<String>]) {
+    for (member, ch) in cast.iter_mut().zip(characters.iter()) {
+        if ch.is_some() {
+            member.character = ch.clone();
+        }
+    }
+}

package/rust/kroma-db/src/markers.rs

@@ -0,0 +1,203 @@
+//! Episode segment markers: one row per `(item_id, kind)`, bounds in ms.
+
+use super::*;
+use kroma_domain::{Marker, MarkerKind};
+
+fn kind_str(kind: MarkerKind) -> &'static str {
+    match kind {
+        MarkerKind::Intro => "intro",
+        MarkerKind::Credits => "credits",
+    }
+}
+
+fn kind_from_str(s: &str) -> Option<MarkerKind> {
+    match s {
+        "intro" => Some(MarkerKind::Intro),
+        "credits" => Some(MarkerKind::Credits),
+        _ => None,
+    }
+}
+
+pub fn item_ids_with_markers(pool: &Pool) -> Result<std::collections::HashSet<String>> {
+    let conn = pool.get()?;
+    let mut stmt = conn.prepare("SELECT DISTINCT item_id FROM markers")?;
+    let rows = stmt.query_map([], |r| r.get::<_, String>(0))?;
+    Ok(rows.collect::<rusqlite::Result<_>>()?)
+}
+
+/// An intro-less episode also has none: combine with the ledger.
+pub fn has_markers(pool: &Pool, item_id: &str) -> Result<bool> {
+    let conn = pool.get()?;
+    let n: i64 = conn.query_row(
+        "SELECT COUNT(*) FROM markers WHERE item_id=?1",
+        params![item_id],
+        |r| r.get(0),
+    )?;
+    Ok(n > 0)
+}
+
+/// Unknown kinds are skipped, so a future kind cannot break older clients.
+pub fn markers_for_item(conn: &Connection, item_id: &str) -> rusqlite::Result<Vec<Marker>> {
+    let mut stmt = conn.prepare(
+        "SELECT kind, start_ms, end_ms FROM markers WHERE item_id = ?1 ORDER BY start_ms",
+    )?;
+    let rows = stmt.query_map(params![item_id], |r| {
+        Ok((
+            r.get::<_, String>(0)?,
+            r.get::<_, i64>(1)?,
+            r.get::<_, i64>(2)?,
+        ))
+    })?;
+    let mut out = Vec::new();
+    for r in rows {
+        let (kind, start, end) = r?;
+        if let Some(kind) = kind_from_str(&kind) {
+            out.push(Marker {
+                kind,
+                start_ms: start.max(0) as u64,
+                end_ms: end.max(0) as u64,
+            });
+        }
+    }
+    Ok(out)
+}
+
+/// [`markers_for_item`] over many items; ids absent from the result have none.
+pub(crate) fn markers_for_items(
+    conn: &Connection,
+    item_ids: &[&str],
+) -> rusqlite::Result<std::collections::HashMap<String, Vec<Marker>>> {
+    let mut out: std::collections::HashMap<String, Vec<Marker>> = std::collections::HashMap::new();
+    for chunk in item_ids.chunks(super::IN_CHUNK) {
+        let ph = vec!["?"; chunk.len()].join(",");
+        let mut stmt = conn.prepare(&format!(
+            "SELECT item_id, kind, start_ms, end_ms FROM markers \
+             WHERE item_id IN ({ph}) ORDER BY start_ms",
+        ))?;
+        let rows = stmt.query_map(rusqlite::params_from_iter(chunk.iter()), |r| {
+            Ok((
+                r.get::<_, String>(0)?,
+                r.get::<_, String>(1)?,
+                r.get::<_, i64>(2)?,
+                r.get::<_, i64>(3)?,
+            ))
+        })?;
+        for row in rows {
+            let (item_id, kind, start, end) = row?;
+            if let Some(kind) = kind_from_str(&kind) {
+                out.entry(item_id).or_default().push(Marker {
+                    kind,
+                    start_ms: start.max(0) as u64,
+                    end_ms: end.max(0) as u64,
+                });
+            }
+        }
+    }
+    Ok(out)
+}
+
+/// Overwrites only when `source` ranks at least as high as the stored one
+/// (`manual` > `fingerprint` > `chapters`).
+pub fn set_marker(
+    pool: &Pool,
+    item_id: &str,
+    kind: MarkerKind,
+    start_ms: u64,
+    end_ms: u64,
+    source: &str,
+) -> Result<()> {
+    let conn = pool.get()?;
+    conn.execute(
+        "INSERT INTO markers (item_id, kind, start_ms, end_ms, source, updated_at) \
+         VALUES (?1, ?2, ?3, ?4, ?5, datetime('now')) \
+         ON CONFLICT(item_id, kind) DO UPDATE SET \
+           start_ms = excluded.start_ms, end_ms = excluded.end_ms, \
+           source = excluded.source, updated_at = excluded.updated_at \
+         WHERE (CASE excluded.source WHEN 'manual' THEN 3 WHEN 'fingerprint' THEN 2 WHEN 'chapters' THEN 1 ELSE 0 END) \
+            >= (CASE markers.source WHEN 'manual' THEN 3 WHEN 'fingerprint' THEN 2 WHEN 'chapters' THEN 1 ELSE 0 END)",
+        params![item_id, kind_str(kind), start_ms as i64, end_ms as i64, source],
+    )?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testing::TempPool;
+
+    fn pool_with_item() -> TempPool {
+        let pool = crate::testing::temp_pool("mark");
+        let conn = pool.get().unwrap();
+        conn.execute("INSERT INTO libraries (id,name,kind,path,added_at) VALUES ('lib','L','shows','/x','t')", []).unwrap();
+        conn.execute(
+            "INSERT INTO items (id,kind,title,container,library,added_at) VALUES ('e1','episode','Ep','mkv','lib','t')",
+            [],
+        )
+        .unwrap();
+        drop(conn);
+        pool
+    }
+
+    #[test]
+    fn set_read_and_order_markers() {
+        let p = pool_with_item();
+        assert!(!has_markers(&p, "e1").unwrap());
+        assert!(item_ids_with_markers(&p).unwrap().is_empty());
+
+        set_marker(&p, "e1", MarkerKind::Credits, 60_000, 65_000, "chapters").unwrap();
+        set_marker(&p, "e1", MarkerKind::Intro, 0, 5_000, "chapters").unwrap();
+
+        assert!(has_markers(&p, "e1").unwrap());
+        assert!(item_ids_with_markers(&p).unwrap().contains("e1"));
+
+        let conn = p.get().unwrap();
+        let markers = markers_for_item(&conn, "e1").unwrap();
+        assert_eq!(markers.len(), 2);
+        assert_eq!(markers[0].kind, MarkerKind::Intro);
+        assert_eq!(markers[0].start_ms, 0);
+        assert_eq!(markers[0].end_ms, 5_000);
+        assert_eq!(markers[1].kind, MarkerKind::Credits);
+
+        let batch = markers_for_items(&conn, &["e1", "ghost"]).unwrap();
+        assert_eq!(batch["e1"].len(), 2);
+        assert!(!batch.contains_key("ghost"));
+    }
+
+    #[test]
+    fn provenance_precedence() {
+        let p = pool_with_item();
+        set_marker(&p, "e1", MarkerKind::Intro, 0, 5_000, "fingerprint").unwrap();
+        // Lower-ranked source: must not clobber the fingerprint marker.
+        set_marker(&p, "e1", MarkerKind::Intro, 999, 1_000, "chapters").unwrap();
+        let conn = p.get().unwrap();
+        assert_eq!(markers_for_item(&conn, "e1").unwrap()[0].end_ms, 5_000);
+        drop(conn);
+
+        set_marker(&p, "e1", MarkerKind::Intro, 100, 200, "manual").unwrap();
+        let conn = p.get().unwrap();
+        let m = &markers_for_item(&conn, "e1").unwrap()[0];
+        assert_eq!((m.start_ms, m.end_ms), (100, 200));
+    }
+
+    #[test]
+    fn a_marker_kind_this_build_does_not_know_is_skipped_rather_than_fatal() {
+        let p = pool_with_item();
+        let conn = p.get().unwrap();
+        conn.execute_batch(
+            "INSERT INTO markers (item_id,kind,start_ms,end_ms,source,updated_at) VALUES ('e1','intro',0,30000,'chapters','t');\
+             INSERT INTO markers (item_id,kind,start_ms,end_ms,source,updated_at) VALUES ('e1','recap',30000,45000,'chapters','t');\
+             INSERT INTO markers (item_id,kind,start_ms,end_ms,source,updated_at) VALUES ('e1','credits',3500000,3600000,'chapters','t');",
+        )
+        .unwrap();
+
+        let markers = markers_for_item(&conn, "e1").unwrap();
+        assert_eq!(
+            markers.len(),
+            2,
+            "the future 'recap' kind is dropped, not surfaced"
+        );
+        assert_eq!(markers[0].kind, MarkerKind::Intro);
+        assert_eq!(markers[1].kind, MarkerKind::Credits);
+        assert_eq!(markers_for_items(&conn, &["e1"]).unwrap()["e1"].len(), 2);
+    }
+}

package/rust/kroma-db/src/media/person.rs

@@ -0,0 +1,213 @@
+//! There is no person table: cast and crew live in each title's `metadata`
+//! JSON, so a lookup reads every credit through SQLite's JSON1 and matches them
+//! in Rust. Folding is why it cannot be a `WHERE`: a slug has already lost the
+//! accents and punctuation an SQL comparison would need.
+
+use anyhow::Result;
+use rusqlite::Connection;
+
+use kroma_domain::people::{self, Credit, CreditedTitle, PersonMatch};
+use kroma_domain::slug::{slug_eq, slugify};
+
+use crate::Pool;
+
+const MOVIE_CREDITS: &str = "\
+    SELECT i.id, json_extract(c.value,'$.name'), json_extract(c.value,'$.tmdbId') \
+      FROM items i, json_each(i.metadata,'$.cast') c \
+     WHERE i.kind != 'episode' AND i.metadata IS NOT NULL \
+    UNION ALL \
+    SELECT i.id, json_extract(c.value,'$.name'), json_extract(c.value,'$.tmdbId') \
+      FROM items i, json_each(i.metadata,'$.crew') c \
+     WHERE i.kind != 'episode' AND i.metadata IS NOT NULL";
+
+const SHOW_CREDITS: &str = "\
+    SELECT s.id, json_extract(c.value,'$.name'), json_extract(c.value,'$.tmdbId') \
+      FROM shows s, json_each(s.metadata,'$.cast') c \
+     WHERE s.metadata IS NOT NULL \
+    UNION ALL \
+    SELECT s.id, json_extract(c.value,'$.name'), json_extract(c.value,'$.tmdbId') \
+      FROM shows s, json_each(s.metadata,'$.crew') c \
+     WHERE s.metadata IS NOT NULL";
+
+/// The person `lookup` names, with the movies and shows crediting them.
+/// `lookup` is a provider person id, a URL slug, or a display name in any
+/// casing; see [`people::resolve_person`] for which one answers. Episodes are
+/// excluded: they inherit their show's credits.
+pub fn resolve_person(pool: &Pool, lookup: &str) -> Result<Option<PersonMatch>> {
+    let want = slugify(lookup);
+    if want.is_empty() {
+        return Ok(None);
+    }
+    let id = lookup.parse::<u64>().ok();
+    // The id and the fold are both answered here so that a credit which is
+    // neither never becomes a `Credit`: `people::resolve_person` re-applies the
+    // same rules over the survivors, which is where the namesake tie-break lives.
+    let keep = |name: &str, credit_id: Option<u64>| {
+        (id.is_some() && credit_id == id) || slug_eq(name, &want)
+    };
+    let conn = pool.get()?;
+    let mut credits = read_credits(&conn, MOVIE_CREDITS, CreditedTitle::Movie, &keep)?;
+    credits.extend(read_credits(
+        &conn,
+        SHOW_CREDITS,
+        CreditedTitle::Show,
+        &keep,
+    )?);
+    Ok(people::resolve_person(credits, lookup))
+}
+
+fn read_credits(
+    conn: &Connection,
+    sql: &str,
+    title: fn(String) -> CreditedTitle,
+    keep: &dyn Fn(&str, Option<u64>) -> bool,
+) -> Result<Vec<Credit>> {
+    let mut stmt = conn.prepare(sql)?;
+    let mut rows = stmt.query([])?;
+    let mut credits = Vec::new();
+    // `get_ref` BORROWS out of the statement; `get` would build a String for
+    // every credit in the library before anything could reject it, and only a
+    // handful are ever the person being looked up.
+    while let Some(row) = rows.next()? {
+        let Ok(name) = row.get_ref(1)?.as_str() else {
+            continue;
+        };
+        let tmdb_id = row
+            .get_ref(2)?
+            .as_i64_or_null()?
+            .and_then(|id| u64::try_from(id).ok());
+        if !keep(name, tmdb_id) {
+            continue;
+        }
+        credits.push(Credit {
+            name: name.to_string(),
+            tmdb_id,
+            title: title(row.get::<_, String>(0)?),
+        });
+    }
+    Ok(credits)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    use crate::media::test_support::pool;
+    use crate::testing::TempPool;
+    use rusqlite::params;
+
+    type Credited<'a> = (&'a str, Option<u64>);
+
+    fn credits(cast: &[Credited], crew: &[Credited]) -> String {
+        let person = |(name, id): &Credited| serde_json::json!({"name": name, "tmdbId": id});
+        serde_json::json!({
+            "tmdbId": 1,
+            "tmdbUrl": "x",
+            "genres": [],
+            "cast": cast.iter().map(person).collect::<Vec<_>>(),
+            "crew": crew.iter().map(person).collect::<Vec<_>>(),
+        })
+        .to_string()
+    }
+
+    fn seeded_pool() -> TempPool {
+        let pool = pool();
+        let conn = pool.get().unwrap();
+        conn.execute(
+            "INSERT INTO libraries (id,name,kind,path,added_at) VALUES ('lib','L','movie','/x','t')",
+            [],
+        )
+        .unwrap();
+        let movie = |id: &str, cast: &[Credited], crew: &[Credited]| {
+            conn.execute(
+                "INSERT INTO items (id,kind,title,container,library,added_at,metadata) \
+                 VALUES (?1,'movie',?1,'mkv','lib','t',?2)",
+                params![id, credits(cast, crew)],
+            )
+            .unwrap();
+        };
+        movie(
+            "m1",
+            &[("Timothée Chalamet", Some(1234))],
+            &[("Denis Villeneuve", None)],
+        );
+        movie(
+            "m2",
+            &[("Emily Blunt", None)],
+            &[("Denis Villeneuve", None)],
+        );
+        conn.execute(
+            "INSERT INTO shows (id,library,title,added_at,metadata) VALUES ('s1','lib','S','t',?1)",
+            params![credits(&[("Adam Scott", None)], &[("Ben Stiller", None)])],
+        )
+        .unwrap();
+        conn.execute(
+            "INSERT INTO items (id,kind,title,container,library,show_id,season,episode,added_at,metadata) \
+             VALUES ('e1','episode','Ep1','mkv','lib','s1',1,1,'t',?1)",
+            params![credits(&[("Adam Scott", None)], &[])],
+        )
+        .unwrap();
+        drop(conn);
+        pool
+    }
+
+    #[test]
+    fn a_slug_finds_every_movie_and_show_crediting_the_person_it_names() {
+        let pool = seeded_pool();
+
+        let director = resolve_person(&pool, "denis-villeneuve").unwrap().unwrap();
+        let actor = resolve_person(&pool, "timothee-chalamet").unwrap().unwrap();
+
+        assert_eq!(director.name, "Denis Villeneuve");
+        assert_eq!(director.movie_ids, ["m1", "m2"]);
+        assert!(director.show_ids.is_empty());
+        assert_eq!(actor.movie_ids, ["m1"]);
+    }
+
+    #[test]
+    fn a_credit_on_a_show_never_drags_in_its_episodes() {
+        let pool = seeded_pool();
+
+        let found = resolve_person(&pool, "adam-scott").unwrap().unwrap();
+
+        assert_eq!(found.show_ids, ["s1"]);
+        assert!(found.movie_ids.is_empty());
+    }
+
+    #[test]
+    fn a_display_name_finds_what_its_slug_finds_so_older_clients_keep_working() {
+        let pool = seeded_pool();
+
+        let by_name = resolve_person(&pool, "Timothée Chalamet").unwrap();
+
+        assert_eq!(by_name, resolve_person(&pool, "timothee-chalamet").unwrap());
+    }
+
+    #[test]
+    fn a_stored_person_id_answers_on_its_own() {
+        let pool = seeded_pool();
+
+        let found = resolve_person(&pool, "1234").unwrap().unwrap();
+
+        assert_eq!(found.name, "Timothée Chalamet");
+        assert_eq!(found.tmdb_id, Some(1234));
+        assert_eq!(found.movie_ids, ["m1"]);
+    }
+
+    #[test]
+    fn a_credit_stored_before_ids_were_kept_reports_none() {
+        let pool = seeded_pool();
+
+        let found = resolve_person(&pool, "denis-villeneuve").unwrap().unwrap();
+
+        assert_eq!(found.tmdb_id, None);
+    }
+
+    #[test]
+    fn an_uncredited_or_blank_lookup_finds_nobody() {
+        let pool = seeded_pool();
+
+        assert!(resolve_person(&pool, "Nobody").unwrap().is_none());
+        assert!(resolve_person(&pool, "  ").unwrap().is_none());
+    }
+}