A multi-channel live streaming platform with automated scheduling, Discord integration, and protected video archive. Built on top of Datarhei Restreamer for video processing.

• Multi-Channel Scheduling - Schedule streams by hour with priority-based automatic switching
• Automatic Fallback - Falls back to nearest scheduled stream when current ends
• Discord Bot Integration - Live notifications, EPG commands, and stream control
• Protected Video Archive - HMAC-based timecode authentication for secure access
• Mux Service - Seamless stream multiplexer with adaptive bitrate output and crash recovery
• HLS Adaptive Streaming - Quality selection via HLS.js with Plyr player and automatic error recovery
• Automated SSL - Let's Encrypt certificates via acme.sh
• Cloudflare Compatible - Proper handling of CF-Connecting-IP headers
• HTTP/2 Support - ALPN negotiation for modern clients

                                    ┌──────────────┐
                                    │   Internet   │
                                    └──────┬───────┘
                                           │
                                    ┌──────▼───────┐
                                    │   HAProxy    │ :80, :443 (HTTP/2)
                                    │ SSL/Routing  │
                                    └──────┬───────┘
              ┌────────────────────────────┼────────────────────────────┐
              │                            │                            │
              │ example.com                │ example.com                │ stream.example.com
              │ /                          │ /live/*                    │
              │                            │                            │
       ┌──────▼──────┐              ┌──────▼──────┐              ┌──────▼──────┐
       │  Quart API  │◄────SSE──────│     Mux     │              │  Restreamer │
       │   :8080     │   /events    │    :8091    │              │   (:8080)   │
       │             │              │             │              │    :1935    │
       │ - Web UI    │              │ - ABR HLS   │◄────HLS──────│    :6000    │
       │ - SSE       │              │ - 720p/576p │              │             │
       │ - Schedule  │              │ - Playhead  │              │ - Ingest    │
       │ - Discord   │              │   switching │              │ - Transcode │
       │ - Archive   │              │             │              │ - HLS out   │
       └─────────────┘              └─────────────┘              └─────────────┘

**Data Flow:**
1. **Ingest** → Streamers push to Restreamer via SRT/RTMP
2. **Restreamer** → Ingests live streams, transcodes, outputs unified HLS
3. **Scheduling** → API tracks schedule, broadcasts playhead via SSE
4. **Muxing** → Mux service follows playhead, switches Restreamer HLS inputs, outputs ABR stream
5. **Delivery** → HAProxy routes requests, terminates SSL, serves to viewers

## Tech Stack

| Component | Technology |
|-----------|------------|
| Backend | Python 3.13, Quart (async Flask) |
| Frontend | Bootstrap 5, Plyr.js, HLS.js |
| Streaming | Datarhei Restreamer 2.12 |
| Mux | FFmpeg ABR (720p + 576p) |
| Proxy | HAProxy (HTTP/2, health checks) |
| ASGI Server | Uvicorn |
| Containerization | Docker Compose |
| SSL | acme.sh (Let's Encrypt) |

## Installation

### Prerequisites

- Docker and Docker Compose
- A domain name pointing to your server
- (Optional) Cloudflare for CDN/proxy

### Quick Start

1. **Clone and configure environment**

   ```bash
   git clone <repository-url>
   cd television
   cp variables.env.dist variables.env

Edit variables.env and set all required variables (see Configuration).

2. Initialize data directories

   ./init.sh

3. Start the acme.sh service

   docker-compose up -d acme-sh

4. Register ACME account

   source variables.env
   docker exec acme.sh --register-account -m $EMAIL

   Copy the ACCOUNT_THUMBPRINT from the output and add it to variables.env.

5. Start the stack

   docker-compose up -d --build --remove-orphans

6. Issue SSL certificates

   source variables.env
   docker exec acme.sh --issue -d $SERVER_NAME --stateless
   docker exec acme.sh --issue -d $CORE_API_HOSTNAME --stateless

7. Install certificates

   source variables.env
   docker exec acme.sh --install-cert -d $SERVER_NAME \
     --reloadcmd "cat \$CERT_KEY_PATH \$CERT_FULLCHAIN_PATH > /certificates/$SERVER_NAME.pem"
   docker exec acme.sh --install-cert -d $CORE_API_HOSTNAME \
     --reloadcmd "cat \$CERT_KEY_PATH \$CERT_FULLCHAIN_PATH > /certificates/$CORE_API_HOSTNAME.pem"

8. Reload HAProxy

   docker kill -s USR2 haproxy

9. Set up automatic certificate renewal

   Add to crontab:

   0 0 1 * * docker exec acme.sh --cron && docker kill -s USR2 haproxy

ABR_VARIANTS format:

[
  {"height": 720, "video_bitrate": "2800k", "audio_bitrate": "128k"},
  {"height": 576, "video_bitrate": "1400k", "audio_bitrate": "96k"}
]

Each variant specifies a resolution height (source is capped at this), video bitrate, and audio bitrate. Source stream (copy) is always included as stream_0.

Stream multiplexer that monitors the API's playhead and outputs a continuous stream from Restreamer channels.

Features:

• SSE monitoring - Listens to /events for playhead changes
• Seamless switching - Continuous segment numbering with #EXT-X-DISCONTINUITY markers across playhead transitions. Players stay connected without reloading.
• Crash recovery - Automatic recovery with discontinuity markers on ffmpeg crashes. No full resets that break clients.
• Internal routing - Direct container-to-container access bypasses Cloudflare for optimal performance
• Two modes - Copy (passthrough) or ABR (adaptive bitrate)
• No upscaling - ABR mode caps output at source resolution
• Stale segment cleanup - Background cleanup of old .ts segments to prevent disk filling
• Modular architecture - Separated concerns: config, ffmpeg runner, segment store, stream management, playhead monitoring

Modes (set via MUX_MODE env var):

Copy mode output:

• /live/stream.m3u8 - Single quality stream (passthrough)

ABR mode output:

• /live/stream.m3u8 - Master playlist (ABR)
• /live/stream_0/ - Source (passthrough, no re-encoding)
• /live/stream_1/ - 720p (2800k video, 128k audio) - only if source > 720p
• /live/stream_2/ - 576p (1400k video, 96k audio) - only if source > 576p

Switching behavior:

• On playhead change: segments continue numbering, #EXT-X-DISCONTINUITY tag injected, ffmpeg restarts with new input (~4s gap)
• On crash: seamless recovery with discontinuity marker, segment numbering continues (no viewer disruption)

Frontend Features:

• Automatic error recovery - HLS.js detects network/media errors and automatically recovers
• Global modals - Weather and Archive modals accessible from all pages
• SSE real-time updates - Live visitor count, EPG changes, playhead updates
• Responsive design - Mobile-friendly Bootstrap 5 interface

1. Access the Restreamer admin panel at https://stream.example.com/ui

2. Create channels and configure them with JSON metadata in the Description field:

   { "start_at": "2100", "prio": 0, "details": "Evening show" }

   Field	Description
   start_at	Military time e.g. "1745" (HH:MM), "now" for immediate, or "never" to disable
   prio	Priority level (higher takes precedence)
   details	Optional description for Discord announcements

SRT (recommended):

srt://SERVERADDR:6000?mode=caller&transtype=live&pkt_size=1316&streamid=STREAM-UUID.stream,mode:publish,token:CHANGEME

RTMP:

rtmp://SERVERADDR/STREAM-UUID.stream/CHANGEME

1. Use .streams to list all available Restreamer processes with their names, IDs, and current state (running/stopped)
2. Use .start <name or id> to start a specific process (name matching is case-insensitive)
3. Use .stop <name or id> to stop it
4. Use .rnd to switch to a random stream (excludes the currently playing one)

To reduce noise in logs, successful (200 OK) responses are filtered from access logs:

API Service (api/main.py):

• All 200 OK and 404 Not Found responses are hidden from uvicorn/hypercorn access logs
• Only other status codes (3xx, 4xx, 5xx) appear in logs

Mux Service (mux/app/server.py):

• 200 OK responses for /health and .m3u8 playlist requests are hidden
• Segment requests (.ts) and errors still appear in logs

Visitor Tracking:

• Private/internal IP addresses (Docker, LAN, loopback) are excluded from visitor counts
• Prevents internal services from appearing as watchers

Configure granular logging via environment variables:

television/
├── api/
│   ├── static/                  # CSS, JS, images
│   ├── templates/
│   │   ├── base.html            # Base template with modals
│   │   ├── index_mux.html       # Mux mode template
│   ├── main.py                  # Application entry point
│   ├── services/                # Core/backend service layer
│   │   ├── core_api.py          # Restreamer Core API client
│   │   └── stream_manager.py    # Stream orchestration
│   ├── integrations/
│   │   └── discord_bot_manager.py
│   ├── web/                     # HTTP route layer
│   │   ├── frontend_routes.py
│   │   ├── api_routes.py
│   │   ├── playlist_routes.py
│   │   ├── sse_routes.py
│   │   └── ingest_routes.py
│   ├── utils/
│   │   └── obfuscation.py       # Hostname obfuscation
│   ├── Dockerfile
│   └── requirements.txt
├── mux/
│   ├── app/
│   │   ├── main.py              # Application orchestration
│   │   ├── config.py            # Configuration management
│   │   ├── ffmpeg_runner.py     # FFmpeg process lifecycle
│   │   ├── segment_store.py     # HLS segment & playlist management
│   │   ├── stream_manager.py    # Stream switching logic
│   │   ├── playhead_monitor.py  # SSE monitoring
│   │   ├── hls_viewer_tracker.py # HLS viewer counting
│   │   ├── server.py            # HTTP server for HLS output
│   │   └── utils.py             # Utility functions
│   ├── scripts/
│   │   └── run.sh
│   ├── Dockerfile
│   └── requirements.txt
├── haproxy/
│   ├── haproxy.cfg
│   └── Dockerfile
├── data/                        # Runtime data (gitignored)
│   ├── acme/                    # ACME certificates data
│   ├── certificates/
│   ├── restreamer/
│   ├── recorder/                # Recorder channel files (vod/, thumb/)
├── docker-compose.yml
├── variables.env.dist
└── init.sh

MIT License