Filesystem Media Sources

A filesystem media source is a directory of media files Sovereign scans itself, with no Radarr or Sonarr in front of it. Sovereign reads the title’s identity from the folder and file names, looks it up on TMDb for its artwork and metadata, and imports the files exactly as it would an Arr one. A source holds either films or television, set by its MediaType. This page covers how to configure a source and how to name your files so each one is found.

---

Configuration

Point an entry at the directory as the container sees it. Titles are looked up on TMDb through Sovereign’s metadata service, so there’s no API key to get or set.

Sovereign__DataSources__Filesystem__0__Path=/media/Movies
Sovereign__DataSources__Filesystem__0__MediaType=Movie
Sovereign__DataSources__Filesystem__0__Description=Films on the NAS
Sovereign__DataSources__Filesystem__1__Path=/media/Television
Sovereign__DataSources__Filesystem__1__MediaType=Television
Sovereign__DataSources__Filesystem__1__Description=Series on the NAS

Repeat the entry with an incrementing index for more than one directory. MediaType is either Movie (the default) or Television; a Mixed or Unknown entry is logged and skipped at startup, because neither has an importer. An entry whose directory doesn’t exist when the server starts is logged and skipped too. One directory holds one kind of media, so keep films and series in separate trees and give each its own entry. Sovereign never writes to the directory, so mount it read-only as described in NFS Media Storage.

Each directory is scanned on the same schedule as an Arr source, every fifteen minutes, and appears on the admin Media Sources page with the number of files it currently supplies.

---

Naming Your Movie Files

The recommended layout is one folder per film, named with the title and the year in parentheses, holding the video file:

• Directory/media/Movies/

  • DirectoryThe Glass Wren (1995)/

    • The Glass Wren (1995).mkv
  • DirectoryParallel Park 3 (1990)/

    • Parallel Park 3 (1990).mkv
  • DirectoryLeaving Cádiz in August (2026)/

    • Leaving Cádiz in August (2026).mp4

Sovereign reads the folder name first, because it’s far cleaner than a release file name, and falls back to the file name for a flat directory of files. Three things in a name matter, in this order of precedence:

1. A provider id tag identifies the film outright, with no search at all. Radarr, Plex, Kodi and Jellyfin all write one, so a library that was ever managed by one of them imports with no guesswork:

   The Glass Wren (1995) [tmdbid-12345]/
   The Glass Wren (1995) {tmdb-12345}/
   The Glass Wren (1995) [imdbid-tt1234567]/
   The Glass Wren (1995) {imdb-tt1234567}/
   The Glass Wren (1995) - [Bluray-1080p][EAC3 5.1][x265] [tt1234567].mkv

   A TMDb id is used as is. An IMDb id (tt followed by seven or eight digits, with or without an imdb- prefix) is resolved through TMDb.

2. The year in parentheses anchors the title: everything before (1995) is the title, whatever follows it is ignored. Put the year in parentheses when a title itself ends in a number, such as Parallel Park 3 (1990) or Varmint Lodge 2 (1994), so the film’s own number is never mistaken for its year.

3. A bare year in a release-style name is read when there are no parentheses. In Parallel.Park.3.1990.1080p.BluRay.x264-GRP.mkv the last plausible year is the release year and everything before it is the title, so Parallel Park 3 is found for 1990 and Varmint.Lodge.2.1994.1080p.mkv is the 1994 film called Varmint Lodge 2. Dots and underscores are read as spaces in a name that has no spaces of its own.

A name with no year at all is searched by title alone, cut at the first release tag (1080p, BluRay, x264, WEB-DL, …), and accepted only when TMDb has a single film by that title.

A file Sovereign can’t confidently match is skipped, and it’s named in the log on every scan with the path, why the match was refused, the films TMDb offered, and the tag that would settle it.

No confident TMDb match for /media/Movies/Ninth Take (2026)/Ninth Take (2026).mkv (title Ninth Take, year 2026, imdb null): 2 results match the title and year and nothing tells them apart; candidates: 123456 Ninth Take (2026), 234567 Ninth Take (2026); skipped until the folder is renamed or tagged [tmdbid-N]

Here two films called Ninth Take came out in 2026, and nothing in the folder name says which one you have. Add [tmdbid-123456] to the folder and the next scan imports it. The same line covers a title TMDb doesn’t hold at all (TMDb returned no results) and a folder whose name doesn’t match any result closely enough, in which case the nearest few are listed so you can see what TMDb calls the film.

You don’t have to read the log to find these. The admin Media Sources page lists every path a source’s last scan skipped, with the reason, the candidates and the tag to add, and an entry drops off the list as soon as a scan imports the file or finds it gone.

---

Naming Your Television Files

The recommended layout is one folder per series, holding a folder per season, holding the episode files:

• Directory/media/Television/

  • DirectoryThe Vellmouth Night Desk (2019) [tvdbid-123456]/

    • DirectorySeason 01/

      • The Vellmouth Night Desk - S01E01 - Night Shift.mkv
      • The Vellmouth Night Desk - S01E02 - The 4B.mkv
    • DirectorySpecials/

      • The Vellmouth Night Desk - S00E01 - Christmas on the Desk.mkv
  • DirectoryGullwing Court (2001)/

    • DirectorySeason 01/

      • Gullwing.Court.S01E01.Vacancy.1080p.BluRay.x264-GRP.mkv

The series folder names the series, and the file name numbers the episode. The file name doesn’t need to repeat the series title.

The Series Folder

The first folder under the source root identifies the series, the same way a movie folder identifies a film. A provider id tag wins outright:

The Vellmouth Night Desk (2019) [tvdbid-123456]/
The Vellmouth Night Desk (2019) {tvdb-123456}/
The Vellmouth Night Desk (2019) {tmdb-65432}/

A [tvdbid-...] tag gives the most reliable match. Sonarr writes one into every folder it renames, so a library that was ever managed by Sonarr identifies exactly, with no search and no ambiguity. A [tvdbid-...] or {tmdb-...} tag is also how you import a series whose name on TMDb differs from the one on disk, which a search would refuse.

Without a tag, the folder is searched by title and year, and the year in parentheses anchors the title the same way it does for a film. Television needs the year more than film does: remakes and revivals share a title far more often, and a search that can’t tell two of them apart is refused.

The Episode File

Sovereign reads the season and episode numbers from the file name. Every common spelling is understood:

In the file name	Read as
S01E02, s01e02, S01.E02, S01_E02	Season 1, episode 2
1x02, 01x02	Season 1, episode 2
S05E15E16	Season 5, episodes 15 and 16
S01E01-E02	Season 1, episodes 1 and 2
S01E01-03	Season 1, episodes 1, 2 and 3

Whatever follows the numbers is the episode title, cut at the first release tag, and is used only when TMDb has no title of its own for that episode.

Season Folders

A season folder is read as Season 01, Season 1, S01 or Series 1, and all of them mean the same season, so a library that holds a legacy Season 1 beside a padded Season 01 imports both into one season. Specials and Season 00 are season 0.

The season comes from the file name. Where a file’s own numbering disagrees with the folder it sits in, the file name wins and the mismatch is logged: a file named S02E03 under Season 01 is treated as a misfiled season 2 episode. A series directory with no season folders at all works too, as long as each file carries its own numbering.

Matching Rules

A TMDb search result is claimed only when its name matches the parsed title exactly (ignoring case, punctuation and accents) and its first-air year is within one of the parsed year, or when TMDb returns a single result. Anything less certain is skipped, along with every file under that folder. A skipped series is named in the log on every scan, with the reason, the series TMDb offered, and the tags that would settle it:

No confident TMDb match for series Saltfen (2014): no result matches the title and year closely enough; candidates: 345678 Saltfen (Shorts) (2013), 456789 Saltfen: Behind the Tide (2020); every file under it is skipped until the folder is renamed or tagged [tvdbid-N] or {tmdb-N}

Here TMDb calls the show Saltfen (Shorts), which is why the folder didn’t match. Add a [tvdbid-...] or {tmdb-...} tag to the folder, or rename it to match TMDb, and the next scan picks it up.

Series also need a TheTVDB id, which films don’t, because Sovereign keys series by it. A series TMDb holds no TheTVDB id for imports only when its folder carries a [tvdbid-...] tag, which then supplies the id. Without one the series is skipped and logged the same way, since importing it under some other key would give you two entries for the same show the day you add Sonarr. When a folder’s [tvdbid-...] tag disagrees with the TheTVDB id TMDb reports, the match is refused. Each of these refusals is logged again on every scan.

Episode Numbering Comes From TMDb

Episode titles, descriptions, air dates and stills come from TMDb, which for a handful of series numbers episodes differently from TheTVDB. The usual cause is a series that aired its episodes out of the order they were made: TMDb’s season 1 episode 1 is then the first one broadcast, while TheTVDB’s is the first one produced.

Your file still lands on the episode its name claims, and nothing is misplaced, but the title shown against it is TMDb’s for that number. Adding a Sonarr source for the series corrects it, because Sonarr’s sync adopts the episode and replaces its metadata.

One File per Episode

When two files resolve to the same episode, only the larger is imported and the rest are logged. Two files of the same film are handled the same way.

A multi-episode file (one file holding S05E15E16) is attached to the first episode it names, because a file belongs to one episode. The second episode is still created and still appears in the series, without a file of its own. Sonarr models the same file as belonging to both episodes, so a library that has both sources will show the file against different episodes of the pair depending on which source supplied it. Both play the same thing.

---

What Is Ignored

These apply to both kinds of source:

• Extras folders - Featurettes, Trailers, Behind The Scenes, Deleted Scenes, Interviews, Scenes, Shorts, Extras, Other, Sample, Samples, Subs and Subtitles are skipped whole, so their contents are never searched for as titles.
• Samples and trailers - a file with sample as a separate word anywhere in its name, or whose name ends in -trailer, is skipped.
• Hidden entries and symbolic links - dot-prefixed names are never read, and links aren’t followed, so a link pointing outside the directory can’t make a path playable.
• Edition tags - {edition-Director's Cut} and any other {...} or [...] group is stripped before the title is read.
• Files under one megabyte, and anything that isn’t a video container: .mkv, .mp4, .m4v, .avi, .mov, .wmv, .ts, .m2ts, .mpg, .mpeg, .webm, .flv.
• Artwork and metadata files - a series folder’s poster.jpg, fanart.jpg and tvshow.nfo aren’t video files, so they’re never read. Sovereign takes its artwork from TMDb.

A television file that carries no readable season and episode number is skipped and logged by name, so a stray behind the scenes.mkv tells you exactly why it didn’t import.

---

Examples

Movies

Path	Read as
The Glass Wren (1995)/The Glass Wren (1995).mkv	The Glass Wren, 1995
The Glass Wren (1995) [tmdbid-12345]/The Glass Wren (1995) - [Bluray-1080p][EAC3 5.1][x265]-GRP.mkv	TMDb id 12345, no search
The Glass Wren/The.Glass.Wren.1995.1080p.BluRay.x264-GRP.mkv	The Glass Wren, 1995 (year from the file)
The.Larkspur.Job.2001.1080p.BluRay.x264-GRP.mkv	The Larkspur Job, 2001
Parallel Park 3 (1990)/Parallel Park 3 (1990).mkv	Parallel Park 3, 1990
Parallel.Park.3.1990.2160p.UHD.BluRay.x265.mkv	Parallel Park 3, 1990
Parallel Park (1985) {edition-Director's Cut}/Parallel Park (1985).mkv	Parallel Park, 1985
Glumwick (2001) [tt7654321]-alfaHD.mkv	IMDb id tt7654321, resolved through TMDb
The.Glass.Wren.720p.BluRay.mkv	The Glass Wren, no year; imported only if TMDb has one film by that title
The Glass Wren (1995)/The Glass Wren (1995)-sample.mkv	ignored
The Glass Wren (1995)/Featurettes/making-of.mkv	ignored

Television

Path	Read as
The Vellmouth Night Desk (2019) [tvdbid-123456]/Season 01/The.Vellmouth.Night.Desk.S01E01.mkv	TheTVDB id 123456, season 1 episode 1
Gullwing Court (2001)/Season 01/Gullwing.Court.S01E01.Vacancy.mkv	Gullwing Court 2001 by search, season 1 episode 1
Gullwing Court (2001)/Season 1/Gullwing.Court.S01E02.mkv	the same season 1 as Season 01
The Vellmouth Night Desk (2019)/Specials/The.Vellmouth.Night.Desk.S00E01.mkv	season 0, episode 1
Titanback Express (2023)/Season 02/Titanback.Express.S02E07E08.mkv	season 2, episodes 7 and 8; the file goes to episode 7
Show (2001)/Season 01/Show.1x02.mkv	season 1, episode 2
Show (2001)/Show.S04E07.mkv	season 4 episode 7, with no season folder
Show (2001)/Season 01/Show.S02E03.mkv	season 2 episode 3, and the mismatch is logged
Show (2001)/Season 01/behind the scenes.mkv	ignored, and logged by name

---

Living Alongside Radarr and Sonarr

A title that both a directory and an Arr supply is one entry with two files, not two entries. Movies are keyed by their TMDb id, series by their TheTVDB id, and files by their source and path.

The Arr’s metadata wins. On a movie Radarr supplies, the directory adds its file and nothing else, and the title, overview, ratings, genres, collection and artwork stay as Radarr set them. On a series Sonarr supplies, the directory never changes anything Sonarr describes: the series, and every season and episode Sonarr lists, keep Sonarr’s metadata and artwork. A file naming an episode or season Sonarr doesn’t list still imports. Sovereign creates that episode (and its season, if needed) from TMDb, and if Sonarr lists it later, Sonarr takes it over instead of adding a second copy.

Removing a file from the directory removes only that file at the next scan. The title itself stays as long as any source still has a file for it, and leaves the library, with its artwork and generated assets, when none does. Removing a whole series folder retires the series only when no other source still reports it.

Pointing a directory at a tree an Arr also manages is allowed, and Sovereign tells you when it happens rather than stopping it. Every scan logs a warning naming the other source and how many files it shares, and the admin Media Sources page shows a shared files badge on both sources with the same figures. Nothing breaks, but each shared title then lists the same file once per source, which is rarely what you meant, so keep the two kinds of source on separate directories.

---

Mediainfo

An Arr supplies a file’s codecs, resolution, languages and runtime; a directory can’t, so Sovereign probes each new or rewritten file once with FFprobe and stores the result in the same form. A file is re-probed only when its size or last-modified time changes, so a steady-state scan is a directory walk with no probing at all. A file whose probe fails is still imported and is described at first playback instead.

---

Rate and Cost

A directory source asks Sovereign’s metadata service about a title only when it meets something new, and about each title at most once a day. Your server keeps each answer for a day, so between refreshes a scan is just a walk of the directory.