Naming And Organizing#

Renaming and organizing change files on disk, so do them after the metadata is reviewed.

Movie Versions And Parts#

The Emby and Jellyfin presets keep editions of one movie in a shared movie folder with a different filename for each version. They keep the movie title and year before the version label. Your saved custom patterns stay unchanged. Stacked CD1/CD2 movie parts share that folder's poster and fanart; unrelated movies in one folder keep separate artwork.

Rename Files: Quick How-To#

1. Make the folder writableMetaTana can only rename files it can write. In Docker, mount the media folder read/write (remove :ro) and make sure the PUID/PGID user can write to it. A read-only folder still scans; Folders shows Read only with "Scans work, file changes are blocked", and renames stay blocked.
2. Optional: choose file outputTo also write NFO and artwork for the folder, pick your player under For your player when you add the folder (the default, None, writes no sidecar files), or later turn on Write NFO files in the folder's Edit folder drawer on Folders. Settings › Files › Media player preset sets the default for every folder.
3. Set the patternOpen Settings › Files › Naming, then Edit next to Movies, Shows, or Anime. Start from a preset (Simple, Plex, Full, Kodi, or Anime Absolute), or edit Raw pattern. The Preview card shows the result for sample titles or My Library. If your saved patterns don't load, the page shows Couldn’t load your naming patterns with Retry, and editing stays paused so your saved patterns aren't replaced.
4. Run the renameIn Library, select the items, then choose Rename in the selection toolbar. The Bulk Rename dialog previews every change; uncheck anything you want to skip, then select Rename N Files.
5. Undo if neededThe results show Undo this batch to reverse the whole run. Later, open Activity with Show: Renames: renames are grouped by batch with Undo all, and each row has its own Undo. Associated NFO, artwork, and subtitle files move back too.

Pattern syntax#

• A token is written ${token}, for example ${title}, ${year}, ${showTitle}, ${seasonNr2}, ${episodeNr2}, ${episodeTitle}, ${resolution}, or ${ext}. The Tokens panel lists them all.
• / starts a new folder level.
• Formatters follow a ;: ${title;upper}, or ${genres;first(2);join(, )}. truncate(n) shortens a value to at most n characters, cutting at a word break where it can: ${edition;truncate(32)}.
• {?token}…{/token} outputs its contents only when that token has a value.
• A retired token renders as empty text, and the rename preview shows "This token is no longer supported". Remove it from the pattern.

The default movie pattern:

${title} (${year})/${title} (${year}).${ext}

turns a file into Big Buck Bunny (2008)/Big Buck Bunny (2008).mkv.

Show folders include the year#

Show folders carry the show's first-air year through the ${showYear} token. The default TV and anime pattern is:

${showTitle}{?showYear} (${showYear}){/showYear}/Season ${seasonNr2}/${showTitle} - S${seasonNr2}E${episodeNr2}{?episodeTitle} - ${episodeTitle}{/episodeTitle}.${ext}

so an episode lands in Doctor Who (2005)/Season 01/. The Kodi, Plex, Emby, and Jellyfin presets (Settings › Files › Media player preset and For your player) and every naming preset in Settings › Files › Naming (Simple, Plex, Full, Kodi, Anime Absolute) do the same. When the year is unknown, the folder is the show title alone.

• Two shows never share a folder. Organize skips a look-alike folder that holds another show and uses the folder with the year instead. If no other folder is left, the move waits with "another show with this name already uses that folder". Library Rename refuses the same move.
• Existing folders stay put. A show already in Doctor Who/ is not moved to Doctor Who (2005)/ automatically, even in a folder with Autopilot renames approved. Run Rename in Library to move it; the preview shows the new folder names first.
• Saved patterns are not changed. A custom pattern you saved, or a yearless preset you picked earlier, keeps its folders. Pick a preset again to get the year.
• Show files leave with the last episode. The show's tvshow.nfo, art and actor photos move with the last episode that leaves the folder, so renaming a whole show moves everything, and organizing one episode leaves them with the rest of the show.

Multi-episode files#

MetaTana keeps every episode of a file like Show.S01E01-E03.mkv, so rename and organize name the whole range. A pattern that names only the first episode, including the default TV pattern, gets the range added after the episode number:

A pattern that already uses ${episodeNrEnd} or ${episodeNrEnd2} (last episode in the range) is left as you wrote it, so S${seasonNr2}E${episodeNr2}E${episodeNrEnd2} gives S01E01E03. Organize without a pattern names the file Show - S01E01-E03. Organize holds a multi-episode file back only when a rescan is needed to confirm its episodes.

Daily shows#

A file named by air date can be organized once the show's provider episode list has exactly one episode for that date. Organize names it with that episode's season and number. When several episodes aired that day, the file waits until you pick one under Choose the episode (see Manage a TV show). Autopilot renames date-named files too, but only when exactly one episode aired that day and the provider's air date for that episode matches the file's date.

Plex editions#

Plex reads a movie's edition (Director's Cut, Extended, and so on) from an {edition-Name} tag in the folder and file name. When you pick Plex under For your player when adding a folder, or the Plex preset in Settings › Files › Media player preset or Naming, the movie pattern adds that tag:

${title} (${year}){?edition} {edition-${edition}}{/edition}/${title} (${year}){?edition} {edition-${edition}}{/edition}.${ext}

A movie with an edition becomes Alien (1979) {edition-Director's Cut}/Alien (1979) {edition-Director's Cut}.mkv. A movie without one keeps the plain Alien (1979)/Alien (1979).mkv. To get the same result from another pattern, add the {?edition} {edition-${edition}}{/edition} block after the year.

The Plex preset caps the edition name at 32 characters, because Plex ignores longer ones. Its tag is {?edition} {edition-${edition;truncate(32)}}{/edition}. A pattern saved by an earlier Plex preset is upgraded automatically; patterns you wrote yourself are not changed. In Settings › Files › Naming, a movie pattern without the edition tag is left alone, because it is also the Kodi preset and the default. Pick Plex again there to add the tag.

A scan reads the tag back: Blade Runner (1982) {edition-Final Cut}.mkv is the movie Blade Runner (1982), Final Cut edition, and the tag is not part of the title. So a library renamed with the Plex preset matches the same titles and editions on the next scan.

Filename characters in Settings › Files › Naming apply after the pattern: Spaces, Colons, ASCII only, and Lowercase extensions.

Autopilot Renames Wait In The Inbox#

You can let Autopilot tidy a folder for you. Pick Tidy into Movies and TV folders under File handling when you add the folder, or turn on Tidy into Movies and TV folders in the folder's Edit folder drawer on Folders. Leave files where they are, the default, means Autopilot proposes no renames for that folder.

Tidy keeps your own type folders. A file that already sits under a folder for its kind, such as Movies, Films, TV, TV Shows, Series, or Anime, stays in that folder along with any grouping folders inside it (Movies/Action/Alien (1979)/). Only files outside such a folder are sorted into new Movies and TV folders.

This choice on each folder is the only switch for renames; there is no global organize setting.

In a folder whose Rename files in this folder is Ask first, Autopilot moves nothing until you approve. Its rename proposals from every run wait in the Inbox under Renames, and Home's Inbox card has a Rename row. Select Review renames to see how many files change on disk, how many move to a different folder, and how many lose words from the filename, then select Rename N files. Approving renames, one at a time or all at once, approves only those renames and never changes the folder's rename mode. To let Autopilot rename new files in a folder without asking, set Rename files in this folder to Always in its Edit folder drawer; before each move it checks the file again and holds any file that is still changing. Setting a folder to Never, or turning Tidy into Movies and TV folders off, stops renames there, and renames already waiting for that folder leave the Inbox right away. Every rename is saved in Activity under Show: Renames, with Undo. See Inbox.

A rename held because the file was still copying or playing comes back for approval once the wait is over, in folders that still ask. If the file is gone by then, the held rename is dropped and the next scan proposes a new one.

When a Tidy rename moves the last file out of a folder, MetaTana removes that folder and any parent folders it leaves empty. Undo does the same for the folder the rename created. A folder counts as empty when it holds nothing, or only system files such as .DS_Store or Thumbs.db. Library folders, and folders with anything else in them, are never removed.

Undo also removes the empty folders it leaves behind in a destination or an output folder, such as the Alien (1979)/ folder an Organize made there.

If MetaTana stops in the middle of a move, for example after a crash or a power cut, it finishes or undoes that move the next time it starts. A movie and its NFO, artwork, and trailer end up together, either all in the new folder or all back where they were.

If you renamed a file outside MetaTana and a scan picked it up under the new name, a rename back to the old name completes instead of failing. When the old record has the same file size, MetaTana treats both as the same file and keeps its watch state.

Dry run (Preview only (no file changes) in Settings › General › Scanning) also holds back renames that were already approved: Autopilot proposes every move and rename for you to approve in the Inbox instead of moving files.

Rename Inputs#

Rename patterns can use fields such as:

• title
• year
• season and episode
• absolute episode number
• episode title
• edition or version
• provider IDs
• people fields
• movie set fields
• language or technical hints

Use patterns that match how your playback clients expect to scan local metadata.

• A special with no title of its own is named S00E01.mkv, not with the show's title.
• A title that starts with a dot loses the dot (45 (2006)/), because dot-names are hidden from scans and media servers.
• An existing folder keeps its spelling, including macOS-style accents.
• A Rescrape with Rename files keeps a file at the top of a library folder inside that folder.

Preview Before Execute#

The rename preview shows:

• current file path
• proposed target path
• sidecars that move with the media
• conflicts
• invalid or missing tokens
• whether a rename is skipped

Do not run broad rename batches when the preview still contains wrong identities.

MetaTana never renames or deletes one file from inside BDMV or VIDEO_TS as though it were a standalone movie. The complete disc folder must stay together. Organize and Rename move that folder only within the same drive, and never copy a disc folder to another drive. A disc folder move to another drive is refused before anything starts, with This disc folder is on a different drive from its destination. Move it within the same drive, or use Arrivals to publish it to another drive. Arrivals can file a complete disc folder to a destination on another drive: it copies the whole folder into a hidden staging folder beside the destination, checks every file, moves it into place, and only then removes the source files that still match. If MetaTana stops partway, it finishes or discards the copy on the next start, and anything it cannot confirm waits for you with nothing deleted. Deleting the disc's control file directly and automatic Undo are not offered, because either could damage a disc folder or miss files that appeared later. Run a new whole-folder action instead. An unavailable library stops preview and execute before file work starts. A read-only library can still show a preview, but execute stays blocked until write access is restored.

Organize, Undo, Delete, and duplicate cleanup also work on drives without hard link support, such as exFAT or FAT USB drives and some SMB shares. MetaTana never replaces a file that is already at the destination.

Organize Destinations#

Destinations are organized libraries. A destination can be used for movies, shows, anime, or other kinds of content.

Routing can use the folder, the type, tags, or your own rules. Keep routing simple until the library has clean metadata.

Destinations and routing rules are on Folders, in the Destinations and Advanced routing sections. The Naming section there shows your patterns with an example, and Edit naming opens Settings › Files › Naming. A library folder can also use its own pattern: set Naming to Custom in the folder's Edit folder drawer, and choose Rename files in this folder: Always, Ask first, or Never.

Rollback Thinking#

Before a large move:

1. Back up the databaseSelect Back up now in Settings › Maintenance › Backups, or copy the app data directory. See Back up your library. A database backup restores library records; Undo moves the files back.
2. Test with a small batchPick one folder or a small filter. Run the rename. Check the result before doing the rest.
3. Check Activity for failuresEach rename row shows what it did and the outcome. Failed rows tell you what stopped.
4. Confirm moved files and sidecars exist at the new pathsThe sidecar count in the Activity row should match what landed on disk.
5. Confirm Library points to the new pathsCheck the Files section on the title's page. If it still shows the old path, the database didn't follow the move.

Check both the old and new paths, not only that the rename reported success.