Obscura
A private screening room for your entire library.
Obscura is a self-hosted media browser that brings your videos, movies, TV series, comics, manga, books, image galleries, and audio into one organized, searchable interface — running entirely on your own hardware, on your own network.
There are no cloud accounts, no subscriptions, and no data leaves your home. Everything runs inside a single Docker container. You provide the media; Obscura handles the rest.
What Obscura manages
| Media type | What you get |
|---|---|
| Videos & Movies | HLS adaptive streaming, on-demand transcoding, trickplay sprites, frame-strip scrubbing, markers. |
| TV Series | Season and episode organization inferred from your folder layout, with full metadata and per-episode progress. |
| Comics & Manga | cbz/zip archives and image folders organized into series, with natural page order, ComicInfo metadata, reading progress, and a dedicated paged or webtoon reader. |
| Books | Your reading collection alongside every other media type — browsable, searchable, and readable from any device. |
| Image Galleries | Folder-based and archive-based galleries with grid and lightbox modes, ratings, tags, and performer/studio linking. |
| Audio | Albums, tracks, cover art, waveforms, performer and studio linking, shuffle, and a built-in player. |
| Performers, Studios & Tags | Rich cross-referenced entities that span every media type — link a performer to their videos, audio, and galleries from one profile. |
How it works
- Run the Docker image — PostgreSQL, ffmpeg, and the web server ship as one container. No external dependencies.
- Mount your media — point one or more directories at
/mediaand register them as library roots in Settings. - Scan — Obscura walks your library, fingerprints files, generates thumbnails and previews, and organizes everything into the appropriate library type.
- Identify — run the identify engine to pull in metadata from plugins and scrapers. Titles, cover art, cast, ratings, and descriptions fill in automatically.
- Browse and play — open the app from any browser on your local network.
Key capabilities
Metadata, everywhere
Every entity — video, comic, book, audio track, performer, studio — carries the same rich metadata surface: title, cover art, description, ratings, tags, and provenance. Plugin-powered providers handle identification automatically, with Stash-compatible scrapers and StashDB endpoints supported natively.
Mobile-first
Every view is designed for a phone first. Browse, search, play, and read from any device on your network. Touch targets, gesture navigation, and bottom navigation are designed before the desktop expansion — not bolted on after.
One container
PostgreSQL 16, ffmpeg, audiowaveform, and the background worker all run inside one Docker image. Mount /data for application state, mount your media under /media, expose port 8008, and you're running. No environment variables required.
Plugin system
Extend Obscura with TypeScript or Python plugins that add metadata providers, scrapers, and identify sources. The community scraper index is built in — browse, install, and enable scrapers directly from the Settings page.
Background jobs you can see
Scanning, probing, transcoding, and scraping all happen as background jobs. The Operations dashboard shows every running and queued job in real time so you always know what the system is doing.
Get started
New to Obscura?
Start with the Quick Start guide. It walks through the one-command Docker install, volume setup, and first boot in about five minutes. Then read First Boot before pointing it at a real library.
Coming from Stash?
Obscura supports native StashDB endpoints and is compatible with community Stash scrapers. See Stash Compatibility for migration guidance.
Want to write a plugin?
Start at Plugins · Overview. The Manifest and Capabilities pages are the reference; the TypeScript and Python guides walk through real plugins end-to-end.
Want to understand the code?
Start at Architecture. Monorepo Layout, Database, and API & Jobs drill into each layer.
:::tip Pre-1.0 note Obscura is under active development. We do not maintain backwards-compatibility shims between schema breaks. When something destructive changes, a one-time gate in the UI explains what's happening and asks for consent before proceeding. The Upgrading page covers the policy. :::