docs: update README with comprehensive feature documentation
- Add architecture diagram showing all components - Document all features: media control, audio visualizer, web UI/PWA, media browser, display control, scripts/callbacks, HA integration - Add platform support matrix (Windows, Linux, macOS, Android) - Add configuration example with all sections - Expand quick start for both server and HA integration - Document security features
This commit is contained in:
@@ -1,15 +1,177 @@
|
|||||||
# Remote Media Player
|
# Remote Media Player
|
||||||
|
|
||||||
Control your PC's media playback from Home Assistant.
|
Control your PC's media playback from Home Assistant or a standalone web UI.
|
||||||
|
|
||||||
This repository contains two independent components as git submodules:
|
This repository contains two independent components as git submodules:
|
||||||
|
|
||||||
## Components
|
- **[media-server](media-server/)** -- FastAPI media server with web UI ([repo](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server))
|
||||||
|
- **[haos-integration](haos-integration/)** -- HACS-ready Home Assistant integration ([repo](https://git.dolgolyov-family.by/alexei.dolgolyov/haos-hacs-integration-media-player))
|
||||||
|
|
||||||
| Submodule | Description | Repository |
|
## Architecture
|
||||||
|-----------|-------------|------------|
|
|
||||||
| [media-server](media-server/) | REST API server for your PC | [media-player-server](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server) |
|
```text
|
||||||
| [haos-integration](haos-integration/) | HACS-ready Home Assistant integration | [haos-hacs-integration-media-player](https://git.dolgolyov-family.by/alexei.dolgolyov/haos-hacs-integration-media-player) |
|
┌─────────────────────┐ HTTP/WebSocket ┌─────────────────────────┐
|
||||||
|
│ Home Assistant │◄────────────────────────►│ Your PC │
|
||||||
|
│ │ (Token Auth) │ │
|
||||||
|
│ ┌───────────────┐ │ │ ┌───────────────────┐ │
|
||||||
|
│ │ Media Player │ │ │ │ Media Server │ │
|
||||||
|
│ │ Entity │ │ │ │ (FastAPI) │ │
|
||||||
|
│ ├───────────────┤ │ │ ├───────────────────┤ │
|
||||||
|
│ │ Script Button │ │ Web UI │ │ Media Controller │ │
|
||||||
|
│ │ Entities │ │◄────────(PWA)──────────►│ │ Audio Visualizer │ │
|
||||||
|
│ ├───────────────┤ │ │ │ Browser Service │ │
|
||||||
|
│ │ Display │ │ │ │ Display Service │ │
|
||||||
|
│ │ Brightness/ │ │ │ │ Script Runner │ │
|
||||||
|
│ │ Power │ │ │ │ Callback System │ │
|
||||||
|
│ └───────────────┘ │ │ └───────────────────┘ │
|
||||||
|
└─────────────────────┘ └─────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### Media Control
|
||||||
|
|
||||||
|
- Play / Pause / Stop / Next / Previous
|
||||||
|
- Volume control (0-100%) and mute toggle
|
||||||
|
- Seek within tracks
|
||||||
|
- Real-time track info (title, artist, album, artwork)
|
||||||
|
- Status updates via WebSocket with HTTP polling fallback
|
||||||
|
|
||||||
|
### Audio Visualizer
|
||||||
|
|
||||||
|
- Real-time FFT spectrum analysis (32 frequency bins)
|
||||||
|
- On-demand WASAPI loopback capture (Windows), PulseAudio (Linux), CoreAudio (macOS)
|
||||||
|
- Beat detection with reactive album art effects
|
||||||
|
- Configurable FPS (10-60), bin count (8-128), and device selection
|
||||||
|
- Dynamic WebGL background with audio reactivity
|
||||||
|
|
||||||
|
### Web UI (PWA)
|
||||||
|
|
||||||
|
- Installable Progressive Web App with offline support
|
||||||
|
- Dark / light theme with accent color picker (9 presets + custom)
|
||||||
|
- Tabbed interface: Player, Display, Browser, Quick Actions, Settings
|
||||||
|
- Sticky mini-player when scrolling
|
||||||
|
- Vinyl record animation with groove effect
|
||||||
|
- Responsive layout (desktop, tablet, mobile with safe area support)
|
||||||
|
- Localization: English and Russian (auto-detected)
|
||||||
|
- Header quick links (configurable external URLs)
|
||||||
|
|
||||||
|
### Media Browser
|
||||||
|
|
||||||
|
- Browse configured media folders with breadcrumb navigation
|
||||||
|
- Grid, compact grid, and list view modes
|
||||||
|
- Thumbnail generation and caching
|
||||||
|
- Metadata display (artist, album, duration, bitrate)
|
||||||
|
- Search, filter, and pagination
|
||||||
|
- Play files or entire folders with the system default player
|
||||||
|
|
||||||
|
### Display Control
|
||||||
|
|
||||||
|
- Monitor brightness adjustment (0-100%) via DDC-CI
|
||||||
|
- Monitor power on/off
|
||||||
|
- Multi-monitor support with model/resolution info
|
||||||
|
|
||||||
|
### Scripts & Callbacks
|
||||||
|
|
||||||
|
- **Scripts**: Define and execute custom commands (shutdown, lock, sleep, etc.)
|
||||||
|
- **Callbacks**: Hook into media events (`on_play`, `on_pause`, `on_turn_off`, etc.)
|
||||||
|
- Full CRUD management from the web UI
|
||||||
|
- Timeout enforcement and output capture (max 10KB)
|
||||||
|
|
||||||
|
### Home Assistant Integration
|
||||||
|
|
||||||
|
- Standard `media_player` entity with full playback controls
|
||||||
|
- Button entities for each configured script
|
||||||
|
- Number entities for monitor brightness sliders
|
||||||
|
- Switch entities for monitor power
|
||||||
|
- Config flow UI or YAML configuration
|
||||||
|
- Multiple server instances supported
|
||||||
|
|
||||||
|
### Security
|
||||||
|
|
||||||
|
- Bearer token authentication with multiple named tokens
|
||||||
|
- Path validation to prevent directory traversal
|
||||||
|
- Command argument sanitization
|
||||||
|
- No shell injection (proper subprocess API)
|
||||||
|
- GZip compression for responses > 1KB
|
||||||
|
|
||||||
|
## Platform Support
|
||||||
|
|
||||||
|
| Platform | Media Control | Volume | Visualizer | Display |
|
||||||
|
|-------------|----------------|---------------------|-----------------|---------------|
|
||||||
|
| **Windows** | WinRT (winsdk) | pycaw (COM) | WASAPI loopback | DDC-CI |
|
||||||
|
| **Linux** | MPRIS (D-Bus) | PulseAudio/PipeWire | PulseAudio | XRandR / ACPI |
|
||||||
|
| **macOS** | osascript | CoreAudio | CoreAudio | IOKit |
|
||||||
|
| **Android** | Termux API | Termux API | - | - |
|
||||||
|
|
||||||
|
Supported players include Spotify, Chrome, Edge, Firefox, VLC, foobar2000, Windows Media Player, Groove Music, and any MPRIS2-compliant player on Linux.
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### 1. Media Server (on your PC)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd media-server
|
||||||
|
pip install . # or pip install .[windows] on Windows
|
||||||
|
python -m media_server.main --generate-config # create config.yaml
|
||||||
|
python -m media_server.main --show-token # view API tokens
|
||||||
|
python -m media_server.main # start server
|
||||||
|
```
|
||||||
|
|
||||||
|
Open `http://localhost:8765` in a browser and enter your token.
|
||||||
|
|
||||||
|
See [Media Server README](media-server/README.md) for service installation (Windows Task Scheduler / Linux systemd), configuration reference, and API documentation.
|
||||||
|
|
||||||
|
### 2. Home Assistant Integration
|
||||||
|
|
||||||
|
**HACS (recommended):** Add `https://git.dolgolyov-family.by/alexei.dolgolyov/haos-hacs-integration-media-player` as a custom repository, then install "Remote Media Player".
|
||||||
|
|
||||||
|
**Manual:** Copy `haos-integration/custom_components/remote_media_player/` to your HA `custom_components/` folder.
|
||||||
|
|
||||||
|
Configure via Settings > Devices & Services > Add Integration > "Remote Media Player", providing your server host, port, and API token.
|
||||||
|
|
||||||
|
See [HAOS Integration README](haos-integration/README.md) for detailed instructions.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
The media server is configured via `config.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
host: 0.0.0.0
|
||||||
|
port: 8765
|
||||||
|
|
||||||
|
api_tokens:
|
||||||
|
home_assistant: "your-token-here"
|
||||||
|
mobile: "another-token"
|
||||||
|
|
||||||
|
visualizer_enabled: true
|
||||||
|
visualizer_fps: 30
|
||||||
|
visualizer_bins: 32
|
||||||
|
|
||||||
|
media_folders:
|
||||||
|
music:
|
||||||
|
path: "C:\\Users\\You\\Music"
|
||||||
|
label: "Music"
|
||||||
|
|
||||||
|
scripts:
|
||||||
|
lock_screen:
|
||||||
|
command: "rundll32.exe user32.dll,LockWorkStation"
|
||||||
|
label: "Lock Screen"
|
||||||
|
icon: "mdi:lock"
|
||||||
|
shutdown:
|
||||||
|
command: "shutdown /s /t 0"
|
||||||
|
label: "Shutdown"
|
||||||
|
|
||||||
|
callbacks:
|
||||||
|
on_turn_off:
|
||||||
|
command: "rundll32.exe user32.dll,LockWorkStation"
|
||||||
|
|
||||||
|
links:
|
||||||
|
spotify:
|
||||||
|
url: "https://open.spotify.com"
|
||||||
|
icon: "mdi:spotify"
|
||||||
|
label: "Spotify"
|
||||||
|
```
|
||||||
|
|
||||||
## Cloning
|
## Cloning
|
||||||
|
|
||||||
@@ -17,60 +179,10 @@ This repository contains two independent components as git submodules:
|
|||||||
# Clone with submodules
|
# Clone with submodules
|
||||||
git clone --recurse-submodules https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-mixed.git
|
git clone --recurse-submodules https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-mixed.git
|
||||||
|
|
||||||
# Or if already cloned, initialize submodules
|
# Or initialize submodules after cloning
|
||||||
git submodule update --init --recursive
|
git submodule update --init --recursive
|
||||||
```
|
```
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────┐ HTTP/WebSocket ┌─────────────────────┐
|
|
||||||
│ Home Assistant │◄────────────────────────►│ Your PC │
|
|
||||||
│ │ (Token Auth) │ │
|
|
||||||
│ ┌───────────────┐ │ │ ┌───────────────┐ │
|
|
||||||
│ │ Media Player │ │ │ │ Media Server │ │
|
|
||||||
│ │ Entity │ │ │ │ (FastAPI) │ │
|
|
||||||
│ └───────────────┘ │ │ └───────┬───────┘ │
|
|
||||||
│ ┌───────────────┐ │ │ │ │
|
|
||||||
│ │ Script Button │ │ │ ┌───────▼───────┐ │
|
|
||||||
│ │ Entities │ │ │ │ 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)
|
|
||||||
- Real-time updates via WebSocket
|
|
||||||
- Script buttons (shutdown, restart, lock, sleep, hibernate, custom)
|
|
||||||
- Secure token-based authentication
|
|
||||||
|
|
||||||
## Quick Start
|
|
||||||
|
|
||||||
### 1. Set up the Media Server (on your PC)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd media-server
|
|
||||||
pip install . # or pip install .[windows] on Windows
|
|
||||||
python -m media_server.main
|
|
||||||
```
|
|
||||||
|
|
||||||
See [Media Server README](media-server/README.md) for detailed instructions.
|
|
||||||
|
|
||||||
### 2. Set up Home Assistant Integration
|
|
||||||
|
|
||||||
Copy `haos-integration/custom_components/remote_media_player/` to your HA config folder, or install via HACS.
|
|
||||||
|
|
||||||
See [HAOS Integration README](haos-integration/README.md) for detailed instructions.
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT License
|
MIT License
|
||||||
|
|||||||
Reference in New Issue
Block a user