Media Servers And Watch State#

MetaTana keeps your library in step with Plex, Jellyfin, Emby, and Kodi, and with Trakt (Pro). It makes the local metadata clean before a server imports it, then syncs watched state, progress, and metadata in the directions you choose. Set up sync only after identities, metadata, and paths are stable enough to trust.

For every control on the page, see Sync. For the click-by-click setup, see Connect a media server and Add Trakt.

Media Servers#

MetaTana works with Plex, Jellyfin, Kodi, and Emby. Support varies by server and field: a server may import movie NFO fields but ignore a season NFO field, or show stream details differently through its API. Depending on the server, MetaTana can:

• write NFO and artwork files the server reads
• test the connection and ask the server to refresh only the changed folders
• map local paths to the paths the server sees
• show the differences between MetaTana and the server before anything is pushed
• pull or push watched state and progress, by hand or on a schedule

Things to know about each server:

• Emby and Jellyfin: pick whose watch state syncs. In Add server or service on Sync, after a successful Test connection, a server with more than one user shows Sync watch state for. Pick the user whose watched status and resume points MetaTana should sync. Until you pick one, watch state does not sync. To change it later, use Watch state for in the server's Server settings.
• Moves refresh the old folder too. After a rename, Inbox renames, a tidy into Movies and TV folders, a scrape rename, or an Undo of renames in Activity, MetaTana refreshes the folder the file left as well as its new folder, so the server drops the old entry. Kodi also cleans those folders, never the whole library. If a folder is outside Kodi's sources, Kodi gets a full library update and no clean.
• Server sign-ins are encrypted on desktop. Saved tokens, API keys, and passwords are encrypted with your system keychain. If you move the app data folder to another computer, the server card asks for the sign-in again; until then MetaTana does not contact that server.

These docs claim a field works with a server only when a real server import or readback showed it. The per-server field table is in NFO format.

Servers On Sync#

Each server you add on Sync stores the connection and what it can do. Depending on the client, MetaTana can test the connection, ask the server to refresh its library, compare the metadata the server shows, and sync watched state or progress.

Each server, and Trakt, has a card with its status and one main action. The card's ⋯ menu has Sync now, Test connection, Review differences, Refresh library, and the pull and push actions the server supports. Server settings on the card holds the connection, path mappings, and what syncs. A card shows Reconnect when the server can't be reached or its sign-in stopped working.

Path Mappings#

Path mappings translate the path MetaTana sees into the path a playback server sees. You usually need one when MetaTana runs in Docker, the player runs on another host, or the same network share is mounted differently on two machines.

Example:

• MetaTana sees /media/Movies/Example.mkv.
• The playback server sees /mnt/library/Movies/Example.mkv.
• Map /media to /mnt/library in that server's Server settings.

A correct metadata match does not compensate for a bad path mapping. If the client cannot locate a file, verify the mapping before changing metadata or repeating sync.

Each refresh checks the server's library folders. A folder outside all of them gets a full library refresh instead. When the server may not see some of your folders, its card on Sync shows Can’t see N folders, lists them, and offers Add path mapping, which opens Server settings.

Library Refresh#

When Refresh library is on for a server, MetaTana asks it to refresh after anything that changes files the server reads: a scrape, an organize or rename, a file filed from Arrivals, and editor saves that write an NFO or artwork (NFO rewrite, poster or fanart from a file or URL, season artwork).

Requests are grouped per server. MetaTana waits until nothing new has changed for 30 seconds, or at most one minute, then sends one refresh for everything that changed. A batch of 200 episodes is one request, not 200.

MetaTana refreshes only the changed folders when the server supports it:

It falls back to refreshing every library when a folder is outside all of the server's libraries (usually a missing path mapping), when the server does not support the folder request, or when more than 20 folders changed at once. If a refresh fails, Sync in the sidebar shows a status dot and Activity keeps the error.

Automatic Sync#

Sync is manual unless you turn on a schedule. On the Sync page, under Sync options, set Sync servers automatically to Every hour, Every 6 hours, or Once a day. It is Off by default.

A scheduled run does the same as Sync now on a server card, and as Sync now at the top of the page. For each enabled server it runs, in order, only the directions you switched on:

1. Watched pull (Plex and Kodi).
2. Progress pull. On Plex and Kodi this pulls resume points. On Jellyfin and Emby it pulls watched state and resume points together, since they have no separate watched pull.
3. Progress push, or for Kodi Watched push when progress push is off.

A scheduled run does not apply anything from Review differences.

The pull follows the same rule as a manual pull: if you marked an item unwatched in MetaTana after its last play on the server, it stays unwatched. The push that follows never marks anything unwatched on the server, so it cannot undo the pull.

The first run happens one full interval after you turn it on. The pull and the push each appear in Activity. If the pull fails, the push still runs, and a server that fails does not stop the others.

Preview Before Applying#

Review differences on a server's card shows what differs before anything changes. It compares watched state and progress, the metadata the server shows against MetaTana's accepted values, and MetaTana's playback state against existing NFO files.

Choose Pull, Push, or Ignore on each row, or Pull all, Push all, or Ignore all, then select Apply N changes:

• Push: update the server from MetaTana.
• Pull: update MetaTana from the server.
• Ignore: note the difference without changing either side.

Opening the review changes nothing in MetaTana, in sidecar files, in media files, or on the server. Sync options › Conflicts sets which side wins when MetaTana and the server disagree during a sync: Newer wins, MetaTana wins, or Server wins.

What Each Choice Changes#

Metadata pull and push do not rename media or rewrite NFOs. Metadata pull does not write back to the server, and locked local fields remain protected. Local NFO operations do not contact the playback server.

Applying a row changes only that row. Bulk choices run the same decision for each selected row; they never start a full sync of the server. Before recording success, MetaTana checks the result again. A failed or unconfirmed row stays visible as failed instead of being recorded as synced.

Activity (Show: Sync) keeps the server, title, direction, outcome, and the field differences after the review closes. Use it to check or retry a failed sync.

Watched State And Progress#

Watched state and progress are bidirectional user data. Decide which side is authoritative before the first apply:

• Pull when the playback server contains the history you trust.
• Push when MetaTana contains the reviewed state you want the server to use.
• Ignore a known difference that should remain unchanged.

For a server that has been offline, review what it has first. Pull the changes you trust, then review what MetaTana would push. This avoids overwriting newer server history with older local data.

Trakt#

Trakt keeps your watched history in step, both ways: MetaTana pushes the titles and episodes you watched and pulls the ones Trakt has recorded. Playback progress and ratings are not synced. Once Trakt is connected, MetaTana can also read Trakt ratings as a rating source. Trakt sync needs Pro; on Free, the Trakt card on Sync offers Upgrade to Pro instead of its sync controls.

Trakt needs two things: the Trakt client keys in Settings › Providers (under More, Trakt client keys) and your Trakt sign-in, which you start from the Trakt card on Sync. Trakt's terms don't allow hosted proxying, so Trakt sync runs only in the app: your Trakt sign-in stays in your local settings and never goes through Skyhook.

Trakt syncs in the background every 15 minutes and keeps trying when it fails. After 3 failed tries in a row, MetaTana shows one notice, Couldn't sync watched status with Trakt, and the Trakt card shows why the last sync failed, for example Trakt sync has failed 3 times. If it keeps failing, select Reconnect on that card. The card says Reconnect needed only when Trakt rejects the saved sign-in, or when it can't be opened on this computer (app data moved to another computer, or the system keychain was reset). A rate limit or network problem keeps Trakt connected, and MetaTana tries again later.

• One episode at a time. Trakt sync marks the single episode you watched. Absolute-numbered anime and files that hold several episodes (Show.S01E01-E03.mkv) line up with the right Trakt episodes too.
• Unwatched stays unwatched. When you mark a title unwatched in MetaTana, it stays unwatched until Plex, Kodi, or Trakt records a play newer than your change. The next Push or Both sync removes that movie or those episodes from your Trakt history. A failed removal stays queued for retry and is reported in the sync result. Pull-only sync does not remove Trakt history.
• Pulls keep your history. A pull keeps the first watched date and the play count.
• Problems are counted. A sync that hit problems says how many and what they were, instead of showing a success message.

Before the first large sync, take a backup and pull a small set first, such as one show or recent activity, then check Activity (Show: Sync) before pushing anything. If your local titles have wrong matches, you'll push wrong watched state to Trakt, which is hard to clean up.

Safe Order#

1. Clean local identity firstFix wrong matches and lock fields that must not change.
2. Write and inspect sample sidecarsConfirm the format expected by clients that read NFOs.
3. Add the serverOn Sync, use Add server or service: enter the sign-in, select Test connection, and choose what syncs.
4. Add path mappingsIn Server settings, map MetaTana's paths to the server's view of the same files.
5. Refresh the server's libraryConfirm a few typical titles appear with the expected identity and path.
6. Review differencesCheck several rows before using a bulk choice.
7. Apply and checkWait for the sync to finish, then check both MetaTana and the playback client.

Troubleshooting#

For path and import failures, see Playback client cannot see files. For a click-by-click connection flow, see Connect a media server.