Add Local Media Folder Libraries to ErsatzTV Legacy

Local libraries are the simplest way to get media into ErsatzTV Legacy: you point one or more file system directories at a named library, choose the media kind, and ErsatzTV scans and indexes everything it finds. There is no third-party media server required — ErsatzTV reads directly from disk. Local libraries are the right choice when your media is already organized on a local drive or network share that ErsatzTV can access, or when you prefer not to run a separate media server alongside ErsatzTV.

The Local Media Source

All local libraries belong to a single LocalMediaSource. Unlike Plex, Jellyfin, or Emby, the local source has no connection parameters, authentication tokens, or remote server to contact. It exists purely as a container that groups local libraries together under a single source entry in the ErsatzTV database. Each LocalLibrary is a named library associated with the local source. It carries:

Field	Description
`Name`	A human-readable label for the library (e.g. `Movies`, `Kids TV`)
`MediaKind`	The type of content the library holds (see below)
`LastScan`	Timestamp of the most recent completed scan
`Paths`	One or more `LibraryPath` records pointing to directories on disk

A LibraryPath holds the actual folder path that ErsatzTV scans:

Field	Description
`Path`	The absolute path to a directory (e.g. `/media/movies`)
`LastScan`	Timestamp of when this path was last scanned

Within each path, ErsatzTV tracks individual subdirectories as LibraryFolder records. Each folder has a path, an optional parent folder reference (for nested structures), an Etag for change detection, and links to the MediaFile records found inside it. Image folders additionally support a ImageFolderDuration that controls how long each image is displayed on screen.

Supported Media Kinds

When creating a local library you select a LibraryMediaKind that tells ErsatzTV what kind of content to expect and how to parse metadata. The media kind cannot be changed after a library is created.

Value	Display Name	Description
`Movies`	Movies	Feature films and standalone videos treated as individual movie items
`Shows`	Shows	TV series organized into seasons and episodes
`MusicVideos`	Music Videos	Music video content with artist and album metadata
`OtherVideos`	Other Videos	Miscellaneous video content that doesn’t fit movie or TV show conventions
`Songs`	Songs	Audio tracks (music files)
`Images`	Images	Still image files for use in image-based channel programming
`RemoteStreams`	Remote Streams	Playlist or stream URL files pointing to remote streams

The Media Kind is fixed at library creation time. If you need to change the kind for an existing collection of files, create a new library with the correct kind and delete the old one.

Adding a Local Library

Open Local Libraries

In the ErsatzTV sidebar, navigate to Media Sources → Local Libraries (served at /media/sources/local). A table lists all existing local libraries with their names and media kinds.

Create a New Library

Click Add Local Library. The editor opens at /media/sources/local/add.

Name the Library

Enter a descriptive name in the Name field. This name appears throughout the ErsatzTV UI (schedules, search results, channel programming). Examples: Feature Films, Kids Shows, Concert Videos.

Choose a Media Kind

Select the appropriate Media Kind from the dropdown. This selection is permanent and determines how ErsatzTV parses and organizes the files it finds.

Add One or More Paths

Type a directory path into the Path field and click Add Path. ErsatzTV validates that the path exists on the file system before accepting it. Repeat to add additional paths — a single library can span multiple directories. Example paths:

/media/movies
/mnt/nas/tv/drama
D:\Media\MusicVideos (Windows hosts)

Save the Library

Click Add Local Library (or Save Local Library for an existing one). ErsatzTV creates the library and its path records. The library now appears in the list.

Trigger a Scan

The library does not contain any media until it is scanned. Trigger a scan from the library list or via the API. See Scanning below.

Scanning Local Libraries

ErsatzTV walks the directories in your library paths and builds an index of all media files it finds. Two scan modes are available:

Regular Scan
Deep Scan

A regular (quick) scan compares directory etags against what ErsatzTV last recorded. Folders whose contents have not changed are skipped, making periodic scans fast even for large libraries. New files, modified files, and deleted files are all handled automatically.

Scan Library via API

POST /api/libraries/{id}/scan

Replace {id} with the ErsatzTV library ID shown in the URL when editing the library. Returns 200 OK when queued or 404 Not Found if the library does not exist.

Scan a Single Show via API

For Shows libraries, you can target a single TV show instead of rescanning the entire library:

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

{
  "ShowTitle": "The Sopranos",
  "DeepScan": false
}

Field	Type	Description
`ShowTitle`	`string`	Required. The show title exactly as it appears in ErsatzTV.
`DeepScan`	`bool`	Optional (default `false`). Set to `true` to force re-indexing of all episodes.

Returns 400 Bad Request if the show is not found in the library or the library does not support single-show scanning. Targeted deep scans will also extract embedded text subtitles for the scanned show if that feature is enabled in Settings.

Single-show scanning is also accessible from the show detail page in the ErsatzTV UI via the Scan button. This is useful when you add a new season or want to force a metadata refresh for one series without waiting for a full library scan.

Subtitle Support

ErsatzTV automatically discovers and indexes subtitles found alongside your media files. Two subtitle delivery mechanisms are supported:

Sidecar Subtitles

Sidecar subtitles are separate files placed in the same folder as the video file, following a naming convention. Common formats recognized:

SRT (.srt) — SubRip text subtitles
ASS / SSA (.ass, .ssa) — Advanced SubStation Alpha
WebVTT (.vtt) — Web Video Text Tracks

Language is inferred from the subtitle file name (e.g. movie.en.srt → English). When no language can be determined from the file name, ErsatzTV assigns the und (undetermined) language tag.

A known issue was fixed where content with multiple sidecar subtitles would have subtitle metadata incorrectly merged (e.g. language codes mixing between files). If you experienced this, the next local library scan will automatically clean up the affected records.

Embedded Subtitles

ErsatzTV also indexes subtitle streams embedded inside video files. Each embedded subtitle track is represented as a Subtitle record with:

Field	Description
`SubtitleKind`	`Embedded` for in-file tracks, `Sidecar` for external files
`Codec`	The subtitle codec (e.g. `subrip`, `ass`, `hdmv_pgs_subtitle`, `dvd_subtitle`)
`Language`	BCP-47 language code (e.g. `en`, `fr`, `ja`)
`Default`	Whether this track is marked as the default subtitle stream
`Forced`	Whether the track is marked as forced
`SDH`	Whether the track is marked as SDH (Subtitles for the Deaf and Hard of Hearing)
`IsExtracted`	Whether the text subtitle has been extracted to disk for direct playback

Text-based embedded subtitles (SRT, ASS, WebVTT, MOV text) can be extracted to disk by enabling Extract Embedded Text Subtitles in ErsatzTV’s Settings. Once extracted, they behave identically to sidecar subtitles during playback. Image-based subtitle formats — including PGS (hdmv_pgs_subtitle, pgssub), DVD subtitles (dvd_subtitle, dvdsub), and VobSub (vobsub) — are detected but not extracted; they are handled at transcode time.

A fix resolved an edge case where an embedded subtitle with stream index zero would create an invalid subtitle record. Affected items will be automatically cleaned up on the next local library scan.

Managing Library Paths

A single local library can have multiple directory paths. All paths must exist on the file system at the time they are added. You can:

Add a path by typing in the Path field and clicking Add Path
Delete a path by clicking the delete icon next to it in the library editor — you will be shown how many media items will be removed
Move a path to a different library by clicking the move icon — useful when reorganizing content between libraries without losing playout history

Deleting a library path removes all media item records associated with that path from ErsatzTV. Any schedules referencing those items will lose those entries. This operation cannot be undone.

Running ErsatzTV in Docker

When ErsatzTV runs in a Docker container, the host paths to your media must be mounted into the container. The path you enter in the local library editor must be the path inside the container, not the path on your host.

services:
  ersatztv:
    image: ghcr.io/ersatztv/ersatztv:latest
    environment:
      TZ: America/Chicago
    ports:
      - "8409:8409"
    volumes:
      - ersatztv_config:/config
      - /srv/media:/media:ro       # host /srv/media → container /media
    tmpfs:
      - /transcode

volumes:
  ersatztv_config:

In the example above, a library path of /media/movies (inside the container) corresponds to /srv/media/movies on the host. When adding the library in ErsatzTV, enter the container-side path (/media/movies).

Mount media volumes as read-only (:ro) whenever possible. ErsatzTV only needs read access to your media files — it writes nothing to those directories.

For more container configuration options including NVIDIA GPU passthrough, see Docker Operations.

Supported File Formats

ErsatzTV leverages FFmpeg for media analysis and playback, so any container format that FFmpeg can read is supported. Commonly used formats include:

Video containers: MKV, MP4, AVI, MOV, TS, M2TS, WEBM, FLV
Audio containers (Songs): MP3, FLAC, OGG, AAC, M4A, WAV, OPUS
Image formats (Images): JPEG, PNG, GIF, WebP, BMP, TIFF

NFO sidecar files (.nfo) following the Kodi/Jellyfin naming convention are parsed for additional metadata (titles, years, plot summaries, ratings, tags) and take precedence over data embedded in the media file.

API: Libraries

Reference for the /api/libraries/{id}/scan and /api/libraries/{id}/scan-show endpoints.

Docker Operations

Container deployment guide including volume mount patterns for media directories.

Get Started

Core Concepts

Configuration

Scheduling

Media Server Integration

Streaming & Clients

Operations

Add Local Media Folder Libraries to ErsatzTV Legacy

The Local Media Source

Supported Media Kinds

Adding a Local Library

Scanning Local Libraries

Scan Library via API

Scan a Single Show via API

Subtitle Support

Sidecar Subtitles

Embedded Subtitles

Managing Library Paths

Running ErsatzTV in Docker

Supported File Formats

API: Libraries

Docker Operations

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Scheduling

Media Server Integration

Streaming & Clients

Operations

Documentation Index

​The Local Media Source

​Supported Media Kinds

​Adding a Local Library

​Scanning Local Libraries

​Scan Library via API

​Scan a Single Show via API

​Subtitle Support

​Sidecar Subtitles

​Embedded Subtitles

​Managing Library Paths

​Running ErsatzTV in Docker

​Supported File Formats

​Related Pages

API: Libraries

Docker Operations

Build docs developers (and LLMs) love

The Local Media Source

Supported Media Kinds

Adding a Local Library

Scanning Local Libraries

Scan Library via API

Scan a Single Show via API

Subtitle Support

Sidecar Subtitles

Embedded Subtitles

Managing Library Paths

Running ErsatzTV in Docker

Supported File Formats

Related Pages