Skip to main content
ErsatzTV organizes all playable content through a two-level hierarchy: media sources at the top, and libraries within them. A media source represents the origin system where your media lives — a local file system, a Plex Media Server, a Jellyfin server, or an Emby server. A library is a named, scannable collection of media within that source, scoped to a particular media type such as movies, TV shows, or music videos. Understanding this distinction is important because it affects how ErsatzTV discovers content, how it keeps metadata in sync, and how it resolves file paths at playback time.

​
Media Sources

A media source (MediaSource) is the root entity for any origin of content. ErsatzTV supports four kinds of media sources, defined by the MediaSourceKind enum: Each media source holds a list of Library objects representing the individual libraries defined within that source.

​
Libraries

A library (Library) is a named collection of media items that ErsatzTV scans and indexes. It carries:
  • Name — the display name shown in the UI and used when building collections
  • MediaKind — the type of media the library contains (see below)
  • LastScan — the timestamp of the most recent completed scan
  • Paths — a list of LibraryPath entries, each representing a root folder path to scan
When ErsatzTV scans a library, it walks the registered paths, discovers media files, extracts metadata (from NFO sidecar files or the remote server), and stores the results in its local database. Subsequent scans detect additions, removals, and metadata changes.

​
Library Media Kinds

The LibraryMediaKind enum defines what type of content a library holds: A single media source can contain multiple libraries of different kinds. For example, a Plex server might have a Movies library and a Shows library both scanned independently.

​
Local Media Source

The LocalMediaSource is a simple subtype of MediaSource with no additional properties — its libraries point directly to paths on the local file system. Path entries in a local library (LibraryPath.Path) are absolute file system paths. ErsatzTV will scan these directories recursively for supported media file types.

Local Libraries

Configure local file system paths and set up automatic scanning for media stored on the ErsatzTV host.

Plex Integration

Connect a Plex Media Server and sync libraries from your existing Plex setup.

Jellyfin Integration

Link a Jellyfin server and import its libraries into ErsatzTV for scheduling.

Emby Integration

Connect an Emby server to pull libraries and collections into ErsatzTV.

​
Remote Media Sources: Plex, Jellyfin, and Emby

Remote media sources extend the base MediaSource with server-specific connection and metadata fields.

​
Plex (PlexMediaSource)

​
Jellyfin (JellyfinMediaSource)

​
Emby (EmbyMediaSource)

​
Path Replacements

When ErsatzTV plays back media sourced from a remote server (Plex, Jellyfin, or Emby), the server stores media at a path that reflects its own file system. If ErsatzTV is running on a different machine — or if the media is mounted at a different path — those server-side paths won’t be valid for direct file access. Path replacements solve this by mapping the server-side path prefix to the corresponding local path prefix. Example — Plex path replacement:
With this replacement, a Plex item at /media/movies/The Matrix (1999)/The Matrix.mkv would be accessed locally at /mnt/nas/movies/The Matrix (1999)/The Matrix.mkv. Each remote source type (PlexMediaSource, JellyfinMediaSource, EmbyMediaSource) carries its own PathReplacements list with source-specific fields:
Path replacements are critical when ErsatzTV and your media server run in separate Docker containers or on separate machines. Without correct replacements, ErsatzTV may fail to read media files for direct-play or transcoding.

​
Scanning

ErsatzTV maintains a LastScan timestamp on each library and a LastScan on each LibraryPath. You can trigger a scan in two ways:
1

Manual Scan

Trigger a scan from the ErsatzTV UI on the Libraries page, or via the API. ErsatzTV will walk all registered paths, find new or changed files, and update its database.
2

Automatic Periodic Scan

ErsatzTV can be configured to run library scans automatically at a regular interval. This keeps the database in sync without manual intervention, especially useful when media is frequently added to local folders or synced from remote servers.
After adding a new library path or adding a large batch of files, trigger a manual scan immediately so the new content becomes available for scheduling without waiting for the next periodic scan.

​
Library Paths

Each Library holds a list of LibraryPath objects. A LibraryPath represents a single root directory to scan and stores:
  • Path — the absolute file system path of the root folder
  • LastScan — when this specific path was last scanned
  • MediaItems — the media items discovered under this path
  • LibraryFolders — the subfolder structure tracked for incremental scanning
A library can have multiple paths, allowing you to aggregate media from different locations into a single named library.