Adding Libraries

Libraries tell Dubby where your media files are stored. Each library has a type (movies, TV shows, or podcasts), a name, and one or more filesystem paths.

Creating a library

Open the Dubby web interface and go to Settings > Libraries
Click Add Library
Choose a library type:
- Movies — Each folder contains a single film
- TV Shows — Folders organized by show, season, and episode
- Podcasts — RSS feed subscriptions (no filesystem paths needed)
Give it a name (e.g., “Movies”, “Anime”, “Kids TV”)
Add one or more paths pointing to your media directories
Click Create

Dubby immediately starts scanning the new library.

Docker volume mounts

In Docker, your media directories must be mounted into the container. Add them to your docker-compose.yml:

services:
  dubby:
    volumes:
      - /path/to/movies:/media/movies
      - /path/to/tv:/media/tv
      - /path/to/anime:/media/anime

Then use the container paths (e.g., /media/movies) when creating libraries in the Dubby UI.

Multiple paths per library

The API supports multiple filesystem paths per library, which is useful when your media is spread across multiple drives. All paths in a library share the same type and metadata settings.

Library scanning

Automatic scanning

When Valkey/Redis is configured (REDIS_URL), Dubby watches your library directories for filesystem changes using chokidar. New or modified files are automatically detected and enqueued for processing. The watcher includes stability checks to wait for files to finish copying before triggering a scan.

Without Valkey, automatic scanning is disabled — use manual scans instead.

Manual scanning

Trigger a scan from the UI or API:

Quick scan (default) — Only processes new and changed files
Full scan — Re-processes all files and refreshes metadata from external providers

# Scan a specific library via API
curl -X POST http://localhost:3000/v1/libraries/{id}/scan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "quick"}'

# Scan all libraries
curl -X POST http://localhost:3000/v1/libraries/scan-all \
  -H "Authorization: Bearer $TOKEN"

What happens during a scan

Discover — Walk the filesystem and parse filenames to extract title, year, season/episode numbers. Extras (trailers, samples, featurettes, bonus content) are automatically filtered out. For TV libraries, show and season records are pre-created before processing individual episodes.
Prepare (per file) — Quick FFprobe to detect codecs, resolution, duration, audio tracks, and embedded subtitles. Insert or update the media record. For TV episodes with chapter markers, intro boundaries are detected automatically.
Enrich (per file) — Search TMDB for matching metadata, download artwork (poster, backdrop, logo), descriptions, cast, crew, and genre information.
Enhance (per file) — If configured, download subtitles from OpenSubtitles. Mark the item as ready.
Post-scan — Update the library timestamp. If enabled, queue ahead-of-time optimization and season-level intro detection (audio fingerprinting). Queue keyframe analysis for any items that haven’t been analyzed yet.

Each file is processed independently and appears in the library as soon as its prepare step completes — you don’t have to wait for the entire scan to finish. The three per-file stages (prepare → enrich → enhance) run on separate queues so CPU-bound work (probing) doesn’t block network-bound work (metadata fetching).

Scan progress is visible in real-time via the admin dashboard.

Deduplication

Only one scan per library can run at a time. Requesting a scan while one is already in progress returns a 409 Conflict response.

Deleting a library

Deleting a library removes all associated metadata, watch progress, and database records. Your media files on disk are never deleted.

Path validation

When adding paths, the server validates that:

The path exists on the filesystem
The path is readable by the server process

Admins can also create new directories from the UI if needed.