Gallery Docs
Documentation version
Gallery Docs

Organize your media files

General Tips on how to get the best matching results for movies or series.

We always use TMDB as the source of truth for movies and series.

We DO NOT support movies or series split across multiple files. They must all be a single file.

Movies#

Each movie should be in it’s own directory. You may optionally include multiple versions of the movie in the same directory. All of those movie files MUST be the same movie as the directory name. We will use the directory name to match against TMDB.

The directory name should be formatted like so Movie Name (year)

You may optionally include a [tmdbid-<id>] in the directory name. This will be used to match against TMDB instead of searching for the movie name/year in TMDB.

TV Shows#

Each Series should be in it’s own directory.

The Series top level directory should be formatted like so Series Name (year)

You may optionally include a [tmdbid-<id>] in the directory name. This will be used to match against TMDB instead of searching for the series name/year in TMDB.

Inside of the top level Series directory you should include the episodes in a subdirectory formatted like so Season <number>

Each file inside of the Season <number> directory should contain a string that dictates the season and episode number like so S01E01.

You CANNOT include tmdbid-<id> in the filename of the episode. This is because TMDB does not provide a way to match against episode numbers. We attempt to match against the filename with SXXEYY where XX is the season number and YY is the episode number. If not we try to match against the filename with EYY where YY is the episode number. If not we try to clean the filename and match against the episode titles in the season from TMDB. If not we try to match the substring of the episode title in the filename with the episode title in the season from TMDB. If not, we do NOT add the episode to the album.

For BEST results, the filename should be formatted like so S01E01 - Episode Title.

You may optionally include multiple versions of the series in the same directory. All of those series files MUST be the same series as the directory name. We will use the directory name to match against TMDB.

Books#

Book libraries follow the Jellyfin book layout: one folder per book, optionally grouped by author. Gallery also copes with looser layouts, so a perfect structure is not required.

We use OpenLibrary as the source of truth for books. A book that OpenLibrary does not know stays in the library under the title taken from its file name.

Supported files#

Kind Extensions
Ebooks epub, pdf
Comics cbz, cbr
Audiobooks mp3, m4b, m4a, ogg, flac, aac, opus, wav

mobi and azw3 are not supported. Convert them to epub.

Best layout#

Books/
  Frank Herbert/
    Dune/
      Dune.epub
      Dune.pdf          <- another format of the same book
      cover.jpg
  Neil Gaiman/
    Norse Mythology.epub
Audiobooks/
  Andy Weir/
    Project Hail Mary/
      Part 01.mp3
      Part 02.mp3
Comics/
  Plastic Man (1944)/
    Plastic Man #002 (1944).cbz
  • Ebooks: each ebook file is one book. Files of the same book in other formats become extra formats of that book.
  • Audiobooks and comics: all files in one folder are one book (one series for comics). Name the folder after the book.
  • Author folders are optional. A folder named First Last or Last, First above a book is used as the author hint.

All of these find the same book:

Dune.epub                               (inside Frank Herbert/Dune/)
Dune - Frank Herbert.epub
Frank Herbert - Dune.epub
Herbert, Frank - Dune.epub
Dune by Frank Herbert.epub
Frank Herbert - [Dune Chronicles 1] - Dune (1965).epub

Gallery removes release noise before it searches: (epub), [ebook], -groupname123, RtR, (Publisher, 2007) and similar. A year in parentheses and a series in square brackets are kept as hints. A file named only Vol. 01 or 020 takes its title from the folder above it.

When a file name has two parts, Gallery cannot always tell which part is the author. It tries each reading and only accepts the one that OpenLibrary confirms, so a wrong reading never replaces a right one. Names such as Call of Cthulhu RPG - Blood Brothers that are not “Title - Author” stay as one title.

Audiobooks#

Put each audiobook in its own folder. Gallery plays the files of one folder in order, and it sorts numbers by value, so 2-01 plays before 10-01.

Audiobooks/
  Daniel Keyes - Flowers for Algernon/
    001.mp3
    002.mp3
  Harry Potter/
    Book 1. Harry Potter & the Sorcerer's Stone/
      1-01 Introduction.mp3
      cover.jpg
    Book 2. Harry Potter & the Chamber of Secrets/
  Brave New World/
    Brave New World   Aldous Huxley   Audiobook Full.mp3

Gallery reads these, from strongest to weakest:

  1. Audio tags. The album tag names the book, and album_artist or artist names the author. Tags of the form series and series-part give the series. An artist tag that repeats the title is ignored, and a tag author is kept only when OpenLibrary knows the name, because some files carry the narrator there.
  2. The folder name. Author - Title, Title - Author, or just the title.
  3. The file name of a single-file audiobook. Fields can be separated by three spaces, and words such as Audiobook Full are ignored.

Each audio file shows its title tag as the chapter title. A title such as 001 or Track 01 names nothing, so Gallery shows the file name then. Gallery reads the narrator from a narrator tag, a “Read by” comment, or the composer tag (without the publisher and the author), and shows “Narrated by” on the book page.

A cover image in the book folder (cover, folder, poster, or any name that contains cover) is used when OpenLibrary has no cover.

Keep files that are not part of the book, such as replacement chapters, out of the book folder. Gallery adds every audio file in a folder to the book. Files with sample in the name are skipped.

Series#

Gallery stores the series and the position of a book in it. It reads them from, in this order:

  • tags: series and series-part in audio files, calibre:series in EPUB files, and ComicInfo.xml
  • a bracket in the name: Brandon Sanderson - [Mistborn 01] - The Final Empire.epub
  • a number in the name: Book 3. Title, 03. Title, Title - 3 - Author, Author - Dark Tower 05 - Title
  • a folder: Redwall Series, Narnia Collection, or a folder whose books all start with the folder name, as in Harry Potter/Book 1. Harry Potter & the Sorcerer's Stone

A file that the file watcher adds on its own joins the series of the books already stored beside it, when its title starts with the folder name. A scan of the whole library finds series for every folder.

Libraries can sort and filter by series. The book page shows Series #N.

Metadata inside files#

Gallery reads these before the file name. They are the most reliable source:

  • epub files: the title, author, ISBN, and series (calibre:series) stored inside the file.
  • metadata.opf or content.opf beside a book. It counts only when that folder holds one book.
  • ComicInfo.xml inside a cbz file.

Forcing a match#

Add an OpenLibrary work ID or an ISBN to the file or folder name. Gallery then skips the name search:

Dune [olid-OL893415W].epub
Dune [isbn-9780441172719].epub

Re-matching#

A normal scan only looks at new or changed files. Run a scan with Refresh metadata to match every file again, for example after you rename files.

Music#

Music libraries follow the Jellyfin music layout: each album sits in its own folder, and one folder holds one album. Gallery does not need artist folders, but they are fine.

We read the tags inside the audio files first. File and folder names only fill what the tags lack. MusicBrainz then adds IDs, genres, labels, and a cover when it knows the album. An album that MusicBrainz does not know still enters the library with its tags.

Best layout#

Music/
  AC-DC/
    Flick of the Switch (1983)/
      cover.jpg
      01 - Rising Power.flac
      02 - This House Is on Fire.flac
  Soundtrack Album/
    Whatever You.mp3
    Like To.mp3

Every file needs a title, and an album or an artist. Gallery takes each from the first source that has it:

Value Sources, in order
Title title tag, then the file name
Track number track tag, then a number at the start of the file name (01 - , 01. , 1-05 )
Album album tag, then the folder name
Album artist albumartist tag, then the artist tags, then the folder name
Year date tag, then the folder name

A loose file that names an artist but no album, such as Enya - Orinoco Flow.mp3 in the library root, goes into that artist’s Unknown Album. A file with neither an album nor an artist from any source is not imported. The scan reports each skipped file with the reason.

A folder that mixes albums splits by the album tag, so a dump folder of tagged songs still sorts into its albums. Hidden files (._song.mp3) and system folders (@eaDir, #recycle) are ignored.

Folder names such as Artist - Album (2011) [FLAC], 2011 - Album, [2008] Artist - Album, and Artist-Album-2011-GROUP give an album, an artist, and a year.

Multiple discs and compilations#

Disc subfolders (CD1, Disc 2) belong to the album folder above them. A compilation tag, or tracks by many artists with no albumartist tag, give the album the artist Various Artists. Each track keeps its own artist.

Covers#

Gallery uses the first of these:

  1. A cover file in the album folder: cover, folder, poster, default, front, albumart, or album as jpg, png, or webp. A lone image in the folder counts too, and so does one of these names in an Artwork or Covers subfolder.
  2. The picture embedded in a track.
  3. The Cover Art Archive, when MusicBrainz knows the album.

Matching MusicBrainz#

For each album Gallery searches MusicBrainz by album and artist. It accepts a release only when the title, the artist, and the track list all agree. Your tags and file names stay as you wrote them. If the tags hold a MusicBrainz Album Id, Gallery uses that release without a search.

MusicBrainz allows one request per second, so a large library needs time on its first scan. Albums appear as the scan goes.

Re-matching#

A normal scan only looks at folders with new or changed files. Run a scan with Refresh metadata to match every album again, for example after you fix tags.

Edit this page