markandClaude Fable 5
f2bf565623
* docs: add Home Assistant 0.4.0 hardening roadmap * fix: protect media credentials and resume state * feat: authenticate RelayTV API operations * fix: make targeting and media state reliable * test: add Home Assistant integration CI * fix: validate API credentials during setup * release: prepare HACS 0.4.0 * fix: align pytest dependency pin * fix: close URL sanitizer gaps and correct player state reporting Sync the sensitive-query-key list with the RelayTV server (adds auth, exp, jwt, X-Emby-Token, X-Jellyfin-Token), filter query credentials from relative URLs instead of returning them verbatim, and preserve brackets around IPv6 literal hosts. Also report volume on RelayTV's 0-100 scale unconditionally (a raw 1 is 1%, not full volume) and give the coordinator its own position_updated_at stamp — the base DataUpdateCoordinator has no last_update_success_time, so media_position_updated_at silently fell back to now() on every read and the seek bar never extrapolated. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# RelayTV Home Assistant Integration
|
|
|
|
This integration provides a RelayTV `media_player` entity, RelayTV service actions, and an optional Home Assistant sidebar panel embedding RelayTV UI.
|
|
|
|
## Implemented Behavior
|
|
|
|
- `media_player` platform is enabled (`custom_components/relaytv/media_player.py`).
|
|
- Hybrid state updates:
|
|
- bootstrap/reconnect uses RelayTV `GET /status`
|
|
- RelayTV `GET /ui/events` SSE provides hot-state updates
|
|
- `status` events are treated as authoritative full snapshots
|
|
- `playback` / `queue` / `jellyfin` events trigger fast updates or targeted refreshes
|
|
- Sidebar panel is registered via Home Assistant frontend iframe panel APIs.
|
|
- Optional bearer-token authentication is validated during setup and supports
|
|
Home Assistant reauthentication.
|
|
- Credential-bearing query parameters are removed from entity state and
|
|
persisted resume keys.
|
|
- RelayTV services are registered from `services.yaml`:
|
|
- `smart_url`
|
|
- `play_now`
|
|
- `announce`
|
|
- `play_temporary`
|
|
- `overlay`
|
|
- `play_synced`
|
|
- `snapshot`
|
|
- `play_with_resume`
|
|
- `upload_media`
|
|
- `upload_media_play`
|
|
- `upload_media_enqueue`
|
|
|
|
## Setup
|
|
|
|
1. Place this folder at:
|
|
|
|
`/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`), a
|
|
server/display name, and the optional RelayTV API token.
|
|
|
|
## Options
|
|
|
|
- `panel_enabled`
|
|
- `panel_target_entry_id`
|
|
- `sensor_stream_mappings`
|
|
|
|
## Notes
|
|
|
|
- `smart_url` uses RelayTV `POST /smart`, which enqueues while already playing and otherwise starts playback immediately.
|
|
- `play_now` and `announce` currently target RelayTV `POST /play`.
|
|
- RelayTV also exposes `POST /play_now`, but this integration does not currently use its preserve-current behavior.
|
|
- Upload services target RelayTV `POST /ingest/media`, `POST /ingest/media/play`, and `POST /ingest/media/enqueue`.
|
|
- Upload services accept either a Home Assistant local media source selection or an allowlisted `file_path` visible inside the Home Assistant container.
|
|
- Overlay requires `text` or `image_url`.
|
|
- Snapshot requires active playback on the RelayTV server.
|
|
- Snapshot responses are normalized to absolute URLs for Home Assistant entity attributes.
|
|
- The integration keeps `/status` as bootstrap/fallback and does not treat `/ui/events` as a replay log.
|
|
- Version 0.4.0 requires Home Assistant 2026.7 or newer.
|
|
|
|
For fuller documentation and examples, see the repository root README.
|