alexei.dolgolyov/media-player-mixed
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README with comprehensive feature documentation

Browse Source 
- 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:
Admin
2026-03-23 02:21:38 +03:00
parent cfd1c92905
commit 19323085cc
1 changed files with 169 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+169 -57
View File
@@ -1,15 +1,177 @@
# 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:
## 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 |
|-----------|-------------|------------|
| [media-server](media-server/) | REST API server for your PC | [media-player-server](https://git.dolgolyov-family.by/alexei.dolgolyov/media-player-server) |
| [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) |
## Architecture
```text
┌─────────────────────┐ 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
@@ -17,60 +179,10 @@ This repository contains two independent components as git submodules:
# Clone with submodules
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
```
## 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
MIT License