# Remote Media Player for Home Assistant

Control your PC's media playback from Home Assistant.

## Components

| Component | Description | Documentation |
|-----------|-------------|---------------|
| [Media Server](media_server/) | REST API server for your PC | [README](media_server/README.md) |
| [HAOS Integration](custom_components/remote_media_player/) | Home Assistant custom component | [README](custom_components/remote_media_player/README.md) |

## Overview

```
┌─────────────────────┐         HTTP/REST         ┌─────────────────────┐
│   Home Assistant    │◄─────────────────────────►│    Your PC          │
│                     │      (Token Auth)         │                     │
│  ┌───────────────┐  │                           │  ┌───────────────┐  │
│  │ Media Player  │  │                           │  │ Media Server  │  │
│  │    Entity     │  │                           │  │   (FastAPI)   │  │
│  └───────────────┘  │                           │  └───────┬───────┘  │
│                     │                           │          │          │
└─────────────────────┘                           │  ┌───────▼───────┐  │
                                                  │  │ Media Control │  │
                                                  │  │ - Windows     │  │
                                                  │  │ - Linux       │  │
                                                  │  │ - macOS       │  │
                                                  │  │ - Android     │  │
                                                  │  └───────────────┘  │
                                                  └─────────────────────┘
```

## Features

- Play/Pause/Stop media
- Next/Previous track
- Volume control and mute
- Seek within tracks
- Display current track info (title, artist, album, artwork)
- Secure token-based authentication

## Supported Platforms

| Platform | Media Control | Volume Control | Status |
|----------|---------------|----------------|--------|
| Windows | WinRT Media Transport | pycaw | Fully tested |
| Linux | MPRIS D-Bus | PulseAudio/PipeWire | Not tested |
| macOS | AppleScript | System volume | Not tested |
| Android | Termux:API | Termux volume | Not tested |

> **Note:** Windows is the primary supported platform. Linux, macOS, and Android implementations exist but have not been thoroughly tested and may have limited functionality.

## Quick Start

### 1. Set up the Server (on your PC)

```bash
cd media_server
pip install -r requirements.txt
python -m media_server.main --generate-config
python -m media_server.main
```

See [Media Server README](media_server/README.md) for detailed instructions.

### 2. Set up Home Assistant Integration

1. Copy `custom_components/remote_media_player/` to your HA config
2. Restart Home Assistant
3. Add integration via UI with your server's IP and token

See [Integration README](custom_components/remote_media_player/README.md) for detailed instructions.

## Project Structure

```
haos-integration-media-player/
├── media_server/                    # Server component
│   ├── main.py                      # Entry point
│   ├── routes/                      # API endpoints
│   ├── services/                    # Platform media controllers
│   └── service/                     # Service installers
│
├── custom_components/
│   └── remote_media_player/         # HAOS Integration
│       ├── media_player.py          # Media player entity
│       └── config_flow.py           # UI configuration
│
└── README.md
```

## License

MIT License