Skip to content
MetaTana

These docs are for MetaTana 2.0, coming soon

On this page

Connect A Media Server

Plex, Jellyfin, Kodi, and Emby are the players MetaTana keeps in step with your library. Add a server, set up path mappings, then run the first sync.

Step 1: Open Sync

Select Sync in the sidebar. Media servers and Trakt both live here. With no server yet, the media servers card says No media servers and offers Add server.

Sync page with no media servers yet, showing Add server.
Sync with no media servers yet

Step 2: Add the server

Select Add server (or Add server or service). The drawer asks for the connection first, then what to sync.

Add server or service drawer: Type, Name, Host and Port, API key (or Username and Password for Kodi), Test connection, then the Sync switches, File choice, and Disc and path compatibility.
Add server or service

Connection fields:

  • Type: Jellyfin, Plex, Kodi, or Emby (Trakt is also here)
  • Name: a label, for example "Living Room"
  • Host and Port: separate fields. Plex uses port 32400, Jellyfin and Emby 8096, Kodi 8080
  • API key: for Plex, Jellyfin, and Emby. Kodi uses Username and Password instead.

Step 3: Test connection

Select Test connection before saving. It shows Works, or Couldn't connect with the reason. Fix any failure here; a server that can't connect won't sync later either. When the server has more than one user, choose one under Sync watch state for once the test works. If you save while the test fails, MetaTana asks you to confirm with Save anyway.

For Plex, the test reads your libraries with the token, so a wrong or empty token fails as Sign-in refused. Copy the token again and retest.

HTTPS with a self-signed certificate

A server on HTTPS with a certificate you made yourself (self-signed), or one from your own home certificate authority, fails the test with Couldn't connect · Certificate problem. There are two ways to fix it.

Trust this certificate. This works on desktop and Docker. Under the failed test, MetaTana shows the certificate the server presented: who it was issued to, when it expires, and its SHA-256 fingerprint. Compare the fingerprint with the one on your server, for example with openssl x509 -in server.crt -noout -fingerprint -sha256. If they match, select Trust this certificate. MetaTana tests again and saves that certificate with the server.

From then on, MetaTana accepts that exact certificate for that server and refuses any other. It checks the certificate before it sends your API key or password. Only trust a certificate when you know the server is yours.

  • When the certificate changes (renewed, or the server was rebuilt), the test shows Certificate changed and the new certificate. Check it, then trust it again.
  • Changing the server's Host or Port forgets the trusted certificate.
  • The same Trust this certificate choice appears in the server's settings on the Sync page when its test fails.

Trust your home certificate authority. This suits several servers, or certificates that renew often. The server's certificate must name the address you enter in Host.

  • Desktop: install the authority's certificate in your computer's certificate store (Keychain Access on macOS, the Windows certificate store, or your Linux distribution's CA store), then restart MetaTana.
  • Docker: mount the certificate into every MetaTana container and set NODE_EXTRA_CA_CERTS to its path, then recreate the containers:
environment:
  NODE_EXTRA_CA_CERTS: /certs/home-ca.pem
volumes:
  - ./home-ca.pem:/certs/home-ca.pem:ro

Step 4: Pick what syncs

The Sync section has a switch for each direction this server supports: Refresh library (refresh only the changed folders on the server after MetaTana files or edits titles, grouped and sent within about a minute), Watched pull, Watched push, Progress pull, and Progress push.

File choice sets which copy the server should prefer when a title has more than one file, and Disc and path compatibility covers disc folders and path differences.

After you save the server, the Sync page checks which of your library folders it reads. If any of those folders has NFO and artwork output off, it shows NFO and artwork are off in N folders once, listing the folders. Turn on switches output on for those folders only, and Autopilot writes NFO and artwork for files it scrapes from then on. Not now leaves them as they are; you can turn output on later with Write NFO files in the folder's Edit folder drawer on Folders.

Step 5: Add path mappings if needed

If MetaTana and the server see the same files under different paths, add a path mapping. This is the most common reason a server "can't find" files.

Select Server settings on the server's card and use Path mappings › Add mapping. When the server can't see some of your folders, its card lists them with Add path mapping.

Path mappings example MetaTana inside Docker sees /library/movies. Plex on the host sees /mnt/media/movies. Add a mapping from /library/movies to /mnt/media/movies for this server. Without it, watched-state and metadata pushes refer to paths Plex can't find.

Step 6: Run the first sync

The server's card shows Review N differences when MetaTana and the server disagree. Select it, choose Pull, Push, or Ignore on each row (or Pull all and Push all), then select Apply. When nothing differs, the card offers Sync now.

Once the first sync looks right, set Sync options › Sync servers automatically (Off, Every hour, Every 6 hours, or Once a day) to run it on a schedule. Conflicts in the same place decides which side wins when both changed: Newer wins, MetaTana wins, or Server wins.

Sync page with a connected Jellyfin server, its Review differences button, and the Trakt card.
Sync with a connected server
Don't bulk-push wrong metadata at scale Clean up the library first; see Triage attention items. Wrong metadata pushed to a server is much harder to clean up than getting it right locally.

Going deeper