LumeRecorder

Record live TV with your own server

LumeRecorder is a small, free and open-source DVR server you run at home. Lume tells it what to record, and it records on its own, even while every Apple device is asleep. Recordings play back in Lume on all your devices, including ones that are still recording.

Recording is part of Lume Pro. The server itself is free.

What you need

An always-on machine
A NAS, mini PC, home server, 64-bit Raspberry Pi or a Mac that stays awake. The Docker image runs on Intel/AMD and ARM.
Docker
Docker or Docker Desktop, or Apple's container tool on a Mac with Apple silicon. Most NAS systems have Docker built in.
Disk space
Streams are saved as they arrive, without re-encoding. An HD channel usually takes a few gigabytes per hour.
The same network
The server and your Apple devices should be on the same home network, so Lume can find it and play recordings.

1
Step 1
Start the server
Pick how you run containers. Every option keeps recordings and settings in a data folder next to it, so they survive updates.
Save this as docker-compose.yml in a new folder, then start it from that folder. Host networking lets Lume find the server automatically.
docker-compose.yml
```
services:
  lume-recorder:
    image: ghcr.io/bilipp/lumerecorder:latest
    container_name: lume-recorder
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/data
```
```
docker compose up -d
```
On Synology, QNAP, Unraid or TrueNAS you can paste the same file into the system's Docker or Container Manager as a new project.
On a Mac or Windows PC with Docker Desktop, publish the port instead of using host networking. Save this as docker-compose.yml and start it.
docker-compose.yml
```
services:
  lume-recorder:
    image: ghcr.io/bilipp/lumerecorder:latest
    container_name: lume-recorder
    restart: unless-stopped
    ports:
      - "8090:8090"
    volumes:
      - ./data:/data
    environment:
      BONJOUR: "0"
```
```
docker compose up -d
```
Docker Desktop can't announce the server on your network, so you'll enter its address in Lume by hand. Make sure Docker Desktop starts at login.
On a Mac with Apple silicon you can use Apple's container tool instead of Docker.
```
container system start
mkdir -p ~/LumeRecorder-data
container run -d --name lume-recorder \
  -p 0.0.0.0:8090:8090 \
  -v ~/LumeRecorder-data:/data \
  -e BONJOUR=0 ghcr.io/bilipp/lumerecorder:latest
```
The container runs in a lightweight VM, so you'll enter your Mac's address in Lume by hand. Keep the Mac from sleeping while recordings are scheduled.
Prefer to run it without containers? It needs Swift 6 and ffmpeg; see building from source.
2
Step 2
Get the pairing code
When the server starts, it prints a 6-digit pairing code to its log and a new one every 10 minutes. Show the current code at any time with:
```
docker exec lume-recorder lume-recorder pair
```
With Apple's tool, run container exec lume-recorder lume-recorder pair instead. On a NAS, the code is also in the container's log view.
3
Step 3
Pair Lume
1. In Lume, open Settings › Live TV › Recording Server.
2. Read Before You Pair and tap I Understand.
3. Choose your server under Servers on This Network. If it isn't listed, tap Enter Address Manually, type the server's IP address (for example 192.168.1.20) and tap Connect. Lume uses port 8090 unless you add another.
4. Enter the Pairing Code from the server and tap Pair.
Pair once: the pairing syncs to your other Apple devices through iCloud.
4
Step 4
Record
- Record now: choose Record from a channel's menu or in the player.
- Record later: open a programme in the Guide and choose Schedule Recording.
- Watch: open Recordings from the Live TV toolbar or Settings › Live TV. On Apple TV you can also show it in the Live TV sidebar.

Settings

Change these as environment entries in docker-compose.yml (or -e NAME=value with Apple's tool).

Variable	Default	What it does
`SERVER_NAME`	Hostname	The name Lume shows for the server.
`PORT`	8090	The port the server listens on.
`MAX_CONCURRENT`	4	How many recordings may run at once. Each one uses a connection to your provider.
`MIN_FREE_GB`	2	Recordings won't start when less than this many gigabytes are free.
`BONJOUR`	1	`0` turns off automatic discovery, for setups where it can't work.
`TZ`	UTC	Timezone for log timestamps, e.g. `Europe/Berlin`.

Run docker compose up -d again after changing them.

Troubleshooting

Lume doesn't find the server

Make sure Lume may use your local network (on iPhone and iPad: Settings › Privacy & Security › Local Network). Automatic discovery only works with host networking on Linux. With Docker Desktop, Apple's tool, bridge networking or separate VLANs, tap Enter Address Manually and type the machine's IP address.

My NAS already runs its own Bonjour service

Two discovery services on one machine get in each other's way. Set BONJOUR to 0 and add the server by address. The LumeRecorder README shows how to announce it through the NAS's own service instead.

The pairing code is rejected

Codes change every 10 minutes, so fetch the current one. After five wrong codes, pairing is locked for a minute.

A recording fails while I'm watching

The server opens its own connection to your provider. If your plan allows only one connection at a time, watching and recording at once can fail. Raise your connection limit with your provider or avoid overlapping.

A recording failed for lack of space or too many recordings

Free up disk space or lower MIN_FREE_GB, and raise MAX_CONCURRENT if your provider allows more connections.

What happens if the server restarts?

Recordings that were running resume when it's back, with a short gap. Scheduled ones whose time passed while it was off are marked as failed.

Updating

From the folder with docker-compose.yml, pull the new image and restart. Recordings and pairings stay in the data folder.

docker compose pull && docker compose up -d

Every option, the HTTP API and the source code are in the LumeRecorder repository on GitHub.

← Back to Lume

What you need

Start the server

Get the pairing code

Pair Lume

Record

Settings

Troubleshooting

Updating