RelayTV – Home Assistant Integration

RelayTV transforms Home Assistant into a programmable local media automation engine.

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).

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.

---

🚀 What RelayTV Enables Today

🎬 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

---

⭐ Key Mobile UX Feature: “Share to Home Assistant” → Play / Enqueue

One of the best day-to-day workflows is using your phone like a “remote link picker”:

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

This feels incredible in practice: you browse normally on your phone, tap Share, and your TV starts playing.

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)

---

🔵 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

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:
      entity_id: media_player.relaytv_living_room
    data:
      url: "{{ shared_url }}"
  - service: notify.notify
    data:
      title: "RelayTV"
      message: "Playing: {{ shared_url }}"

Variant: Mobile Share → Enqueue Instead of Play Now

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:
      entity_id: media_player.relaytv_living_room
    data:
      url: "{{ shared_url }}"
  - service: notify.notify
    data:
      title: "RelayTV"
      message: "Enqueued: {{ shared_url }}"

---

1) Doorbell → Show Front Door Camera (RTSP)

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

2) Morning Video Alarm Clock (Playlist + Lights)

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

3) Late-Night Motion → Jump Scare (Fun Mode)

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)

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).

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)

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

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:

/ config / custom_components / relaytv

Restart Home Assistant.

---

🔐 License

TBD