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 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:
KindDescription
LocalMedia stored directly on the file system where ErsatzTV is running. No authentication or network connection required.
PlexA Plex Media Server instance, connected via the Plex API. Requires a Plex token.
JellyfinA Jellyfin server, connected via the Jellyfin HTTP API. Requires a user API key.
EmbyAn Emby server, connected via the Emby API. Requires an API key.
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:
KindValueDescription
Movies1Feature films and standalone video files treated as movies.
Shows2TV series, organized by show → season → episode.
MusicVideos3Music videos associated with an artist and album.
OtherVideos4Any video content that doesn’t fit movies, shows, or music videos — home recordings, shorts, etc.
Songs5Audio files (music tracks) used in Song playout items.
Images6Still image files that can be used in image-based playout items.
RemoteStreams7References to external streaming URLs treated as media items.
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. 
Library "Movies" (Kind: Movies)
  └── Path: /media/movies
Library "TV Shows" (Kind: Shows)
  └── Path: /media/tv

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)

PropertyDescription
ServerNameThe friendly name of the Plex Media Server.
ProductVersionThe Plex server version string.
PlatformThe OS platform the Plex server runs on.
PlatformVersionThe OS version.
ClientIdentifierThe unique identifier used by ErsatzTV when authenticating with Plex.
ConnectionsA list of PlexConnection entries (each has a URI and an IsActive flag).
PathReplacementsA list of PlexPathReplacement entries for path mapping.
LastCollectionsScanTimestamp of the last Plex collections sync.

​
Jellyfin (JellyfinMediaSource)

PropertyDescription
ServerNameThe friendly name of the Jellyfin server.
OperatingSystemThe OS the Jellyfin server runs on.
ConnectionsA list of JellyfinConnection entries with the server URI.
PathReplacementsA list of JellyfinPathReplacement entries.
LastCollectionsScanTimestamp of the last collections sync.

​
Emby (EmbyMediaSource)

PropertyDescription
ServerNameThe friendly name of the Emby server.
OperatingSystemThe OS the Emby server runs on.
ConnectionsA list of EmbyConnection entries.
PathReplacementsA list of EmbyPathReplacement entries.
LastCollectionsScanTimestamp of the last collections sync.

​
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: 
PlexPath:  /media/movies
LocalPath: /mnt/nas/movies
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:
SourceSource Path FieldLocal Path Field
PlexPlexPathLocalPath
JellyfinJellyfinPathLocalPath
EmbyEmbyPathLocalPath
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us