Skip to content
mcgeezyPublic

About

Turn a Linux box connected to your TV into a self-hosted, local-first media hub. Play web videos, browse Plex, Jellyfin, or Emby, and rewind live TV—all from your phone, with Home Assistant automation built in.

Topics

Resources

Stars

99 stars

Watchers

1 watching

Forks

Repository files navigation

RelayTV

Your media, on your TV.

Turn a Linux box connected to your TV into a self-hosted, local-first media hub. Browse your libraries, send videos to the TV, and control playback from your phone or desktop browser. When you're watching with family or friends, they can scan the TV's QR code to browse and add their picks to the queue too.

Install RelayTV · Explore integrations · Read the docs

Build status Published on GitHub Container Registry Home Assistant integration Android companion app

RelayTV controlling a living-room TV from modern phone interfaces

Local-first · No RelayTV account · No app telemetry · No cloud dependency for core playback

Your libraries, links, and live TV in one place

RelayTV brings Plex, Jellyfin, Emby, Seerr, web videos, and live channels into one web interface. Pick up a series, queue videos for the evening, or tune in to a favorite channel from the same remote. Whether you're watching on your own or choosing something together, your connected media is easy to browse from a phone or desktop.

  1. Connect your services once. Set up the libraries, live sources, and optional Seerr requests you want to use in RelayTV.
  2. Open your remote. Scan the TV's QR code or open the Web UI in a browser on the same local network. No RelayTV account or companion app is needed.
  3. Choose what happens next. Browse a library, play something on the TV, add a pick to the shared queue, or request a movie or series through Seerr when requests are enabled.

For a shared viewing session, family and friends can open the same remote on their phones to browse, control playback, and add to the queue.

The QR code opens this TV's RelayTV interface. Available media comes from your configured services and accounts. Seerr can use shared requests or require individual sign-in, depending on your setup; if you enable RelayTV's optional API token, anyone using the remote needs that token to control playback.

Play. Browse. Control. Automate.

▶️ Play

Paste a media URL into the Web UI, share a link or local audio/video file from Android, or upload media through Home Assistant. Play now, add to the queue, or resume something from history. Playback runs on the Linux box, so your phone can leave the remote page while the TV keeps playing. Temporary playback can interrupt a session and resume it afterward.

🎬 Browse

Explore Plex, Jellyfin, or Emby from a responsive library built for phones and desktops. Search for a movie, browse seasons and episodes, then play now or add to the queue. Connect Seerr to discover movies and series, request something missing, and follow its request status. Add IPTV playlists, curate My Channels, and favorite the live sources you use.

🎛️ Control

Scan the QR code on the TV's idle screen or open the Web UI from a browser. Control playback, volume, and the shared queue from your phone. For live streams with a seekable buffer, rewind within the cached window and jump back to live. The Android app adds separate Play and Queue share targets, native media controls, mDNS discovery, and profiles for multiple RelayTV screens. RelayTV devices can also send a queue or active playback to one another on the local network.

To queue a YouTube playlist, open Link, paste its URL, and choose Add entire playlist. Videos are added in playlist order while current playback continues. A video link with playlist context also offers the usual Play and Queue actions for that individual video. Import status and cancellation stay available in the Link dialog, including after a reload. Finite playlists support up to 1,000 videos; private lists need configured YouTube cookies, and unavailable entries are reported when they can be detected.

Sharing a YouTube playlist through Android's Queue or Play target also imports it automatically, including video links containing a finite playlist ID (while video links inside a dynamic YouTube Mix still play or queue that individual video). Queue appends during playback or paused playback; when idle it starts the first video and queues the rest. Play starts the first video and puts the rest ahead of the interrupted video's resume entry and existing queue. Existing phone builds can use this server behavior without an app update.

🏠 Automate

Make every screen a Home Assistant media_player, or use the local HTTP API from scripts, dashboards, services, and agent workflows. Smart play, temporary media, overlays, snapshots, direct uploads, and synchronized multi-screen starts all keep the playback engine beside the TV.

See it in action

RelayTV phone remote with now playing controls and queue RelayTV Jellyfin series page and season browser on a phone

Everything you need from the couch

Play, pause, seek, change volume, manage the queue, resume history, and send something new without taking over the television UI.

Your library, ready to browse

Search your connected library, explore series and seasons, and play or queue a pick from the phone. Shown here: the Jellyfin/Emby browser.
RelayTV My Channels IPTV page with favorites and live channels on a phone

Live TV, curated the way you watch

Add M3U playlists or pick from the free-provider directory, then build a My Channels list, pin favorites to the top, and send a live channel to the TV — all from the same phone remote. Rewind within the available stream buffer, then jump back to live.

RelayTV living-room idle dashboard on a television

The TV keeps playing. Your phone is the remote.

RelayTV runs on the Linux device connected to the display. It owns playback, queue advancement, history, overlays, and the idle dashboard locally, while companion apps and automations remain optional ways to control it.

See the product overview for the complete system model and real cross-device workflows.

Install in minutes

RelayTV is built for 64-bit Raspberry Pi-class devices (with dedicated Pi 4 and Pi 5 hardware profiles), Intel mini PCs, NUCs, HTPCs, and other amd64 or arm64 Linux hosts connected directly to a television. The installer can set up Docker with your approval when needed.

mkdir -p ~/relaytv
cd ~/relaytv
curl -fsSL https://raw.githubusercontent.com/mcgeezy/relaytv/main/install.sh | bash

Then scan the QR code on the TV's idle screen, or open http://YOUR_RELAYTV_HOST:8787/ui from a phone or desktop browser on the same network. Open Settings to connect your media services, then browse your libraries or send a video to the TV. The same QR code lets family and friends join in when you're watching together.

Need runtime choices, hardware notes, or an existing source checkout? See the complete installation guide, or follow the public getting-started path.

Made for the stack you already own

  • Home Assistant — entities, services, automations, and dashboard workflows.
  • RelayTV for Android — share links directly to the TV and control playback from your phone.
  • YouTube and Web Video — send a video link to the TV, watch live streams, and queue videos from supported sites.
  • Plex — secure account linking and server selection, responsive Home, Movies, TV, search, season and episode browsing, media and track choices, resume, queue, direct-play, and transcoding workflows.
  • Jellyfin and Emby — responsive Home, Movies, TV, series, season, episode, search, resume, and queue workflows.
  • Seerr — discover movies and series, request missing titles, and track requests. Play available Jellyfin items when RelayTV can match them to your connected library. Choose shared requests or individual sign-in.
  • IPTV / M3U — opt-in live sources, curated My Channels, favorites, and availability checks, with rewind and return-to-live controls when the stream has a seekable cache. The rewind window is limited to the buffered media; this does not record shows for later.
  • HTTP API — local automation from shell scripts, dashboards, services, and custom applications.

The core server does not require a RelayTV cloud account. It is designed for a trusted LAN; use a VPN or authenticated reverse proxy rather than exposing the API directly to the public internet. An optional RELAYTV_API_TOKEN can protect control and mutating requests with bearer authentication on shared networks.

For operators and developers

Start here Reference
Installation HTTP API
Native runtime operations Jellyfin/Emby operations
Plex operations IPTV operations
Seerr operations Device sync operations
Architecture Release process
Public documentation Documentation map

The documentation map links the remaining runbooks and machine-checked inventories.

Project and support

RelayTV is open-source software licensed under the GNU General Public License v3.0. RelayTV artwork and marks are covered by the asset and trademark policy.

If RelayTV makes your living-room setup better, you can help by starring the repository, sharing it with another self-hoster, or supporting development.

About

Turn a Linux box connected to your TV into a self-hosted, local-first media hub. Play web videos, browse Plex, Jellyfin, or Emby, and rewind live TV—all from your phone, with Home Assistant automation built in.

Topics

Resources

Stars

99 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Contributors

Languages