Reading
Comics, manga, and books
cbz/zip archives, image folders, and book files scan as organized series. Natural page order, ComicInfo metadata, reading progress, and a dedicated paged or webtoon reader — all in the same library as your videos.
Manages
- Videos
- Series
- Movies
- Comics
- Manga
- Books
- Galleries
- Images
- Audio
- Performers
- Studios
- Tags
- Plugins
Documentation
Where to start
Pick the section that matches what you are trying to do.
01 · Run itSet up your media library
Install with Docker, mount your media directories, run a scan, and start browsing. Library organization, settings, and operations live here.
Quick start→02 · Extend itBuild a metadata pluginWrite providers in TypeScript or Python to identify videos, comics, performers, audio, and more. The community scraper index is built in.
Build plugins→03 · Understand itExplore the architectureSvelteKit, the worker, Postgres, and the shared packages. How code moves from the UI all the way to the database and job queue.
Architecture→What it does
What Obscura manages
Built for a single trusted user on a private network. All processing happens locally — no internet access required, no external services.
Streaming
On-demand HLS
Videos transcode to HLS via ffmpeg as they are needed. Cached renditions are served directly from the app — no separate media server, no manual format conversion.
Audio
Your music collection, organized
Albums, tracks, cover art, waveforms, performer and studio linking. The same metadata pipeline as every other media type, with shuffle and a built-in player.
Metadata
Plugin-powered identification
TypeScript and Python plugins expose providers for movies, series, comics, performers, galleries, and audio. One identify engine covers your entire library.
Operations
Background jobs you can see
Scan, probe, thumbnail, sprite, HLS, and import jobs run in the background. The Operations dashboard mirrors every job in real time — so you always know what the system is doing.
Library
Folders are the schema
Movies, flat series, and seasoned series are inferred from your folder depth. Sidecars and sidecar metadata merge cleanly without overwriting your edits.
Deploy
One Docker image
PostgreSQL, ffmpeg, the web server, and the worker ship as a single image. Mount /data and /media, expose port 8008, and you are running. Nothing else required.
The interface
Dark Room — sharp edges, brass on signal, glass when it floats.
The whole UI follows one design language. Read the Design Language doc for the full spec.
A dashboard built like an instrument panel.
Every media type at a glance — recent activity, library totals, scan state, and job status. Dense, dark, and purposeful.
Rich video playback, start to finish.
HLS adaptive streaming, trickplay frame strip, multi-language subtitles with a dockable transcript panel, and inline metadata editing — all in one page.
Comics and books organized for reading.
Archive chapters and image folders scan into organized series. Natural page order, read/unread progress, and a dedicated reader with paged or webtoon mode.
Mobile is first-class, not a fallback.
Browse, search, read, and play from any phone on your network. Every view is designed for touch before it scales up to desktop.
