Your channels. Your recordings. Your server.
A self-hosted live TV and DVR server for HDHomeRun, IPTV, and HLS sources. Browse a unified guide, watch from any modern browser, and keep recordings on storage you control.
Get started · Configuration · Contributing
SignalHaven brings live television, guide data, scheduling, and playback together in one responsive web app—without sending your viewing history or recordings to a hosted service.
- Watch live TV with an in-player mini guide and channel switching.
- Pause and rewind live streams with a configurable rolling time-shift buffer.
- Record once or automatically with one-off schedules, series rules, retention controls, and conflict visibility.
- Browse one unified guide backed by HDHomeRun guide data or XMLTV sources.
- Manage your lineup by searching, sorting, favoriting, hiding, reordering, and merging duplicate channels across tuners with automatic source fallback.
- Play recordings in the browser with resume progress, captions, and optional Comskip commercial markers.
- Adapt playback to your hardware with direct streaming, quality profiles, and optional VideoToolbox, VA-API, Quick Sync, or NVENC acceleration.
- Use it anywhere on your network through a responsive light- and dark-mode interface.
The recommended installation uses Docker Compose and includes PostgreSQL, FFmpeg, automatic database migrations, health checks, and persistent volumes.
- Docker Engine with Docker Compose
- A supported TV source: HDHomeRun, an M3U/M3U8 playlist, or a direct HLS stream
- Guide data from a supported HDHomeRun subscription or an XMLTV URL/file if you want program listings
- Enough local storage for your recordings and live TV buffer
git clone https://github.com/rrainn/SignalHaven.git
cd SignalHaven
cp .env.example .envOpen .env and replace the default PGPASSWORD with a strong, unique password. Then start SignalHaven:
docker compose up -dOpen http://localhost:3000. Your first step is to create the local administrator account; SignalHaven stores only its username and password hash. The first-run wizard then helps you add a tuner, connect guide data, choose a recordings folder, and review channel mapping.
The administrator can create password-only standard accounts from Settings. Each account has an independent recording library, series rules, guide annotations, channel preferences, appearance, and playback preferences. Standard accounts cannot open global Settings or manage tuners, guide sources, channel topology, diagnostics, or other accounts. See Local accounts and sessions for the complete security and upgrade behavior.
On a Linux Docker host, enable automatic iOS and macOS discovery with the optional Bonjour sidecar:
docker compose --profile bonjour up -dThe sidecar is published separately, uses host networking for link-local
multicast, and advertises the required canonical PUBLIC_URL. Configure its
HTTPS reverse proxy and local DNS before enabling the profile. See
HTTPS service discovery with Bonjour for the deployment and
migration contract.
Your database and recordings persist in Docker volumes. To use an existing PostgreSQL server or change storage and playback behavior, see the configuration reference.
Important
SignalHaven is designed for a trusted home network. Local accounts protect libraries and administrative APIs, and Bonjour clients still require an HTTPS reverse proxy. Built-in authentication and HTTPS do not by themselves make an internet-facing DVR safe; use a carefully maintained reverse proxy, rate limits, firewall or VPN controls, and an appropriate threat model before exposing it outside the trusted network.
Review the release notes, then pull and restart the stack:
docker compose pull
docker compose up -dFor reproducible deployments, set SIGNALHAVEN_IMAGE in .env to a numbered release instead of latest.
The main and Bonjour images are published under matching release tags.
Prerelease images are published under both their exact version and a moving
channel tag. For example, v0.2.0-beta.2 publishes
ghcr.io/rrainn/signalhaven:0.2.0-beta.2 and
ghcr.io/rrainn/signalhaven:beta, with the same tags under
ghcr.io/rrainn/signalhaven-bonjour; alpha versions similarly update :alpha.
These images do not update :latest or stable major/minor tags. Mark the GitHub
Release as a prerelease when publishing it, then set SIGNALHAVEN_IMAGE to the
exact version or channel tag to test it.
| Source | What SignalHaven supports | Guide data |
|---|---|---|
| HDHomeRun | Network discovery, channel import, live TV, and tuner-aware recording | Configured automatically; SiliconDust's guide feed requires an HDHomeRun DVR guide subscription |
| IPTV / M3U | Remote M3U or M3U8 playlists, channel metadata, and live TV | Optional XMLTV URL; channels are matched using playlist metadata such as tvg-id |
| Generic HLS | A direct M3U8 stream represented as one virtual channel | Add a separate XMLTV source if guide data is available |
SignalHaven can also use additional remote or local XMLTV sources when your tuner does not provide guide data.
| Resource | Use it for |
|---|---|
| Configuration | Environment variables, storage, transcoding, time shifting, lineup sync, UI preferences, and observability |
| Accounts | Account bootstrap, roles, sessions, private libraries, upgrades, and security boundaries |
| Architecture | Services, runtime flow, recording lifecycle, and repository design |
| Design and brand guide | Product voice, visual system, and brand assets |
| Contributing guide | Local development, validation commands, and pull request expectations |
| OpenAPI specification | API reference from a running SignalHaven server |
Contributions are welcome. SignalHaven is a pnpm monorepo with a Next.js frontend, an Express API, PostgreSQL through Drizzle ORM, and shared Zod schemas.
To start a development environment:
pnpm install --frozen-lockfile
cp .env.example .env
docker compose up -d postgres
pnpm run devBefore opening a pull request, run the project validation suite:
pnpm run format:check
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run buildRead CONTRIBUTING.md for prerequisites, repository layout, resource-bounded preview commands, and contribution expectations. If you have found a bug or want to propose a feature, open an issue.
I used AI extensively to build this application. While I understand that some people may have concerns about AI-generated code, I believe it is a tool that when used effectively can help developers create better software than they could on their own. This application would still be sitting on my todo list if it wasn't for AI. I have personally reviewed all of the code, and I am confident it meets my standards. However, like humans, AI can make mistakes, so please report any issues you find.
SignalHaven and rrainn LLC do not endorse piracy or any other illegal use of the software. SignalHaven is free, open-source software, and we do not monitor or control how users choose to operate it; users are solely responsible for complying with applicable laws and respecting copyright.
Copyright 2026 rrainn LLC
SignalHaven is not affiliated with SiliconDust, the makers of HDHomeRun.