Skip to content
MetaTana

These docs are for MetaTana 2.0, coming soon

On this page

How MetaTana Works

MetaTana is a local-first app with a hosted account service beside it. The app owns your library: scanning, matching, metadata, files on disk, and sync. The hosted side owns your account, billing, device linking, and the Pro services in Skyhook.

This section explains the model behind each job. For step-by-step walkthroughs see Tasks, and for every control on a page see Pages.

The short version

  1. You add folders on Folders.
  2. MetaTana scans the files and matches each one to a title.
  3. It fills in metadata from local NFO files, providers, artwork, technical facts, and, when you ask, AI Vision.
  4. It saves the metadata you accept in its library database.
  5. You review changes in the Inbox, on each title's page, in the Rescrape dialog, and in Activity.
  6. When you choose to write files, MetaTana queues NFO, artwork, rename, and sync work.
  7. Media servers and exports read the same accepted metadata.

In this section

Architecture

Where MetaTana runs

The app can run as:

  • a desktop app for macOS, Windows, and Linux, with its own app server
  • one Docker container (optionally split into web and background containers), including the Unraid and TrueNAS app stores
  • a web app you open in a browser
  • the command-line tool (Pro) for selected workflows

Each starts and stops MetaTana, runs its background services, and checks the setup when it starts.

The app, the API, and the command-line tool share the same code for each task, so the same rules apply whether you click, call the API, or run a script. Scanning work that takes a lot of time runs in worker threads, and database writes stay in the main process.

The library database

MetaTana keeps your library decisions in a SQLite database. It stores:

  • folder, destination, and routing settings
  • file records and scan results
  • accepted movie, show, season, and episode matches
  • people, collections, tags, and extras
  • background file operations and their history
  • provider IDs and where each value came from
  • settings, media servers, and sync state

The database is not a cache you can throw away: it holds your decisions. MetaTana backs it up every day and before each update; see Back up your library. Every page reads from this one database, so a change made on one page shows on the others, and when files are written, the title's page, Activity, and the files on disk agree.

What is local

The app owns:

  • scanning, folders, destinations, and routing
  • the library database
  • NFO import and export
  • artwork and sidecar file writes
  • renames and moves
  • editing titles and metadata tasks
  • the Inbox, Activity, Library health, duplicates, backups, and export
  • media server setup and sync
  • your own provider keys, when you add them

What is hosted

The hosted side owns:

  • email-code sign-in and device linking
  • accounts, account deletion, billing, and Pro checks
  • hosted metadata through Skyhook
  • hosted AI Vision and AI translation
  • AI credits
  • MetaTana's own provider keys for hosted Pro services, which never reach the app

The hosted side never holds your media library. If MetaTana's servers can't be reached, the app stays signed in, pauses Pro features, and keeps your local library working; see Accounts and Pro. The app can fall back to your own provider keys where you added them.

The Pro check can't be skipped in a release Public desktop and Docker releases ignore every development-only sign-in setting. The command-line tool, API-key access, and MCP all need a verified Pro session with the hosted API. See API.

Integrations

MetaTana works with metadata providers, artwork providers, subtitle sources, media servers, Trakt, and its own hosted account service. Examples include TMDB, TheTVDB, OMDb, Fanart.tv, MDBList, AniList, MyAnimeList, Plex, Jellyfin, Kodi, Emby, and Trakt.

Integrations stay metadata-only. MetaTana works with libraries you already have and the players you use. It does not work with media acquisition, release, or distribution catalogs. Each provider has its own terms, attribution, rate limits, and caching rules, and MetaTana turns a provider on for hosted use only after it passes a provider-policy check; see Provider policy.

Why review comes first

Media metadata is messy. The same title can have remakes, alternate cuts, aired order, DVD order, absolute anime order, specials, extras, and provider disagreements. MetaTana shows its evidence before it writes anything:

  1. Identify.
  2. Preview.
  3. Apply.
  4. Queue file changes.
  5. Check the result in Activity, on the title's page, and in the files on disk.

That is why the app has title pages, side-by-side comparisons, the Inbox, metadata tasks, Activity, and Library health instead of one hidden "fix my library" button.

For a new library or a risky batch, the same order applies:

  1. Scan one small folder first.
  2. Review a few typical titles.
  3. Apply metadata without moving files.
  4. Confirm Activity is clean.
  5. Write NFO and artwork files for a sample.
  6. Rename or organize only after the metadata is right.
  7. Connect media servers on Sync after your metadata is settled.