These docs are for MetaTana 2.0, coming soon
Settings
Settings sits at the bottom of the sidebar. It has five sections: General, Account, Providers, Files, and Maintenance. Settings save as you change them, and each section keeps less-used controls under More at the bottom.
Search settings… above the section list finds a setting by its name or its old tab name, and the matching group shows, for example, Was “Renamer”. Every group is also in ⌘K (Ctrl+K on Windows and Linux) as Settings: …, and G then , opens Settings. Old Settings links open the new place; Upgrading to 2.0 lists where each old tab went.
Some things live on their own pages: watched folders are on Folders, media servers and Trakt are on Sync, and updates are on Help.
General
| Group | What's there |
|---|---|
| Matching | AI Scrape new files, and Manage tags… with tag presets and tag rules |
| Scanning | Watch folders for changes for every folder, Incremental scan, Scrape right after a scan, and Preview only (no file changes). See Scanning and matching |
| After a title is filed | The follow-up steps that run after you approve an arrival |
| Duplicates | Keep the best copy for and Suggest which copy to keep |
| Language & region | Interface language, metadata language, and region |
| Skip while scanning | Files smaller than for movie files, Never scan for folders and files, and Ignore words in names, which removes those words before a name is read |
| More | Profile, Library stats, and Database |
Run setup again at the top of General opens the first-run setup over Settings. Finishing it opens the Library.
Tags
Tag presets are in Manage tags… under Matching. If they don't load, the drawer shows Couldn't load tag presets, and editing and saving stay paused. Select Retry before editing, so a failed load cannot replace your saved list.
Tag rules in the same drawer add a tag on their own. A rule has one tag and one condition: Video is 2160p, 1080p, 720p or SD; Filename contains some text; or Content rating is one or more ratings, for example G or TV-Y. Save applies the rules to your whole library, a new title gets them when it is filed from the Inbox, and a title gets them again after a scan, a Scrape, a rename or Reload Media Info. Removing a rule removes only the tags that rule added; tags you or a folder added stay.
After a title is filed
These steps run after you approve an arrival in the Inbox: Refresh media servers, Subtitle search (Pro), Flag disc copies for follow-up, and Webhooks (Pro). Waiting in Inbox below them shows how many steps will and won't run for the batches waiting now, and Show lists each batch with its first blocking reason.
Nothing runs until you approve: the preview files nothing and runs no step. Locked metadata fields stay protected, and Activity and the arrival's timeline show progress and retries. Turning off Refresh media servers removes that step without blocking the filing itself, and if no media server is set up or ready, MetaTana marks the refresh as skipped instead of pretending it ran.
Account
Plan, Credits, Sign-in & devices, and Privacy & data, with Plan details under More. See Accounts and Pro for plans, sign-in, and devices, and Credits and billing for AI credits.
Providers
| Group | What's there |
|---|---|
| Your keys | Your own metadata provider keys. See API keys |
| Source priority | Which provider fills each field, and the rating sources |
| Subtitles | OpenSubtitles and SubDL, languages, forced and SDH subtitles |
| AI keys | Your own AI provider keys |
| Refresh | How a refresh applies provider values |
| More sources | Anime defaults, artwork and people, artwork languages, trailers, and AI models |
| More | Provider availability, Release countries, Saved translations, Trakt client keys, and Key setup |
MetaTana ignores a language or region value it doesn't recognize instead of sending it to providers. See Providers for what each provider supplies.
Files
| Group | What's there |
|---|---|
| Media player preset | The default player MetaTana writes NFO and artwork files for: Kodi, Plex, Jellyfin, Emby, or None |
| Naming | The naming patterns for movies, episodes, and anime. See Naming and organizing |
| Sidecar files | Subtitle file names |
| NFO files | Flavour and the NFO options. See NFO and artwork |
| More | Scrape defaults: whether a Scrape saves artwork files and writes NFO files by default |
Maintenance
| Group | What's there |
|---|---|
| Library health | Compares the library with the files on disk. See Library health |
| People | Merge duplicate people and clean up cast and crew credits |
| Backups | Database backups, Settings file, Import a tinyMediaManager setup, and Export N titles. See Back up your library |
| Tools | Tools and hooks that run your own scripts. See Tools and hooks |
| Trash | How long replaced and removed files are kept, the largest file to keep, and the size limit |
| Data & diagnostics | The data and logs folders, and Copy diagnostics |
| Advanced | API key, the command-line tool, MCP, and Webhooks. See Set up the local API key |
| Danger zone | Reset library and Factory reset. Both save a Before reset backup first |
| More | Tool order |
The Settings file backup doesn't include provider keys. Database backups do, so keep them private.
Library health
Library health in Maintenance compares what is on disk with what the MetaTana database has recorded. If Library says you have 5,000 titles but disk says 5,200, it tells you which files MetaTana doesn't know about (untracked files), which entries point at files that are gone (ghost entries), and which folders are empty.
| Row | What it does |
|---|---|
| Health summary | A word and the named issues, for example "Healthy · 12 titles missing artwork, 2 duplicates". Details… opens the breakdown: missing metadata, missing artwork, bad naming, duplicates, never scraped, metadata older than 6 months, no subtitles, below 1080p, older codec, and incomplete seasons. |
| Files missing artwork | Show opens Library filtered to them, where you can fetch the artwork. |
| Duplicates | Review opens the duplicates in the Inbox. |
| Deep check | Run deep check uses AI (Pro) to check a limited number of titles, such as whether a poster fits the title, and lists the findings to review. Find orphan files compares the library with disk. |
| Season artwork names | Check… finds season images saved under old names. |
Use it after large imports or metadata repairs, rename or organize batches, files moved by hand, mount or folder path changes, and restores. Library can show missing-file and offline-folder warnings while you browse; Library health runs the broader disk check and cleanup. If a folder moved and MetaTana verified its new path, checks use the new location.
Find orphan files
Find orphan files lists three things:
| Signal | What it means | Fix |
|---|---|---|
| Ghost entries | The database has a title but its file is missing from disk | Fix the mount or path first if the file moved; Remove all ghost entries when the files are gone for good |
| Untracked files | A media file sits inside a watched folder but isn't in the library | Scan the folder, or check why the scan skipped it |
| Empty directories | Folders that held media but no longer do (often after a rename or move) | Remove empty directories. Only folders with nothing in them are deleted |
Review every cleanup set before applying it. A ghost entry, untracked file, or empty folder describes a mismatch; it does not by itself prove which side should change.
Season artwork names
Older versions saved season posters, banners, and fanart as season-poster.jpg (and season-banner, season-fanart) inside the season folder. Season artwork names finds them and renames them to the names your media server reads:
- Select Check…The list shows each image as Show · season N · poster with the old and new names. The names follow the Flavour in Settings › Files › NFO files: Kodi and Emby, Jellyfin, or Plex. See File layout for the names each server uses.
- Read the conflictsAn image whose new name is already taken is left alone and says so. An image in a folder shared by several seasons is skipped, because it is unclear which season it belongs to.
- Select Rename N filesOnly images without a conflict are renamed. An existing file is never replaced.
- Undo if neededThe toast offers Undo, which puts the old names back. The rename can also be undone from Activity.
If nothing uses the old names, the section says "No season artwork uses the old names."
Common checks
- A file moved on disk. It shows as a ghost entry plus an untracked file at the new path. Scan the folder so MetaTana picks up the new path, then check again before removing anything.
- After a rename. Run Find orphan files to list empty directories left behind, and remove them in one action.
- After a Docker mount change or a share going offline. Every title on it can show as a ghost entry. Don't remove them: fix the folder path with Reconnect folder… on Folders, or reconnect the share, then scan and check again. The ghosts clear on their own.
- After a library reset. Every existing media file shows as untracked. Run a fresh scan to identify them again; there is nothing to clean up here.
Tools and hooks
Tools in Maintenance holds your own scripts and tool packs. A tool can run by hand on a title, or as a hook after a scan, scrape, rename, or organize. Tool order under More sets the order, and enables, clones, and exports tools.
Running a tool by hand and hooks that run on their own both need Pro. On Free, hooks are not queued; your saved hooks are kept and run again after you upgrade. Each run is listed in Activity under Show: Tools, with its output under Show output. A failed tool can have effects outside MetaTana, so read its output and its command before running it again.
Test a tool before saving it. Check the sample title, what it runs, and which events trigger it before letting it run on its own.
Values in shell scripts
A Shell Script tool never pastes ${...} values such as file names and titles into the script text. Each value reaches the script as an environment variable, so a file name that contains $(...), ;, or backticks is treated as text and never runs as a command.
- Read values from environment variables, for example
"$METATANA_PATH"in a shell script or$env:METATANA_PATHin PowerShell. - The Windows presets Open In Default App, Quick Preview, and Generate Checksum run PowerShell and read
$env:METATANA_PATH. - The tool editor shows Check this command when a script hands a value to a second program as code, for example
bash -c "... ${item.path}",powershell -Command, orpython -c. MetaTana can only protect values in the first program it starts. Read the value from an environment variable there instead. The warning also covers values inside a here-document (<<) and, on Windows, scripts that use!. A warning never blocks saving or running the tool.
Webhooks
Webhooks in Maintenance › Advanced send a message to another service when something happens, such as a title being filed. Test a webhook before saving it: check the message it sends, where it goes, and which events trigger it.
Webhooks need Pro. Without Pro, Webhooks shows your saved webhooks read-only and MetaTana does not send them. Nothing is deleted, and they send again after you upgrade. If MetaTana cannot reach metatana.com, it keeps sending for 24 hours after it last confirmed Pro.
Hooks and webhooks run in MetaTana's background process. Opening MetaTana signed in to a Pro account confirms Pro for it. A hook or webhook after a scan, scrape, rename, organize, or Arrivals filing that could not confirm Pro is kept across restarts and tried again every five minutes for an hour. For a Docker install that nobody opens in a browser, set METATANA_HOSTED_SESSION_TOKEN so MetaTana can confirm Pro by itself; see Docker installation.
If your saved webhooks don't load, Webhooks shows Couldn't load your saved webhooks with Retry. Adding and editing stay paused until they load, so nothing saved is replaced. If you change webhooks in two windows, the second save does not overwrite the first: it says This list changed in another window, loads the latest list, and asks you to make the change again.
Webhook addresses carry the receiving service's token, so the desktop app encrypts saved webhooks with your system keychain (see where saved keys are stored). If you move the app data folder to another computer, Webhooks shows Saved webhooks can't be opened on this computer. Add them again; nothing is sent until you do.
Where a webhook can point:
- Other devices on your network work, for example Home Assistant, ntfy, or Gotify on a
192.168.x.x,10.x.x.x, or Tailscale100.x.x.xaddress. - The computer MetaTana runs on (
localhost,127.0.0.1), link-local addresses, and cloud metadata addresses such as169.254.169.254are refused. This also applies when a domain name resolves to one of them. - Redirects are not followed. If the receiver answers with a redirect, save the address it redirects to.
Going deeper
- Activity: what ran, what failed, and Undo
- Reference: environment variables and the configuration you set outside the app
- Upgrading to 2.0: where each 1.x Settings tab went