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 connects to Emby Media Server so you can schedule and broadcast content from your Emby libraries as live TV channels. Once the integration is configured, ErsatzTV synchronizes your Emby libraries — movies, shows, music videos, and more — and provides access to Emby collections for schedule building. Like all ErsatzTV media sources, no files are moved or re-encoded during the sync process; ErsatzTV works from the metadata and file paths that Emby already maintains.

​
How the Emby Integration Works

Connecting Emby creates an EmbyMediaSource record in ErsatzTV that holds server-level information:
FieldDescription
ServerNameThe friendly name configured for your Emby server
OperatingSystemThe OS the Emby server is running on (e.g. Linux, Windows)
LastCollectionsScanTimestamp of when Emby collections were last synchronized
The server’s network address is stored in a single EmbyConnection:
FieldDescription
AddressThe base URL of your Emby server (e.g. http://192.168.1.30:8096)

​
Authentication

Emby uses API keys for authentication. You create an API key in Emby and provide it to ErsatzTV along with the server address. ErsatzTV presents this key in its API requests to Emby to enumerate libraries, fetch metadata, and resolve file paths.
API keys provide broad access to your Emby server. Create a dedicated key for ErsatzTV in Emby’s Dashboard → Advanced → API Keys so you can revoke it independently if needed.
To generate an API key in Emby:
  1. Open the Emby web UI and navigate to Dashboard → Advanced → API Keys.
  2. Click New API Key, give it a name (e.g. ErsatzTV), and copy the generated key.

​
Emby Libraries

After connecting, ErsatzTV pulls the list of libraries from Emby. Each becomes an EmbyLibrary that maps to one of ErsatzTV’s media kinds (Movies, Shows, Music Videos, etc.). Libraries carry a ShouldSyncItems flag — only libraries with sync enabled are indexed and made available for scheduling. The ItemId field on each EmbyLibrary is the Emby-assigned item GUID for that library’s root folder. PathInfos stores the resolved path information for the library, which ErsatzTV uses when path replacements are configured.
Emby also supports non-file media items (e.g. content served via HTTP or NFS). ErsatzTV can synchronize movies with non-file media sources from Emby movie libraries.

​
Connecting Emby

1

Open Media Sources

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

Add Connection Details

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

Save and Connect

Click Save. ErsatzTV will contact your Emby server to validate the connection and record ServerName and OperatingSystem from Emby’s system info response.
4

Refresh Libraries

Once connected, click the Refresh Libraries icon to synchronize the library list from Emby. Libraries added to Emby after initial setup require a refresh to appear in ErsatzTV.
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 indexed by ErsatzTV. Disabled libraries are not available as content sources.
6

Configure Path Replacements (if needed)

If ErsatzTV and Emby run on different hosts with different path structures, click the Edit Path Replacements icon and define your path mappings. See Path Replacements below.
7

Trigger a Library Scan

With libraries enabled, initiate a scan from the library list. ErsatzTV queues the scan as a background job.

​
Path Replacements

Path replacements are necessary when ErsatzTV and Emby run on separate machines (or in separate containers) and the file system paths differ between hosts. Emby reports file paths from its own perspective; ErsatzTV must map those to paths it can reach directly. An EmbyPathReplacement maps an EmbyPath prefix to a LocalPath prefix:
FieldDescription
EmbyPathThe path prefix as reported by Emby from its host
LocalPathThe corresponding path prefix on the ErsatzTV host
Example scenario: Emby runs on a Windows machine where media is stored at C:\Media. ErsatzTV runs on Linux and mounts the same share at /mnt/media.
Emby PathLocal Path
C:\Media\Movies/mnt/media/Movies
C:\Media\TV/mnt/media/TV
ErsatzTV strips the matching EmbyPath prefix from each file path and substitutes LocalPath. Add one rule per distinct path prefix — you can have as many rules as needed.
When running ErsatzTV in Docker, be sure to mount your media directories into the container. The container path you choose becomes the Local Path in your replacement rules. See Docker Operations for volume mount examples.
If ErsatzTV and Emby both have access to media at the same absolute paths (e.g. both on the same machine), no path replacements are needed.

​
Emby Collections

Collections created in Emby are synchronized to ErsatzTV and can be used directly in channel schedules. The LastCollectionsScan timestamp on EmbyMediaSource tracks when collections were last fetched.
Emby collection scans support both quick mode (trusting Emby’s etags for change detection) and deep mode (re-fetching all collection data regardless of etags). Deep scans have always been available for Emby collections. If a quick scan misses a collection change, trigger a deep scan manually.

​
Scanning Libraries

ErsatzTV offers multiple ways to trigger an Emby library scan:

UI Scan

Navigate to the library list and click the scan button. The scan runs as a background job.

API: Scan Library

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

API: Scan Show

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

​
Scan Library via API

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

​
Scan a Single Show via API

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

{
  "ShowTitle": "Severance",
  "DeepScan": false
}
FieldTypeDescription
ShowTitlestringRequired. The show title exactly as it appears in ErsatzTV.
DeepScanboolOptional (default false). When true, forces full re-indexing of all episodes.
Returns 400 Bad Request with an error message if the show is not found in the specified library or if the library does not support single-show scanning.
Targeted show scanning can also be started from the show detail page in the ErsatzTV UI via the Scan button, in either quick or deep scan mode.

​
Troubleshooting

Update Connection Details

To change the Emby server address or API key, navigate to Media Sources → Emby and click the Edit button next to the server entry.

API Reference

Full documentation for the library scan endpoints, including request bodies and response codes.

Build docs developers (and LLMs) love

Get started for freeTalk to us