RelayTV-HA/README.md

Your TV, native in Home Assistant.

Add your self-hosted RelayTV screens to Home Assistant as real media-player devices — control playback, launch media, trigger overlays, and drop RelayTV into automations, dashboards, and voice.

Install · See it in action · Services · RelayTV server

Local-first · No RelayTV account · Bearer-token auth · Credential-safe playback state

One integration. Every way you control the TV.

🎛️ Control it

Every RelayTV server becomes a Home Assistant media_player: play, pause, stop, next, previous, seek, volume, mute, turn on/off — with live artwork, title, and progress on your dashboards, the mobile app, and voice assistants.

🤖 Automate it

Call RelayTV-specific actions from scripts and automations — smart play, temporary interrupt-and-resume, overlays, snapshots, synchronized multi-screen start, and direct uploads from Home Assistant media to the TV.

🧩 Embed it

Pin the full RelayTV web UI as a Home Assistant sidebar panel, so the remote, queue, and Jellyfin/Emby library are always one click away — without leaving Home Assistant.

RelayTV keeps the playback engine beside the TV while Home Assistant stays the control plane. Live event updates keep entity state fresh, with a /status poll as the reconnect fallback.

See it in action

The images above are captured from a live Home Assistant instance with scripts/readme-screenshots.mjs.

Install in minutes

HACS

HACS currently supports only public GitHub repositories; it cannot install directly from this Gitea repository. Keep the mcgeezy/relaytv-ha mirror and its releases current if you want to continue distributing through HACS.

1. Open HACS in Home Assistant.
2. Add https://github.com/mcgeezy/relaytv-ha as a custom repository with category Integration.
3. Install RelayTV and restart Home Assistant.
4. Add the integration from Settings → Devices & Services → Add Integration.

Manual

1. Download and extract relaytv.zip from the Gitea release, or copy custom_components/relaytv from the repository, into your Home Assistant config:

   /config/custom_components/relaytv/
   

2. Restart Home Assistant.

3. Go to Settings → Devices & Services → Add Integration and search for RelayTV.

Configure

Enter:

• RelayTV base URL — for example http://relaytv-host:8787
• Display name — how this RelayTV instance appears in Home Assistant
• RelayTV API token — only if RELAYTV_API_TOKEN is enabled on the server

Use Reconfigure on the integration entry to change the server address, display name, or API token. The token is stored in the Home Assistant config entry and sent only as a bearer authorization header to RelayTV.

From the integration options you can also configure:

• panel_enabled — enable or disable the sidebar panel
• panel_target_entry_id — which RelayTV server the shared panel points at
• sensor_stream_mappings — map sensors to temporary playback URLs

Send links from your phone

Add this automation to relay links shared from the Home Assistant mobile app straight to the TV:

alias: RelayTV - Smart play from share
description: Opens shared URLs/text in RelayTV via relaytv.smart_url
triggers:
  - event_type: mobile_app.share
    trigger: event
conditions:
  - condition: template
    value_template: "{{ shared | trim | length > 0 }}"
actions:
  - data:
      url: "{{ shared | trim }}"
    action: relaytv.smart_url
mode: single
variables:
  shared: |-
    {{ trigger.event.data.url
       if trigger.event.data.url is defined else
       (trigger.event.data.text if trigger.event.data.text is defined else '') }}

RelayTV Services

Service	RelayTV endpoint	Notes
relaytv.smart_url	POST /smart	Smart play/enqueue behavior
relaytv.play_now	POST /play	Immediate playback; clears queue
relaytv.announce	POST /play	Alias of play_now
relaytv.play_temporary	POST /play_temporary	Temporary interrupt + resume flow
relaytv.overlay	POST /overlay	Text/image overlay
relaytv.play_synced	POST /play_at	Multi-entity time-aligned start
relaytv.snapshot	POST /snapshot (fallback GET /snapshot)	Captures current frame
relaytv.play_with_resume	POST /play + POST /seek_abs	Resume per-URL saved position
relaytv.upload_media	POST /ingest/media	Upload local HA media/file and return a RelayTV media URL
relaytv.upload_media_play	POST /ingest/media/play	Upload local HA media/file and start playback
relaytv.upload_media_enqueue	POST /ingest/media/enqueue	Upload local HA media/file and append to queue

Example service calls

Smart play / enqueue:

service: relaytv.smart_url
target:
  entity_id: media_player.relaytv_living_room
data:
  url: https://www.youtube.com/watch?v=dQw4w9WgXcQ

Temporary playback (interrupt, then resume what was playing):

service: relaytv.play_temporary
target:
  entity_id: media_player.relaytv_living_room
data:
  url: https://example.com/doorbell-chime.mp3
  timeout: 10
  volume: 0.6

Overlay a message on the TV:

service: relaytv.overlay
target:
  entity_id: media_player.relaytv_living_room
data:
  text: Front door opened
  duration: 8
  position: top-right

Upload a local file and play it:

service: relaytv.upload_media_play
target:
  entity_id: media_player.relaytv_living_room
data:
  file_path: /config/www/clip.mp4
  title: Shared Clip

file_path must be readable by Home Assistant and allowed by allowlist_external_dirs. In the service UI, the file field can also select a local Home Assistant media-source item.

Typical use cases

• Send shared links from Home Assistant automations to a RelayTV screen
• Upload and play local Home Assistant media files on RelayTV
• Launch temporary doorbell or announcement media, then resume playback
• Display overlay messages on TVs around the home
• Add RelayTV as a dashboard- and voice-accessible media target
• Keep multiple RelayTV devices available in one Home Assistant setup
• Start synchronized playback across more than one RelayTV screen

Security and upgrading to 0.4.0

Version 0.4.0 sanitizes credential-bearing playback URLs before they reach Home Assistant state or resume storage. Existing resume data is migrated and limited to the 500 most recent media keys automatically.

Home Assistant recorder history written by an older version is not rewritten. If a previous media identifier contained an upstream Jellyfin/Emby API key or signed URL, rotate that credential and consider purging old history for the RelayTV media-player entity.

For defense in depth, update the RelayTV server to a version that redacts private playback fields from public status, queue, history, and SSE payloads. The matching server update also lets Home Assistant process RelayTV thumbnails across origins without browser CORS errors.

Known limitations

• relaytv.play_now maps to RelayTV POST /play (queue-clearing behavior); the server's preserve-current POST /play_now is not yet used
• No dedicated clear_queue Home Assistant service is registered
• Upload services require a local media-source item or a file path available inside the Home Assistant container
• Overlay calls must include at least text or image_url
• Snapshots require active playback on the RelayTV server
• /ui/events is treated as a live push stream, not a replay log; /status remains the reconnect/bootstrap fallback
• Releases predating POST /auth/check remain compatible, but the current server release is recommended for public-payload redaction and cross-origin thumbnails

Companion projects

• RelayTV server — the local playback engine and web UI.
• RelayTV for Android — share links directly to the TV and control playback from your phone.

Planned / work in progress

• iPhone companion app
• Continued multi-device and automation improvements
• Ongoing UX polish across the RelayTV ecosystem

Compatibility

Version 0.4.0 requires Home Assistant 2026.7 or newer and is automatically tested against Home Assistant 2026.7.2 and the current RelayTV server API.

For local verification:

python -m pip install --requirement requirements_test.txt
ruff check custom_components tests
python -m pytest -q

To regenerate the README images from a live Home Assistant instance:

HA_TOKEN=<long-lived-token> node scripts/readme-screenshots.mjs \
  --ha=http://homeassistant.local:8123 \
  --device=<relaytv_device_id> \
  --entity=media_player.living_room_tv \
  --ws=ws://127.0.0.1:3000/

Support the project

If RelayTV is useful to you, donations help fund continued development of the server, this Home Assistant integration, the Android app, and future companion apps.

Buy me a coffee: https://buymeacoffee.com/relaytv

License

RelayTV Home Assistant is licensed under the GNU General Public License, version 3 only (GPL-3.0-only). See LICENSE.