# 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

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