Raspberry Pi DVR with TVHeadend: TV Tuner Setup and Recording Guide

A Raspberry Pi DVR uses TVHeadend as the recording backend, a USB DVB tuner to receive over-the-air or cable signals, and a USB SSD for recording storage. TVHeadend runs as a server on the Pi and exposes a web interface on port 9981 for channel management, EPG scheduling, and recording rules. Clients including Kodi, Plex, and any IPTV app connect to TVHeadend over the local network to watch live TV and access recordings. This guide covers the hardware, the correct Bookworm-compatible install path for TVHeadend, tuner and EPG configuration, and remote access setup. If the goal is security camera recording rather than TV, see Raspberry Pi RTSP Surveillance Guide for that use case.

Last tested: TVHeadend 4.3 on Raspberry Pi OS Bookworm Lite 64-bit | May 2025 | Raspberry Pi 4 Model B (4GB) | Hauppauge WinTV-dualHD USB DVB-T/T2 tuner, USB SSD (Samsung T7 500GB)

Hardware for a Raspberry Pi DVR

Pi 4 (4GB) is the recommended board for a Raspberry Pi DVR running TVHeadend. It handles two simultaneous stream recordings plus a live view without CPU contention. Pi 5 works and its faster CPU handles transcoding better if Plex DVR is part of the stack. Pi 3B+ is viable for single-stream recording but will struggle with simultaneous record and live stream on a congested network. Pi 2 and Pi Zero are not recommended for DVR use.

Hardware checklist: Raspberry Pi 4 (4GB) or Pi 5. Official 5V/3A USB-C PSU for Pi 4 or 5V/5A for Pi 5. USB DVB-T/T2 tuner with confirmed Linux driver support (Hauppauge WinTV-dualHD, generic RTL2832U-based sticks, or TeVii DVB devices). USB SSD, 500GB minimum for meaningful recording storage. microSD card (16GB) for the OS. Gigabit Ethernet cable. Active cooling recommended for sustained recording loads.

The choice of tuner determines which broadcast standard you can receive. DVB-T/T2 covers over-the-air digital terrestrial TV (Freeview in the UK, TNT in France, Freenet TV in Germany, and similar services across Europe and Australia). DVB-C covers digital cable. DVB-S/S2 covers satellite. Check your local broadcast standard before ordering a tuner. In the US, over-the-air TV uses ATSC rather than DVB; the HDHomeRun series is the most widely supported ATSC tuner for TVHeadend on Pi.

Mount the USB SSD for recording storage before starting the install. Format it as ext4 and add it to /etc/fstab for automatic mount at boot:

sudo mkfs.ext4 /dev/sda1
sudo mkdir -p /mnt/recordings
# Add to /etc/fstab:
UUID=$(blkid -s UUID -o value /dev/sda1)
echo "UUID=$UUID /mnt/recordings ext4 defaults,nofail 0 2" | sudo tee -a /etc/fstab
sudo mount -a

Expected result: df -h /mnt/recordings shows the SSD mounted with its full capacity available. If the mount fails, check dmesg | tail -20 for USB errors. On Pi 4, high-current USB SSDs may need a powered USB hub if the Pi’s USB port cannot supply enough current during spin-up.

Installing TVHeadend on Raspberry Pi

Flash Raspberry Pi OS Bookworm Lite 64-bit using Raspberry Pi Imager. Set hostname, username, SSH, and Ethernet in the Imager advanced settings. After first boot, update the system:

sudo apt update && sudo apt full-upgrade -y

Add the TVHeadend APT repository and install. TVHeadend maintains its own repository at apt.tvheadend.org. The stable branch is stable; the nightly builds are unstable. Use stable for a production DVR:

sudo apt install -y apt-transport-https curl
curl -fsSL https://apt.tvheadend.org/stable/tvheadend.gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/tvheadend.gpg
echo "deb [signed-by=/usr/share/keyrings/tvheadend.gpg] \
  https://apt.tvheadend.org/stable bookworm main" \
  | sudo tee /etc/apt/sources.list.d/tvheadend.list
sudo apt update
sudo apt install -y tvheadend

During installation, the package prompts for an admin username and password. Set these to something you will remember. TVHeadend starts automatically after installation as a systemd service.

Expected result: Navigating to http://[pi-hostname]:9981 from a browser on the same network shows the TVHeadend setup wizard. If the page does not load, check the service status with systemctl status tvheadend. Common install failures include GPG key errors (re-run the key import step) and DNS failures on the Pi during repository fetch (check network connectivity with ping apt.tvheadend.org).

Plug the USB tuner into the Pi before proceeding. TVHeadend detects it on the next configuration step. If the tuner was plugged in before installing TVHeadend, verify it is detected with dmesg | grep -i dvb. A successfully detected tuner shows adapter initialisation messages.

Configuring TVHeadend: Tuners, EPG, and Recording

Open the TVHeadend web interface at http://[pi-hostname]:9981 and log in with the credentials set during install. The first-run wizard appears and walks through tuner detection, network assignment, and initial channel scan.

Tuner configuration: Navigate to Configuration > DVB Inputs > TV Adapters. The USB tuner appears here. Enable it and assign it to a network. For DVB-T/T2, create a network under Configuration > DVB Inputs > Networks, select the correct pre-defined mux list for your country and region, and save. TVHeadend uses mux lists to know which frequencies to scan.

Run a channel scan: in the Networks page, click the scan button next to your network. TVHeadend tunes each mux and decodes the service list. Scan time varies by region and tuner. Expect 2 to 10 minutes for a full DVB-T scan. When complete, navigate to Configuration > Channel/EPG > Channels to see the discovered channels. Map them to services using the service list if they did not auto-map.

EPG (Electronic Programme Guide): TVHeadend receives EPG data from the broadcast signal itself via DVB EIT (Event Information Table). Enable EIT grabbing in Configuration > Channel/EPG > EPG Grabber Modules by enabling the “OTA” (over the air) grabber. The EPG populates automatically during the next scan or within a few hours of the tuner being active. For regions where broadcast EPG is sparse, the WebGrab+Plus external grabber integrates with TVHeadend and pulls EPG from online sources.

Recording configuration: Navigate to Configuration > Recording. Set the recording path to /mnt/recordings (the USB SSD mount point). Set the file naming format to include date and program title. Configure the pre-roll and post-roll padding (typically 2-5 minutes before and after the scheduled time) to account for schedule overruns.

Schedule a recording: open the EPG view, find a programme, and click the record button. TVHeadend creates a timer entry and records the programme at the scheduled time. Completed recordings appear in Digital Video Recorder > Finished Recordings and are accessible as files in /mnt/recordings.

Expected result: The EPG shows programme listings for all configured channels. Clicking record on a programme creates a pending timer. After the programme airs, the recording appears in Finished Recordings. If the recording is empty or zero bytes, check the tuner signal strength in the TV Adapters page during the recording window. A signal quality below 50% will produce intermittent or failed recordings.

Remote Access and Client Apps for Raspberry Pi DVR

TVHeadend is a server application. Clients connect to it over the network. The built-in web interface at port 9981 is accessible from any browser. For a better playback experience, several dedicated clients integrate with TVHeadend directly.

Kodi is the most capable TVHeadend client. Install the PVR TVHeadend HTSP Client addon in Kodi, enter the Pi’s IP address and TVHeadend credentials, and Kodi gains full live TV, EPG, and recording management. This turns any TV with a Kodi device into a full DVR client. Kodi can run on a second Pi, a Fire TV stick with Kodi installed, or any Android or Windows machine on the network.

IPTV Simple Client in Kodi provides a lighter integration if only live stream playback is needed rather than full EPG and recording management. TVHeadend exposes an M3U playlist URL at http://[pi]:9981/playlist that IPTV Simple consumes.

Plex DVR integrates with TVHeadend via the HDHomeRun emulation mode. Enable the HDHomeRun emulator in TVHeadend’s configuration, then add the Pi as a tuner in Plex’s live TV setup. This routes live TV through Plex’s interface and allows Plex to handle the recording schedule. The full TVHeadend IPTV server setup with Kodi integration is covered in Raspberry Pi IPTV Server: Complete TVHeadend Setup Guide.

For secure remote access to the TVHeadend interface from outside the home network, Tailscale is the correct approach. It provides authenticated mesh VPN access without opening ports on the router. See Tailscale Raspberry Pi: Complete Secure Remote Access Guide. Do not expose TVHeadend’s port 9981 directly to the internet without authentication; the default configuration has no rate limiting on login attempts.

Secure the Pi itself with UFW and SSH key authentication:

sudo apt install -y ufw
sudo ufw allow from 192.168.1.0/24 to any port 9981
sudo ufw limit ssh
sudo ufw enable

# Generate SSH key on local machine, then:
ssh-copy-id youruser@pi-hostname

Expected result: TVHeadend port 9981 is accessible from local network devices. SSH accepts key authentication. The UFW status shows both rules active. External access to port 9981 is blocked, accessible only via Tailscale or SSH tunnel.

Troubleshooting a Raspberry Pi DVR

TVHeadend service fails to start. Check journalctl -u tvheadend -n 50 for the error. Common causes: port 9981 already in use (check with sudo ss -tlnp | grep 9981), corrupt database (the TVHeadend database lives in /home/hts/.hts/tvheadend. If it is corrupt from a power loss during write, delete the folder and reconfigure from scratch), or insufficient permissions on the recording directory (run sudo chown -R hts:video /mnt/recordings).

Tuner not detected. Run dmesg | grep -i dvb immediately after plugging in the tuner. If nothing appears, the tuner is not recognised. Check that the firmware for the tuner is installed: sudo apt install -y linux-firmware covers most common DVB tuner firmware blobs. If the tuner still does not appear, check the manufacturer’s Linux compatibility page. Some tuners require custom firmware not in the standard linux-firmware package.

Poor signal quality or missing channels. In TVHeadend’s TV Adapters page, check the signal strength and SNR values while the tuner is active. For DVB-T, signal quality below 70% typically means antenna positioning or cable quality issues. A directional external antenna pointed at the transmitter dramatically improves DVB-T reception compared to a basic indoor loop. Check the Ofcom signal checker (UK), RTE signal checker (Ireland), or equivalent national authority tool for your transmitter direction before positioning the antenna.

Recordings fail or are corrupt. Check available space on the USB SSD with df -h /mnt/recordings. A full disk causes immediate recording failure. Check USB bus errors with dmesg | grep -i error | tail -20. On Pi 4, high-current USB SSDs occasionally disconnect under sustained write load if the USB port cannot supply enough current. Use a powered USB hub. Verify the SSD is mounted with mount | grep recordings; if it is not mounted the recording path resolves to the OS SD card, which fills up quickly.

EPG not populating. The DVB EIT grabber requires the tuner to be actively tuned to a mux to receive EPG data. Run a manual EPG scan in Configuration > Channel/EPG > EPG Grabber and watch the grabber log for output. If EIT data is not received, the broadcaster may not transmit full EPG data via DVB EIT, which is common in some regions. Install WebGrab+Plus as an alternative XML EPG source and configure TVHeadend to consume its XMLTV output.

FAQ

What TV tuner works best with a Raspberry Pi DVR and TVHeadend?

For DVB-T/T2 (Europe, Australia, Asia): the Hauppauge WinTV-dualHD has two tuners in one USB stick, allowing simultaneous recording of two channels or recording one while watching another live. The generic RTL2832U-based sticks (sold as “RTL-SDR” or “DVB-T sticks”) work but vary in quality. For ATSC (North America): the HDHomeRun Connect Quatro is the most widely supported option with TVHeadend and handles four simultaneous streams. Verify the specific tuner model on the LinuxTV DVB compatibility list at linuxtv.org before purchasing.

How much storage does a Raspberry Pi DVR need?

A standard-definition DVB-T recording uses approximately 1-2 GB per hour. An HD recording uses 3-6 GB per hour depending on the channel’s broadcast bitrate. A 500GB USB SSD holds roughly 80-100 hours of HD recordings. For a household that records several hours per week, 1TB is a comfortable starting point. TVHeadend can automatically delete oldest recordings when disk usage exceeds a configurable threshold. Set this in Configuration > Recording > Digital Video Recorder Profiles to prevent the disk from filling completely.

Can a Raspberry Pi DVR record two channels simultaneously?

Yes, if the tuner supports it or multiple tuners are connected. The Hauppauge WinTV-dualHD has two independent tuners in one USB device, enabling two simultaneous recordings from different muxes. A single-tuner DVB stick can record two channels simultaneously only if both channels are broadcast on the same mux (same frequency), because the tuner only needs to tune to one mux. TVHeadend handles mux sharing automatically. For three or more simultaneous recordings, use a multi-tuner device or connect multiple USB tuners.

What is the difference between a Raspberry Pi DVR and a Raspberry Pi NVR?

A DVR (Digital Video Recorder) records broadcast TV signals received through a TV tuner. TVHeadend is the standard Pi DVR software. An NVR (Network Video Recorder) records video from IP cameras over the network. Frigate and motionEye are the current Pi NVR options. They are architecturally different: a DVR needs a broadcast tuner and receives MPEG transport streams from the air or cable. An NVR needs IP cameras and records RTSP streams over the local network. If the goal is security camera recording rather than TV, the correct guide is the Raspberry Pi RTSP Surveillance Guide.

Can I watch Raspberry Pi DVR recordings on my phone or TV?

Yes. TVHeadend recordings are stored as standard MPEG-TS or MKV files on the USB SSD. They are accessible directly via the file system over SMB (Samba) or via the TVHeadend web interface’s stream URL. Kodi with the TVHeadend HTSP addon provides the most integrated experience on any device that runs Kodi. For phone access, the Tvhguide app (Android) and Kodi on iOS connect to TVHeadend directly. Plex can also serve the recordings folder as a media library if Plex Media Server is installed alongside TVHeadend on the same Pi.

References:

• TVHeadend documentation: tvheadend.org/projects/tvheadend/wiki
• TVHeadend APT repository: apt.tvheadend.org
• LinuxTV DVB compatibility list: linuxtv.org/wiki/index.php/DVB_USB
• WebGrab+Plus XMLTV guide: webgrabplus.com
• Raspberry Pi Imager: raspberrypi.com/software

---

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 4 Model B (4GB), Hauppauge WinTV-dualHD, Samsung T7 500GB USB SSD. Last tested OS: Raspberry Pi OS Bookworm Lite 64-bit. TVHeadend 4.3.