haos-hacs-integration-media-player/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:
```bash
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
```yaml
# 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
```yaml
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
```yaml
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`:

```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
```yaml
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:

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

## Lovelace Card Examples

### Basic Media Control Card
```yaml
type: media-control
entity: media_player.remote_media_player
```

### Mini Media Player (requires custom card)
```yaml
type: custom:mini-media-player
entity: media_player.remote_media_player
artwork: cover
source: icon
```

### Entities Card
```yaml
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