File Layout#

This page shows where MetaTana keeps its state on disk, and where it writes sidecar files next to your media.

Where state lives (per platform)#

MetaTana keeps its state in one folder: the SQLite database, database backups, logs, and thumbnails. The default location depends on the platform. Recoverable trash is not kept here; it sits in each library folder (see Recoverable trash).

Inside the data directory#

Desktop apps keep these files in a data folder inside the app folder above. That data folder is the app's METATANA_DATA_DIR. Settings › Maintenance › Data & diagnostics shows its exact path, with a button to open it.

$METATANA_DATA_DIR/
├── metatana.db              # SQLite database (your library records and settings)
├── metatana.db-wal          # SQLite WAL journal (do not edit)
├── metatana.db-shm          # SQLite shared memory (do not edit)
├── backups/                 # library database backups
│   ├── metatana-20260929T030000123Z-daily-v<schema>.db
│   └── metatana-20260930T081500456Z-manual-v<schema>.db
├── logs/                    # app logs
├── runtime/                 # files the running app keeps for itself
├── thumbnails/              # artwork thumbnails (rebuilt when missing)
├── artwork-thumbnails/
├── desktop/                 # desktop app only: window state, sign-in
└── .env                     # optional environment variables

Each backup file name carries the time, the kind (daily, pre-migration, manual, pre-restore, or pre-reset), and the database version. In these examples, stands for that version number; it changes as the app updates. Settings › Maintenance › Backups shows these kinds as Daily, Before upgrade, Manual, Before restore, and Before reset. A restore also writes restore-pending.json and restore-status.json in backups/; leave them alone and use Settings › Maintenance › Backups instead.

Sidecars on disk (per content type)#

Sidecars are written next to your media files, not in $METATANA_DATA_DIR. By default the layout follows the Kodi-style names that most media servers read.

Movie#

/library/movies/Big Buck Bunny (2008)/
├── Big Buck Bunny (2008).mkv
├── Big Buck Bunny (2008).nfo
├── poster.jpg
├── fanart.jpg
├── clearart.png
├── logo.png
└── Subs/
    ├── Big Buck Bunny (2008).en.srt
    └── Big Buck Bunny (2008).en.forced.srt

TV show + episode#

/library/shows/Caminandes (2013)/
├── tvshow.nfo
├── poster.jpg
├── fanart.jpg
├── banner.jpg
├── season01-poster.jpg
├── season01-fanart.jpg
├── season-specials-poster.jpg
├── .actors/
│   └── First_Last.jpg
├── Season 01/
│   ├── Caminandes S01E01.mkv
│   ├── Caminandes S01E01.nfo
│   ├── Caminandes S01E01-thumb.jpg
│   └── Caminandes S01E01.en.srt
└── Season 02/
    └── ...

Show folders include the show's first-air year, as in Caminandes (2013)/Season 01/. The Kodi, Plex, Emby, and Jellyfin presets and the Settings › Files › Naming defaults and presets all use it; when the year is unknown it is left out. Two different shows never share one show folder. Existing show folders are not moved automatically, and saved custom patterns are not changed. See Naming and organizing.

If a folder already holds episodes of more than one show, a Scrape or Fetch season artwork writes no tvshow.nfo, show artwork, or season artwork into it, so one show's files never replace another's. The same goes for an episode that sits directly in a library or incoming folder (or in a season folder directly inside one): that folder is not a show folder, so it gets no show files and no .actors/ folder. Episode NFOs and episode stills are still written.

Artwork and subtitle names per media server#

MetaTana writes these names. The Plex column applies when Flavour in Settings › Files › NFO files is Plex or Plex artwork naming is selected. Subtitle names follow Subtitle file names in Settings › Files › Sidecar files.

Movies that sit loose in one shared folder get no extrafanart/, extrathumbs/, or .actors/ folder, because Kodi reads those folders for every movie in the folder. Autopilot keeps a poster or other image that is already in the folder and readable, and replaces only broken ones; Rescrape still replaces them, with Undo.

Where a library already has the older disc.png or thumb.jpg, MetaTana keeps writing to those files. The single extrafanart.jpg is no longer written, because no media server reads it. Plex reads a two- or three-letter language code (en or eng) followed by .forced, .sdh, or .cc; it reads .hi as Hindi, which is why Plex subtitles for the deaf and hard of hearing end in .sdh.

Season artwork per media server#

Each media server looks for season posters, banners, and fanart under different names. MetaTana writes the names your server reads. Flavour in Settings › Files › NFO files decides where season art goes. Plex artwork naming also selects the Plex names.

When episodes sit directly in the show folder with no season folder, season art always uses the show-folder names (season01-poster.jpg). MetaTana also reads the other servers' names and the older Season 01/season-poster.jpg name, so art written by another tool or an earlier version still shows up. Settings › Maintenance › Library health › Season artwork names renames those older Season 01/season-poster.jpg files to your server's names, never replacing an existing file, with Undo. A show scrape writes season art for every season on disk that has artwork, unless the season's artwork is locked.

Renaming or organizing an episode keeps Plex season posters and banners in their season folder, including Specials. Undo puts them back and restores any artwork they replaced.

Recoverable trash#

When MetaTana removes a duplicate copy, or replaces an NFO or artwork file, it keeps the old file in one hidden .metatana-trash folder at the root of the library folder. Only when the file is on a different drive from the library folder does the trash go beside the file instead.

/library/movies/
├── Big Buck Bunny (2008)/
│   ├── Big Buck Bunny (2008).nfo
│   └── poster.jpg
└── .metatana-trash/
    ├── duplicate-resolve/   # duplicate copies moved to the trash
    ├── replaced/            # NFO and artwork files MetaTana replaced
    └── undo/                # files an Undo moved aside

Undo puts files back from here, and removes folders it left empty. Kept files are deleted after 30 days by default. Settings › Maintenance › Trash shows the total size, sets how many days to keep files (Keep files for, 1 to 365, under Edit), and has Empty trash. It also sets the Largest file to keep (20 MB by default; larger files get no copy) and the Trash size limit (5 GB by default; past it, the oldest files go first). A copy is also skipped when it would leave less than 1 GB free on the drive. Emptying the trash, or the retention period passing, removes Undo from the changes that needed those files. Media servers ignore hidden folders, but if your server or backup tool lists them, exclude .metatana-trash.

Collection set artwork#

Kodi reads a collection's set artwork only from the Movie set information folder you choose in Kodi's settings, so check that it points at the folder that holds your set folders. MetaTana writes a collection's set.nfo, poster, and fanart to a set folder only when two or more titles of that collection are in your library, and never inside a movie's own folder:

• When the titles already share a folder named after the collection, that folder is used.
• When the titles sit in different top-level folders of one library folder, the set folder is /.
• Otherwise the set folder is inside the folder that holds the titles.
• With one title, MetaTana uses an existing folder named after the collection that holds the title's folder, or writes no set files.

Actor images#

Cast headshots go in an .actors/ folder next to the NFO, named with underscores for spaces: .actors/First_Last.jpg. This is the name Kodi documents. A movie that shares its folder with other movies, or an episode directly in a library or incoming folder, gets no .actors/ folder. When Actor headshot overwrite policy (in Settings › Providers › More sources › Artwork & people) is set to Keep existing files (the default), an older .actors/First Last.jpg is copied to the new name and the old file is left in place.

Anime (absolute order)#

/library/anime/Caminandes/
├── tvshow.nfo
├── poster.jpg
├── fanart.jpg
├── Caminandes - 001.mkv
├── Caminandes - 001.nfo
├── Caminandes - 002.mkv
└── Caminandes - 002.nfo

Settings › Files › NFO files chooses the NFO format (Kodi, Emby, Jellyfin, Plex, or MediaPortal) and its options; each folder can also use its own format. It also decides where season art goes (see above); other sidecars land in the same place for every format. Settings › Files › Naming controls folder and file naming. See Naming and organizing.

Docker mount layout (reference)#

A typical Docker setup mounts:

services:
  metatana:
    image: ghcr.io/metatana/metatana-app:stable
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data                     # $METATANA_DATA_DIR
      - /mnt/media/movies:/library/movies    # a folder you add in MetaTana
      - /mnt/media/shows:/library/shows      # a folder you add in MetaTana
    environment:
      - TMDB_API_KEY=...

On the Folders page you then add /library/movies and /library/shows: the container paths, not the host paths. See Troubleshooting: scan found too few files.

Going deeper#

• Reference: environment variables: METATANA_DATA_DIR, METATANA_DB_PATH, port overrides
• Back up your library: backups and restore
• NFO and artwork: sidecar format detail
• Library health: checking disk against the database (Settings › Maintenance › Library health)
• Docker deployment: compose example with the full layout