Name your media files

tofa reads names the way most media servers do, so a library that worked elsewhere usually just works. If you're starting fresh, name things like below and matching is reliable on the first scan.

Movies#

One folder per movie, with the year:

Movies/
  Heat (1995)/
    Heat (1995).mkv
  Alien (1979)/
    Alien (1979).mkv

Files loose in the library root also work (Movies/Heat (1995).mkv). The year isn't required, but it keeps remakes apart, so include it.

Quality and source tags in filenames are fine; they're ignored for matching:

Heat (1995) 2160p BluRay REMUX.mkv

A movie split over two files stacks into one title when the parts are numbered cd1/cd2, part1/part2, or disc1/disc2. Full disc rips (VIDEO_TS, BDMV) work too: the folder that contains them carries the title and year.

Shows#

One folder per show, one folder per season, season and episode in the filename:

Shows/
  Severance (2022)/
    Season 01/
      Severance S01E01.mkv
      Severance S01E02.mkv

• Two different shows with the same name must carry the year in the show folder (The Flash (1990) and The Flash (2014)); without it they are one name to tofa and end up as a single title.
• Season folders: Season 01, Season 1, and S01 all work.
• Episode markers: S01E02 is the most reliable. Also recognized: 1x02, EP02, dates for daily shows (2023.07.14), and plain episode numbers for absolute-numbered shows (Long Anime/1156.mkv).
• Two episodes in one file: S01E01-E02.
• Specials go in a Specials or Season 00 folder, or carry S00E01-style numbers in the filename.

One rule matters more than the rest: a show file with no recognizable episode marker is skipped. A movie without a year still scans; Shows/Severance/finale.mkv does not.

For different cuts of a show, such as colour and black-and-white editions, use {edition-Colour} and {edition-Black and White} tags. Put them on episode filenames for an edition picker within one show, or on show folders for separate listings with separate watched state. See TV edition naming examples, then run a library scan after renaming.

Episode order#

Most shows are numbered the way they aired, and that is what tofa assumes. Some collections use a different scheme, and you can tell tofa per show: open the show, choose Edit, and pick the order under Advanced.

• Aired is the default. Season and episode numbers follow the broadcast order.
• Absolute is for files that carry one running number across the whole show (Long Anime/1156.mkv), common for anime with hundreds of episodes. A show set to Absolute also displays its episodes as one continuous list instead of season groups.
• DVD appears for shows where we have home-release ordering data, for the handful of series whose discs arranged episodes differently than the broadcast did.

An order a show cannot use is simply not offered. Before a change applies, tofa previews what would change so you can confirm your files really are numbered that way. Ordering only changes how episodes are labeled and arranged; watch progress is never touched.

The same Advanced panel lets you hide season grouping for a show or prefer its original-language title. A library-wide default for episode ordering lives in the library's settings; the per-show choice always wins.

4K and 1080p of the same title#

Give both copies the same title and year; only the quality tags should differ:

Movies/
  Heat (1995)/
    Heat (1995) 2160p.mkv
    Heat (1995) 1080p.mkv

In the same library they merge into one title with a version picker automatically. If you keep 4K in its own library (say Movies and Movies 4K), turn on Cross-library version merge under Admin, then Libraries, and enable Merge versions on the libraries involved.

Trailers, samples, and extras#

Files named trailer.* or sample.*, files ending in -trailer, -sample, -featurette, -behindthescenes and similar, and anything inside folders named Trailers, Extras, Featurettes and so on are treated as extras and left out of the library. Don't name a real movie file trailer.mkv.

Subtitles#

Subtitle tracks inside the video file work, both text (SRT, ASS, VTT) and image-based (PGS, VobSub). Separate subtitle files work too: name them after the video, with optional language and flags between the name and the extension, or drop them in a Subs folder next to it.

Heat (1995)/
  Heat (1995).mkv
  Heat (1995).en.srt
  Heat (1995).en.forced.srt
  Heat (1995).is.sdh.srt
  Subs/
    german.srt

SRT, ASS/SSA, and VTT files are picked up. Use two- or three-letter language codes (en, eng, is); forced, sdh, and cc mark forced and hearing-impaired tracks. Files added later are noticed automatically.

Artwork#

Own posters, backgrounds, and logos? Drop poster.jpg, fanart.jpg, or logo.png into a folder and tofa uses them over the artwork it fetches. See Add your own artwork for the full list of names and recommended sizes.

Skipping folders#

Put an empty file named .tofaignore (or .nomedia) in a folder and tofa skips it and everything below it. Unfinished downloads (.part, .tmp, .crdownload and similar) are skipped automatically.

If something still matches wrong, you don't have to rename anything: Fix a wrong match sorts it from the web interface.