alexei.dolgolyov
de4b7cf9b4
- Change execute_script API from positional args list to named params dict - Update service schema, API client, and constants - Add execute_script service documentation to README
167 lines
5.1 KiB
Markdown
167 lines
5.1 KiB
Markdown
# Remote Media Player - Home Assistant Integration
|
|
|
|
[](https://github.com/hacs/integration)
|
|
[](https://git.dolgolyov-family.by/alexei.dolgolyov/haos-hacs-integration-media-player/releases)
|
|
|
|
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](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server)
|
|
|
|
See the Media Server documentation for installation and setup instructions.
|
|
|
|
## Installation
|
|
|
|
### HACS (Recommended)
|
|
|
|
1. Open HACS in Home Assistant
|
|
2. Click the three dots menu > **Custom repositories**
|
|
3. Add this repository URL: `https://git.dolgolyov-family.by/alexei.dolgolyov/haos-hacs-integration-media-player`
|
|
4. Select category: **Integration**
|
|
5. Click **Add**
|
|
6. Search for "Remote Media Player" and click **Download**
|
|
7. Restart Home Assistant
|
|
|
|
### Manual Installation
|
|
|
|
1. Download the latest release from the [Releases](https://git.dolgolyov-family.by/alexei.dolgolyov/haos-hacs-integration-media-player/releases) page
|
|
2. Extract and copy the `custom_components/remote_media_player` folder to your Home Assistant `config/custom_components/` directory
|
|
3. Restart Home Assistant
|
|
|
|
## Configuration
|
|
|
|
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 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`:
|
|
|
|
```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:
|
|
|
|
```yaml
|
|
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`:
|
|
|
|
```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
|
|
|
|
```yaml
|
|
type: media-control
|
|
entity: media_player.remote_media_player
|
|
```
|
|
|
|
## Documentation
|
|
|
|
For detailed documentation, see [custom_components/remote_media_player/README.md](custom_components/remote_media_player/README.md).
|
|
|
|
## Support
|
|
|
|
- [Report an Issue](https://git.dolgolyov-family.by/alexei.dolgolyov/haos-hacs-integration-media-player/issues)
|
|
- [Media Server Repository](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server)
|
|
|
|
## License
|
|
|
|
MIT License
|