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. **One or more protocol players are detected for the same device** - Matching prefers MAC/serial/UUID-style identifiers and only falls back to IP as a last resort
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. **Serial / UUID / protocol-specific IDs** - Used before any IP fallback
373. **IP address** - Last resort when strong identifiers are missing or unreliable
38
39The controller will also try to validate or enrich reported MAC addresses with ARP before falling back to weaker matching.
40
41### Player Creation Flow
42
43```
441. Chromecast player registers → No native parent → delayed evaluation is scheduled
452. No native player appears → PlayerController creates a UniversalPlayer, even for this single unmatched protocol
463. AirPlay player registers → Matches existing UniversalPlayer by identifiers → gets linked to it
474. DLNA player registers → Matches existing UniversalPlayer → Added as linked protocol
48```
49
50### Feature Aggregation
51
52The Universal Player aggregates features from all linked protocols:
53- Volume control from the protocol that supports it best
54- Power control from any protocol that supports it
55- Pause/Play from active protocol
56
57### Playback Routing
58
59The Universal Player does NOT have `PLAY_MEDIA` capability. Instead:
601. User selects "Living Room" and starts playback
612. PlayerController uses `_select_best_output_protocol()` to choose best protocol
623. Playback is routed to the selected protocol player (e.g., Chromecast)
634. User can switch to different protocol in player settings
64
65## Configuration
66
67Universal Players are auto-created and require no user configuration. However, users can:
68- Rename the player
69- Choose preferred output protocol
70- Disable/enable the player
71- Remove the universal player to wipe its config and restart protocol discovery from scratch
72
73## Cleanup
74
75When a Universal Player is permanently removed, all protocol parent links are cleared so discovery can start over cleanly.
76
77If 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.
78
79## Technical Details
80
81### Player ID Format
82
83Universal players use the format: `up{device_key}`
84
85Where `device_key` is typically the normalized MAC address.
86If no stable MAC is available, the provider falls back to UUID-like identifiers and finally the first protocol player's ID.
87
88### File Structure
89
90```
91universal_player/
92├── __init__.py      # Provider setup
93├── provider.py      # UniversalPlayerProvider class
94├── player.py        # UniversalPlayer class
95├── constants.py     # Constants (prefix, etc.)
96├── manifest.json    # Provider manifest (builtin)
97└── README.md        # This file
98```
99
100### Provider Features
101
102The 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.
103