Skip to main content
← back to extensions

Film Library

@magistr/film-libraryv2026.10.25.10· MIT· 1d agoBEHAVIORSWORKFLOWS
01README

Multidimensional film catalog for a home server, built from a bounded SSH listing (no recursive find), name parsing, TMDB metadata, and Jev (TypeSafe System One) judgments.

  • scan — list each root to maxDepth levels in one SSH session, classify every entry (film / series / episode / collection member / subtitle / software / 3D models / archive / junk) and parse release names into title, alternative titles, year and technical tags (resolution, source, codec, HDR, audio, edition, language tags, group). Handles scene names, Cyrillic + English double titles, translit, and tracker noise.
  • names — Jev resolves each entry before TMDB is called: what kind of thing it is (film / series / concert / documentary / clip / not video) and which of the parser's readings (Russian title, English title, folder vs file parse) is the real title. Emits TMDB queries for confirmed films only.
  • resolve — accepts clear TMDB hits; Jev picks among the candidates of ambiguous searches. Writes the TMDB ids to enrich.
  • catalog — film facts, dimensions (genres, decades, countries, languages, directors, resolutions, sources, HDR, collections) and worklists: unmatched, non-film in film folders, library duplicates with keep-best hints, downloads already owned (or upgrades), downloads to import, series in the film library, non-film downloads.

Pairs with @magistr/tmdb (match + enrich) and @swamp/typesafe-ai + @webframp/typesafe-batch (Jev). Ships the @magistr/film-library-refresh workflow wiring the whole pipeline.

02Release Notes

2026.10.25.10

  • Repo-wide republish; no functional change.
03Behaviors1
@magistr/film-libraryv2026.10.25.10extensions/models/film_library.ts

Global Arguments

ArgumentTypeDescription
hoststringHost with the film shares (unraid)
sshUser?stringSSH user
fn scan()
List the film roots (bounded depth, one SSH session), classify and parse every entry, and write the inventory
fn names()
Resolve each entry's kind and title from Jev's answers (parser readings as fallback), write the TMDB search queries and the Jev name/kind questions still open
fn resolve()
Decide each searched film's TMDB id: clear search hits are accepted, ambiguous ones go to Jev; write the ids to enrich and the Jev questions still open
fn import()
Move downloaded films (files or folders under an incoming root) into a library root on the host, in one SSH session. Never overwrites: an existing destination is a conflict; a source already gone with the destination present counts as already imported. For torrent-backed downloads use the transmission model's relocate instead, so seeding follows the files
fn remove-downloads(path: string, libraryCopy: string)
Delete downloads that are already in the library. Each item names the download (under an incoming root, any depth) and its library copy (under a library root); the download is deleted only if the library copy exists at that moment. Torrent-backed downloads should go through the transmission model's remove-torrent instead
ArgumentTypeDescription
pathstring
libraryCopystring
fn catalog()
Join inventory, names, resolution and TMDB enrichment into film facts, dimensions, issue worklists and a summary

Resources

removals(infinite)— Outcome of deleting downloads already in the library (remove-downloads)
imports(infinite)— Outcome of moving downloads into the library (import)
inventory(infinite)— Every top-level entry of the film roots, classified and name-parsed
names(infinite)— Jev-resolved kind and title per entry, TMDB search queries, and the Jev name/kind batches still to ask
resolution(infinite)— Per-film TMDB id decisions, ids to enrich, and the Jev batches for ambiguous searches
film(infinite)— Film fact: one file or folder with parsed tags, resolved name and TMDB metadata
dimension(infinite)— Rollup dimension (genres / decades / countries / languages / directors / resolutions / sources / hdr / collections)
issues(infinite)— Worklists: unmatched, non-film in film folders, library duplicates, downloads already owned / to import, series in library, non-film downloads
library(infinite)— Catalog summary with counts, sizes and dimension cardinalities
04Workflows1
@magistr/film-library-refreshb8077fcc-f086-4042-b8d4-1c72c6395b90

Refresh the film catalog end to end, Jev first. scan lists /mnt/user/films/cinema and /mnt/user/downloads/complete (bounded depth, one SSH session) and parses every name into candidate readings. names emits the open Jev questions; Jev (TypeSafe System One via @webframp/typesafe-batch) classifies each entry (film / series / concert / documentary / clip / not video) and confirms which readings are the real title; names runs again and decides. tmdb match searches only the Jev-confirmed titles of fi

scanRead state: list and classify both roots; gate on a non-empty inventory with every root present.
1.scanfilms.scan
2.assert-inventory
names-preEmit the open Jev name and kind questions.
1.names-prefilms.names
jev-namesJev: kind of every entry, and which readings are the real title.
1.jev-kinds-${{ self.i }}jev.triage_batch
2.jev-names-${{ self.i }}jev.triage_batch
names-postDecide kinds and titles with Jev's answers; gate on having films to search.
1.names-postfilms.names
2.assert-names
matchTMDB search for every film's confirmed title.
1.tmdb-matchtmdb.match
2.assert-match
resolve-preAccept clear hits; emit Jev questions for ambiguous searches.
1.resolve-prefilms.resolve
jev-pairsJev: which TMDB candidate is this file (ambiguous searches only).
1.jev-pairs-${{ self.i }}jev.triage_batch
resolve-postDecide again with Jev's answers.
1.resolve-postfilms.resolve
enrichTMDB details for every decided id.
1.tmdb-enrichtmdb.enrich
catalogBuild facts, dimensions and worklists; gate on a written summary.
1.catalogfilms.catalog
2.assert-catalog
05Previous Versions9
2026.10.15.9MIT

2026.10.15.9

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.8MIT

2026.10.15.8

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.6MIT

2026.10.15.6

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.5MIT

2026.10.15.5

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.4MIT

2026.10.15.4

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.3MIT

2026.10.15.3

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.2MIT

2026.10.15.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.1MIT

2026.10.15.1

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.08.1MIT

2026.10.08.1

  • Initial release: scan (bounded SSH listing, classification, release-name parsing), resolve (Jev-decided TMDB ids, Jev kind classification, open question batches), catalog (film facts, dimensions, worklists, summary) and the @magistr/film-library-refresh workflow.
06Stats
A
100 / 100
Downloads
15
Archive size
58.7 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
Repository
https://github.com/umag/swamp-workspace
07Platforms
08Labels
#films#movies#library#catalog#tmdb#unraid