RelayTV/RelayTV-HA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update READMEs to current integration feature set

Browse Source 
Document actual media_player support, registered services, options, and current service semantics/limitations to match implemented behavior.
This commit is contained in:
mark
2026-03-19 20:39:08 -05:00
parent d581a66ef0
commit 88743f8b0a
2 changed files with 100 additions and 508 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+67 -374
View File
@@ -1,403 +1,96 @@
# RelayTV – Home Assistant Integration
# RelayTV Home Assistant Integration
RelayTV transforms Home Assistant into a **programmable local media automation engine**.
RelayTV integrates with Home Assistant as a local `media_player` plus RelayTV-specific services.
It exposes your RelayTV server as a `media_player` (plus services), supports queue-based playback, and makes it easy to drive **local HDMI playback** from automations (doorbells, sensors, schedules, scenes, and AI).
## Current Feature Set
> Tip: The YAML below uses the `relaytv.*` service names as examples. If your integration exposes slightly different names/fields, keep the **automation patterns** and adjust the service calls accordingly.
- Creates a `media_player` entity for each RelayTV config entry.
- Polls RelayTV `GET /status` every 3 seconds.
- Supports media controls from Home Assistant:
- Play, pause, stop
- Next and previous
- Seek
- Volume set
- Turn on / turn off
- Registers a Home Assistant sidebar panel that embeds the RelayTV UI.
- Supports multi-target synchronized start (`play_synced`) using RelayTV `POST /play_at`.
- Supports snapshots (`snapshot`) and exposes `snapshot_url` on the entity.
- Stores resume positions and provides `play_with_resume` behavior.
- Supports optional sensor->stream mappings that trigger temporary playback when a mapped sensor turns `on`.
---
## RelayTV Services
# 🚀 What RelayTV Enables Today
| Service | RelayTV endpoint | Notes |
| --- | --- | --- |
| `relaytv.smart_url` | `POST /smart` | One-button play/enqueue behavior from RelayTV |
| `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 |
## 🎬 Media Player Control
- `media_player` entity support
- Play / pause / stop / seek / volume
- Queue management
- Resume playback support (where implemented)
- Local HDMI playback
- yt-dlp powered “smart URL” stream resolution
## Installation (Manual)
---
1. Copy this repository's `custom_components/relaytv` folder into your Home Assistant config:
# ⭐ Key Mobile UX Feature: “Share to Home Assistant” → Play / Enqueue
`/config/custom_components/relaytv/`
One of the best day-to-day workflows is using your phone like a “remote link picker”:
2. Restart Home Assistant.
3. Go to **Settings -> Devices & Services -> Add Integration**.
4. Search for **RelayTV**.
5. Enter:
- RelayTV base URL (example: `http://relaytv-host:8787`)
- Display name for this RelayTV instance
1. On iOS/Android, **share a link** (YouTube, Twitch, a direct stream URL, etc.)
2. Choose **Home Assistant** from the share sheet
3. Home Assistant fires an event (`mobile_app.share`) containing the shared `url` or `text`
4. An automation can then **play now** or **enqueue** on RelayTV
## Options
This feels *incredible* in practice: you browse normally on your phone, tap Share, and your TV starts playing.
From the integration options flow, you can configure:
> Pro tip: Use the HA UI automation editor to duplicate this automation into variants:
> - “Share → Play Now (Living Room)"
> - “Share → Enqueue (Bedroom)"
> - “Share → Ask which TV” (roadmap: actionable notification picker)
- `panel_enabled`: enable/disable sidebar panel registration
- `panel_target_entry_id`: which RelayTV config entry is used by the shared sidebar panel
- `sensor_stream_mappings`: list of sensor-to-URL mappings for temporary playback triggers
---
# 🔵 Practical Automation Use Cases (Available Now)
- 🚪 Doorbell / camera pop on the TV
- ⏰ Morning video alarm clock
- 🌙 Bedtime routines (relaxing queue + auto stop)
- 🏠 Home/Away/Movie mode scenes that change what’s on screen
- 📺 Queue-based “experiences” (workouts, parties, timers, intros)
- 📲 **Mobile Share → Play/Enqueue** from iOS/Android browsing (see below)
---
# 🟢 Creative & Fun Automation Ideas
- 👻 Late-night motion jump scares
- 🧟 Halloween mode (seasonal triggers + ambient loops)
- 🐶 Dog cam on bark detection
- 🎉 Birthday surprise mode
- 🎮 Easter-egg triggers (sensor patterns launch hidden clips)
---
# 🔴 Advanced Home Automation Scenarios
- 🤖 AI-powered announcements (TTS + relevant clip)
- 🌧 Weather-based media (radar, warnings, checklist videos)
- 📈 Energy monitoring visualizations (play alert/graph clip)
- 🛡 “Command center” camera rotation on alarm events
- 📰 AI daily digest queue (headlines + summaries)
---
# 🧠 Core Services (Examples)
| Service | Description |
|--------|-------------|
| `relaytv.play_now` | Immediately plays a URL |
| `relaytv.enqueue` | Adds URL to queue |
| `relaytv.smart_url` | Resolves URL via yt-dlp (when applicable) |
| `relaytv.clear_queue` | Clears current queue |
| `relaytv.seek` | Seek to a time position |
| `relaytv.volume_set` | Adjust volume |
---
# ✅ Automation Examples (YAML)
## 0) Drop-in: Share to Home Assistant → Play Now (Mobile)
**What it does:** When you share a link to the Home Assistant app, this plays it immediately on RelayTV.
- Trigger: `mobile_app.share`
- Uses: `trigger.event.data.url` (preferred) or `trigger.event.data.text`
## Example Service Calls
```yaml
alias: RelayTV - Mobile Share -> Play Now
mode: queued
trigger:
- platform: event
event_type: mobile_app.share
action:
- variables:
shared_url: >-
{{ trigger.event.data.url
if trigger.event.data.url is defined
else (trigger.event.data.text if trigger.event.data.text is defined else '') }}
- condition: template
value_template: "{{ shared_url | length > 0 }}"
- service: relaytv.play_now
target:
service: relaytv.play_now
target:
entity_id: media_player.relaytv_living_room
data:
url: "{{ shared_url }}"
- service: notify.notify
data:
title: "RelayTV"
message: "Playing: {{ shared_url }}"
data:
url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
use_ytdlp: true
cec: false
```
### Variant: Mobile Share → Enqueue Instead of Play Now
```yaml
alias: RelayTV - Mobile Share -> Enqueue
mode: queued
trigger:
- platform: event
event_type: mobile_app.share
action:
- variables:
shared_url: >-
{{ trigger.event.data.url
if trigger.event.data.url is defined
else (trigger.event.data.text if trigger.event.data.text is defined else '') }}
- condition: template
value_template: "{{ shared_url | length > 0 }}"
- service: relaytv.enqueue
target:
service: relaytv.play_temporary
target:
entity_id: media_player.relaytv_living_room
data:
url: "{{ shared_url }}"
- service: notify.notify
data:
title: "RelayTV"
message: "Enqueued: {{ shared_url }}"
data:
url: https://example.com/doorbell-chime.mp3
timeout: 10
volume: 0.6
```
---
## 1) Doorbell → Show Front Door Camera (RTSP)
```yaml
alias: RelayTV - Doorbell Camera Pop
mode: single
trigger:
- platform: state
entity_id: binary_sensor.front_door_ding
to: "on"
action:
- service: relaytv.play_now
target:
service: relaytv.overlay
target:
entity_id: media_player.relaytv_living_room
data:
url: "rtsp://user:pass@10.0.55.10:554/stream1"
- service: relaytv.volume_set
target:
entity_id: media_player.relaytv_living_room
data:
volume_level: 0.55
data:
text: Front door opened
duration: 8
position: top-right
```
## 2) Morning Video Alarm Clock (Playlist + Lights)
## Known Limitations
```yaml
alias: RelayTV - Morning Video Alarm
mode: single
trigger:
- platform: time
at: "06:45:00"
condition:
- condition: state
entity_id: person.mark
state: "home"
action:
- service: light.turn_on
target:
entity_id: light.bedroom
data:
brightness_pct: 10
- delay: "00:00:05"
- service: relaytv.play_now
target:
entity_id: media_player.relaytv_bedroom
data:
url: "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID"
- service: relaytv.volume_set
target:
entity_id: media_player.relaytv_bedroom
data:
volume_level: 0.25
- delay: "00:05:00"
- service: light.turn_on
target:
entity_id: light.bedroom
data:
brightness_pct: 45
```
- `relaytv.play_now` currently maps to RelayTV `POST /play` (queue-clearing behavior).
- No dedicated `enqueue` or `clear_queue` Home Assistant service is currently registered by this integration.
- Overlay calls must include at least `text` or `image_url`.
- Integration uses local polling; it does not currently use WebSocket push updates.
## 3) Late-Night Motion → Jump Scare (Fun Mode)
## Compatibility
```yaml
alias: RelayTV - Late Night Jump Scare
mode: single
trigger:
- platform: state
entity_id: binary_sensor.hall_motion
to: "on"
condition:
- condition: time
after: "01:00:00"
before: "04:00:00"
action:
- service: relaytv.volume_set
target:
entity_id: media_player.relaytv_living_room
data:
volume_level: 0.85
- service: light.turn_on
target:
entity_id: light.hallway
data:
brightness_pct: 100
- service: relaytv.play_now
target:
entity_id: media_player.relaytv_living_room
data:
url: "https://www.youtube.com/watch?v=YOUR_JUMPSCARE_CLIP"
- delay: "00:00:12"
- service: light.turn_off
target:
entity_id: light.hallway
```
## 4) Alarm Trigger → “Command Center” Camera Rotation (Queue)
```yaml
alias: RelayTV - Alarm Command Center
mode: restart
trigger:
- platform: state
entity_id: alarm_control_panel.house
to: "triggered"
action:
- service: relaytv.clear_queue
target:
entity_id: media_player.relaytv_living_room
- service: relaytv.enqueue
target:
entity_id: media_player.relaytv_living_room
data:
url: "rtsp://user:pass@10.0.55.10:554/front"
- service: relaytv.enqueue
target:
entity_id: media_player.relaytv_living_room
data:
url: "rtsp://user:pass@10.0.55.10:554/driveway"
- service: relaytv.enqueue
target:
entity_id: media_player.relaytv_living_room
data:
url: "rtsp://user:pass@10.0.55.10:554/backyard"
- service: relaytv.play_now
target:
entity_id: media_player.relaytv_living_room
data:
url: "rtsp://user:pass@10.0.55.10:554/front"
```
## 5) Party Mode Script (Intro Clip + Playlist)
Create this as a **Script** in HA (Settings → Automations & Scenes → Scripts).
```yaml
party_mode_relaytv:
alias: Party Mode (RelayTV)
mode: single
sequence:
- service: relaytv.clear_queue
target:
entity_id: media_player.relaytv_living_room
- service: relaytv.enqueue
target:
entity_id: media_player.relaytv_living_room
data:
url: "https://www.youtube.com/watch?v=YOUR_INTRO_CLIP"
- service: relaytv.enqueue
target:
entity_id: media_player.relaytv_living_room
data:
url: "https://www.youtube.com/playlist?list=YOUR_PARTY_PLAYLIST"
- service: relaytv.volume_set
target:
entity_id: media_player.relaytv_living_room
data:
volume_level: 0.65
- service: relaytv.play_now
target:
entity_id: media_player.relaytv_living_room
data:
url: "https://www.youtube.com/watch?v=YOUR_INTRO_CLIP"
```
## 6) “AI Announcement” Pattern (TTS + Video)
```yaml
alias: RelayTV - AI Announcement Pattern
mode: single
trigger:
- platform: state
entity_id: binary_sensor.garage_door_open_too_long
to: "on"
action:
- service: tts.speak
data:
media_player_entity_id: media_player.kitchen_speaker
message: "Garage door has been open for a while."
- service: relaytv.play_now
target:
entity_id: media_player.relaytv_living_room
data:
url: "https://www.youtube.com/watch?v=YOUR_ALERT_CLIP"
```
## 7) Energy Spike → Alert Clip + Reduce Loads
```yaml
alias: RelayTV - Energy Spike Alert
mode: single
trigger:
- platform: numeric_state
entity_id: sensor.home_power_kw
above: 8.0
for: "00:02:00"
action:
- service: relaytv.play_now
target:
entity_id: media_player.relaytv_living_room
data:
url: "https://www.youtube.com/watch?v=YOUR_POWER_ALERT_CLIP"
- service: switch.turn_off
target:
entity_id:
- switch.space_heater
- switch.shop_fan
```
---
# 🛣 Roadmap (Future Capabilities)
## 🔔 Interrupt + Resume Service
Temporarily interrupt playback for alerts, then auto-resume prior content.
## 🪟 Overlay Mode
Display notification banners without stopping playback.
## 🔄 Multi-Screen Sync
Synchronize playback across multiple RelayTV servers (perfect for whole-home announcements).
## 🖼 Snapshot Previews
Capture/preview before switching content (helps with camera pops).
## 🎛 Sensor → Stream Mapping UI
Map motion/doorbell sensors to streams directly in the integration options UI (no YAML required).
## 🧠 AI Clip Generator
Generate short clips (image + TTS + theme) for alerts, seasons, and events.
## 📢 Smart Alert Replacement
Insert custom “house announcements” during downtime or between queued items.
---
# 📦 Installation
## HACS
1. Add as Custom Repository (Integration)
2. Install
3. Restart Home Assistant
4. Add Integration
5. Configure server address
## Manual
Copy `custom_components/relaytv` into:
```text
/ config / custom_components / relaytv
```
Restart Home Assistant.
---
# 🔐 License
TBD
Validated against RelayTV app routes in `/opt/relaytv/app/relaytv_app/routes.py` and API docs in `/opt/relaytv/docs/API.md`.
custom_components/relaytv/README.md
+29 -130
View File
@@ -1,143 +1,42 @@
# RelayTV -- Home Assistant Integration
# RelayTV Home Assistant Integration
The RelayTV Home Assistant integration adds a sidebar panel that embeds
the RelayTV web UI directly inside Home Assistant.
This integration provides a RelayTV `media_player` entity, RelayTV service actions, and an optional Home Assistant sidebar panel embedding RelayTV UI.
This integration does **not** create media entities or mirror playback
state into HA.\
RelayTV remains the authoritative playback engine and UI.
## Implemented Behavior
------------------------------------------------------------------------
- `media_player` platform is enabled (`custom_components/relaytv/media_player.py`).
- Polling coordinator refreshes RelayTV `GET /status` every 3 seconds.
- Sidebar panel is registered via Home Assistant frontend iframe panel APIs.
- RelayTV services are registered from `services.yaml`:
- `smart_url`
- `play_now`
- `announce`
- `play_temporary`
- `overlay`
- `play_synced`
- `snapshot`
- `play_with_resume`
## What This Integration Does
## Setup
- Adds a dedicated **RelayTV** sidebar panel
- Embeds the RelayTV `/ui` interface via iframe
- Allows control from desktop or mobile HA apps
- Keeps RelayTV fully self-contained
1. Place this folder at:
------------------------------------------------------------------------
## Requirements
- A running RelayTV instance accessible from Home Assistant
- RelayTV reachable via HTTP (e.g. `http://relaytv-host:8787`)
- Home Assistant 2023.x or newer recommended
------------------------------------------------------------------------
## Installation (Manual)
1. Copy the `relaytv_webui` folder into:
```{=html}
<!-- -->
```
/config/custom_components/
So it becomes:
/config/custom_components/relaytv_webui/
`/config/custom_components/relaytv/`
2. Restart Home Assistant.
3. Add integration: **Settings -> Devices & Services -> Add Integration -> RelayTV**.
4. Provide RelayTV base URL (example: `http://relaytv-host:8787`) and a server/display name.
3. Go to:
## Options
```{=html}
<!-- -->
```
Settings → Devices & Services → Add Integration
- `panel_enabled`
- `panel_target_entry_id`
- `sensor_stream_mappings`
4. Search for **RelayTV Web UI Panel**.
## Notes
5. Enter the base URL where RelayTV is reachable from Home Assistant.
- `play_now` and `announce` currently target RelayTV `POST /play`.
- Overlay requires `text` or `image_url`.
- Snapshot responses are normalized to absolute URLs for Home Assistant entity attributes.
Example:
http://relaytv-host:8787
------------------------------------------------------------------------
## Configuration Options
After installation, you can configure:
Option Description
--------------- ----------------------------
Sidebar title Display name in HA sidebar
Sidebar icon Any valid MDI icon
Sidebar path URL slug used in HA
------------------------------------------------------------------------
## Example Configuration
Base URL:
http://192.168.1.50:8787
Custom sidebar path:
relaytv
Resulting HA path:
http://homeassistant.local:8123/relaytv
------------------------------------------------------------------------
## How It Works
The integration registers a built-in Home Assistant **iframe panel**.
No polling, no entities, no media_player integration.
RelayTV's own API and state model remain independent and
server-authoritative.
------------------------------------------------------------------------
## Security Notes
- RelayTV should only be exposed on trusted networks.
- If accessing via HTTPS reverse proxy, use the proxied URL as the
base URL.
- Ensure CORS and authentication policies match your deployment
environment.
------------------------------------------------------------------------
## Recommended Deployment Pattern
For maximum reliability:
- Run RelayTV in Docker
- Bind-mount `/data` for persistent queue/history
- Use stable and beta containers during upgrades
- Point HA at the stable instance
------------------------------------------------------------------------
## Roadmap
Planned future enhancements:
- Optional HA media_player entity bridge
- Service calls for play/enqueue
- WebSocket event push support
- HACS compatibility
------------------------------------------------------------------------
## Support
If the panel fails to load:
1. Verify RelayTV is reachable from the HA container
2. Confirm the base URL is correct
3. Check HA logs for integration load errors
4. Confirm no mixed HTTP/HTTPS blocking issues
------------------------------------------------------------------------
**RelayTV --- A local-first media runtime for your television.**
For fuller documentation and examples, see the repository root README.