A small, self-hosted DVR server for the Lume IPTV app. Lume schedules a recording ("record this programme"); LumeRecorder runs on an always-on machine (NAS, mini PC, Raspberry Pi, Mac) and records the stream with ffmpeg to HLS on disk, even when every Apple device is asleep. Finished and in-progress recordings play back in Lume over short-lived signed links.
- One ffmpeg process per recording, stream copy (no transcoding), HLS output.
- Automatic retries with
#EXT-X-DISCONTINUITYwhen the source drops. - Survives restarts: running recordings resume, missed ones are marked.
- Pairing with a 6-digit code, per-device bearer tokens (stored hashed).
- Bonjour discovery (
_lume-recorder._tcp), JSON HTTP API, no database.
Your responsibility: only record content you are entitled to record and keep. LumeRecorder ships no channels or streams. It records what your Lume app points it at, using your provider credentials, for your private use.
On a Mac you can run LumeRecorder as a menu-bar app instead of a container:
- Download
LumeRecorder-<version>.dmgfrom the latest release, open it, and drag LumeRecorder into Applications. - Open the app. A record icon appears in the menu bar. Click it to see the pairing code, recording status and paired devices.
ffmpeg is built in, so there's nothing else to install. The app registers itself to open at login (toggle it in the menu), keeps the
Mac from idle-sleeping while recordings are running or scheduled, and stops
ffmpeg cleanly when you quit. Data lives in
~/Library/Application Support/LumeRecorder, the log in
~/Library/Logs/LumeRecorder/lume-recorder.log. The environment variables
from Configuration still apply. A Mac whose lid is closed
(without an external display) still sleeps and misses recordings.
# docker-compose.yml
services:
lume-recorder:
image: ghcr.io/bilipp/lumerecorder:latest
container_name: lume-recorder
restart: unless-stopped
network_mode: host # needed for Bonjour discovery
volumes:
- ./data:/datadocker compose up -d
docker logs lume-recorder | grep "Pairing code"Or build from this checkout: docker build -t lumerecorder .
docker build -t lumerecorder .
docker run -d --name lume-recorder --restart unless-stopped \
--network host -v "$PWD/data:/data" lumerecorder
docker exec lume-recorder lume-recorder pairOn Docker Desktop (macOS/Windows) host networking can't carry Bonjour: publish
the port instead (-p 8090:8090 -e BONJOUR=0) and add the server in Lume by
address.
container system start
container build -t lumerecorder:dev .
mkdir -p ~/LumeRecorder-data
container run -d --name lume-recorder \
-p 0.0.0.0:8090:8090 -v ~/LumeRecorder-data:/data \
-e BONJOUR=0 lumerecorder:dev
container exec lume-recorder lume-recorder pairThe container runs in a VM, so Bonjour doesn't reach your network: in Lume use Settings → Recording Server → Enter Address Manually with your Mac's IP and port 8090.
The server runs as the unprivileged lume user. The entrypoint hands /data
to that user when it can; shared host folders (Docker Desktop, Apple
container) refuse chown, in which case it runs as the folder's owner or, if
only root can write there, as root, and says so in the log.
Needs Swift 6 and ffmpeg (brew install ffmpeg / apt install ffmpeg):
swift run -c release lume-recorder --data-dir ./dataOn macOS this also advertises the server via Bonjour, so the iOS Simulator and devices on your LAN discover it.
- Start the server. It logs a code, and logs a new one every 10 minutes:
Pairing code: 123 456 (valid 10 min) - Print the current code at any time:
docker exec lume-recorder lume-recorder pair(orlume-recorder pair --data-dir ./data). The Mac app shows it in its menu. - In Lume, pick the discovered server (or enter
host:port) and type the code.
A code stays valid for its whole 10-minute window, so several devices can pair
with it. After 5 wrong codes within a minute, pairing is locked for that
minute (429). Devices can be listed and unpaired from Lume.
Every variable also has a CLI flag on lume-recorder serve (e.g. --port,
--data-dir, --max-concurrent); a flag wins over its variable.
| Variable | Default | Meaning |
|---|---|---|
PORT |
8090 |
HTTP port |
HOST |
0.0.0.0 |
Bind address |
DATA_DIR |
/data (Docker), ./data otherwise |
State, secrets and recordings |
MAX_CONCURRENT |
4 |
Recordings that may run at once (each holds one provider connection) |
MIN_FREE_GB |
2 |
Refuse/fail recordings below this much free disk |
SERVER_NAME |
hostname | Name shown in Lume and in Bonjour |
PUBLIC_URL |
unset | Base URL for playback links when a request carries no Host header |
FFMPEG_PATH |
ffmpeg on PATH |
ffmpeg executable |
LOG_LEVEL |
info |
trace, debug, info, notice, warning, error, critical |
BONJOUR |
1 |
0 disables Bonjour (NetService on macOS, avahi in Docker) |
SINGLE_FILE_RECORDINGS |
0 |
1 merges each finished recording into one recording.ts (see below) |
TZ |
UTC | Container timezone (log timestamps only; the API is UTC) |
Data layout:
DATA_DIR/
├── server.json server id + playback-signing secret (keep private)
├── recordings.json recording records, including stream URLs (keep private)
├── devices.json paired devices (SHA-256 token hashes only)
├── pairing-code.json current pairing code (read by `lume-recorder pair`)
└── recordings/<id>/ index.m3u8 + a<attempt>_<n>.ts segments
(finished, with SINGLE_FILE_RECORDINGS: index.m3u8 + recording.ts)
Files are written atomically and readable only by the server user (0600).
The server advertises _lume-recorder._tcp with TXT records id=<server id>,
version=<version>, api=1.
-
macOS (
swift run): advertised withNetService. -
Docker on Linux: the entrypoint starts
avahi-daemoninside the container. This only reaches your LAN withnetwork_mode: host. -
Bridge networking, Docker Desktop (macOS/Windows), or VLANs: multicast doesn't leave the container. Set
BONJOUR=0and enterhost:8090in Lume. -
The host already runs avahi-daemon (common on NAS systems): two mDNS responders on one host fight over the hostname. Set
BONJOUR=0and put this file in the host's/etc/avahi/services/lume-recorder.service, with the id fromdocker exec lume-recorder lume-recorder server-id:<?xml version="1.0" standalone='no'?> <!DOCTYPE service-group SYSTEM "avahi-service.dtd"> <service-group> <name replace-wildcards="yes">%h</name> <service> <type>_lume-recorder._tcp</type> <port>8090</port> <txt-record>id=PASTE-SERVER-ID</txt-record> <txt-record>version=0.3.1</txt-record> <txt-record>api=1</txt-record> </service> </service-group>
All JSON; dates are ISO-8601 UTC (fractional seconds optional on input).
Errors always look like {"error":{"code":"snake_case","message":"…"}}.
Swift clients should use LumeRecorderKit (in Kit/), which wraps all of this.
| Method & path | Auth | Purpose |
|---|---|---|
GET /api/v1/info |
none | ServerInfo {id, name, version, apiVersion} |
POST /api/v1/pair |
none | {code, deviceName} → {token, deviceID, server}; 401 pairing_invalid, 429 rate_limited |
GET /api/v1/recordings |
bearer | All recordings, newest start first |
POST /api/v1/recordings |
bearer | Schedule/start one → 201. Optional Idempotency-Key header: a repeat from the same device returns the original with 200 |
POST /api/v1/recordings/{id}/stop |
bearer | Scheduled → cancelled; recording → graceful stop → completed |
DELETE /api/v1/recordings/{id} |
bearer | Stop if needed, delete media and record → 204 |
POST /api/v1/recordings/{id}/playback |
bearer | {url, expiresAt}: signed HLS link valid 12 h (409 not_playable before the first segment) |
GET /api/v1/status |
bearer | Active/scheduled counts, disk space, maxConcurrent |
GET /api/v1/devices |
bearer | Paired devices |
DELETE /api/v1/devices/{id} |
bearer | Unpair (your own device too) → 204 |
GET /play/{id}/{expiry}/{sig}/{file} |
signature | index.m3u8 / *.ts. Works while recording. .ts honours Range |
Create body: {streamURL, title, channelName?, channelLogoURL?, programmeDescription?, start, end, sourceRef?}. Rules: http/https stream URL,
end > start, end in the future, at most 12 h. A start in the past starts
immediately. If that would exceed MAX_CONCURRENT you get 409 concurrency_limit, and low disk gives 507 insufficient_storage. A scheduled
recording that hits either limit at its start time becomes failed with that
failureReason.
Recording.status is scheduled, recording, completed, failed or
cancelled. Clients must tolerate unknown future values. The stream URL is
never returned by the API or written to the log.
Bearer auth: Authorization: Bearer <token>. Playback links carry their HMAC
in the path (/play/<id>/<expiry>/<hmac>/index.m3u8). That way the
playlist's relative segment URIs inherit the signature, and players need no
headers.
- ffmpeg reads the source in real time (
-readrate 1, with a 10 s initial burst where supported), so a "live" channel that is really a file is recorded at wall-clock pace rather than slurped. - If ffmpeg exits before the end, the recorder retries with backoff from 2 s up to 30 s. Each attempt appends to the same playlist behind a discontinuity.
- At the end, or on stop, ffmpeg gets SIGINT (then SIGTERM/SIGKILL after 10 s).
The playlist always ends with
#EXT-X-ENDLIST. - A recording that captured nothing becomes
failedwithno_segments: <last ffmpeg lines>, URLs redacted. If the source refuses to open five times in a row (each attempt dying within 2 s) before anything was captured, the recorder stops early withsource_unavailable: <last ffmpeg lines>. - On restart, running recordings resume as a new attempt. Ones that ended while
the server was down become
completed(if media exists) orfailed. Scheduled ones whose window passed becomefailed(missed). - With
SINGLE_FILE_RECORDINGS=1, a recording still records (and plays live) as segments. When it finishes, the segments are concatenated into onerecording.tsthat any player opens directly, andindex.m3u8is rewritten to address it with#EXT-X-BYTERANGE, so playback in Lume is unchanged. The merge copies the recording once, so it needs the recording's size in free disk on top ofMIN_FREE_GB. Without that space, or on any error, the recording keeps its segments. It only applies to recordings that finish while the setting is on. docker stop(SIGTERM) stops ffmpeg cleanly and keeps the rowsrecording, so they resume when the container is back.
swift build && swift test # server (Swift Testing + HummingbirdTesting)
(cd Kit && swift test) # client kit
(cd MacApp && swift build) # macOS menu-bar app
MacApp/scripts/build-app.sh # LumeRecorder.app + DMG in MacApp/dist/build-app.sh bundles an LGPL ffmpeg built from the official source release
by MacApp/scripts/build-ffmpeg.sh (no external libraries, about 4 minutes on
first build, cached in MacApp/.build/). Set FFMPEG_BINARY to bundle another
static build. It signs ad-hoc by default. Set SIGN_IDENTITY (Developer ID)
and NOTARY_PROFILE for a build that opens on other Macs without a Gatekeeper
warning. The DMG layout comes from MacApp/Resources/dmg-settings.py
(dmgbuild, installed into a venv on first
use).
The macOS app job signs every push to main with a Developer ID
certificate. On a v* tag it also notarizes the app and attaches
LumeRecorder-<version>.dmg to the GitHub release. A release tag fails
without these repository secrets, and PRs build ad-hoc signed:
| Secret | Value |
|---|---|
MACOS_CERTIFICATE_P12_BASE64 |
base64 -i cert.p12: the "Developer ID Application" certificate with its private key, exported from Keychain Access |
MACOS_CERTIFICATE_PASSWORD |
the password set during that export |
NOTARY_KEY_P8_BASE64 |
base64 -i AuthKey_XXXX.p8: an App Store Connect API key (Users and Access → Integrations, role Developer) |
NOTARY_KEY_ID |
that key's ID |
NOTARY_ISSUER_ID |
the issuer ID shown above the key list |
gh secret set MACOS_CERTIFICATE_P12_BASE64 < <(base64 -i cert.p12)
gh secret set MACOS_CERTIFICATE_PASSWORD
gh secret set NOTARY_KEY_P8_BASE64 < <(base64 -i AuthKey_XXXX.p8)
gh secret set NOTARY_KEY_ID
gh secret set NOTARY_ISSUER_IDThe real-ffmpeg integration test is skipped when ffmpeg isn't installed. See
AGENTS.md for architecture and invariants.
AGPL-3.0. See LICENSE.