Open-source · local-first · self-hosted

Make your Linux box the TV.

RelayTV plays media on a Linux device connected over HDMI. Your phone, browser, media server, Home Assistant, and automations simply tell it what to do.

amd64 + arm64DockerNo app telemetryGPL-3.0

Not a casting app. RelayTV is the player connected to the display—not an app running inside your existing smart TV.

Star on GitHubFollow releases and support RelayTV—
Living room online
RelayTV idle screen on a television with phone remote and library views
Playback stays on your hardware
How it works

The endpoint your self-hosted stack was missing.

Media and control stay modular. RelayTV owns playback beside the screen while the services you already run remain in charge of their own jobs.

01
Sources & Control SurfacesKeep existing servers & remotes modular
Media & Discovery
Plex / Jellyfin / EmbyUnified or per-server library browse
SeerrDiscovery & media requests
IPTV / URLs / UploadsYouTube playlists, M3U DVR & files
Remotes & Automation
Android / Web RemoteShare targets, QR & browser control
Home Assistant & HTTP APImedia_player, overlays & scripts
02
RelayTV EndpointDedicated Linux host beside the display
Docker · amd64 / arm64RelayTVLinux playback endpoint
mpv + GPU decodeDirect DRM / audio output
Durable queueSQLite state & history
Browse & DVR proxyServer keys stay on host
Native Qt overlaysIdle QR, toasts & alerts
Owns the session — phones can lock or leave
03
Your TVDirectly attached screen
Appliance-grade television outputNo smart-TV apps, vendor accounts, or cloud coordinator
Local-first execution: queueing, decoding, and overlays stay on your LAN.
Credential boundary: Plex, Jellyfin, Emby, and Seerr tokens remain on the host.
Interrupt & resume: automations can overlay or play a clip, then restore the queue.
One endpoint, four jobs

Built around what happens in the room.

Browse from the couch, queue from a phone, automate an interruption, then let the box keep playing without a cloud coordinator.

Explore every feature →
01

Play

Turn URLs, YouTube playlists, and local audio or video into durable playback, with queue advancement and history owned by the endpoint.

  • mpv playback
  • YouTube playlists
  • Persistent queue
  • Local uploads
  • TV notifications
02

Browse

Use a unified or individual library to explore what you host, resume playback, request what is missing, or curate live channels.

  • Unified Browse
  • Plex
  • Jellyfin
  • Emby
  • Seerr
  • IPTV / M3U
03

Control

Scan the TV's QR code or use Android to control playback, rewind cached live streams, and manage the shared queue without TV menus.

  • QR & web remote
  • Android sharing
  • Live DVR rewind
  • Multiple screens
04

Automate

Make the screen part of the house with media-player controls, temporary playback, overlays, snapshots, and synchronized starts.

  • Home Assistant
  • HTTP API
  • Overlays
  • Synced playback
Real workflows

From intent to the TV, without taking it over.

These are captures from a running RelayTV—not conceptual mockups.

Android share sheet with RelayTV Play and RelayTV Queue targets
Share → queue → TV

Send it from wherever you found it.

Share a video, YouTube playlist, or local file to Play or Queue in Android. RelayTV takes over and confirms the action on screen.

Jellyfin Continue Watching and Next Up rails in RelayTV
Browse → resume → play

Your library stays connected.

Browse Plex, Jellyfin, or Emby from a phone—together or individually—then resume or queue the title on the television.

RelayTV device and media controls in Home Assistant
Event → action → resume

The screen becomes part of the home.

Automate an overlay or temporary clip, then continue what was already playing.

Operator reality

Know what fits before you install.

RelayTV is intentionally opinionated about where playback runs and equally clear about the network boundary around it.

Full compatibility matrix →

Hardware and runtime

A 64-bit Linux host connects directly to the display. Runtime behavior depends on the graphics session and devices the host exposes.

  • amd64 or arm64
  • Wayland, X11, DRM/KMS
  • Optional GPU via /dev/dri
  • Optional HDMI-CEC

Network and privacy

Core playback has no RelayTV account or cloud control plane. Treat the API like any other capable service on your network.

  • Trusted LAN by default
  • Optional bearer token
  • VPN or protected proxy remotely
  • No app telemetry
Ready when your hardware is

Install in minutes. Understand every step.

Run the installer on a supported 64-bit Linux device connected to your TV. It can install Docker with your approval, then deploys RelayTV's published image.

relaytv · install
mkdir -p ~/relaytv
cd ~/relaytv
curl -fsSL https://relaytv.app/install.sh | bash

Then scan the QR code on the TV's idle screen or open http://YOUR_RELAYTV_HOST:8787/ui.

Before you begin

Questions worth answering upfront.

Does RelayTV cast to a smart TV or streaming stick?

No. RelayTV runs on the Linux host connected to the TV and renders playback there. If you need an app inside an existing smart TV or Chromecast-style receiver, RelayTV is not that.

What hardware do I need?

A 64-bit amd64 or arm64 Linux host connected to the display. Mini PCs, NUCs, HTPCs, and capable Raspberry Pi-class devices can fit; display, codec, GPU, audio, and CEC results still depend on the hardware and runtime profile.

Can I expose RelayTV to the internet?

It is designed for a trusted LAN. For remote access, use a VPN or authenticated reverse proxy and enable the optional RelayTV API token. Do not expose an unauthenticated API directly.

Is it free and open source?

Yes. RelayTV and its companion projects are GPL-3.0 licensed, have no paid tier, and require no RelayTV account for core playback.