# Remote Media Player - Home Assistant Integration

[![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg)](https://github.com/hacs/integration)
[![GitHub Release](https://img.shields.io/github/v/release/DolgolyovAlexei/haos-hacs-integration-media-player)](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