Files
OrbitTv/docs/metadata-and-matching.md
T
pauljdandClaude Opus 5.5 ceea2f2017
pauljd/davidson-ci: Davidson CI / quality (push) Failing after 2m55s
pauljd/davidson-ci: Davidson CI / ai-review (push) Successful in 1m11s
Record full import results and metadata coverage
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-11-01 20:37:58 +00:00

8.2 KiB

Orbit TV metadata and matching

Approved direction, 1 November 2026. This is a design: none of it is built yet except the coverage check described in the roadmap.

Metadata and tagging strategy

Orbit keeps only a thin record per title today, so the plan is to widen it and keep Orbit's own tags in a separate layer. The Emby data itself is never edited.

What the code keeps now

Record Fields held Used for
SampleItem ID, title, type, minutes, format, duration Everything scheduled
AfterDarkMovie Item, year, rating, up to 8 genres Film review for 102
SeriesCandidate ID, title, year, rating, variant label Series review for 103
EpisodeCandidate ID, title, season, episode, duration, media label Episode order
ScheduledMedia Item, locked source ID, locked duration The timeline

What to add

Need Field Status
Better identification Original title, stable external IDs, collections Not requested today
Classification Genres on all types, tags, studios, overview Genres on films only
Era and order Year, original air date, season, episode Partly held
Suitability Content rating Held on films and series, not used for any filtering
Curation Cast, director Not requested today

Emby's documentation has to confirm each field's request name, and the coverage check in the roadmap shows how often the provider fills them.

Orbit's own tag layer

Each tag records its value, where it came from and how sure Orbit is. Sources rank in this order: user-confirmed, curated title rule, provider metadata, then inferred. Only user-confirmed tags count as settled, and an unknown value stays unknown.

Example Format and genre tags Primary preset Possible crossover
The X-Files Scripted, science fiction, supernatural mystery, cult, 1990s Paradox Orbit Sci-Fi
CSI Scripted, crime, procedural, forensic Evidence None
Blue Planet Documentary, wildlife, ocean, natural history Terra Odyssey
The 'Burbs Film, horror comedy, cult, 1980s Orbit VHS After Dark
Dragon Ball Z Animated series, action anime, fantasy Vortex None

Documentary versus scripted, and traditional versus CGI, need explicit values including "unknown". Ring X adds promotion, show type, event date and PPV status.

Three limits in today's code

  • Saved data cap: saved setup is capped at 512 KiB in one encrypted file, too small for a real library. The catalogue needs its own encrypted local store, chosen after the audit gives real record sizes.
  • Hardcoded channels: saved state has fixed slots for one, toonami and afterDark, and only accepts 101 to 103. Adding channel 26 needs a generic channel list with a tested migration.
  • Listed isn't playable: a catalogue entry only proves a title is listed. Keep separate states for listed, source checked and failed, and recheck when tuning, as Orbit does now.

Library scale

The checks on Paul's account reported 98,441 films, 34,103 series and 1,053,303 episodes on 1 November 2026. At 200 titles a page, films and series take about 663 requests. Episodes would take over 5,000, which is why they aren't imported up front. The design has to hold at that size:

  • Storage: an indexed on-device database, not the saved setup file. Android's built-in SQLite needs no new dependency.
  • Import: paged in the background, resumable, throttled, and stopped by a rate-limit reply. Films and series first.
  • Episodes: fetched per series only when a series is approved or needed, not imported up front.
  • Refresh: changes since the last import, never a full re-read.
  • Matching: filter with provider queries or the local index, so no screen or schedule step scans the whole library in memory.
  • Review screens: show a short ranked list, with paging for the rest.
  • Playback checks: only for titles going onto a channel, never for the whole library.

Measured on 1 November 2026: the full import finished at 132,545 titles (98,441 films, 34,104 series) in a 33.9 MB database, about 261 bytes per title. The second half, 67,145 titles, took 1,588 seconds with a slowest page of 57 seconds. Page size never dropped below 200, so the longer timeout was enough; a 15-second limit would have failed on those pages.

What the metadata supports

Early samples show genres and external IDs on nearly every film and series (3,998 and 3,997 of the first 4,000 imported), so stable-ID identification and genre matching look reliable. Studios and cast are usable but not complete, and episodes carry little of their own, so they should inherit from their series. Coverage across all 132,545 titles: year 132,111, external IDs 131,287, date 129,182, genres 129,119, rating 86,863, tags 58,224. So about a third of titles have no rating, which matters for profiles and mature channels: an unrated title can't be treated as safe.

Recommendation engine design

The engine should behave like a TV programmer who proposes and waits: it suggests from rules it can explain, and nothing reaches a channel until the viewer accepts it. It runs on the box, with no AI or cloud service.

Pipeline

Each stage builds on what Orbit has, and the existing clock schedule stays as the last step.

Stage What happens What it reuses or needs
A. Discovery Paged read of what this account can see EmbyClient, with new paging and rate-limit handling
B. Normalise Map provider data to one internal record, keeping provider IDs separate Existing validation and text limits
C. Identify Match by stable ID first, then title and year. Handle remakes, alternate titles and duplicates. labelSeriesVariants already flags duplicate entries
D. Tag Add Orbit tags with source and confidence New, from the tag layer above
E. Match Rank titles against each preset New
F. Review Show a short list with ticks and reasons Existing review screens as the pattern
G. Schedule Feed confirmed titles to the clock engine SampleChannel, with new limits
H. Repeats Rotation and cooldowns scaled to library size New

How matching decides

Titles are ranked in tiers, because exact weights shouldn't be picked before the audit shows real data.

  1. User decisions: explicit picks and exclusions always win.
  2. Hard filters: rating, playability and low-confidence identity can remove a title, whatever else matches.
  3. Curated title match: the preset's own list and verified aliases.
  4. Strong signals: format or subgenre, such as documentary or police procedural.
  5. Medium signals: genre, era and stated preference.
  6. Context signals: cast, studio or franchise, where they make sense for that preset.
  7. Weak signals: keyword similarity can add a candidate but never justify one alone.

Every suggestion stores the reasons behind it, so "why recommended" reads directly from them. A three-film channel can't follow the repeat rules of a large one, and Orbit shouldn't create empty schedules to satisfy a rule.

What the viewer sees

A suggestion is short and gives its reason: "Paradox: 8 matching series found. These match your interest in cult science fiction and supernatural mysteries."

  • Controls: add, remove, replace, ignore and view why.
  • Missing titles: shown unticked and marked unavailable, never implied as playable.
  • Dismissals: remembered, so a dismissed idea doesn't keep returning without a new reason.
  • Discovery: familiar favourites, balanced discovery or surprise me. This is a possible later preference.
  • Remote use: a few items per screen, since the viewer is using a D-pad from the sofa.

Privacy and control

Orbit learns only from what the viewer chooses or enables: favourite genres and decades, accepted and rejected suggestions, explicit exclusions, and optional local watch history. Personalisation can be turned off, its history cleared, and it never adds channels or titles by itself after setup. There are no engagement goals.

OrbitOffice uses the same matching for events such as an Arnie Triple Bill or a Wrestling PPV Night. Events are optional, never scheduled automatically, name missing films honestly and can be switched off entirely.