HD Homey

A secure web proxy for HDHomeRun devices that enables remote access to your live TV streams over the internet.

Stream live TV from your HDHomeRun devices anywhere with secure authentication, role-based access control, and real-time video transcoding.

📚 Read the full documentation →

Repository Structure

HD Homey uses a monorepo structure with npm workspaces:

hd-homey/
├── apps/
│   ├── web/          # Main Next.js application
│   │   ├── migrations/  # Database migrations
│   │   ├── src/         # Source code
│   │   └── public/      # Static assets
│   ├── docs/         # VitePress documentation site
│   └── android/      # Android app (coming soon)
├── .specify/         # Specifications and constitution
└── specs/            # Implementation plans

Quick Start

# Download configuration files
curl -O https://raw.githubusercontent.com/shaunburdick/hd-homey/main/compose.yml
curl -O https://raw.githubusercontent.com/shaunburdick/hd-homey/main/.env-example

# Configure environment
cp .env-example .env
# Edit .env and set AUTH_SECRET (generate with: openssl rand -base64 32)

# Start the application
docker compose up -d

Access HD Homey at http://localhost:3000 and create your first admin account.

📖 Full Installation Guide

Features

• 📺 Tuner Management - Add and configure multiple HDHomeRun devices with automatic channel scanning
• 🎬 Live Streaming - Watch in your browser or external players with secure token-based authentication
• 🔄 Video Transcoding - Real-time MPEG-2 to H.264/HLS conversion with shared session management
• 👥 User Management - Role-based access control with admin and viewer roles
• 🔐 Secure Authentication - Better-Auth powered with scrypt password hashing and JWT sessions
• ⚙️ Easy Configuration - Simple environment variables with Docker Compose support

📖 View All Features

Documentation

The complete documentation is available at shaunburdick.github.io/hd-homey with guides for:

• Installation - Docker Compose, Docker Run, and source installation
• Quick Start - Get up and running in 5 minutes
• Configuration - Environment variables and settings
• Features - Detailed feature documentation
• Troubleshooting - Common issues and solutions
• API Reference - HDHomeRun lineup API compatibility

Support

• 📖 Documentation: shaunburdick.github.io/hd-homey
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Contributing

Contributions are welcome! See the Contributing Guide for details.

Tech Stack: Next.js 16, React 19, TypeScript 5, SQLite, Better-Auth, FFmpeg

For Developers:

• Review AGENTS.md for development guidelines
• Check CHANGELOG.md for recent changes
• Follow the spec-driven development process (see .specs/)
• Ensure tests pass: npm test

License

AGPL-3.0-only - See LICENSE file for details

Acknowledgments

• Built for HDHomeRun devices by SiliconDust
• Powered by Next.js and Better-Auth