Move from Jellyfin to Finetic

What the migration does#

Finetic's Jellyfin migration is a guided transfer of trusted catalogue and user state. It is not a Jellyfin database conversion, and it does not modify Jellyfin.

Finetic reads supported information through Jellyfin's HTTP API, adds media folders that are visible inside the Finetic server, scans the files using Finetic's own catalogue engine, and presents a dry run before writing user state.

You can start it during first-run setup or later from Administrator → Libraries → Move from Jellyfin.

Before you begin#

Keep both servers running during analysis. You need:

• a Jellyfin administrator username and password;
• the HTTP or HTTPS address Jellyfin exposes to the Finetic server;
• the Movies and TV Shows folders mounted into Finetic;
• one existing Finetic account for each profile you want to map, or permission to create invitations;
• a current backup of important application state.

The Jellyfin and Finetic mount paths do not have to be identical. They must lead to the same underlying files.

Supported data#

For Movies and TV Shows that Finetic can safely match, the migration can bring:

Existing Finetic viewing state wins by default. Replacement is a separate explicit choice for each mapped profile.

Deliberate exclusions#

Finetic does not claim to migrate:

• Jellyfin passwords or password hashes;
• administrator roles;
• raw session-by-session playback history;
• playlists or ratings;
• Jellyfin's downloaded artwork cache;
• music, books, photos or plugin-specific libraries;
• Jellyfin server or plugin configuration.

New users choose their own Finetic password through an invitation. Finetic resolves metadata and artwork through local files and the providers configured on the Finetic server.

Step 1: connect#

The wizard searches the local network using Jellyfin discovery. Select a result, or enter a manual address such as:

http://192.168.1.20:8096

Sign in with a Jellyfin administrator account. Finetic sends that password only to the configured Jellyfin origin. It stores neither the password nor the temporary Jellyfin access token in PostgreSQL, configuration, reports or browser state.

The token exists in server memory until analysis finishes, then Finetic signs out. If Finetic restarts first, reconnect before continuing.

Step 2: map libraries#

Select every Movies or TV Shows library you want Finetic to scan. For each Jellyfin path, provide the folder as Finetic sees it.

Jellyfin sees: /config-media/tv
Finetic sees:  /media/tv

Finetic verifies that its folder exists and is a directory. Media is not copied, renamed or modified. Read-only mounts remain recommended.

Unsupported Jellyfin libraries appear as excluded rather than silently disappearing.

Step 3: map people#

Each enabled Jellyfin profile can be:

1. mapped to an existing Finetic account;
2. assigned a new Finetic invitation; or
3. skipped.

Name matches are suggested but remain visible. For existing Finetic profiles, leave Replace existing Finetic state off unless you deliberately want Jellyfin's values to replace current favourites, watched state and resume positions.

Invited people receive a normal Finetic access scope derived from the selected libraries. Their migration records remain staged until they accept and create an account.

Step 4: analyse#

Finetic saves the selected roots and runs its own catalogue scan. It then matches Jellyfin identities in this order:

1. exact file path after mount-path translation;
2. one unique TMDB, TVDB or IMDb identity;
3. one unique title and year, or series/season/episode identity;
4. unmatched or ambiguous.

Exact path and provider matches are selected automatically. Semantic matches are shown as Review. Ambiguous and unmatched records are never applied automatically.

The analysis can take as long as a normal scan of the selected media. Closing or refreshing the browser does not make the scan faster.

Step 5: review and apply#

The dry run separates:

• exact matches;
• review matches;
• unmatched items;
• unsupported items;
• user-state records available to import.

Review matches remain off unless you explicitly include them. The wizard shows a representative list and explains the matching reason.

Choose Migrate verified data only after the totals make sense. The completion screen reports imported, preserved and invitation-pending records and provides a downloadable JSON report.

Failure and recovery#

Transient Jellyfin rate limits and server failures are retried for safe read requests. Redirects are rejected, response sizes are bounded and every source request has a timeout.

Finetic maintains a migration ledger. Rollback changes only a record that still equals the value written by migration. If someone watched a title or changed a favourite after migration, rollback preserves that later activity instead of blindly restoring an older value.

Jellyfin remains available throughout, and the original media files are unchanged.

Privacy boundary#

Migration occurs directly between your Finetic and Jellyfin servers. It does not send library names, media titles, paths, users, passwords, history or artwork to the Finetic commercial service or public website.

For broader product data boundaries, see Privacy and data boundaries.