# RelayTV Home Assistant Integration

![RelayTV Screenshots](https://raw.githubusercontent.com/mcgeezy/relaytv-ha/main/relaytv-ha.png)

RelayTV for Home Assistant adds your self-hosted RelayTV servers as Home Assistant entities and services, making it easy to control playback, launch media, trigger overlays, and integrate RelayTV into automations and dashboards.

RelayTV server:  
https://github.com/mcgeezy/relaytv

Android companion app:  
https://github.com/mcgeezy/relaytv-android

Support the project:  
https://buymeacoffee.com/relaytv

---

## What This Integration Adds

RelayTV integrates with Home Assistant as a local `media_player` plus RelayTV-specific services.

### Core features

- Creates a `media_player` entity for each RelayTV config entry
- Supports multiple RelayTV servers
- Uses RelayTV live event updates plus `/status` refresh fallback
- Supports an optional RelayTV API bearer token with reauthentication
- Adds a Home Assistant sidebar panel for the RelayTV web UI
- Exposes RelayTV-specific services for smart play, temporary playback, overlays, snapshots, synchronized playback, upload/play, upload/enqueue, and resume behavior
- Supports automation-friendly control from scripts, dashboards, and mobile workflows

### Supported media controls

- Play
- Pause
- Stop
- Next
- Previous
- Seek
- Set volume
- Mute and unmute
- Turn on
- Turn off

### Advanced RelayTV features

- Smart queue/play behavior
- Temporary interrupt + resume playback
- Text and image overlays
- Snapshot capture
- Multi-target synchronized playback
- Resume-position support
- Direct media upload from Home Assistant local media/files to RelayTV ingest endpoints
- Optional sensor-to-stream mapping triggers

---

## 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 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 |

---

## Home Assistant Companion App Share Automation

Add this automation to share links to the Home Assistant Phone App and play them on TV

```yaml
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 '') }}
```

---

## Installation

### HACS

1. Open HACS in Home Assistant
2. Add this repository as a custom repository with category `Integration`
3. Install `RelayTV`
4. Restart Home Assistant
5. Add the `RelayTV` integration from **Settings → Devices & Services**

### Manual

1. Copy `custom_components/relaytv` into your Home Assistant config:

   ```text
   /config/custom_components/relaytv/
   ```

2. Restart Home Assistant
3. Go to **Settings → Devices & Services → Add Integration**
4. Search for **RelayTV**
5. Enter:
   - RelayTV base URL, for example `http://relaytv-host:8787`
   - Display name for this RelayTV instance
   - RelayTV API token, 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 is sent only as a bearer authorization header to RelayTV.

---

## Configuration Options

From the integration options flow, you can configure:

- `panel_enabled` — enable or disable sidebar panel registration
- `panel_target_entry_id` — choose which RelayTV server is used by the shared sidebar panel
- `sensor_stream_mappings` — map sensors to temporary playback URLs

## 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 allows Home Assistant to process RelayTV
thumbnails across origins without browser CORS errors.

---

## Example Service Calls

### Smart play / enqueue

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

### Immediate playback

```yaml
service: relaytv.play_now
target:
  entity_id: media_player.relaytv_living_room
data:
  url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
  use_ytdlp: true
  cec: false
```

### Temporary playback

```yaml
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 message

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

### Upload media and play

```yaml
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`.
When using 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 previous playback
- Display overlay messages on TVs around the home
- Add RelayTV as a dashboard-accessible media target
- Keep multiple RelayTV devices available in one Home Assistant setup
- Start synchronized playback across more than one RelayTV screen

---

## Known Limitations

- `relaytv.play_now` currently maps to RelayTV `POST /play` (queue-clearing behavior)
- RelayTV also exposes `POST /play_now`, but this integration does not currently use its preserve-current behavior
- No dedicated `clear_queue` Home Assistant service is currently registered by this integration
- 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
- RelayTV 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: https://github.com/mcgeezy/relaytv
- RelayTV Android app: https://github.com/mcgeezy/relaytv-android

### Planned / work in progress

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

---

## Support The Project

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

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

---

## Compatibility

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

For local verification:

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

## License

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