ErsatzTV Legacy can connect to your Plex Media Server and use its libraries as content sources for live TV channels. Once connected, ErsatzTV reads your Plex libraries — Movies, TV Shows, Music Videos, and more — and lets you schedule that content across any number of channels. Plex collections are also synchronized so you can build schedules around them. No media is copied or re-encoded at scan time; ErsatzTV simply indexes what Plex already knows about.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.
How the Plex Integration Works
When you add a Plex media source, ErsatzTV stores connection details about your Plex server and a token that authorizes it to make API requests on your behalf. These details are captured in thePlexMediaSource model:
| Field | Description |
|---|---|
ServerName | The friendly name of your Plex Media Server |
ProductVersion | The Plex Media Server version string |
Platform | The OS platform Plex is running on (e.g. Windows, Linux) |
PlatformVersion | The OS version on the Plex host |
ClientIdentifier | The unique machine identifier assigned by Plex |
LastCollectionsScan | Timestamp of when Plex collections were last synchronized |
PlexConnection and marks one as active:
| Field | Description |
|---|---|
IsActive | Whether this connection is the one currently in use |
Uri | The full URI for this connection (e.g. http://192.168.1.10:32400) |
Authentication
ErsatzTV uses the Plex PIN flow to obtain an authentication token. You do not enter a token manually — the flow opens plex.tv in your browser, where you authorize ErsatzTV. The resulting token is stored in ErsatzTV’s secrets store and is used for all subsequent API calls to Plex.Plex Libraries
After connecting, ErsatzTV synchronizes the list of libraries from Plex. Each library becomes aPlexLibrary record that maps to one of ErsatzTV’s media kinds (Movies, Shows, Music Videos, etc.). Libraries have a ShouldSyncItems flag — only libraries with sync enabled will have their content indexed and made available for scheduling.
The Key field on each PlexLibrary corresponds to the internal Plex library section key (e.g. "1", "2"). ErsatzTV also tracks LastNetworksScan per library to manage periodic syncing of Plex network metadata.
Connecting Plex
Open Media Sources
In the ErsatzTV sidebar, navigate to Media Sources → Plex. The page is served at
/media/sources/plex.Sign in to Plex
Click Sign in to Plex. ErsatzTV will open a new browser tab pointing to
plex.tv where you authorize the connection. After authorizing, return to ErsatzTV — the page will automatically update once the PIN flow completes.Refresh Libraries
After signing in, your Plex server will appear in the table. Click the Refresh Libraries icon (↺) next to your server to pull the latest list of libraries from Plex.
Enable Libraries for Sync
Click the Edit Libraries icon (video library icon) to open the library preferences editor. Toggle Sync Items on for each library you want ErsatzTV to index. Libraries with sync disabled will not appear as content sources in the scheduler.
Configure Path Replacements (if needed)
If ErsatzTV and Plex run on different machines, click the Edit Path Replacements icon (folder icon) to add path mappings. See Path Replacements below.
Path Replacements
Path replacements are required when ErsatzTV and Plex Media Server run on different machines (or in separate containers with different volume mounts). Plex reports file paths relative to its own file system. ErsatzTV needs to resolve those paths to locations it can actually read. APlexPathReplacement maps a PlexPath prefix to a LocalPath prefix:
| Field | Description |
|---|---|
PlexPath | The path prefix as Plex sees it on its host |
LocalPath | The corresponding path prefix on the ErsatzTV host |
/data/movies. ErsatzTV runs on a separate machine that mounts the same NAS share at /mnt/nas/movies.
| Plex Path | Local Path |
|---|---|
/data/movies | /mnt/nas/movies |
/data/tv | /mnt/nas/tv |
PlexPath prefix from any file path Plex reports and substituting LocalPath. You can add as many replacement rules as needed — one per distinct path prefix.
If ErsatzTV and Plex run on the same machine with identical path layouts, no path replacements are needed.
Plex Collections
Plex collections are synchronized alongside library content. TheLastCollectionsScan timestamp on PlexMediaSource records when collections were last fetched. Collections can be used in ErsatzTV schedules just like manually created collections — you can schedule an entire Plex collection as a block or classic schedule item.
Collection syncs can be triggered as deep scans. By default, collection scans use a quick scan that trusts Plex etags for change detection. If a quick scan misses an update, use the Deep Scan option to force a full re-sync.
Scanning Libraries
ErsatzTV supports three ways to trigger a library scan:UI Scan
Navigate to the library list and click the scan icon next to a library. The scan runs in the background.
API: Scan Library
Send a
POST request to /api/libraries/{id}/scan where {id} is the ErsatzTV library ID.API: Scan Show
Send a
POST request to /api/libraries/{id}/scan-show with a JSON body to scan a specific TV show within a library.Scan Library via API
200 OK on success or 404 Not Found if the library ID does not exist.
Scan a Single Show via API
| Field | Type | Description |
|---|---|---|
ShowTitle | string | Required. The exact title of the show as stored in ErsatzTV. |
DeepScan | bool | Optional (default false). Forces re-indexing of all episodes even if etags match. |
400 Bad Request with an error message if the show title is not found in the specified library, or if the library does not support single-show scanning.
Targeted show scanning can also be triggered from the show’s detail page in the ErsatzTV UI using the Scan button. Both quick and deep scan modes are available.
Title Synchronization
ErsatzTV keeps Plex movie and other video titles in sync with Plex. When Plex updates a title, the next periodic library scan will automatically detect and apply the change in ErsatzTV. Deep scans are not required for title updates — the title is included in ErsatzTV’s etag calculation for Plex items, so any title change triggers a re-index on the next scan.The first library scan after ErsatzTV updates its etag calculation for Plex titles will behave like a deep scan for all affected items. Subsequent periodic scans will update titles normally.
Troubleshooting
Fix Plex Credentials
If the Plex token becomes invalid (e.g. after a Plex password change), a Fix Plex Credentials button appears on the Plex Media Sources page. Click it to restart the PIN authorization flow without losing your library configuration.
API Reference
Full documentation for library scan endpoints, including request and response shapes.