Skip to content

Movies & TV libraries

Movies and TV are two separate library types, but they share one ingester and one playback pipeline. Both play through Orb's in-house native video engine on desktop and mobile, with HLS remux/transcode as the browser path. The goal is to play the original file untouched whenever the client can decode it, and only transcode when it has to.

To create a library, add a Movie or TV root under Admin → Libraries (see Your library).

Supported formats

.mkv, .mp4, .m4v, .mov, .webm, .ts, .m2ts, .avi

Each file is probed on ingest for its real video/audio/subtitle tracks, codecs, HDR metadata, and duration — the filename is only a hint, always cross-checked against the probe.

Folder layout

Movies

One movie per folder is the cleanest layout, but flat files work too. Include the year in parentheses to disambiguate remakes:

Movies/
  Blade Runner 2049 (2017)/
    Blade Runner 2049 (2017).mkv
  Dune Part Two (2024)/
    Dune.Part.Two.2024.2160p.BluRay.HDR.x265.mkv
  The Matrix (1999).mkv

Edition tags in the filename (Extended Cut, Director's Cut, IMAX, Remux) are detected and shown on the movie.

TV shows

Group episodes by show, then by season. Episode files need a season/episode marker — S01E02, s1e2, and multi-episode forms like S01E01-E02 are all recognized:

Shows/
  Severance/
    Season 01/
      Severance.S01E01.mkv
      Severance.S01E02.mkv
    Season 02/
      Severance.S02E01.mkv

The parser also handles common anime/scene patterns ([Group] Show - 01 [1080p].mkv). A file's declared library type wins, so a stray Show.S01E03.mkv dropped in a Movies library is still treated correctly.

Subtitles

Orb surfaces subtitles from three places:

  • Embedded tracks in the container (text and bitmap — PGS/VOBSUB).
  • Sidecar files next to the video (.srt, .ass, .vtt, …).
  • OpenSubtitles downloads, when credentials are configured under Admin → Settings → Integrations.

The native player renders text subtitles through libass with per-track styling (size, colour, outline, position) and sync adjustment.

Extras generated on ingest

  • Trickplay — a strip of seek-preview thumbnails shown when you scrub the timeline.
  • Episode thumbnails — pulled from the metadata provider, or extracted from the file when none exist.
  • Intro / Credits markers — detected so the player can show Skip Intro and Skip Credits buttons and a next-up card.
  • Posters & backdrops — fetched from the metadata providers.

Playback paths

The quality menu reflects what your client and server can do:

  • Direct (source) — the original file, byte-for-byte, with no transcode. This is the default on the native player and the full-resolution/HDR path. It requires a client that can decode the source.
  • HLS remux — repackages the original streams into HLS without re-encoding, for browsers that can play the codec but not the container.
  • HLS transcode — re-encodes to a chosen rung (2160p/1080p/720p/480p) when the client can't handle the source. Hardware acceleration sets the quality ceiling here; see Installation → Hardware acceleration.

Resume position is tracked per item across episodes.

Metadata enrichment

Movies and shows are matched and enriched against TMDB (primary), with TheTVDB, TVMaze, OMDb, iTunes, Cinemeta, AniList, and AniDB available depending on the media type and your per-library selection. Configure the providers and credentials under Metadata plugins and Admin → Settings → Integrations.

Next steps