TVHomeRun Icon

TVHomeRun

Stream your HDHomeRun DVR content on all your devices

TVHomeRun is a family of apps for managing and streaming content from your HDHomeRun DVR devices. It consists of a backend server that automatically discovers your DVR devices and converts content to streaming-ready formats, plus native applications for all your devices and the web.

With TVHomeRun, you can watch live TV and your recorded shows as well as schedule and manage your recordings. Enjoy your content with quick, responsive, native apps on Apple TV, iPhone, iPad, or any web browser.

Project Components

🖥️

Backend Server

Node.js server that discovers HDHomeRun devices, provides REST APIs, converts recordings to HLS format, and maintains a SQLite database of your content.

Auto-discovery HLS Proxy REST API SQLite
View on GitHub →
📱

iOS App

Native SwiftUI application for iPhone and iPad with touch-optimized interface, grid browsing, video playback with resume support, and progress tracking.

SwiftUI iOS 15+ Resume Playback Touch UI
View on GitHub →
📺

tvOS App

Apple TV application built with SwiftUI, featuring a custom video player with quick skip controls, remote-optimized navigation, and seamless episode transitions.

SwiftUI tvOS 15+ Remote Control Auto-play
View on GitHub →
🌐

Web Interface

Modern web application with responsive design for desktop, tablet, and mobile. Features HLS streaming, keyboard shortcuts, and a tvOS-inspired dark theme.

Vanilla JS Bootstrap 5 HLS.js Responsive
View on GitHub →

FAQ

Why not just use the official HDHomeRun apps?

The official HDHomeRun iPhone, iPad and AppleTV apps are not optimized for responsive playback. TVHomeRun converts HDHomeRun content into HLS streams which are much more suitable for low latency streaming. For example, when skipping forward in the HDHomeRun apps, typically after a short delay the audio will be the first to advance while the video stays frozen for a second or two. While not the end of the world, this makes quickly skipping forwards and backwards to the spot you want very laggy. TVHomeRun works like old TiVo devices which were optimized for fast scrubbing.

Additionally, the HDHomeRun is designed to only work on the local network, making it extremely difficult to work over VPNs or the Internet. With TVHomeRun, only the backend server needs to be on the same network as the HDHomeRun. All other components can be anywhere that the backend server can be reached.

What is required for TVHomeRun to work?

You must at least run tvhomerun-backend and one of the frontend apps. The backend must be on the same local network that the HDHomeRun is on. The frontends such as tvhomerun-ios can be run anywhere that has direct IP connectivity to the backend. Typically, tvhomerun-backend and thhomerun-web are run on a server that stays on all the time. The frontends run on iPhone, iPads, AppleTV and web browsers which may come and go as needed.

tvhomerun-backend requires Node.js and ffmpeg and requires enough disk space to store the streaming cache. tvhomerun-web is also a Node.js application but requires very little disk space. tvhomerun-ios and tvhomerun-tvos are native Swift applications and are available on the App Store.

Quick Start Guide

1

HDHomeRun DVR

Your HDHomeRun device with DVR subscription recording content on your local network.

→
2

Backend Server

Node.js server running on your network (e.g., Raspberry Pi, NAS, or PC).

→
3

Your Devices

Access content from Apple TV, iPhone, iPad, or web browser.

Step 1: Set Up the Backend Server

# Clone the backend repository
git clone https://github.com/anders94/tvhomerun-backend.git
cd tvhomerun-backend

# Install dependencies
npm install

# Start the server (default port 3000)
npm start

Requirements: Node.js v14+ and at least one HDHomeRun device with DVR on your local network. The server will automatically discover your HDHomeRun devices and sync content every hour. Access the API at http://your-server-ip:3000

Step 2: Choose Your Client Application

📺 Apple TV (tvOS)

  1. Clone tvhomerun-tvos repository
  2. Open in Xcode 14.0+
  3. Build and run on your Apple TV
  4. Configure server URL on first launch

📱 iPhone/iPad (iOS)

  1. Clone tvhomerun-ios repository
  2. Open in Xcode 14.0+
  3. Build and install on your device
  4. Enter server URL in settings

🌐 Web Browser

  1. Clone tvhomerun-web repository
  2. Run npm install
  3. Start with npm start
  4. Access at http://localhost:8080

Or configure backend URL: npm start -- --backend http://server-ip:3000

Step 3: Start Streaming

  • Browse your recorded shows with thumbnails and metadata
  • Select any episode to start playback
  • Progress is automatically saved across all devices
  • Episodes auto-play when one finishes

Key Features

🔍

Automatic Discovery

Backend automatically finds HDHomeRun devices using UDP broadcast and network scanning

▶️

Resume Playback

Pick up exactly where you left off on any device

📊

Progress Tracking

Visual indicators show what you've watched and what's new

🎬

HLS Streaming

Native HLS format for smooth playback on Apple devices and browsers

🔄

Auto-sync

Content syncs every hour to keep your library up to date

💾

Offline Database

SQLite database enables browsing even when devices are offline

System Architecture

HDHomeRun DVR

Network device with recorded content

↓

TVHomeRun Backend

Node.js + Express + SQLite

  • Device Discovery
  • Content Indexing
  • HLS Transcoding
  • REST API Server
↓

tvOS App

SwiftUI + AVKit

iOS App

SwiftUI + AVKit

Web App

JavaScript + HLS.js

Technology Stack

Backend

  • Node.js
  • Express.js
  • SQLite
  • UDP/HTTP Protocols

Apple Apps

  • Swift 5.7+
  • SwiftUI
  • AVKit/AVFoundation
  • Combine

Web App

  • Vanilla JavaScript
  • Bootstrap 5
  • HLS.js
  • Express.js

Contributing

TVHomeRun is an open-source project. Contributions, bug reports, and feature requests are welcome on any of the repositories.

Backend → iOS → tvOS → Web →