GrandSlam

HDHomeRun Web Streaming System - Watch your HDHomeRun channels from any browser with adaptive bitrate streaming.

Features

• Auto-discovery of HDHomeRun devices on your network
• Multi-bitrate HLS transcoding (480p / 720p / 1080p)
• Adaptive streaming - quality adjusts to your bandwidth
• Responsive web UI - works on desktop and mobile
• Session management - shared streams, automatic cleanup
• Kubernetes ready - includes manifests for k8s deployment

Requirements

• Python 3.11+
• FFmpeg (for transcoding)
• HDHomeRun device on local network

Quick Start

# Clone the repo
git clone https://github.com/RustyBower/GrandSlam.git
cd grandslam

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install
pip install -e .

# Configure (set your HDHomeRun IP)
cp .env.example .env
# Edit .env with your HDHR_HOST

# Run
uvicorn grandslam.main:app --reload

Open http://localhost:8000 and click a channel to start streaming.

Docker

# Build
docker build -t grandslam .

# Run
docker run -p 8000:8000 -e HDHR_HOST=10.0.10.49 grandslam

Kubernetes Deployment

Container images are automatically built and pushed to ghcr.io/rustybower/grandslam on every push.

# Deploy using the GHCR image
kubectl create namespace grandslam
kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: grandslam
  namespace: grandslam
spec:
  replicas: 1
  selector:
    matchLabels:
      app: grandslam
  template:
    metadata:
      labels:
        app: grandslam
    spec:
      containers:
      - name: grandslam
        image: ghcr.io/rustybower/grandslam:master
        ports:
        - containerPort: 8000
        env:
        - name: HDHR_HOST
          value: "YOUR_HDHR_IP"
EOF

Configuration

Variable	Default	Description
HDHR_HOST	hdhomerun.local	HDHomeRun device hostname/IP
MAX_STREAMS	4	Max concurrent streams (match tuner count)
SESSION_TIMEOUT	30	Seconds before idle stream cleanup
HLS_OUTPUT_DIR	data/streams	HLS segment output directory

API Endpoints

Method	Endpoint	Description
GET	/api/devices	List HDHomeRun devices
GET	/api/channels	List available channels
POST	/api/streams	Start a stream
POST	/api/streams/{id}/heartbeat	Keep stream alive
DELETE	/api/streams/{id}	Stop a stream
GET	/hls/{id}/master.m3u8	HLS master playlist
GET	/health	Health check

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Browser   │────▶│  GrandSlam  │────▶│  HDHomeRun  │
│   (hls.js)  │◀────│  (FastAPI)  │◀────│   Device    │
└─────────────┘     └─────────────┘     └─────────────┘
                          │
                          ▼
                    ┌─────────────┐
                    │   FFmpeg    │
                    │ (transcode) │
                    └─────────────┘

License

MIT