Movie & TV indexing

Authored by Claude · Last updated November 5, 2026AI generated documentation written by reading the source code

self-hosted

To get your movies and TV shows into Cardinal Cinema, you need to index them with Cardinal Media Server.

Movies and TV work differently from music. Your folder and file names are the source of truth. The title, year, show, season and episode come from the names you gave your files, or from a movie's NFO file when you keep one beside it; tags embedded inside the video file only fill in extras like the description, genres and release date. Video files in the wild are tagged with disc labels and release group names far more often than with anything useful, and your folders are what you actually curated.

Nothing is guessed, and nothing is looked up on the internet. A file either matches the rules below or it is indexed as unsorted and the run log says exactly why.

Supported file types

Extension	Status
`mkv`	Indexed
`mp4`	Indexed
`m4v`	Indexed
`mov`	Indexed
`webm`	Indexed
`avi`, `wmv`, `mpg`, `vob`, `ts`, `m2ts`, `flv`	Indexed, not playable yet

The formats marked not playable yet are indexed like any other video: they get their title, artwork and technical details, and they appear in Cardinal Cinema marked as unplayable. Their details are read by ffprobe, because only ffprobe can open these containers; without ffprobe on the server, these files are recorded as errors in the run log. No browser can play them as they are, so they become playable when the server learns to convert video, in the next release.

A file that cannot be read at all is recorded as an error, and the run log gives the reason in plain words: the file is damaged or is not the format its extension says, or an mp4 is incomplete.

DVD folders

A vob file on its own, such as Show Name - 2004-10-07.VOB, is indexed like any other video. The VOB files of a copied DVD are not: a DVD splits one film into parts (VTS_01_1.VOB, VTS_01_2.VOB, …) beside its menus, so indexing each one would fill your library with fragments. A VOB is treated as part of a DVD when it sits in a VIDEO_TS folder, or when its name is VIDEO_TS.VOB or VTS_01_1.VOB-style. DVD folders are not indexed yet, and the run log lists each one with the reason.

Sample clips

Releases often ship a short sample clip beside the real video, usually in a Sample folder. Sample clips are skipped in both the movies and the TV library: they are not indexed at all, not even as unsorted. A video file is a sample clip when:

it sits in a folder named Sample or Samples (any capitalization), at any depth below the library root, or
its name, without the extension, ends in -sample, .sample or _sample, or is just sample (any capitalization).

Skipped:

✅ Nate.Bargatze.Hello.World.2023.1080p.WEB.H264-NAISU/Sample/nate.bargatze.hello.world.2023.1080p.web.h264-naisu-sample.mkv
✅ Movie (2020)/movie.2020.1080p-sample.mkv

Not skipped:

❌ The Sample (2015)/The Sample (2015).mkv → a title that ends in the word is not a sample clip
❌ Free Samples (2012)/Free Samples (2012).mkv → only a folder named exactly Sample or Samples counts
❌ Show Name/Season 01/Show Name - S01E01 - Sample.mkv → - Sample is an episode title

Sample clips that were indexed before this rule existed stay until you de-index them.

Movies

Use this folder structure in your movies library.

/movies                                   🠘 Movies library root
  /[...]                                  🠘 Other folders, any depth, optional (e.g. /Kids, /4K)
    /Movie Title (2019)                   🠘 Movie folder: title + year¹
      Movie Title (2019).mkv              🠘 The movie file²
      Movie Title (2019).en.srt           🠘 Optional subtitles³
      Movie Title (2019).nfo              🠘 Optional NFO file⁷
      poster.jpg                          🠘 Optional poster⁴
      backdrop.jpg                        🠘 Optional backdrop⁴
      /Extras                             🠘 Optional extras folder⁵
        Trailer - Teaser.mkv
        Deleted Scene - Airport.mkv
    Loose Movie (2018).mp4                🠘 A movie file with no folder is fine⁶

¹ Movie name

A movie folder is named Title (Year). The year is four digits between 1888 and two years from now, wrapped in parentheses or square brackets, placed after the title and separated from it by a space.

The year-first form that music accepts is not accepted for movies, because 2001 - A Space Odyssey, 1917, 2012 and 300 are titles, not years.

The year is optional but strongly recommended. Without it, two different movies that share a title are merged into one.

Valid movie names:

✅ Blade Runner 2049 (2017)
✅ Blade Runner 2049 [2017]
✅ 2001 - A Space Odyssey (1968) → the title is "2001 - A Space Odyssey"
✅ Blade Runner 2049 (2017) {imdb-tt1856101} → see Identifiers
✅ Blade Runner 2049 → no year, and a note in the run log

Invalid movie names:

❌ 2017 - Blade Runner 2049 → indexed with the title "2017 - Blade Runner 2049" and no year
❌ Blade Runner 2049 2017 → a bare trailing year is part of the title, unless the name is a release name
❌ Blade Runner 2049(2017) → no space, so the whole name is the title and there is no year

A movie name always produces a movie. The invalid forms produce a wrong title and no year, and every one of them writes a note in the run log, so you can see exactly which folder to rename. Nothing is silently wrong, and nothing is silently skipped.

Release names

Names copied straight from a release, like Ghost.In.The.Shell.2017.2160p.UHD.BluRay.x265-GROUP, are read too, for both folders and files. A name is read as a release name when it has no year in parentheses or brackets, and it either uses dots or underscores instead of spaces, or contains a release tag such as 1080p, BluRay, WEB-DL, HDR, DTS-HD or x265.

Dots and underscores are read as spaces. A name that mixes them with spaces, like Death at a Funeral.2010.1080p.BluRay or Kill.Bill.Vol.1.2003.1080p.BluRay.REMUX.DTS-HD.MA 5.1-GROUP, is read the same way.
The year is the last four-digit year before the first release tag. A year at the very start of the name is always part of the title, so 1917 and 2001 keep their numbers.
The first release tag and everything after it (resolution, source, HDR, audio, codec and the -GROUP suffix) is ignored. The version label still comes from the file itself.
A year range is not a year. Harry Potter (2001 - 2011) COMPLETE (1080p …) is "Harry Potter" with no year, and so is a pair of years in a name that calls itself a collection, like The.Mummy.Trilogy.1999.2008.1080p. Elsewhere two years in a row are a number in the title and the year, so Wonder.Woman.1984.2020.1080p is "Wonder Woman 1984" (2020).
A dot between two digits in the title is a decimal point, not a space, so Gojira-1.0 and Jackass.3.5 keep their numbers. The year and the tags after it are still separate words.
Edition words beside the year, such as Extended, Director's Cut, Unrated, Remastered, IMAX, Theatrical and Collector's Edition, become the edition instead of part of the title. Words like Final or Cut on their own stay in the title, so The Final Cut is left alone.

Valid release names:

✅ Ghost.In.The.Shell.2017.2160p.UHD.BluRay.TrueHD.7.1.HDR.x265-CtrlHD → "Ghost In The Shell", 2017
✅ Avatar 2009 Extended Collector's Edition 2160p UHD BluRay DTS-HD MA 5.1 DV HDR x265-HiDt → "Avatar", 2009, edition "Extended Collector's Edition"
✅ Blade.Runner.2049.2017.1080p.BluRay.x264 → "Blade Runner 2049", 2017
✅ 1917.2019.2160p.WEB-DL → "1917", 2019
✅ Avatar (2009) 1080p BluRay x264 → "Avatar", 2009, and the tags after the year are ignored
✅ Gojira-1.0.2023.1080p.BluRay.DD+.7.1.x264-SPHD → "Gojira-1.0", 2023
✅ Jack and Jill (2011) (1080p BDRip x265 10bit DTS-HD MA 5.1 + AC3 5.1 - r0b0t) [TAoE] → "Jack and Jill", 2011. The bracket after the release tags is the release group's tag, not a version label, so the label comes from the file itself (1080p)

Invalid release names:

❌ Blade.Runner.2049.1080p.BluRay → no year, so the title is "Blade Runner 2049" and the run log notes the missing year
❌ The Matrix 1999 Remastered → spaces and no release tag, so this is not a release name and the whole name is the title

A release name loses the apostrophes and capitalization of the real title, which is why a cleanly named movie folder takes precedence over it (see Movie file).

² Movie file

The best name for the movie file is the same name as its folder. Anything after the year follows this grammar, in this order:

Title (Year) - Edition - Part N [Version].ext

Valid movie file names:

✅ Blade Runner 2049 (2017).mkv
✅ Blade Runner 2049 (2017) - Director's Cut.mkv → edition "Director's Cut", same movie
✅ Blade Runner 2049 (2017) [4K HDR].mkv and … [1080p].mkv → two versions of one movie, labelled from the brackets
✅ Blade Runner 2049 (2017) [2160].mkv → [2160] is outside the year range, so it is a version label
✅ Blade Runner 2049 (2017) 2160p UHD BluRay x265 [4K HDR].mkv → still labelled "4K HDR", because the bracket holds a release tag of its own
✅ The Lord of the Rings (2001) - Part 1.mkv and … - Part 2.mkv → one movie in two parts, played back to back
✅ anything.mkv inside Blade Runner 2049 (2017)/ → the identity comes from the folder
✅ Ghost.In.The.Shell.2017.2160p.BluRay.mkv inside Ghost in the Shell/ → "Ghost in the Shell" (2017): the folder's title with the file's year
✅ Jagten.2012.1080p.BluRay.x264-GROUP.mkv inside The Hunt/ → "The Hunt" (2012): the folder names the film, whatever the release calls it
✅ hd1080-bug-x264.mkv inside Bug/ → "Bug"
✅ Superman.IV.The.Quest.for.Peace.1987.1080p.BluRay.mkv inside Superman IV/ → "Superman IV The Quest for Peace" (1987): the release spells out the title the folder shortened
✅ halcyon-drdolittle.1080p-x264.mkv inside Dr Dolittle/ → "Dr Dolittle": the part after the release group's halcyon- prefix names the folder's title
✅ Dawn.Of.The.Dead.2004.1080p.BluRay.x264-GROUP.mkv inside Dawn of the Dead/Dawn.Of.The.Dead.2004.1080p.BluRay.x264-GROUP/ → "Dawn of the Dead" (2004): see release folders

Invalid movie file names:

❌ Blade Runner 2049 - Director's Cut.mkv → an edition needs the year in front of it, otherwise the - is read as part of the title
❌ halcyon-drdolittle.1080p-x264.mkv inside Kids/, beside other films → the title is "halcyon-drdolittle": a release group prefix is only recognized when the folder names the rest
❌ Blade Runner 2049 (2017) 1080p BluRay x264 [GROUP].mkv → no label from the brackets: a bracket that follows release tags and holds none of its own is the release group's, and is ignored

When the folder and the file name disagree, the first of these rules that applies decides. A movie NFO file with a title or a year overrides all of them. Titles count as the same when they match ignoring case, punctuation and spacing, so DrDolittle, Dr. Dolittle and Dr Dolittle are one title.

The folder holds one film, its name follows the movie name rules rather than a release's, and the file is a release name → the folder names the movie, and the file adds its year, edition and version. When the release title is not all lower case and holds every word of the folder's title, the release's spelling is used instead. A file named Title (Year), with or without release tags after it, is never overridden, and neither is a file whose year contradicts the folder's.
Both name the same title and year → the folder's spelling is used, and the folder is the movie's folder.
Both name the same title, and the folder has no year → the folder's title, with the file's year when it has one. A release-named file of the scene's group-title shape, like halcyon-drdolittle, matches on the part after the group.
The folder has a year and the file has none → the folder.
The folder is Title (Year) and the file is a release name → the folder, unless the title and the year both differ. Star.Wars.Episode.IV.A.New.Hope.1977.1080p.mkv inside Star Wars (1977)/ is "Star Wars" (1977), while Frozen.II.2019.1080p.mkv inside Frozen (2013)/ is "Frozen II" (2019).
Otherwise the file's own name wins, and the folder is treated as a grouping folder.

A folder holds one film when every video file directly inside it has the same title, so two versions or two parts of a film still count as one, and sample clips are ignored. A subfolder other than Extras, the extras type folders, Sample, Subs, Subtitles or artwork folders makes it a grouping folder. A folder whose name calls it a collection, like The Mummy Trilogy, never names the film inside it. In a folder holding several films, only a file with the folder's own title takes the folder's name.

Release folders

A release is often downloaded as a folder named like the release, which you then put inside a folder named after the movie:

/movies
  /Dawn of the Dead                                          🠘 Title folder
    /Dawn.Of.The.Dead.2004.1080p.BluRay.DTS.x264-GROUP       🠘 Release folder, the movie's folder
      Dawn.Of.The.Dead.2004.1080p.BluRay.DTS.x264-GROUP.mkv

When the movie's folder is a release name and the folder above it names the same title, the title folder's spelling is used, with the release's year when the title folder has none. The years must not contradict each other: a release of the 2004 film inside Dawn of the Dead (1978)/ keeps its own name. The release folder is still the movie's folder, so its artwork and its Extras folder go inside the release folder.

✅ Dawn of the Dead/Dawn.Of.The.Dead.2004.1080p.BluRay…/… → "Dawn of the Dead" (2004)
✅ Air Bud/Air.Bud.1997.1080p.AMZN.WEB-DL…/… → "Air Bud" (1997)
✅ Nate Bargatze Hello World/Nate.Bargatze.Hello.World.2023.1080p.WEB.H264-NAISU/nate.bargatze.hello.world.2023.1080p.web.h264-naisu.mkv → "Nate Bargatze Hello World" (2023), however the file inside is capitalized
❌ Kids/Frozen.2013.1080p.BluRay/Frozen.2013.1080p.BluRay.mkv → "Frozen" (2013), spelled by the release, because Kids is a grouping folder rather than the title

Part markers are Part, pt, CD and Disc, each with an optional space or dash before the number. When a version has no bracketed label, the label is derived from the file itself instead, such as 2160p HDR10 or 1080p. The HDR part (HDR10, HDR10+, HLG or Dolby Vision) needs ffprobe, which ships with the Docker image.

The same movie folder appearing under two different grouping folders — /Kids/Frozen (2013) and /4K/Frozen (2013) — resolves to one movie with two versions. That is intentional.

³ Subtitles

A subtitle file belongs to a video when it shares the video's name, up to the extension.

Movie (2019).srt
Movie (2019).en.srt
Movie (2019).en.forced.srt
Movie (2019).en.sdh.srt

The language is a two- or three-letter code, or a full BCP-47 tag such as pt-BR. The flags sdh, hi and cc all mark a track as being for the hearing impaired, and forced marks a forced track.

Supported formats are srt, vtt, ass, ssa, and sub + idx. Image-based subtitles (sub + idx) are listed but cannot be displayed yet.

Subtitles are read from your folders every time you open a movie or episode, not stored during indexing, so a subtitle file you add later shows up immediately without re-indexing.

⁴ Artwork

Put poster.jpg and backdrop.jpg in the movie's folder, and optionally a transparent logo.png and clearart.png. The extensions jpg, jpeg, png and webp are all accepted, and these alternative names are accepted too:

File	Used as
`poster.*`	Poster
`folder.`, `cover.`	Poster
`backdrop.*`	Backdrop
`fanart.*`	Backdrop
`logo.`, `clearlogo.`	Logo
`clearart.*`	Clearart

Artwork named after the movie's video file, the way Kodi and tinyMediaManager save it, is read too:

File	Used as
`<video file name>-poster.*`	Poster
`<video file name>.*`	Poster
`<video file name>-fanart.*`	Backdrop
`<video file name>.fanart.*`	Backdrop
`<video file name>-logo.`, `<video file name>-clearlogo.`	Logo
`<video file name>-clearart.*`	Clearart

✅ Independence.Day.1996.1080p.BluRay.x264-nikt0.jpg beside Independence.Day.1996.1080p.BluRay.x264-nikt0.mkv → poster
✅ Independence.Day.1996.1080p.BluRay.x264-nikt0.fanart.jpg beside the same file → backdrop
✅ Blade Runner 2049 (2017)-poster.png and Blade Runner 2049 (2017)-fanart.jpg beside Blade Runner 2049 (2017).mkv → poster and backdrop
❌ Independence Day.jpg beside Independence.Day.1996.1080p.BluRay.x264-nikt0.mkv → not used: the name must match the video file's exactly, apart from capitalization

When a folder has both, the folder names in the first table win. A movie with more than one version reads the names of its first version's file.

Folder artwork is only used when the folder holds exactly one movie. A folder called Frozen (2013) that contains both Frozen (2013).mkv and Frozen II (2019).mp4 is a grouping folder, so neither movie takes its poster.jpg. Artwork named after the video file has no such limit, because it can only belong to that one file.

Artwork is processed by the cinema artwork thumbnails job, which runs automatically after indexing. With online artwork turned on, the kinds a movie has no file for are filled in from online providers, and a file you add later takes their place.

⁵ Extras

A folder named Extras (any capitalization) inside a movie's folder holds that movie's extras. The type of each extra is the first - segment of its file name when that segment is one of:

Trailer, Teaser, Deleted Scene, Behind the Scenes, Featurette, Interview, Scene, Short, Bloopers

Anything else is typed as Other, and the whole file name becomes its title.

Folders named for one kind of extra are read too, beside or instead of Extras. Everything in one of them is an extra of that kind, unless its file name starts with one of the names above:

Folder (any capitalization)	Type
`Behind The Scenes`	Behind the Scenes
`Deleted Scenes`	Deleted Scene
`Featurettes`	Featurette
`Interviews`	Interview
`Scenes`	Scene
`Shorts`	Short
`Trailers`	Trailer
`Other`	Other

✅ Avatar (2009)/Trailers/Official Trailer.mkv → a trailer, "Official Trailer"
✅ Avatar (2009)/Featurettes/Interview - James Cameron.mkv → an interview, "James Cameron": the file name's type wins over the folder's

An Extras folder only counts when the folder it sits in actually holds a movie. /movies/Marvel/Extras/Trailer.mkv does not invent a movie called "Marvel"; that file is indexed as unsorted. A folder named for one kind of extra beside no movie is not an extras folder at all, but an ordinary grouping folder:

✅ Shorts/Piper (2016).mkv → the movie "Piper" (2016), because there is no movie beside Shorts for it to be an extra of

⁶ Loose files

A movie file sitting directly in the library root, or in a grouping folder, is indexed from its own name. It works, but there is no folder of its own to read a poster.jpg from, so artwork can only come from images named after the file or a cover embedded inside it.

A folder holding several films, like James Bond/, Star Wars/ or Harry Potter (2001 - 2011) COMPLETE/, is a grouping folder too: each file names its own film.

⁷ NFO files

An NFO file beside a movie describes it. Cardinal reads two kinds, and looks for them in this order, using the first file that is one of the two:

<video file name>.nfo, beside the video
movie.nfo, in the movie's own folder
The NFO of another version of the movie in the same folder

An extra uses its movie's NFO. TV shows and episodes do not read NFO files yet.

Kodi NFOs are the XML files that Kodi, tinyMediaManager, MediaElch and similar tools write, with a <movie> root. These elements are read:

Element	Used as
`<title>`	Title
`<year>`, or the year of `<premiered>`	Year
`<premiered>` (or `<releasedate>`), as `YYYY-MM-DD`	Release date
`<plot>`, or `<outline>` when there is no plot	Overview
`<tagline>`	Tagline
`<mpaa>`	Content rating: `Rated PG-13` and `US:PG-13` are both read as `PG-13`
`<studio>`	Studio (the first one)
`<uniqueid type="imdb">`, `type="tmdb"` and `type="tvdb"`, `<imdbid>`, `<tmdbid>`, `<tvdbid>`, and `<id>` when it holds an IMDb id	Identifiers

<originaltitle> is read and kept, but not shown yet. Everything else, such as the cast, the ratings and artwork addresses, is ignored, and nothing is ever downloaded because of an NFO.

URL NFOs are plain text files whose first line is the address of the movie's page on IMDb, TMDB or TVDB. The identifier is read from the address. When the lines after it are plain paragraphs of prose, they become the overview, up to the first line that looks like release information.

✅ https://www.imdb.com/title/tt0116629/ → the IMDb identifier tt0116629
✅ https://www.themoviedb.org/movie/602-independence-day → the TMDB identifier 602
✅ The address, a blank line, then On July 2, a giant alien mothership enters orbit around Earth… → the identifier, and that paragraph as the overview
❌ See https://www.imdb.com/title/tt0116629/ for details → not a URL NFO, because the address must be the whole first line

Anything else is ignored. Most releases ship an NFO of release information instead, with ASCII art and tables like RUNTiME.........: 02h:06m:21s. Those are skipped, even when they mention an IMDb page somewhere inside. So are NFOs larger than 1 MB, NFOs that are not well-formed XML, and Kodi NFOs for TV shows or episodes. An NFO that cannot be read never stops indexing.

NFOs can be saved as UTF-8 or UTF-16 with a byte order mark, as UTF-8 without one, or as Latin-1, with Windows or Unix line endings. Entities declared inside an NFO are never expanded, and nothing an NFO points to is ever fetched.

An NFO wins over the names. Its title and year are the movie's title and year, whatever the folder and file are called; whatever the NFO leaves out still comes from the names. That makes an NFO the way to name a movie whose files you would rather not rename:

✅ Godzilla Minus One/Gojira-1.0.2023.1080p.BluRay.mkv with an NFO saying <title>Godzilla Minus One</title> and <year>2023</year> → "Godzilla Minus One" (2023), and Godzilla Minus One/ becomes the movie's folder, so its poster.jpg is used
✅ Blade Runner 2049/Blade Runner 2049.mkv with an NFO saying <year>2017</year> → "Blade Runner 2049" (2017), with no missing-year note
❌ Two versions in two folders, with an NFO in only one of them that disagrees with their names → the versions become two movies. Give every version the same NFO, or none

A movie's NFO is read when its video file is indexed. An NFO you add or change later is read the next time that video is indexed, so to pick it up straight away, de-index the movie and index again.

TV shows

Use this folder structure in your TV library.

/tv                                                   🠘 TV library root
  /Show Name (2005)                                   🠘 Show folder: name + optional first-aired year¹
    poster.jpg                                        🠘 Optional show artwork⁴
    backdrop.jpg
    /Season 01                                        🠘 Season folder²
      poster.jpg                                      🠘 Optional season poster
      Show Name - S01E01 - Pilot.mkv                  🠘 Episode file³
      Show Name - S01E01 - Pilot.jpg                  🠘 Optional episode thumbnail⁴
      Show Name - S01E01 - Pilot.en.srt               🠘 Optional subtitles
      Show Name - S01E02-E03 - Two Parter.mkv         🠘 One file, two episodes
      /Extras                                         🠘 Optional season extras⁵
    /Specials                                         🠘 Season 0
      Show Name - S00E01 - Christmas Special.mkv
    /Extras                                           🠘 Optional show extras⁵

¹ Show folder

Every folder in the library root, or in a grouping folder, is a show folder, and everything inside it belongs to that show. The folders below it can be anything: season folders, release folders, discs, years or a regional version. None of them is ever another show, whatever its name.

The show folder uses the same name grammar as a movie: Name (Year), where the year is the year the show first aired. Anything else in brackets stays in the name, so The Office (US) and The Office (UK) are two shows. A show folder named like a release is read as a release name and cleaned:

✅ Breaking.Bad.2008.1080p → "Breaking Bad" (2008)
✅ Smallville.S01-S10.1080p.BluRay.x265-GROUP → "Smallville"
✅ 24 S01-09 br 10bit hevc-GROUP → "24"
✅ Home Improvement 1991-1999 DVD Remux NTSC → "Home Improvement" (1991), the first year of a range
✅ Leah.Remini.Scientology.and.the.Aftermath.Seasons.1-3.WEBRip.1080p → "Leah Remini Scientology and the Aftermath"

Episode files must live inside their show's folder. An episode file sitting at the library root has no show, so it is indexed as unsorted. So is one inside a season folder at the library root, such as /tv/Season 01/S01E01.mkv.

A folder named Movies, Movie, Films or Film (any capitalization) anywhere inside a show folder is ignored by the TV library, along with everything in it. Films are not episodes, so put them in your movies library instead. Files there that were indexed before this rule existed stay until you de-index them.

✅ /movies/Bean (1997)/Bean (1997).mp4 → a movie in the movies library
❌ /tv/Mr. Bean/Movies/Bean.The.Movie.1997.1080p.BluRay.mp4 → not indexed at all: not an episode, not an extra and not unsorted

Grouping folders

To keep shows in grouping folders, such as /tv/Kids or /tv/Anime, create a Library that points at each grouping folder. The folders inside a Library's folder are then the show folders. Without a Library, a grouping folder is read as a show.

✅ /tv/Kids/Bluey (2018)/Season 01/Bluey - S01E01.mkv, with a Library on /tv/Kids → "Bluey" (2018)
❌ /tv/Kids/Bluey (2018)/Season 01/Bluey - S01E01.mkv, with no Library on /tv/Kids → a show called "Kids"

When a file sits inside several Library folders, the deepest one decides. A Library folder that holds season folders, season packs or episode files directly, like /tv/Frasier holding Season 01, is a show folder rather than a grouping folder, so it stays the show. A Library on a season or Extras folder is ignored, because those folders are inside a show. Library folders outside the TV library root have no effect on TV.

Release folders and season packs

TV is often downloaded a season or a whole show at a time, as one folder named like the release. These folders are read as release names, with the same tags, years and separators as movie release names:

A season pack names one season, with S01 or Season 1 after the title: Show.Name.S01.1080p.BluRay-GROUP or Mindhunter (2017) S01 (1080p NF WEB-DL - GROUP). It is also the season folder for that season, so a season poster can go inside it.
A complete pack holds several seasons or the whole show: Complete, Complete Series, Complete Collection, Complete Seasons, Complete Box Set, or a range like S01-S05, S01-05 or Seasons 1-3. It has no season of its own, so the episodes inside it need season folders or markers.

A release folder inside a show folder never names the show: the show folder does. When the show folder has no year, a year in a release folder's name that names the same show, or in front of the episode marker in the file name (Mindhunter (2017) S01E01), becomes the show's year, but it never decides which show the file belongs to: every season and every extra of Mindhunter/ stays one show, whichever of them carry the year. Name the show folder Mindhunter (2017) if two shows share the name.

A release folder directly in the library root is the show folder, and the show is the title and year read from its name.

Two packs of the same season, such as a 1080p release and a DVD rip, resolve to the same episodes. Each file becomes a version of its episode, labelled from the file itself (for example 1080p and 480p), exactly like movie versions.

Valid layouts:

✅ Mindhunter/Mindhunter (2017) S01 (1080p NF WEB-DL H265 - HONE)/Mindhunter (2017) S01E01 (1080p NF WEB-DL H265 - HONE).mkv → "Mindhunter", season 1, episode 1
✅ ReBoot/ReBoot.S01.1080p.WEB-DL-GROUP/ReBoot.S01E01.The.Tearing.1080p.WEB-DL-GROUP.mkv and ReBoot/ReBoot.S01.DVDRip.x264-OTHER/ReBoot.s01e01.The.Tearing.DVDRip.x264-OTHER.mkv → two versions of "ReBoot" S01E01, "The Tearing"
✅ Mr. Bean/Mr.Bean.Complete.Collection.H264.AC3/S01/S01E01.mp4 → "Mr. Bean", season 1, episode 1, and its Extras folder holds the show's extras
✅ Show.Name.S01.1080p.BluRay/Show.Name.S01E05.1080p.BluRay.mkv at the library root → "Show Name", season 1, episode 5
✅ Show Name (2005)/Show.Name.S02.720p.HDTV/… → "Show Name" (2005), season 2
✅ Mindhunter/Mindhunter (2017) S01 (1080p NF WEB-DL … - HONE)/Mindhunter (2017) S01E01 (1080p NF WEB-DL … - HONE).mkv → "Mindhunter", with 2017 as its year
✅ Frasier/Frasier.COMPLETE.S01-S11.720p.WEB-DL/Season 10/Frasier.S10E24.720p.WEB-DL.mkv → "Frasier", season 10, episode 24
✅ The Amazing Race/The.Amazing.Race.S.31/The.Amazing.Race.S31E01.mkv → "The Amazing Race", season 31
✅ COPS/Cops S01-S28/Season 28/Cops.S28E04.720p.HDTV-GROUP/Cops.S28E04.720p.HDTV-GROUP.mkv → "COPS", season 28, episode 4: a folder per episode is just another folder
✅ The Office/The.Office.US.S01.1080p/… → "The Office", season 1. The release folder's own title does not matter

² Season folder

Season folders are optional. Episodes can sit directly in the show folder, in which case the season number comes from the file name.

Valid season folder names:

✅ Season 1
✅ Season 01
✅ Season-1
✅ Season.1
✅ S01
✅ Series 1 → below the show folder only. In the library root it is a show called "Series 1"
✅ Specials → season 0
✅ Show.Name.S01.1080p.BluRay → season 1, as a season pack
✅ Show Name season 2 and The.Amazing.Race.S.31 → season 2 and season 31
✅ Season One and Reading.Rainbow.Season.Five → season 1 and season 5, spelled out up to twenty
✅ Season 02-TVRip-XviD and S06 1080p BluRay → a season folder with release tags after it, below the show folder only
✅ Radio Active (S1) → a season in brackets after a title, below the show folder only
✅ Show.Name.S05.Extras.1080p.BluRay → the extras of season 5

When season folders are nested, such as a Season 10 folder inside a complete pack, the one nearest the episode is the season folder.

Invalid season folder names:

❌ 1
❌ Season Finale

When the season folder and the episode's file name disagree, the file name wins, and the run log notes the mismatch.

³ Episode file

An episode file must contain an episode marker. Everything before the marker is ignored — the folder already tells the server which show this is — and everything after the - that follows the marker is the episode title.

[Show Name - ]S01E05[-E06][ - Episode Title][ [Version]].ext

A marker only counts when it is delimited: it must be preceded by the start of the name, by -, or by a dash right against it ( -S01E05), and followed by the end of the name, -, [ or .. When a name contains more than one marker, the last delimited marker wins.

The show name in front of the marker never changes the show, but when it clearly names a different show, the episode is still filed under its folder and the run log notes show name in the file and the folder disagree. Move the files to the right show folder, or correct the match. A shortened or longer form of the show's name, an abbreviation, a typo, a year or a region is not a different show, and neither is the name of the plain folder the file is in:

✅ Douglas.Is.Cancelled.S01E01.1080p.WEB.mkv in the Doom Patrol folder → episode 1 of "Doom Patrol", with a note
✅ Star Trek Deep Space Nine - S01E01.mkv in Star Trek DS9, The.Office.US.S01E01.mkv in The Office (US) and Craig.Ferguson.2012.04.04.mp4 in The Late Late Show with Craig Ferguson → no note

A name with no delimited marker is read as a release name, like Show.Name.S01E05.The.Title.1080p.WEB-DL.mkv. There an S01E05 marker counts between words: after a space, dot or underscore, and before the end of the name or another separator. The 1x05 form is never read this way, because names like 4x4 are common. The episode title is the words after the marker, up to the first release tag, whether the words are separated by dots or by spaces.

A few more things are tidied out of the episode title:

The show's name repeated in front of it, as its own - segment.
An underscore followed by a space, which is how a file name writes a colon: Legends of Bikini Bottom_ Sponge-Cano reads "Legends of Bikini Bottom: Sponge-Cano".
A trailing bracket that holds the release group's tag rather than a version label, exactly as for movie files.

Valid episode file names:

✅ Show Name - S01E05 - Title.mkv
✅ S01E05.mkv and s1e5.mkv
✅ Show Name - 1x05 - Title.mkv
✅ S1E1 Podcast - S01E03.mkv → episode 3, because the last delimited marker wins
✅ Show Name - S01E05-E06.mkv, S01E05E06.mkv, S01E05-06.mkv → episodes 5 through 6 in one file
✅ Show Name - S00E01.mkv → a special
✅ Show Name - S01E05 [1080p].mkv and … [2160p].mkv → two versions of one episode
✅ Show.Name.S01E05.1080p.WEB-DL.mkv → episode 5, with no title
✅ ReBoot.S01E01.The.Tearing.1080p.WEB-DL.mkv → episode 1, "The Tearing"
✅ Show Name S01E05 Title.mkv → episode 5, "Title"
✅ SpongeBob SquarePants.S08E01.That Sinking Feeling.DVDRip.x264-GROUP.mkv → episode 1, "That Sinking Feeling"
✅ SpongeBob SquarePants -S03E19 - SpongeBob SquarePants - Chocolate With Nuts.mkv → episode 19, "Chocolate With Nuts"
✅ SpongBob Squarepants -S10E01 - Extreme Spots.mp4 in the SpongeBob SquarePants folder → episode 1 of "SpongeBob SquarePants". A misspelled prefix is still the same show
✅ Show Name - S05E37 - 20,000 Patties Under The Sea.mkv → episode 37, "20,000 Patties Under The Sea"
✅ Show Name - S01E05 - E06.mkv → episodes 5 through 6
✅ Show.Name.S02E09_S02E10_S02E11.Title.mkv and Show.Name.S03E18E19E20E21.Title.mkv → episodes 9 through 11, and 18 through 21
✅ Show.Name.S03E26S04E01.Title.mkv → episode 26 of season 3. A file that spans two seasons is filed under its first episode
✅ Frasier (S01E24) Title.mkv, Show Name [S2E09] Title.mkv and Radio Active (S. 1, Ep. 26) - Title.mkv → a marker in brackets is delimited by them
✅ Show Name - S04E12A - Title.mkv and … - S04E12B - Title.mkv → parts 1 and 2 of episode 12, played one after the other
✅ Planet.Earth.E01.Title.mkv → episode 1 of season 1, or of the season folder it is in
✅ Show Name - 101 - Title.mkv and 01. Title.mkv with no season folder → see numbered episodes with no season folder

Invalid episode file names:

❌ Show Name - Episode 5.mkv → no marker, so the file is unsorted and the run log explains why
❌ S1E1 Podcast.mkv → a marker at the very start of a name needs -, [, . or the end after it, so this is unsorted
❌ Show Name 1x05.mkv → 1x05 is only read when it is delimited, or when the season folder confirms it
❌ Show Name - S01E05 - 06.mkv → episode 5, titled "06": a range with spaces around the dash needs the E (S01E05 - E06)

A file covering more than one episode becomes a single episode entry that spans the range, so it is watched once and counts once.

Episodes named by their air date

Talk shows and news are usually named by the day they aired. A file with no episode marker but a date in its name is that day's episode:

2014-01-06, 2014.01.06, 2014_01_06 or 2014 01 06 (year, month, day)
01-06-2014 or 01.06.2014 (month, day, year)
2012.04.4, a day written with one digit
20140106, with no separators, even glued to the words around it (jayleno20140106guests), but only when the name has no other date

The episode is numbered by its date, so 2014-01-06 is episode 20140106 and the episodes of a season sort by the day they aired. It goes in the season its season folder names, or in a season named after its year when there is no season folder. The date is stored as the episode's air date, and the words after it are the title (often the guests), or the date itself when there are none. An episode marker beats a date: Show Name - S01E05 - 2014-01-06.mkv is episode 5.

✅ Late Night with Conan O'Brien/1998/Late Night with Conan O'Brien - 1998-01-02 - Guests.avi → season 1998, episode 19980102, titled "Guests"
✅ The Late Late Show with Craig Ferguson/Season 10/craig.ferguson.2014.01.06.kathy.griffin.hdtv.x264.mp4 → season 10, episode 20140106, titled "kathy griffin"
✅ Tonight Show with Jay Leno 05-29-1992 (Guests).mp4 → season 1992, episode 19920529, titled "Guests"
❌ Show.Name.2014.13.45.mp4 → not a real date, so the file is unsorted

Episode numbers the season folder confirms

Inside a season folder, a file with no marker can still number its episode in ways that only count because the season folder agrees. A number that names a season counts only when it is the season folder's season:

✅ Season 10/Show Name 10x01 - Title.mkv, Season 6/6-23.Title.avi and Season.Five/Show.Name.5.01.Title.mkv → episode 1, 23 and 1
✅ Show.Name.S08.1080p/group-abs08e01-1080p.mkv, Show Name S10/Show Name S10E 20.mkv and Show.Name.S04.1080p/Show.Name.S0408.1080p.mkv → episode 1 and 8
✅ Season 1/101 - Title.avi and Show.Name.S.26/show.name.2601.hdtv.mp4 → episode 1 of season 1 and of season 26
✅ Season 1/01. Title.mkv and Season 1/01 Title.mkv → episode 1
✅ Happy Days - Season 10/Happy Days 212 - Title.avi → episode 212 of season 10, because the words before the number name the show
❌ Season 3/Show Name 1x05 - Title.mkv → season 1 is not the season folder's, so the file is unsorted
❌ Season 1/Top 10 - Best Moments.mkv → the words before the number are not the show, so the file is unsorted

Numbered episodes with no season folder

A miniseries often numbers its parts with no season folder and no marker. With no season folder above it, a file can still number its episode in two places:

At the very start of the name, followed by . or -: 1.Title.mkv, 01. Title.mkv or 01 - Title.mkv is episode 1 of season 1. A name with a year in it is passed over, because it is more likely a film: 10.Cloverfield.Lane.2016.1080p.mkv stays unsorted.
Right after the show's name, optionally behind a broadcaster's initials: BBC.Frozen.Planet.01.Title.2011.1080p.mkv in Frozen Planet is episode 1 of season 1.

A three digit number is the season and a two digit episode, exactly as a season folder would confirm it: Goosebumps - 101 - The Haunted Mask.mkv is season 1, episode 1, and … - 224 - … is season 2, episode 24. If your show numbers its episodes past 99 instead, such as anime numbered from the first episode, put the files in a season folder or give them a marker: inside Season 1, Show Name - 101 - Title.mkv is episode 101.

✅ Taken/Taken (2002) DvdRip (complete)/10.Taken.mkv → season 1, episode 10, "Taken"
❌ Show/101 - Title.mkv → a three digit number counts only after the show's name
❌ Show/2 Fast 2 Furious.mkv → a number followed by a space alone could be a title
❌ Show/Other Show - 05.mkv → the words before the number are not the show
❌ Show/Show - 720 - Title.mkv and Show/Show - 100 - Title.mkv → a resolution, and no episode 0

⁴ Artwork

Location	File	Used as
Show folder	`poster.` (or `folder.`, `cover.*`)	Show poster
Show folder	`backdrop.` (or `fanart.`)	Show backdrop
Show folder	`logo.` (or `clearlogo.`)	Show logo
Show folder	`clearart.*`	Show clearart
Season folder	`poster.*`	Season poster
Beside the episode	`<episode file name>.jpg` or `<episode file name>-thumb.*`	Episode still

With online artwork turned on, a show or season with no file for a kind gets it from online providers. Episode stills only come from files.

⁵ Extras

An Extras folder inside the show folder holds show-level extras; one inside a season folder holds that season's extras. It can sit at any depth, such as inside a complete pack. The naming grammar is the same as for movie extras, and so are the folders for one kind of extra, such as Shorts, Featurettes or Deleted Scenes.

✅ SpongeBob SquarePants/Shorts/Balloons.mkv → a short of "SpongeBob SquarePants", titled "Balloons"
✅ Show Name/Season 01/Deleted Scenes/Airport.mkv → a deleted scene from season 1
✅ Show Name/Show.Name.S05.Extras.1080p.BluRay/Gag.Reel.mkv → an extra of season 5: a season pack named Extras is that season's extras folder
✅ Show Name/Show Name s01extra07 - Crew Dossier.mkv → an extra of season 1, titled "Crew Dossier"
✅ Show Name/Show Name Series 4/S4 Extras/Outtakes.avi and Show Name/Season 2 Extras/Gag Reel.mkv → extras of season 4 and season 2
❌ Shorts/Shorts - S01E01.mkv at the library root → episode 1 of a show called "Shorts": every folder in the library root is a show folder, including one called Extras

Identifiers

You can put an identifier in braces at the end of a movie or show folder name, and it will be read and stored:

Blade Runner 2049 (2017) {imdb-tt1856101}
Blade Runner 2049 (2017) {tmdb-335984}
Show Name (2005) {tvdb-73244}

Identifiers are optional, and nothing is looked up online because of them. They pin a title to a known work, which matters when two releases share a name, and they are what the Popularity Data Pool will key video plays on when video contribution arrives.

Metadata priority

Fact	First choice	Second choice	Third choice
Movie title and year	A correction, then the NFO file	Folder and file names	— (never from tags)
Show, season, episode number	A correction	Folder and file names	— (never from tags)
Episode title	File name	Embedded tag, unless it is only the file's name or episode code, such as `S01E01` or `Mindhunter (2017) S01E01 (1080p)`	"Episode N"
Movie overview, tagline, content rating, release date, studio	NFO file	Embedded tags	—
Genres, cast, air date, and the overview and content rating of shows and episodes	Embedded tags	—	—
Duration, resolution, codecs, HDR format, audio and subtitle languages, chapters	Read from the file by ffprobe	Read from the file's header	—
Artwork	Sidecar image in the folder, then one named after the video file	Cover embedded in the file	Extracted frame (next release)
Subtitles	Sidecar subtitle files	Embedded text tracks (listed, playable after extraction ships)	—
Identifiers	Movie NFO file	Braces in the name	Embedded tags

Identity is never taken from tags. Everything else is enrichment, and it is only filled in while it is still empty, so correcting a title by renaming a folder, in a movie's NFO, or with a match correction is always the thing that wins.

Playback support

Cardinal Cinema plays your files directly in the browser, exactly as they are on disk, with no conversion in between. Whether a file plays therefore depends on what your browser can decode.

	Chromium	Firefox	Safari
`mp4` / `m4v` / `mov` / `webm` container	✅	✅	✅
`mkv` container	✅	❌	❌
`avi` / `wmv` / `mpg` / `vob` / `ts` / `m2ts` / `flv` container	❌	❌	❌
H.264	✅	✅	✅
HEVC	Hardware decoding only	Partial	✅
AV1 / VP9	✅	✅	Recent hardware
AAC / MP3 / Opus / FLAC	✅	✅	Mostly
AC-3 / E-AC-3	❌ (Edge on Windows ✅)	❌	✅
DTS / TrueHD	❌	❌	❌
External subtitles	✅	✅	✅
Embedded text subtitles, PGS, VOBSUB	❌	❌	❌

Where a file cannot be played, Cardinal Cinema says so rather than failing silently. Every ❌ above is what the next release resolves, by converting the stream on the server before it reaches the browser.

Watching over Remote Access: a single relayed request is capped at about 10 GB, which is less than a large movie file. This is not a problem — the player asks for the next stretch of the file and keeps going, so a file of any size plays to the end. It does mean a long film draws on your relay bandwidth allowance; on your own network, a direct connection is unmetered.

Unsorted videos

Every video file in your movie and TV libraries is indexed, including the ones the rules above cannot place. The only exceptions are sample clips, a movies folder inside a TV show, DVD folders, and system folders such as a NAS recycle bin. A file that cannot be placed is marked unsorted: it still gets its own entry, it still plays, and it appears in the Unsorted shelf in Cardinal Cinema. Your files are never invisible, and they are never quietly discarded.

The run log records the reason for each one:

Reason	What happened
No episode marker	A file in the TV library has no `S01E05`-style marker, no air date, no number its season folder confirms and no numbered part, so there is no way to know which episode it is. Specials, films and bonus videos saved among the episodes, such as `24-Redemption 2008 BluRay.mkv`, land here too: move them to `Specials` with an `S00E01` marker, to an `Extras` folder, or to your movies library.
Extras folder has no movie	An `Extras` folder was found whose parent folder holds no movie of its own.
TV episode in the movies library	A file in the movies library has an `S01E05`-style marker, such as a season pack saved beside a movie. A file like that is only a movie when it is the one film in a folder named for it. Move episodes to the TV library.
File at the library root	A TV file sits at the top of the library with no show folder above it.

Fixing an unsorted file is a rename: give the file a marker, or move it into the folder it belongs to, and index again. Where renaming is not an option, correct the match instead.

Correcting matches

When a name on disk is wrong and renaming it is not an option, give the path a better name instead. A correction is stored against a file or folder, and the indexer reads it before the names on disk.

Correct a	With	Example
Movie file	A title, and optionally a year and an edition	`Resevoir Dogs (1992).mkv` → Reservoir Dogs (1992)
TV file	An episode (season, episode, and the last episode of a file that holds several), a show, or both. Naming a show moves the file to it	`Mystery Show - Episode Five.mkv` → season 1, episode 5
TV show folder	A show, which every file below the folder takes	`Star Trek DS9` → Star Trek: Deep Space Nine (1993), every episode at once

A file's own correction wins over its folder's, and a correction wins over the names, the NFO file and embedded tags. An absent year or edition means none.
An unsorted file that gets a correction leaves the Unsorted shelf, and its run log reason goes with it.
Identifiers can be added to a correction. They are stored on the movie or show, replacing any it had.
Corrections take effect at once, with no indexing run. They cannot be made while a run is in progress or paused.
Corrections are kept by path, so they survive every later run and a media reset. A factory reset removes them. Delete one, and the files go back to what their names say.
A movie or show a correction leaves with nothing to play is removed. If the correction is deleted, it comes back with the same identity, so your ratings and watch history stay attached to it.

There is no screen for corrections yet. They are made through the /cinema/match-overrides endpoints of the Media Server API, described in the API reference, and they need the Indexing.Operate capability, which the Owner and Administrator roles have. Paths are relative to your movies or TV folder:

PUT /api/v1/cinema/match-overrides

{
  "mediaType": "tv",
  "target": "folder",
  "path": "/Star Trek DS9",
  "show": { "title": "Star Trek: Deep Space Nine", "year": 1993 },
  "ids": { "tvdb": "72073" }
}

Renaming and de-indexing

Indexing runs never delete anything. A run adds new files and updates the ones it finds changed; it never removes entries, and it never reports files as missing. Removing entries is always a separate, deliberate action.

The consequence is worth knowing: if you rename a movie folder and index again, the old entry stays behind. The movie then shows an extra version that no longer plays, because the file behind it is gone. The same is true of your music library today.

To clear them out, de-index them from the Indexing page of your Media Server's Admin Dashboard. De-indexing also tidies up after itself: movies, seasons and shows that are left with no videos are removed, so a de-indexed show does not linger as an empty shell.

De-indexing and then indexing again is safe. A season or show that comes back keeps the identity it had, so your ratings and your watch history stay attached to it.

Was this article helpful?

Supported file types​

DVD folders​

Sample clips​

Movies​

¹ Movie name​

Release names​

² Movie file​

Release folders​

³ Subtitles​

⁴ Artwork​

⁵ Extras​

⁶ Loose files​

⁷ NFO files​

TV shows​

¹ Show folder​

Grouping folders​

Release folders and season packs​

² Season folder​

³ Episode file​

Episodes named by their air date​

Episode numbers the season folder confirms​

Numbered episodes with no season folder​

⁴ Artwork​

⁵ Extras​

Identifiers​

Metadata priority​

Playback support​

Unsorted videos​

Correcting matches​

Renaming and de-indexing​

Supported file types

DVD folders

Sample clips

Movies

¹ Movie name

Release names

² Movie file

Release folders

³ Subtitles

⁴ Artwork

⁵ Extras

⁶ Loose files

⁷ NFO files

TV shows

¹ Show folder

Grouping folders

Release folders and season packs

² Season folder

³ Episode file

Episodes named by their air date

Episode numbers the season folder confirms

Numbered episodes with no season folder

⁴ Artwork

⁵ Extras

Identifiers

Metadata priority

Playback support

Unsorted videos

Correcting matches

Renaming and de-indexing