File and folder naming

Good names help the server recognize your titles correctly. This page shows how to name and arrange movies, series, extras, subtitles and images. To see which layouts also work, read Flexible file layout.

The main rule: folder name = title + year, with the video and its companion files in the same folder. The year helps scraping match the right title. Without a year it still works, but titles with the same name are more likely to be matched wrongly.

Put an ID in the name#

If a folder or file name contains a source ID, scraping uses it directly instead of guessing from the name. This is the most accurate way.

Movies/
  Inception (2010) [tmdbid-27205]/
  The Matrix (1999) {imdb-tt0133093}/
TV Shows/
  Breaking Bad (2008) [tmdbid-1396]/
    Season 1/

Accepted forms: [tmdbid-123], {tmdb-123}, [imdbid-tt1234567], {imdb-tt1234567}, [tvdbid-123] (any letter case). The ID is not shown in the display name. A tag on a season folder is the ID of that season.

Movies#

Standard layout: one folder per movie.

Movies/
  Movie Name (2010)/
    Movie Name (2010).mkv
    Movie Name (2010).nfo            (optional)
    poster.jpg                       (optional)
    fanart.jpg                       (optional)
    Movie Name (2010).zh-Hant.srt    (optional external subtitle)

• Write the title and year as Title (2010), Title [2010] or Name.2017.1080p. If there are several, the last year wrapped in separators is used. Release tags such as 1080p, BluRay and x265 are ignored.
• A movie file can sit directly in the library root (Loose Movie (2019).mp4). Then folder-level files such as poster.jpg and movie.nfo are not assigned to it. Use file-name-plus-suffix names instead: Loose Movie (2019)-poster.jpg, Loose Movie (2019).nfo. We recommend one folder per movie.
• Several movies in one folder also work, each as its own title. Folder-level poster.jpg and movie.nfo are then not given to any of them, so name images <file name>-poster.jpg.

Several versions of one movie#

Several videos in one folder whose names are "folder name - version name" are merged into one movie with several versions. You pick the version when you play.

Blade Runner 2049 (2017)/
  Blade Runner 2049 (2017) - 1080p.mkv
  Blade Runner 2049 (2017) - 4K.mkv

• The version name is the text after - (1080p, 4K, Director's Cut and so on).
• At most 8 versions are merged. With more, or when the names do not share a title, each file becomes its own movie.
• An [tmdbid-…] tag does not affect merging; with or without it they count as one movie.
• The same movie in different folders (for example 1080p in one place and 4K in another) is not merged by this rule.

Split videos (CD1 / CD2)#

When one movie is cut into several files, end the names with cd1, cd2 (or part1, disc2, pt2). They are stacked into one movie and play one after another.

CAT-1001/
  CAT-1001-cd1.mp4
  CAT-1001-cd2.mp4

The part number is a single character (1 to 9 or a to d). The separator can be a space, ., _ or -. Letter case does not matter.

Extras (trailers, behind the scenes)#

Two ways:

1. Put them in a sub-folder named one of: trailers, extras, featurettes, behind the scenes, deleted scenes, interviews, scenes, shorts, clips, other, 预告片, 花絮, 特典.
2. Keep them in the movie's folder and add a suffix to the name: -trailer, -featurette, -deleted and so on (XXX-trailer.mp4).

Extras are attached to that movie (or that series or season). They do not become separate movies.

Videos with catalog numbers#

• Name the folder and file with the catalog number, for example CAT-1001/CAT-1001.mp4. Split-video and multi-version rules are the same as above.
• The catalog number field (searchable by catalog number) comes from <num> in the NFO. The server does not guess a catalog number from the file name, because wrong guesses are common. Create the NFO with a scraping tool or plugin, or fill it with a scraping plugin.
• When several titles share one folder, use <file name>-poster.jpg and <file name>.nfo. Otherwise images and NFO are not assigned.

Disc images and disc folders#

• .iso Blu-ray images are supported. One image is one playable unit; the main title, running time and chapters are found automatically. For several discs use the -disc1, -disc2 rule.
• Disc folders are not supported (the unpacked BDMV/ or VIDEO_TS/ structure). The .m2ts and .vob files inside are skipped, so one disc does not turn into dozens of "movies". Pack the disc as an .iso, or convert it to .mkv with MakeMKV.
• DVD .iso, .img and .nrg are not supported yet. They are added to the library without media info.

TV shows#

Standard layout: show folder → season folder → episode files.

TV Shows/
  Breaking Bad (2008)/
    tvshow.nfo                       (optional)
    poster.jpg                       (optional)
    Season 01/
      season.nfo                     (optional)
      Breaking Bad - S01E01 - Pilot.mkv
      Breaking Bad - S01E01 - Pilot.nfo
      Breaking Bad - S01E01 - Pilot-thumb.jpg
      Breaking Bad - S01E02.mkv
    Season 02/
      Breaking Bad - S02E01-E02.mkv  (one file, two episodes)
    Specials/
      Breaking Bad - S00E01.mkv

Season folders can be named Season 1, Season 01, S01, 第2季 or 第二季. Specials and 特别篇 are season 0 (specials). A season folder with no videos does not create a season.

Episode file names can be written like this:

• The episode title comes from the NFO first. Without an NFO, the text after the season/episode marker in the file name is used (cut off at technical tags such as 1080p or WEB-DL). If there is none, "Episode N" is shown.
• The season number comes from the NFO first, then the file name, then the season folder it sits in.
• Season folders are optional. Put episodes directly in the show folder and name them S01E02. Anime that only has episode numbers (no season) can also sit in the show folder with absolute numbering; scraping tries to map the absolute number to the right season and episode, and anything that does not match is listed as needing identification so you can fix it by hand.
• Name a show's season folders with a season number, such as Season N.
• Extras: put an extras (or similar) folder under the show or season folder, as for movies.

Category folders#

You do not have to put every show in the library root.

Series/
  Mainland/
    Some Show/
      Season 1/
  Japan/
    Anime/
      Some Anime/
        Season 1/
        Season 2/

"Mainland", "Japan" and "Anime" are category folders. They do not become shows, and there is no depth limit. The server treats the first folder that holds videos directly, has season folders, or has a tvshow.nfo as the show, so do not put videos directly in a category folder: it would be taken as a show.

Part folders such as Part 1 / Part 2 (including 上部/下部, 第一部/第二部) are treated as two seasons of the same show.

A folder per episode (common in downloaded releases) also works, but only in a TV library, and only inside a show-name folder, for example Show/[Group] Show - 01 [1080p]/ and Show/[Group] Show - 02 [1080p]/. That level needs at least 2 folders, each holding just 1 video, with episode numbers that can be told apart.

Limits and tips#

• Anime movies (one folder and one file each) belong in a Movies library. In a TV library they become shows with very few episodes.
• Episodes of several shows in one folder, with no show folders, cannot be told apart. Use one folder per show.
• A file name that is only a number (01.mkv) still gives the episode number, but the show name then comes from the folder name, so make sure it is correct.

External subtitles and audio tracks#

Put them next to the video. The name is video file name + language tag + extension.

Movie Name (2010).mkv
Movie Name (2010).zh-Hant.srt
Movie Name (2010).en.ass
Movie Name (2010).chs.forced.srt

• Subtitle formats: srt, ass, ssa, vtt, sup (Blu-ray image subtitles), and idx + sub (DVD image subtitles). A standalone .smi or .sub (MicroDVD) is not supported.
• Language tags: zh, zh-Hans, chs, zh-CN (Simplified); zh-Hant, cht, zh-TW, big5 (Traditional); en, eng, ja, jpn and so on. Add forced or default to mark forced and default tracks.
• For a multi-version movie, the folder name can be used as the subtitle's base name, and it applies to all versions.
• Adding or removing a subtitle file is picked up by real-time monitoring or the next scan. You do not need to rebuild the library.

Image files#

Put them in the title's folder, or next to the video using file name + suffix.

Local images take priority over online sources, so images you place by hand are not overwritten by scraping. Supported formats are jpg, png and webp.