alexei.dolgolyov
97c1784ad4
Aligns the integration with the four wire-level changes shipped in
media-server v0.3.0/0.3.1 without breaking back-compat with older
server versions or pre-existing config entries.
- WebSocket auth via Sec-WebSocket-Protocol: media-server.token.<T>
(preferred by server v0.3.0+). The ?token= query is still sent so
older servers and unauthenticated mode both keep working — aiohttp
completes the handshake even when the server doesn't echo the
subprotocol back.
- 429 Too Many Requests surfaced as MediaServerRateLimitError with
Retry-After parsed; execute_script() sleeps min(retry_after, 30)
and retries once before falling through to the caller.
- Optional HTTPS/WSS (CONF_USE_SSL) + optional certificate verification
toggle (CONF_VERIFY_SSL) wired through the config flow, client, and
WebSocket. Defaults preserve http+verified behaviour, so existing
config entries are unchanged.
- X-Request-ID header (uuid4 hex) on every HTTP call so HA-side issues
can be cross-referenced with the server's access/audit logs. The
format matches the server's ^[A-Za-z0-9._-]{1,128}\$ allow-list so
the id is preserved verbatim instead of being replaced server-side.
Bumps manifest version to 0.3.3.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Remote Media Player - Home Assistant Integration
A Home Assistant custom integration 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 with smooth timeline updates
- Displays current track info (title, artist, album, artwork)
- Real-time updates via WebSocket (with HTTP polling fallback)
- Turn on/off/toggle support - Execute custom actions (e.g., lock screen on turn off)
- Script buttons - Execute pre-defined scripts (shutdown, restart, lock, sleep, etc.)
- Configurable via Home Assistant UI
Requirements
- Home Assistant 2024.1.0 or newer
- A running Media Server on your PC
Media Server
This integration requires the Media Server to be running on the PC you want to control.
Media Server Repository: media-player-server
See the Media Server documentation for installation and setup instructions.
Installation
HACS (Recommended)
- Open HACS in Home Assistant
- Click the three dots menu > Custom repositories
- Add this repository URL:
https://git.dolgolyov-family.by/alexei.dolgolyov/haos-hacs-integration-media-player - Select category: Integration
- Click Add
- Search for "Remote Media Player" and click Download
- Restart Home Assistant
Manual Installation
- Download the latest release from the Releases page
- Extract and copy the
custom_components/remote_media_playerfolder to your Home Assistantconfig/custom_components/directory - Restart Home Assistant
Configuration
- Go to Settings > Devices & Services
- Click + Add Integration
- Search for "Remote Media Player"
- 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 Media Server
- Name: Display name for this media player (optional)
Usage
Once configured, the integration creates:
Media Player Entity
A full-featured media player entity with:
- Play/Pause/Stop controls
- Next/Previous track
- Volume control and mute
- Seek functionality
- Current track information
- Turn on/off/toggle actions (execute server-side callbacks)
Turn On/Off/Toggle
The media player supports media_player.turn_on, media_player.turn_off, and media_player.toggle actions. These execute optional callbacks configured on the Media Server (e.g., lock screen on turn off).
Configure callbacks in Media Server's config.yaml:
callbacks:
on_turn_on:
command: "echo PC turned on"
timeout: 10
shell: true
on_turn_off:
command: "rundll32.exe user32.dll,LockWorkStation"
timeout: 5
shell: true
on_toggle:
command: "echo Toggle triggered"
timeout: 10
shell: true
Script Button Entities
Button entities for each script defined on your Media Server:
- Lock/unlock workstation
- Shutdown, restart, sleep, hibernate
- Custom scripts
Execute Script Service
Call remote_media_player.execute_script to run any server-defined script with typed parameters:
service: remote_media_player.execute_script
data:
script_name: set_brightness
params:
level: 75
monitor: primary
Parameters are validated against the script's schema on the server. Scripts define their parameters in config.yaml:
scripts:
set_brightness:
command: "python set_brightness.py"
label: "Set Brightness"
icon: "mdi:brightness-6"
timeout: 10
parameters:
level:
type: integer
required: true
min: 0
max: 100
description: "Brightness level (0-100)"
monitor:
type: select
options: ["primary", "secondary", "all"]
default: "primary"
description: "Target monitor"
Supported parameter types: string, integer, float, boolean, select.
Parameters are passed to scripts as environment variables prefixed with SCRIPT_PARAM_ (e.g., SCRIPT_PARAM_LEVEL=75, SCRIPT_PARAM_MONITOR=primary).
Scripts without parameters work as before — just omit params.
Example Lovelace Card
type: media-control
entity: media_player.remote_media_player
Documentation
For detailed documentation, see custom_components/remote_media_player/README.md.
Support
License
MIT License