jellyplex-gen 0.1.0__tar.gz

jellyplex_gen-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026, Stefan Schönberger <stefan@sniner.dev>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

jellyplex_gen-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: jellyplex-gen
+Version: 0.1.0
+Summary: Generate plausible test media libraries in Plex or Jellyfin format
+Author: Stefan Schönberger
+Author-email: Stefan Schönberger <stefan@sniner.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# jellyplex-gen
+
+Generate plausible test media libraries in Plex or Jellyfin format.
+
+A sibling project to [jellyplex-sync](https://github.com/sniner/jellyplex-sync):
+where `jellyplex-sync` converts between media library formats, `jellyplex-gen`
+produces realistic-looking source material to test it (or anything else that
+operates on Plex/Jellyfin libraries) against.
+
+Generated libraries consist of placeholder files (0-byte by default, or
+pseudorandom bytes up to a configurable per-file maximum) arranged according
+to the chosen format's naming conventions. A format-neutral JSON manifest is
+written alongside, describing the logical content of the library.
+
+## Status
+
+Early. Plex format only, flat hierarchy, single resolution variant per movie.
+Designed so other formats and structures can be added without touching the
+existing code paths.
+
+## Quick start
+
+```bash
+uv run jellyplex-gen plex --seed=hello --movies=50 --out=./testlib
+```
+
+The same `--seed` always produces the same library. Seeds are arbitrary
+alphanumeric strings — they get hashed to an integer internally, so
+reproducibility doesn't depend on Python's `PYTHONHASHSEED`.
+
+To get just the manifest (no files written):
+
+```bash
+uv run jellyplex-gen manifest --seed=hello --movies=50
+```
+
+For copy-semantics or content-aware testing, fill files with up to N bytes
+of pseudorandom content (default is 0, i.e. empty files):
+
+```bash
+uv run jellyplex-gen plex --seed=hello --movies=20 --max-content-size=4096 --out=./testlib
+```
+
+File contents are seeded per-file from the manifest seed and the file's
+relative path, so the same `--seed` + same `--max-content-size` always
+yield byte-identical libraries.
+
+## Architecture
+
+The generator is built around three swappable abstractions:
+
+- **`TitleSource`** — supplies movie titles. The default
+  `CuratedTitleSource` mixes word pools and hand-crafted titles. The
+  protocol leaves room for other sources without touching anything else.
+- **`NamingConvention`** — format-specific: turns a logical movie into
+  directory and file names. Currently only `PlexNamingConvention`.
+- **`LibraryStructure`** — orthogonal to format: decides the parent path
+  of each movie directory. Currently only `FlatLibraryStructure`.
+
+Generation is two-phase: `build_manifest()` produces a format-neutral
+description, `materialize()` writes the actual filesystem layout. The
+manifest can be saved, loaded, and diffed independently of any concrete
+layout.
+
+## License
+
+BSD-3-Clause. See `LICENSE`.

jellyplex_gen-0.1.0/README.md

@@ -0,0 +1,67 @@
+# jellyplex-gen
+
+Generate plausible test media libraries in Plex or Jellyfin format.
+
+A sibling project to [jellyplex-sync](https://github.com/sniner/jellyplex-sync):
+where `jellyplex-sync` converts between media library formats, `jellyplex-gen`
+produces realistic-looking source material to test it (or anything else that
+operates on Plex/Jellyfin libraries) against.
+
+Generated libraries consist of placeholder files (0-byte by default, or
+pseudorandom bytes up to a configurable per-file maximum) arranged according
+to the chosen format's naming conventions. A format-neutral JSON manifest is
+written alongside, describing the logical content of the library.
+
+## Status
+
+Early. Plex format only, flat hierarchy, single resolution variant per movie.
+Designed so other formats and structures can be added without touching the
+existing code paths.
+
+## Quick start
+
+```bash
+uv run jellyplex-gen plex --seed=hello --movies=50 --out=./testlib
+```
+
+The same `--seed` always produces the same library. Seeds are arbitrary
+alphanumeric strings — they get hashed to an integer internally, so
+reproducibility doesn't depend on Python's `PYTHONHASHSEED`.
+
+To get just the manifest (no files written):
+
+```bash
+uv run jellyplex-gen manifest --seed=hello --movies=50
+```
+
+For copy-semantics or content-aware testing, fill files with up to N bytes
+of pseudorandom content (default is 0, i.e. empty files):
+
+```bash
+uv run jellyplex-gen plex --seed=hello --movies=20 --max-content-size=4096 --out=./testlib
+```
+
+File contents are seeded per-file from the manifest seed and the file's
+relative path, so the same `--seed` + same `--max-content-size` always
+yield byte-identical libraries.
+
+## Architecture
+
+The generator is built around three swappable abstractions:
+
+- **`TitleSource`** — supplies movie titles. The default
+  `CuratedTitleSource` mixes word pools and hand-crafted titles. The
+  protocol leaves room for other sources without touching anything else.
+- **`NamingConvention`** — format-specific: turns a logical movie into
+  directory and file names. Currently only `PlexNamingConvention`.
+- **`LibraryStructure`** — orthogonal to format: decides the parent path
+  of each movie directory. Currently only `FlatLibraryStructure`.
+
+Generation is two-phase: `build_manifest()` produces a format-neutral
+description, `materialize()` writes the actual filesystem layout. The
+manifest can be saved, loaded, and diffed independently of any concrete
+layout.
+
+## License
+
+BSD-3-Clause. See `LICENSE`.

jellyplex_gen-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "jellyplex-gen"
+version = "0.1.0"
+description = "Generate plausible test media libraries in Plex or Jellyfin format"
+authors = [{ name = "Stefan Schönberger", email = "stefan@sniner.dev" }]
+requires-python = ">=3.11"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = []
+
+[project.scripts]
+jellyplex-gen = "jellyplex_gen.cli.main:main"
+
+[dependency-groups]
+dev = ["pytest>=8.3.5,<9"]
+
+[tool.uv]
+default-groups = "all"
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+testpaths = ["tests"]
+
+[tool.pyright]
+typeCheckingMode = "standard"
+useLibraryCodeForTypes = true
+venvPath = "."
+venv = ".venv"
+
+[tool.ruff]
+line-length = 96
+
+[tool.ruff.lint]
+ignore = ["E402"]
+per-file-ignores = { "__init__.py" = ["F401"] }
+extend-select = [
+    "I",   # isort
+    "UP",  # pyupgrade
+    "SIM", # flake8-simplify
+    "B",   # flake8-bugbear
+]

jellyplex_gen-0.1.0/src/jellyplex_gen/__init__.py

@@ -0,0 +1,22 @@
+from .generator import build_manifest, materialize
+from .manifest import LogicalMovie, Manifest, Variant
+from .naming import NamingConvention, PlexNamingConvention
+from .seed import rng_from_seed, seed_to_int
+from .structure import FlatLibraryStructure, LibraryStructure
+from .titles import CuratedTitleSource, TitleSource
+
+__all__ = [
+    "CuratedTitleSource",
+    "FlatLibraryStructure",
+    "LibraryStructure",
+    "LogicalMovie",
+    "Manifest",
+    "NamingConvention",
+    "PlexNamingConvention",
+    "TitleSource",
+    "Variant",
+    "build_manifest",
+    "materialize",
+    "rng_from_seed",
+    "seed_to_int",
+]

jellyplex_gen-0.1.0/src/jellyplex_gen/cli/main.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from ..generator import build_manifest, materialize
+from ..naming import PlexNamingConvention
+from ..structure import FlatLibraryStructure
+from ..titles import CuratedTitleSource
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="jellyplex-gen",
+        description="Generate plausible test media libraries in Plex or Jellyfin format.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    plex = sub.add_parser("plex", help="Generate a Plex-format library on disk.")
+    _common_args(plex)
+    plex.add_argument("--out", type=Path, required=True, help="Output directory.")
+    plex.add_argument(
+        "--max-content-size",
+        type=int,
+        default=0,
+        help="Maximum per-file content size in bytes (default: 0 = empty files).",
+    )
+
+    mf = sub.add_parser("manifest", help="Emit only the manifest JSON to stdout.")
+    _common_args(mf)
+
+    args = parser.parse_args()
+
+    manifest = build_manifest(
+        seed=args.seed,
+        movie_count=args.movies,
+        title_source=CuratedTitleSource(),
+    )
+
+    if args.command == "manifest":
+        sys.stdout.write(manifest.to_json() + "\n")
+        return
+
+    out: Path = args.out
+    out.mkdir(parents=True, exist_ok=True)
+    materialize(
+        manifest,
+        out,
+        naming=PlexNamingConvention(),
+        structure=FlatLibraryStructure(),
+        max_content_size=args.max_content_size,
+    )
+    manifest.save(out / "manifest.json")
+    print(
+        f"Generated {len(manifest.movies)} movies in {out} (seed={args.seed!r})",
+        file=sys.stderr,
+    )
+
+
+def _common_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--seed",
+        type=str,
+        default="default",
+        help="Alphanumeric seed for reproducibility.",
+    )
+    p.add_argument(
+        "--movies",
+        type=int,
+        default=20,
+        help="Number of movies to generate.",
+    )
+
+
+if __name__ == "__main__":
+    main()

jellyplex_gen-0.1.0/src/jellyplex_gen/generator.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import random
+from pathlib import Path
+
+from .manifest import LogicalMovie, Manifest, Variant
+from .naming import NamingConvention
+from .seed import rng_from_seed
+from .structure import LibraryStructure
+from .titles import TitleSource
+
+_RESOLUTIONS = ("480i", "576i", "720p", "1080p", "2160p")
+_RESOLUTION_WEIGHTS = (1, 1, 2, 5, 3)
+_EDITIONS = ("Director's Cut", "Extended", "Theatrical", "Remastered", "Unrated")
+
+
+def build_manifest(
+    seed: str,
+    *,
+    movie_count: int,
+    title_source: TitleSource,
+    year_range: tuple[int, int] = (1960, 2024),
+    imdb_prob: float = 0.9,
+    variant_prob: float = 0.7,
+    edition_prob: float = 0.15,
+    nfo_prob: float = 0.3,
+    poster_prob: float = 0.5,
+) -> Manifest:
+    rng = rng_from_seed(seed, salt="::content")
+    movies = tuple(
+        _make_movie(
+            rng,
+            title_source,
+            year_range=year_range,
+            imdb_prob=imdb_prob,
+            variant_prob=variant_prob,
+            edition_prob=edition_prob,
+            nfo_prob=nfo_prob,
+            poster_prob=poster_prob,
+        )
+        for _ in range(movie_count)
+    )
+    return Manifest(seed=seed, movies=movies)
+
+
+def materialize(
+    manifest: Manifest,
+    output_root: Path,
+    *,
+    naming: NamingConvention,
+    structure: LibraryStructure,
+    max_content_size: int = 0,
+) -> None:
+    structure_rng = rng_from_seed(manifest.seed, salt="::structure")
+    for movie in manifest.movies:
+        parent = structure.parent_path(movie, structure_rng)
+        dir_path = output_root / parent / naming.directory_name(movie)
+        dir_path.mkdir(parents=True, exist_ok=True)
+        variants: tuple[Variant | None, ...] = movie.variants or (None,)
+        for v in variants:
+            _write_file(
+                dir_path / naming.video_filename(movie, v),
+                output_root=output_root,
+                manifest_seed=manifest.seed,
+                max_size=max_content_size,
+            )
+        if movie.has_nfo:
+            _write_file(
+                dir_path / naming.sidecar_filename(movie, "nfo"),
+                output_root=output_root,
+                manifest_seed=manifest.seed,
+                max_size=max_content_size,
+            )
+        if movie.has_poster:
+            _write_file(
+                dir_path / naming.sidecar_filename(movie, "poster"),
+                output_root=output_root,
+                manifest_seed=manifest.seed,
+                max_size=max_content_size,
+            )
+
+
+def _write_file(
+    path: Path,
+    *,
+    output_root: Path,
+    manifest_seed: str,
+    max_size: int,
+) -> None:
+    if max_size <= 0:
+        path.touch()
+        return
+    # Per-file RNG keyed on relative path so file order doesn't affect content.
+    rel = path.relative_to(output_root).as_posix()
+    rng = rng_from_seed(manifest_seed, salt=f"::content::{rel}")
+    size = rng.randint(0, max_size)
+    path.write_bytes(rng.randbytes(size))
+
+
+def _make_movie(
+    rng: random.Random,
+    title_source: TitleSource,
+    *,
+    year_range: tuple[int, int],
+    imdb_prob: float,
+    variant_prob: float,
+    edition_prob: float,
+    nfo_prob: float,
+    poster_prob: float,
+) -> LogicalMovie:
+    title = title_source.random_title(rng)
+    year = rng.randint(*year_range)
+    imdb = _gen_imdb_id(rng) if rng.random() < imdb_prob else None
+    variants: tuple[Variant, ...] = ()
+    if rng.random() < variant_prob:
+        variants = (_gen_variant(rng, edition_prob=edition_prob),)
+    return LogicalMovie(
+        title=title,
+        year=year,
+        imdb_id=imdb,
+        variants=variants,
+        has_nfo=rng.random() < nfo_prob,
+        has_poster=rng.random() < poster_prob,
+    )
+
+
+def _gen_imdb_id(rng: random.Random) -> str:
+    return f"tt{rng.randint(1000000, 9999999)}"
+
+
+def _gen_variant(rng: random.Random, *, edition_prob: float) -> Variant:
+    resolution = rng.choices(_RESOLUTIONS, weights=_RESOLUTION_WEIGHTS)[0]
+    edition = rng.choice(_EDITIONS) if rng.random() < edition_prob else None
+    return Variant(resolution=resolution, edition=edition)

jellyplex_gen-0.1.0/src/jellyplex_gen/manifest.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Variant:
+    resolution: str | None = None
+    edition: str | None = None
+    extras: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class LogicalMovie:
+    title: str
+    year: int
+    imdb_id: str | None = None
+    tmdb_id: str | None = None
+    variants: tuple[Variant, ...] = ()
+    has_nfo: bool = False
+    has_poster: bool = False
+
+
+@dataclass(frozen=True)
+class Manifest:
+    seed: str
+    movies: tuple[LogicalMovie, ...] = field(default_factory=tuple)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self, *, indent: int | None = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Manifest:
+        movies = tuple(
+            LogicalMovie(
+                title=m["title"],
+                year=m["year"],
+                imdb_id=m.get("imdb_id"),
+                tmdb_id=m.get("tmdb_id"),
+                variants=tuple(
+                    Variant(
+                        resolution=v.get("resolution"),
+                        edition=v.get("edition"),
+                        extras=tuple(v.get("extras", ())),
+                    )
+                    for v in m.get("variants", ())
+                ),
+                has_nfo=m.get("has_nfo", False),
+                has_poster=m.get("has_poster", False),
+            )
+            for m in data.get("movies", ())
+        )
+        return cls(seed=data["seed"], movies=movies)
+
+    @classmethod
+    def from_json(cls, text: str) -> Manifest:
+        return cls.from_dict(json.loads(text))
+
+    @classmethod
+    def load(cls, path: Path) -> Manifest:
+        return cls.from_json(path.read_text(encoding="utf-8"))
+
+    def save(self, path: Path) -> None:
+        path.write_text(self.to_json(), encoding="utf-8")

jellyplex_gen-0.1.0/src/jellyplex_gen/naming.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from .manifest import LogicalMovie, Variant
+
+
+class NamingConvention(Protocol):
+    def directory_name(self, movie: LogicalMovie) -> str: ...
+    def video_filename(self, movie: LogicalMovie, variant: Variant | None) -> str: ...
+    def sidecar_filename(self, movie: LogicalMovie, kind: str) -> str: ...
+
+
+class PlexNamingConvention:
+    """Plex's documented layout: `<Title> (<Year>) {imdb-tt...}`.
+
+    The video filename starts with the directory name (both Plex and
+    Jellyfin require this). Optional `[bracket]` tags after the base name
+    encode variants. No translation of tag *values* happens here — the
+    generator emits whatever the variant carries.
+    """
+
+    video_extension: str = ".mkv"
+
+    def directory_name(self, movie: LogicalMovie) -> str:
+        name = f"{movie.title} ({movie.year})"
+        if movie.imdb_id:
+            name += f" {{imdb-{movie.imdb_id}}}"
+        return name
+
+    def video_filename(self, movie: LogicalMovie, variant: Variant | None) -> str:
+        base = self.directory_name(movie)
+        tags = self._variant_tags(variant)
+        if tags:
+            base += " " + "".join(f"[{t}]" for t in tags)
+        return base + self.video_extension
+
+    def sidecar_filename(self, movie: LogicalMovie, kind: str) -> str:
+        if kind == "nfo":
+            return self.directory_name(movie) + ".nfo"
+        if kind == "poster":
+            return "poster.jpg"
+        raise ValueError(f"Unknown sidecar kind: {kind}")
+
+    @staticmethod
+    def _variant_tags(variant: Variant | None) -> list[str]:
+        if variant is None:
+            return []
+        tags: list[str] = []
+        if variant.resolution:
+            tags.append(variant.resolution)
+        if variant.edition:
+            tags.append(variant.edition)
+        tags.extend(variant.extras)
+        return tags

jellyplex_gen-0.1.0/src/jellyplex_gen/seed.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import random
+
+_MASK_64 = 0xFFFFFFFFFFFFFFFF
+
+
+def seed_to_int(seed: str, shift: int = 5) -> int:
+    """Derive a deterministic 64-bit integer from an arbitrary string.
+
+    Byte-wise rolling XOR-hash. Independent of Python's per-process hash
+    randomization (PYTHONHASHSEED), so the same string always yields the
+    same int across processes and platforms.
+    """
+    h = 0
+    for b in seed.encode("utf-8"):
+        h = ((h << shift) ^ b) & _MASK_64
+    return h
+
+
+def rng_from_seed(seed: str, *, salt: str = "") -> random.Random:
+    """Return a `random.Random` seeded deterministically from `seed`.
+
+    `salt` lets callers derive independent RNG streams from the same
+    user-facing seed (e.g. one for content, one for structure decisions).
+    """
+    return random.Random(seed_to_int(seed + salt))

jellyplex_gen-0.1.0/src/jellyplex_gen/structure.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import random
+from pathlib import Path
+from typing import Protocol
+
+from .manifest import LogicalMovie
+
+
+class LibraryStructure(Protocol):
+    def parent_path(self, movie: LogicalMovie, rng: random.Random) -> Path: ...
+
+
+class FlatLibraryStructure:
+    """All movie directories sit directly under the library root."""
+
+    def parent_path(self, movie: LogicalMovie, rng: random.Random) -> Path:
+        return Path(".")

jellyplex_gen-0.1.0/src/jellyplex_gen/titles.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import random
+from typing import Protocol
+
+
+class TitleSource(Protocol):
+    def random_title(self, rng: random.Random) -> str: ...
+
+
+_ADJECTIVES = (
+    "Silent", "Forgotten", "Burning", "Last", "Crimson", "Endless",
+    "Hidden", "Distant", "Quiet", "Lonely", "Brave", "Frozen",
+    "Broken", "Golden", "Wandering", "Restless", "Vanished", "Hollow",
+    "Bitter", "Tender", "Twelve", "Northern", "Ancient", "Sacred",
+    "Lost", "Faithful", "Wounded", "Wild", "Pale", "Dark",
+    "Bright", "Velvet", "Glass", "Iron", "Stone", "Paper",
+    "Quiet", "Salt", "Stormy", "Silver",
+)
+
+_NOUNS = (
+    "Shadow", "Empire", "River", "Moon", "Whisper", "Vow",
+    "Code", "Echo", "Hunter", "Sentinel", "Tide", "Gravity",
+    "Compass", "Lantern", "Mirror", "Falcon", "Verdict", "Ember",
+    "Harbor", "Garden", "Tower", "Crown", "Wolf", "Saint",
+    "Bridge", "Witness", "Promise", "Letter", "Garden", "Pilot",
+    "Stranger", "Hour", "Country", "House", "Lover", "Daughter",
+    "Son", "Brother", "Sister", "Captain", "Doctor", "Witness",
+    "Forest", "Mountain", "Valley", "Island", "Desert", "Canyon",
+    "Train", "Engine", "Machine", "Mirror",
+)
+
+_HAND_CRAFTED = (
+    "Twelve Crows in Winter",
+    "Notes on a Quiet War",
+    "The Lighthouse Keeper",
+    "All the Hours Between",
+    "A Letter from Nowhere",
+    "The Cartographer",
+    "Three Days in November",
+    "Bread, Salt, and Iron",
+    "The Last Honest Man",
+    "Songs for the Drowning",
+    "The Long Road Home",
+    "Where the Wolves Wait",
+    "A Brief History of Lying",
+    "The Glass Republic",
+    "Children of Static",
+)
+
+
+class CuratedTitleSource:
+    """Generates plausible-feeling movie titles from small word pools.
+
+    Mixes several patterns so a generated library doesn't look monotonous:
+    plain nouns, adjective + noun, "The X", "X of Y", and the occasional
+    hand-crafted title for texture.
+    """
+
+    def random_title(self, rng: random.Random) -> str:
+        roll = rng.random()
+        if roll < 0.10:
+            return rng.choice(_HAND_CRAFTED)
+        if roll < 0.30:
+            return f"The {rng.choice(_NOUNS)}"
+        if roll < 0.50:
+            return f"The {rng.choice(_ADJECTIVES)} {rng.choice(_NOUNS)}"
+        if roll < 0.65:
+            return f"{rng.choice(_ADJECTIVES)} {rng.choice(_NOUNS)}"
+        if roll < 0.80:
+            a, b = rng.sample(_NOUNS, 2)
+            return f"{a} of {b}"
+        if roll < 0.92:
+            a, b = rng.sample(_NOUNS, 2)
+            return f"{a} and {b}"
+        return rng.choice(_NOUNS)