music-assistant-server

1# Universal Player Provider
2
3## Overview
4
5The Universal Player provider creates virtual players that merge multiple protocol players (AirPlay, Chromecast, DLNA, Squeezelite, SendSpin) for the same physical device into a single unified player.
6
7## When is a Universal Player Created?
8
9A Universal Player is automatically created by the PlayerController when:
10
111. **Multiple protocol players are detected for the same device** - Based on MAC address or IP matching
122. **No native player provider exists** - e.g., a Denon AVR with Chromecast, AirPlay, and DLNA but no native Denon integration
13
14## Example Scenario
15
16Consider a Denon AVR receiver that supports:
17- Chromecast built-in
18- AirPlay 2
19- DLNA
20
21Without a native Denon provider in Music Assistant, the system would normally show three separate players:
22- "Living Room (Chromecast)"
23- "Living Room (AirPlay)"
24- "Living Room (DLNA)"
25
26With the Universal Player provider, these are merged into a single:
27- "Living Room" (Universal Player)
28  - Output protocols: Chromecast, AirPlay, DLNA
29
30## How It Works
31
32### Device Matching
33
34Protocol players are matched to the same device using:
351. **MAC address** - Most reliable, extracted from device info
362. **IP address** - Fallback when MAC is not available
37
38### Player Creation Flow
39
40```
411. Chromecast player registers → No native parent, no other protocols → Stays as regular player
422. AirPlay player registers → Matches Chromecast by MAC → PlayerController creates UniversalPlayer
433. DLNA player registers → Matches existing UniversalPlayer → Added as linked protocol
44```
45
46### Feature Aggregation
47
48The Universal Player aggregates features from all linked protocols:
49- Volume control from the protocol that supports it best
50- Power control from any protocol that supports it
51- Pause/Play from active protocol
52
53### Playback Routing
54
55The Universal Player does NOT have `PLAY_MEDIA` capability. Instead:
561. User selects "Living Room" and starts playback
572. PlayerController uses `_select_best_output_protocol()` to choose best protocol
583. Playback is routed to the selected protocol player (e.g., Chromecast)
594. User can switch to different protocol in player settings
60
61## Configuration
62
63Universal Players are auto-created and require no user configuration. However, users can:
64- Rename the player
65- Choose preferred output protocol
66- Disable/enable the player
67
68## Cleanup
69
70When all protocol players for a device are removed (e.g., provider unloaded), the Universal Player is automatically cleaned up.
71
72If a native provider is later installed (e.g., Denon integration), the Universal Player is replaced by the native player, with all protocols linked to it instead.
73
74## Technical Details
75
76### Player ID Format
77
78Universal players use the format: `up{device_key}`
79
80Where `device_key` is typically the normalized MAC address.
81
82### File Structure
83
84```
85universal_player/
86├── __init__.py      # Provider setup
87├── provider.py      # UniversalPlayerProvider class
88├── player.py        # UniversalPlayer class
89├── constants.py     # Constants (prefix, etc.)
90├── manifest.json    # Provider manifest (builtin)
91└── README.md        # This file
92```
93
94### Provider Features
95
96The Universal Player provider has no special provider features - it doesn't support manual player creation via the UI. Players are only created automatically by the PlayerController.
97