Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ErsatzTV/legacy/llms.txt

Use this file to discover all available pages before exploring further.

ErsatzTV Legacy integrates with Jellyfin to let you build live TV channels from the media already organized in your Jellyfin server. After connecting, ErsatzTV synchronizes your Jellyfin libraries — movies, shows, music videos, and other content — and makes them available as scheduling sources. Jellyfin collections are synced as well, allowing you to schedule curated sets of content without duplicating any library management work.

​
How the Jellyfin Integration Works

When you add a Jellyfin media source, ErsatzTV stores the server connection details and API key in its own database. These are represented by the JellyfinMediaSource model:
FieldDescription
ServerNameThe friendly name configured for your Jellyfin server
OperatingSystemThe OS the Jellyfin server is running on (e.g. Linux, Windows)
LastCollectionsScanTimestamp of when Jellyfin collections were last synchronized
Each Jellyfin server is associated with a single JellyfinConnection that holds the server address:
FieldDescription
AddressThe base URL of your Jellyfin server (e.g. http://192.168.1.20:8096)

​
Authentication

Jellyfin uses API keys for authentication. You must generate an API key in your Jellyfin server and provide it to ErsatzTV along with the server address. ErsatzTV uses this key for all library enumeration and metadata requests.
API keys grant full read access to your Jellyfin server. Create a dedicated API key for ErsatzTV in Jellyfin’s Dashboard → API Keys section rather than reusing an existing key, so you can revoke access independently if needed.
To generate an API key in Jellyfin:
  1. Open the Jellyfin web UI and go to Dashboard → Advanced → API Keys.
  2. Click the + button, give the key a name (e.g. ErsatzTV), and copy the generated token.

​
Jellyfin Libraries

After the initial connection, ErsatzTV synchronizes the list of libraries from Jellyfin. Each becomes a JellyfinLibrary that maps to one of ErsatzTV’s supported media kinds. Libraries carry a ShouldSyncItems flag — only libraries with sync enabled are indexed and available for channel scheduling. The ItemId field on each JellyfinLibrary corresponds to the Jellyfin library’s internal item identifier (a GUID string). PathInfos stores the resolved path information for the library’s root folders, which ErsatzTV uses in combination with path replacements.

​
Connecting Jellyfin

1

Open Media Sources

In the ErsatzTV sidebar, navigate to Media Sources → Jellyfin. The page is served at /media/sources/jellyfin.
2

Add Connection Details

Click Edit (or the pencil icon) next to the Jellyfin entry to open the connection editor at /media/sources/jellyfin/edit. Enter the full Address of your Jellyfin server (including port) and paste in your API Key.
3

Save and Connect

Click Save. ErsatzTV will validate the connection against your Jellyfin server and pull server metadata including ServerName and OperatingSystem.
4

Refresh Libraries

Once connected, click the Refresh Libraries icon to synchronize the list of libraries from Jellyfin. New libraries added to Jellyfin after the initial connection will not appear until you refresh.
5

Enable Libraries for Sync

Click the Edit Libraries icon to open the library preferences panel. Toggle Sync Items on for each library you want ErsatzTV to index and use as a content source.
6

Configure Path Replacements (if needed)

If ErsatzTV and Jellyfin run on different hosts with different file system paths, click the Edit Path Replacements icon and configure your path mappings. See Path Replacements below.
7

Trigger a Library Scan

With libraries enabled, trigger a scan for each library from the library list. ErsatzTV will index the media items in the background.

​
Path Replacements

Path replacements are needed when ErsatzTV and Jellyfin are on different machines or containers whose volume mounts differ. Jellyfin reports file paths relative to its own host. ErsatzTV must translate those paths to locations it can access directly. A JellyfinPathReplacement maps a JellyfinPath prefix to a LocalPath prefix:
FieldDescription
JellyfinPathThe path prefix as Jellyfin reports it from its host
LocalPathThe corresponding path prefix on the ErsatzTV host
Example scenario: Jellyfin runs in a container with media mounted at /media. ErsatzTV runs on the host where the same media directory is at /srv/media.
Jellyfin PathLocal Path
/media/movies/srv/media/movies
/media/shows/srv/media/shows
ErsatzTV strips the matching JellyfinPath prefix and substitutes LocalPath when resolving any file path reported by Jellyfin. Add one replacement rule per distinct path prefix.
When running both ErsatzTV and Jellyfin in Docker, using identical volume mount paths (e.g. mounting the same host directory to the same container path in both) eliminates the need for path replacements entirely.
If ErsatzTV and Jellyfin have access to media at the same paths, no replacements are required.

​
Jellyfin Collections

Collections defined in Jellyfin are synchronized to ErsatzTV and can be used directly in schedules. The LastCollectionsScan timestamp on JellyfinMediaSource records when collections were last fetched.
Jellyfin and Emby collection scans in ErsatzTV support both quick scans (trusting Jellyfin etags for change detection) and deep scans (re-fetching all collection data). If a quick scan misses a collection update, trigger a deep scan manually from the collections interface.

​
Scanning Libraries

ErsatzTV provides multiple ways to trigger a Jellyfin library scan:

UI Scan

Navigate to the library list and click the scan icon. ErsatzTV queues the library for background processing.

API: Scan Library

Send POST /api/libraries/{id}/scan to queue a full library scan by its ErsatzTV library ID.

API: Scan Show

Send POST /api/libraries/{id}/scan-show with a show title to scan only a single TV show within a library.

​
Scan Library via API

POST /api/libraries/{id}/scan
Returns 200 OK when the scan is successfully queued, or 404 Not Found if the library ID does not exist.

​
Scan a Single Show via API

POST /api/libraries/{id}/scan-show

{
  "ShowTitle": "The Bear",
  "DeepScan": false
}
FieldTypeDescription
ShowTitlestringRequired. Must match the show title exactly as stored in ErsatzTV.
DeepScanboolOptional (default false). When true, forces re-indexing of all episodes regardless of etag.
Returns 400 Bad Request with a descriptive error if the show title is not found in the library, or if the library does not support single-show scanning.
Targeted show scanning can also be triggered from the show’s page in the ErsatzTV UI using the Scan button. Supported for both quick and deep scan modes.

​
Performance Notes

Jellyfin library scans are optimized to minimize unnecessary API calls:
  • Periodic scans request only actor/director/writer metadata (People) for items whose etags have changed, significantly speeding up recurring scans especially against Jellyfin 10.11.x.

​
Troubleshooting

Update Connection Details

To update the Jellyfin server address or API key after initial setup, navigate to Media Sources → Jellyfin and click the Edit button next to the server.

API Reference

Full documentation for library scan endpoints, including request and response shapes.

Build docs developers (and LLMs) love

Get started for freeTalk to us