this is a fork of original software with modifications for the use in our hackerspace.
RelayTV turns a Linux box connected to your TV into a local, automation-friendly playback target. Send links from your phone, Home Assistant, scripts, or apps and play them now or queue them for later.
Local-first, no account required, and no cloud dependency for core playback.
Best for: Raspberry Pi and mini PC TV boxes, Home Assistant users, homelab and self-hosted setups, and AI-driven automation workflows.
RelayTV is built for people who want a local, automation-friendly way to send media to a TV without relying on closed casting ecosystems, cloud accounts, or app-specific playback flows.
See docs/INSTALL.md for full installation and runtime notes.
mkdir -p ~/relaytv
cd ~/relaytv
curl -fsSL https://raw.githubusercontent.com/mcgeezy/relaytv/main/install.sh | bashThen open http://:8787/ui
cd /path/to/relaytv
./scripts/install.sh
docker compose up -d --build
./scripts/doctor.sh- Send links from Android to the TV and start playback in seconds
- Queue videos for later without interrupting what’s already playing
- Use Home Assistant as the control layer for a dedicated TV box
- Browse Jellyfin with a clean interface built for desktop/mobile control for playback on TV.
- Trigger playback or on-screen notifications from automations
- Build AI agent workflows that control TV playback through the API
RelayTV is designed as a family of companion projects:
This repository powers the local playback engine, queue manager, browser UI, API, and TV runtime.
Add RelayTV to Home Assistant with entities, services, automations, and side-panel workflows.
Send links directly to RelayTV from Android and control playback from your phone.
- iPhone Companion App — work in progress
- Windows version of RelayTV Server — planned / exploratory
- Play now or enqueue media from URLs
- Persistent queue with auto-advance
- Stream resolution for supported providers
- Local playback history and resumable session state
- Designed for reliable always-on living-room use
- HTTP API for scripts and automations
- Mobile-friendly browser remote UI
- Home Assistant integration for service calls and entity control
- Share-to-TV workflows through companion apps
- Overlay and toast notification support on the TV
- Built for Linux hosts connected directly to a TV
- Works well on Intel mini PCs, NUCs, HTPCs, and Raspberry Pi class devices
- Docker-based deployment
- GitHub Container Registry image publishing
- Native runtime optimized for real-world TV usage
- Home Assistant for entities, services, automations, and dashboard workflows
- Jellyfin for a beautiful library browsing experience
- Android companion workflows for fast share-to-TV control
- Local network automation and scripting through the HTTP API
- Local-first
- No account required
- No tracking
- No cloud dependency for core playback
RelayTV includes a beautiful Jellyfin client experience, making it easy to browse your library and launch playback directly on the connected display.
- Built for the TV screen with a clean, full-screen interface
- Fast access to your Jellyfin library without relying on another playback device
- Local-first playback on the same box connected to your television
- Unified experience alongside RelayTV queueing, remote control, and automation workflows
Whether you are browsing your own media collection or mixing Jellyfin with shared links and automations, RelayTV helps turn a small Linux box into a polished living-room media endpoint.
Once RelayTV is running, this plays a video immediately:
curl -X POST http://127.0.0.1:8787/play_now \
-H "Content-Type: application/json" \
-d '{"url":"https://youtu.be/dQw4w9WgXcQ"}'curl -X POST http://127.0.0.1:8787/enqueue \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/video.mp4"}'curl -X POST http://127.0.0.1:8787/overlay \
-H "Content-Type: application/json" \
-d '{"text":"Doorbell", "duration":2.5}'Primary docs:
- docs/INSTALL.md
- docs/API.md
- docs/JELLYFIN_OPERATIONS.md
- docs/NATIVE_RUNTIME_OPERATIONS.md
- docs/RELEASE.md
For the doc map, see docs/README.md.
- Native Qt is the active desktop runtime
- Wayland and X11 desktop installs default to native Qt
- Rollback is a tagged-baseline redeploy, not a live compatibility mode
- Published images are available through GitHub Container Registry
Published image:
ghcr.io/mcgeezy/relaytv:latest
Planned and in-progress areas include:
- iPhone companion app
- Windows server/runtime support
- continued mobile sharing improvements
- richer TV idle and overlay experiences
- expanded companion app ecosystem
- improved onboarding and release packaging
RelayTV is licensed under the GNU General Public License v3.0. RelayTV artwork and marks are covered by the asset and trademark policy.
If RelayTV is useful to you, please consider:
- starring the repository
- sharing it with others
- supporting development at https://buymeacoffee.com/relaytv
Every bit of support helps move the project forward.