alexei.dolgolyov
5519e449cd
Replace HTTP polling with WebSocket push notifications for instant state change responses. Server broadcasts updates only when significant changes occur (state, track, volume, etc.) while letting Home Assistant interpolate position during playback. Includes seek detection for timeline updates and automatic fallback to HTTP polling if WebSocket disconnects. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remote Media Player for Home Assistant
Control your PC's media playback from Home Assistant.
Components
| Component | Description | Documentation |
|---|---|---|
| Media Server | REST API server for your PC | README |
| HAOS Integration | Home Assistant custom component | README |
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)
cd media_server
pip install -r requirements.txt
python -m media_server.main --generate-config
python -m media_server.main
See Media Server README for detailed instructions.
2. Set up Home Assistant Integration
- Copy
custom_components/remote_media_player/to your HA config - Restart Home Assistant
- Add integration via UI with your server's IP and token
See Integration README 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