haos-hacs-integration-media-player/haos-integration/custom_components/remote_media_player/README.md

Remote Media Player - Home Assistant Integration

A Home Assistant custom component that allows you to control a remote PC's media playback as a media player entity.

Features

• Full media player controls (play, pause, stop, next, previous)
• Volume control and mute
• Seek support
• Displays current track info (title, artist, album, artwork)
• Script buttons - Execute pre-defined scripts (shutdown, restart, lock, sleep, etc.)
• Configurable via Home Assistant UI
• Polling with adjustable interval

Requirements

• Home Assistant 2024.1.0 or newer
• A running Media Server on your PC (see Media Server repository)

Installation

HACS (Recommended)

1. Open HACS in Home Assistant
2. Click the three dots menu > Custom repositories
3. Add this repository URL and select "Integration"
4. Search for "Remote Media Player" and install
5. Restart Home Assistant

Manual Installation

1. Copy the remote_media_player folder to your Home Assistant config/custom_components/ directory:

   config/
   └── custom_components/
       └── remote_media_player/
           ├── __init__.py
           ├── api_client.py
           ├── button.py
           ├── config_flow.py
           ├── const.py
           ├── manifest.json
           ├── media_player.py
           ├── services.yaml
           ├── strings.json
           └── translations/
               └── en.json
   

2. Restart Home Assistant

Configuration

Via UI (Recommended)

1. Go to Settings > Devices & Services
2. Click + Add Integration
3. Search for "Remote Media Player"
4. Enter the connection details:
   • Host: IP address or hostname of your PC running Media Server
   • Port: Server port (default: 8765)
   • API Token: The authentication token from your server
   • Name: Display name for this media player (optional)
   • Poll Interval: How often to update status (default: 5 seconds)

Finding Your API Token

On the PC running Media Server:

python -m media_server.main --show-token

Or check the config file:

• Windows: %APPDATA%\media-server\config.yaml
• Linux/macOS: ~/.config/media-server/config.yaml

Usage

Once configured, the integration creates a media player entity that you can:

Control via UI

• Use the media player card in Lovelace
• Control from the entity's detail page

Control via Services

# Play
service: media_player.media_play
target:
  entity_id: media_player.remote_media_player

# Pause
service: media_player.media_pause
target:
  entity_id: media_player.remote_media_player

# Set volume (0.0 - 1.0)
service: media_player.volume_set
target:
  entity_id: media_player.remote_media_player
data:
  volume_level: 0.5

# Mute
service: media_player.volume_mute
target:
  entity_id: media_player.remote_media_player
data:
  is_volume_muted: true

# Next/Previous track
service: media_player.media_next_track
target:
  entity_id: media_player.remote_media_player

# Seek to position (seconds)
service: media_player.media_seek
target:
  entity_id: media_player.remote_media_player
data:
  seek_position: 60

Automations

Example: Pause PC media when leaving home

automation:
  - alias: "Pause PC media when leaving"
    trigger:
      - platform: state
        entity_id: person.your_name
        from: "home"
    action:
      - service: media_player.media_pause
        target:
          entity_id: media_player.remote_media_player

Example: Lower PC volume during quiet hours

automation:
  - alias: "Lower PC volume at night"
    trigger:
      - platform: time
        at: "22:00:00"
    action:
      - service: media_player.volume_set
        target:
          entity_id: media_player.remote_media_player
        data:
          volume_level: 0.3

Script Buttons

The integration automatically creates button entities for each script defined on your Media Server. These buttons allow you to:

• Lock/unlock the workstation
• Shutdown, restart, or put the PC to sleep
• Hibernate the PC
• Execute custom commands

Available Buttons

After setup, you'll see button entities like:

• button.remote_media_player_lock_screen
• button.remote_media_player_shutdown
• button.remote_media_player_restart
• button.remote_media_player_sleep
• button.remote_media_player_hibernate

Adding Scripts

Scripts are configured on the Media Server in config.yaml:

scripts:
  lock_screen:
    command: "rundll32.exe user32.dll,LockWorkStation"
    label: "Lock Screen"
    description: "Lock the workstation"
    timeout: 5
    shell: true

After adding scripts, restart the Media Server and reload the integration in Home Assistant.

Using Script Buttons

Via UI

Add button entities to your dashboard using a button card or entities card.

Via Automation

automation:
  - alias: "Lock PC when leaving home"
    trigger:
      - platform: state
        entity_id: person.your_name
        from: "home"
    action:
      - service: button.press
        target:
          entity_id: button.remote_media_player_lock_screen

Execute Script Service

You can also execute scripts with arguments using the service:

service: remote_media_player.execute_script
data:
  script_name: "echo_test"
  args:
    - "arg1"
    - "arg2"

Lovelace Card Examples

Basic Media Control Card

type: media-control
entity: media_player.remote_media_player

Mini Media Player (requires custom card)

type: custom:mini-media-player
entity: media_player.remote_media_player
artwork: cover
source: icon

Entities Card

type: entities
entities:
  - entity: media_player.remote_media_player
    type: custom:slider-entity-row
    full_row: true

Entity Attributes

The media player entity exposes these attributes:

Attribute	Description
media_title	Current track title
media_artist	Current artist
media_album_name	Current album
media_duration	Track duration in seconds
media_position	Current position in seconds
volume_level	Volume (0.0 - 1.0)
is_volume_muted	Mute state
source	Media source/player name

Options

After initial setup, you can adjust options:

1. Go to Settings > Devices & Services
2. Find "Remote Media Player" and click Configure
3. Adjust the poll interval as needed

Lower poll intervals = more responsive but more network traffic.

Troubleshooting

Integration not found

• Restart Home Assistant after installing
• Check that all files are in the correct location
• Check Home Assistant logs for errors

Cannot connect to server

• Verify the server is running: curl http://YOUR_PC_IP:8765/api/health
• Check firewall settings on the PC
• Ensure the IP address is correct

Invalid token error

• Double-check the token matches exactly
• Regenerate token if needed: python -m media_server.main --generate-config

Entity shows unavailable

• Check server is running
• Check network connectivity
• Review Home Assistant logs for connection errors

Media controls don't work

• Ensure media is playing on the PC
• Check server logs for errors
• Verify the media player supports the requested action

Multiple PCs

You can add multiple Media Server instances:

1. Run Media Server on each PC (use different tokens)
2. Add the integration multiple times in Home Assistant
3. Give each a unique name

Supported Features

Feature	Supported
Play	Yes
Pause	Yes
Stop	Yes
Next Track	Yes
Previous Track	Yes
Volume Set	Yes
Volume Mute	Yes
Seek	Yes
Script Buttons	Yes
Browse Media	No
Play Media	No
Shuffle/Repeat	No

License

MIT License