Home

Obelo

A fully self-hosted media server for your household's movies, TV, and music.

Obelo scans the video and music files you already have on disk, organizes them into browsable libraries, decorates them with artwork and descriptions from public metadata sources, and streams them to your devices — all from a single binary you run on your own hardware. No accounts on someone else's servers, no phoning home, no vendor lock-in.

Point it at a folder of media, open it in a browser, and press play.

---

Start here

If you want to…	Go to
Get it running in five minutes	Installation
Run it in Docker properly (volumes, compose, GPU)	Docker
Create your admin account and first library	First Run
Look up an environment variable	Configuration
Use the GPU for transcoding	Hardware Transcoding
Have native clients find the server by themselves	LAN Discovery
Install plugins: extra metadata sources, sign-in providers, notifications	Plugins
Write your own plugin	Plugin Development
Share libraries with a friend who also runs Obelo	Linked Servers
Reach it from outside the house, with no port forward	Remote Access with Tailscale
Reach it from outside the house, over a real domain	HTTPS
Put nginx / Caddy / Traefik in front	Reverse Proxy
Fix something that is broken	Troubleshooting

---

What you are signing up for

• Movies, TV, and Music in one server — each library holds one kind, backed by one or more folders on disk (multiple folders merge into one library).
• Identity comes from your file names, not a cloud database. The scanner derives what each file is from its path and embedded tags, so your library is yours and stays correct offline. External metadata only ever decorates — it never decides identity.
• Automatic artwork & metadata (enrichment) from TMDB, MusicBrainz, fanart.tv, TheAudioDB and others. Fully optional and off until you turn it on; until you grant enrichment consent Obelo makes zero outbound calls.
• Three playback tiers, chosen automatically — direct play when the client can handle the file as-is, direct stream (remux) when only the container needs changing, full FFmpeg transcode when it doesn't.
• Hardware-accelerated transcoding — NVENC, VAAPI, Quick Sync, and VideoToolbox, with a live admin view of transcode load and GPU telemetry.
• Share libraries with another household — a friend's Obelo can lend yours a few libraries, and they appear in your apps as ordinary libraries. No central service, no account anywhere, and your watch state stays yours.
• Multi-user with real access control — per-user libraries, content-rating ceilings, private watch state, resume, and named per-device tokens you can revoke individually.
• One process, one binary. A Go server with the React web app embedded inside it. SQLite for state, the filesystem for caches. Nothing else to stand up.

Requirements

• ffmpeg (with ffprobe) on the server's PATH. This is the only runtime dependency, and the Docker image already contains it.
• A folder (or folders) of media, and a browser.

To build from source you additionally need Go 1.25+ and Node.js 22+.

---

Where the rest of the documentation lives

This wiki is the operator's manual. One thing in the repository goes deeper and is worth knowing about:

• CONTEXT.md — the domain glossary. If you are unsure what Obelo means by Title, Edition, identity, or enrichment, it is defined there.

A note on metadata sources

Obelo's enrichment is optional and, when enabled, decorates your library using public sources. Obelo is not endorsed by or affiliated with any of them. This product uses the TMDB API but is not endorsed or certified by TMDB. Music metadata comes from MusicBrainz and the Cover Art Archive; additional artist imagery from fanart.tv and TheAudioDB.