music-assistant-server
225 KB•PY
controller.py
225 KB • 4,870 lines • python
1"""
2MusicAssistant PlayerController.
3
4Handles all logic to control supported players,
5which are provided by Player Providers.
6
7Note that the PlayerController has a concept of a 'player' and a 'playerstate'.
8The Player is the actual object that is provided by the provider,
9which incorporates the (unaltered) state of the player (e.g. volume, state, etc)
10and functions for controlling the player (e.g. play, pause, etc).
11
12The playerstate is the (final) state of the player, including any user customizations
13and transformations that are applied to the player.
14The playerstate is the object that is exposed to the outside world (via the API).
15"""
16
17from __future__ import annotations
18
19import asyncio
20import contextlib
21import time
22import weakref
23from collections.abc import AsyncIterator
24from contextlib import suppress
25from typing import TYPE_CHECKING, Any, cast
26
27from music_assistant_models.auth import Scope
28from music_assistant_models.background_task import TaskSchedule
29from music_assistant_models.config_entries import ConfigEntry
30from music_assistant_models.constants import (
31 PLAYER_CONTROL_FAKE,
32 PLAYER_CONTROL_NATIVE,
33 PLAYER_CONTROL_NONE,
34)
35from music_assistant_models.enums import (
36 ConfigEntryType,
37 EventType,
38 IdentifierType,
39 MediaType,
40 PlaybackState,
41 PlayerFeature,
42 PlayerType,
43 ProviderFeature,
44 ProviderType,
45 RepeatMode,
46 SourceControl,
47)
48from music_assistant_models.errors import (
49 AlreadyRegisteredError,
50 InsufficientPermissions,
51 InvalidCommand,
52 InvalidDataError,
53 MusicAssistantError,
54 PlayerCommandFailed,
55 PlayerUnavailableError,
56 ProviderUnavailableError,
57 UnsupportedFeaturedException,
58)
59from music_assistant_models.media_items import AudioSource
60from music_assistant_models.player import PlayerOptionValueType # noqa: TC002
61from music_assistant_models.player_control import PlayerControl # noqa: TC002
62
63from music_assistant.constants import (
64 ATTR_ACTIVE_SOURCE,
65 ATTR_ANNOUNCEMENT_IN_PROGRESS,
66 ATTR_AVAILABLE,
67 ATTR_ENABLED,
68 ATTR_FAKE_MUTE,
69 ATTR_FAKE_POWER,
70 ATTR_FAKE_VOLUME,
71 ATTR_GROUP_MEMBERS,
72 ATTR_GROUP_VOLUME_SNAPSHOT,
73 ATTR_LAST_POLL,
74 ATTR_MUTE_CONTROL,
75 ATTR_MUTE_LOCK,
76 ATTR_POWER_CONTROL,
77 ATTR_POWERED,
78 ATTR_PREVIOUS_VOLUME,
79 ATTR_SUPPORTED_FEATURES,
80 ATTR_VOLUME_CONTROL,
81 ATTR_VOLUME_TARGET,
82 CONF_ANNOUNCE_TTS_ENGINE,
83 CONF_AUTO_PLAY,
84 CONF_CACHED_ARP_MAC,
85 CONF_ENTRY_MAX_VOLUME,
86 CONF_ENTRY_MIN_VOLUME,
87 CONF_GROUP_MEMBERS,
88 CONF_MAX_VOLUME,
89 CONF_MIN_VOLUME,
90 CONF_MUTE_CONTROL,
91 CONF_PLAY_MEDIA_OVERRIDES_GROUP,
92 CONF_PLAYER_DSP,
93 CONF_PLAYER_QUEUES,
94 CONF_PLAYERS,
95 CONF_POWER_CONTROL,
96 CONF_PROTOCOL_PARENT_ID,
97 CONF_REPORTED_MAC,
98 CONF_VOLUME_CONTROL,
99 CONF_VOLUME_STEP,
100 VERBOSE_LOG_LEVEL,
101)
102from music_assistant.controllers.webserver.helpers.auth_middleware import (
103 get_current_user,
104 get_sendspin_player_id,
105 has_scope,
106)
107from music_assistant.helpers.api import api_command
108from music_assistant.helpers.colors import get_palette_for_url
109from music_assistant.helpers.config_entries import PLAYBACK_TARGET_TYPES
110from music_assistant.helpers.plugin_engines import create_tts_engine_config_entries
111from music_assistant.helpers.util import (
112 TaskManager,
113 enrich_device_mac_address,
114 is_valid_mac_address,
115)
116from music_assistant.models.core_controller import CoreController
117from music_assistant.models.player import Player, PlayerMedia, PlayerState
118from music_assistant.models.player_provider import PlayerProvider
119from music_assistant.models.plugin import PluginProvider, SourceControlValue
120
121from .announcements import AnnouncementsMixin
122from .audio_sources import AudioSourceMixin, AudioSourceSession
123from .constants import PlayerLockPurpose
124from .helpers import handle_player_command, wait_for_power_on
125from .protocol_linking import ProtocolLinkingMixin
126
127if TYPE_CHECKING:
128 from collections.abc import Callable, Iterator
129
130 from music_assistant_models.config_entries import (
131 CoreConfig,
132 PlayerConfig,
133 )
134 from music_assistant_models.player import OutputProtocol
135 from music_assistant_models.player_queue import PlayerQueue
136
137 from music_assistant import MusicAssistant
138 from music_assistant.helpers.json import SerializableType
139
140CACHE_CATEGORY_PLAYER_POWER = 1
141
142# state keys that carry the current_media playback-position anchor; these only
143# change on discrete position events (play/pause/seek/track change/buffer correction)
144POSITION_ANCHOR_KEYS = frozenset(
145 {
146 "current_media.elapsed_time",
147 "current_media.elapsed_time_last_updated",
148 }
149)
150
151# How long the volume level of the last command outranks the level the player reports.
152# Long enough to cover a burst of volume nudges on a player that only reports its volume
153# back some time later, short enough for a change made on the device itself to win again.
154VOLUME_TARGET_EXPIRY = 2.0
155
156# How long a freshly started source session may wait for its first stream request
157# before it is considered never started and released.
158AUDIO_SOURCE_CLAIM_TIMEOUT = 30
159
160# How long a player must stay powered off before the queue it was playing is ended.
161# Home Assistant reports an entity that is (briefly) unavailable or unknown as off, so an
162# external power control can report a power off that comes straight back - which must not
163# stop the music. Long enough to sit out a reloading integration or a device missing a
164# poll, short enough that a real power off is not left streaming.
165EXTERNAL_POWER_OFF_STOP_DELAY = 15
166
167# Player types that must be detached from their (sync)group when they power off.
168# A stereo pair joins a group and leads a sync session exactly like a single speaker does.
169# A GROUP player has no group of its own to leave: its members are released by its own
170# power off, and ungrouping one is defined as powering it off - which is what already
171# brought it here.
172UNGROUP_ON_POWER_OFF_TYPES = {PlayerType.PLAYER, PlayerType.STEREO_PAIR}
173
174# Sentinel used to detect omitted optional arguments where ``None`` is a valid value.
175_SENTINEL: Any = object()
176
177
178class PlayerController(AnnouncementsMixin, AudioSourceMixin, ProtocolLinkingMixin, CoreController):
179 """Controller holding all logic to control registered players."""
180
181 domain: str = "players"
182
183 def __init__(self, mass: MusicAssistant) -> None:
184 """Initialize core controller."""
185 super().__init__(mass)
186 self._players: dict[str, Player] = {}
187 self._controls: dict[str, PlayerControl] = {}
188 self.manifest.name = "Player Controller"
189 self.manifest.description = (
190 "Music Assistant's core controller which manages all players from all providers."
191 )
192 self.manifest.icon = "speaker-multiple"
193 self._poll_task: asyncio.Task[None] | None = None
194 self._player_command_locks: dict[str, asyncio.Lock] = {}
195 # Re-entrancy tracking for get_player_lock, keyed on the task object
196 # (weak ref auto-clears entries if a task is GC'd before its finally runs).
197 self._task_held_locks: weakref.WeakKeyDictionary[asyncio.Task[Any], set[str]] = (
198 weakref.WeakKeyDictionary()
199 )
200 # Lock to prevent race conditions during player registration
201 self._register_lock = asyncio.Lock()
202 # Track pending protocol player evaluations (delayed to allow all protocols to register)
203 self._pending_protocol_evaluations: dict[str, asyncio.TimerHandle] = {}
204 # Serialize delayed evaluations to prevent race conditions
205 self._delayed_evaluation_lock = asyncio.Lock()
206 # Live external AudioSource playing on a player, keyed on player_id
207 self._source_sessions: dict[str, AudioSourceSession] = {}
208 # Subscribers for player state updates (called with player + changed_values)
209 self._state_update_subscribers: list[
210 Callable[[Player, dict[str, tuple[Any, Any]]], None]
211 ] = []
212
213 @contextlib.asynccontextmanager
214 async def get_player_lock(
215 self, player_id: str, purpose: PlayerLockPurpose = PlayerLockPurpose.PLAYBACK
216 ) -> AsyncIterator[None]:
217 """
218 Acquire a purpose-scoped lock for a player, with re-entrant support.
219
220 Tracks lock ownership per asyncio Task so that nested calls within the same
221 task skip re-acquisition (preventing deadlocks), while deferred callbacks
222 (call_later / create_task) correctly acquire a fresh lock.
223
224 If the lock can't be acquired within 30s the body runs anyway, to keep
225 the player responsive when a previous holder is stuck on a hung command.
226
227 :param player_id: The player to lock.
228 :param purpose: Lock category. Commands with different purposes can run
229 concurrently on the same player.
230 """
231 lock_key = f"{purpose.value}_{player_id}"
232 task = asyncio.current_task()
233
234 if task is not None and lock_key in self._task_held_locks.get(task, set()):
235 yield
236 return
237
238 lock = self._player_command_locks.setdefault(lock_key, asyncio.Lock())
239 # Two-stage acquire: a slow-acquire log at 5s and a hard give-up at 30s.
240 # If the previous holder is stuck (e.g. on a dead provider socket), we
241 # proceed without the lock so this player stays responsive.
242 acquired = False
243 try:
244 async with asyncio.timeout(5):
245 await lock.acquire()
246 acquired = True
247 except TimeoutError:
248 self.logger.debug(
249 "Acquiring %s lock for player %s is slow (>5s)", purpose.value, player_id
250 )
251 try:
252 async with asyncio.timeout(25):
253 await lock.acquire()
254 acquired = True
255 except TimeoutError:
256 self.logger.warning(
257 "Timed out (30s) acquiring %s lock for player %s â "
258 "previous holder appears stuck; proceeding without lock",
259 purpose.value,
260 player_id,
261 )
262
263 if acquired and task is not None:
264 self._task_held_locks.setdefault(task, set()).add(lock_key)
265 try:
266 yield
267 finally:
268 if acquired:
269 if task is not None and (held := self._task_held_locks.get(task)) is not None:
270 held.discard(lock_key)
271 if not held:
272 del self._task_held_locks[task]
273 lock.release()
274
275 async def get_config_entries(self) -> tuple[ConfigEntry, ...]:
276 """Return Config Entries for the Player Controller."""
277 return (
278 ConfigEntry(
279 key=CONF_VOLUME_STEP,
280 type=ConfigEntryType.INTEGER,
281 default_value=0,
282 range=(0, 10),
283 required=False,
284 category="generic",
285 ),
286 *await create_tts_engine_config_entries(
287 self.mass, CONF_ANNOUNCE_TTS_ENGINE, category="announcements"
288 ),
289 )
290
291 async def setup(self, config: CoreConfig) -> None:
292 """Async initialize of module."""
293 self._repair_protocol_parent_links()
294 self._poll_task = self.mass.create_task(self._poll_players())
295 self.mass.tasks.register_scheduled_task(
296 task_id="fix_group_member_configs",
297 name="Fix sync group member configurations",
298 handler=self._fix_group_member_configs,
299 schedule=TaskSchedule.weekly(
300 days_of_week=[0],
301 hour=4,
302 minute=0,
303 ),
304 initial_delay=300,
305 )
306
307 async def close(self) -> None:
308 """Cleanup on exit."""
309 if self._poll_task and not self._poll_task.done():
310 self._poll_task.cancel()
311 # Cancel all pending protocol evaluations
312 for handle in self._pending_protocol_evaluations.values():
313 handle.cancel()
314 self._pending_protocol_evaluations.clear()
315 for player in self._players.values():
316 if player.sleep_timer_expires_at is not None:
317 self.mass.cancel_timer(self._sleep_timer_task_id(player.player_id))
318
319 async def get_diagnostics(self) -> dict[str, SerializableType]:
320 """Return diagnostics info for this controller to include in diagnostics reports."""
321 players = list(self._players.values())
322 return {
323 "players_synced": sum(player.state.synced_to is not None for player in players),
324 "players_with_active_group": sum(
325 player.state.active_group is not None for player in players
326 ),
327 "announcements_in_progress": sum(
328 bool(player.extra_data.get(ATTR_ANNOUNCEMENT_IN_PROGRESS)) for player in players
329 ),
330 "pending_protocol_evaluations": len(self._pending_protocol_evaluations),
331 }
332
333 async def on_provider_loaded(self, provider: PlayerProvider) -> None:
334 """Handle logic when a provider is loaded."""
335
336 async def on_provider_unload(self, provider: PlayerProvider) -> None:
337 """Handle logic when a provider is (about to get) unloaded."""
338
339 @property
340 def providers(self) -> list[PlayerProvider]:
341 """Return all loaded/running MusicProviders."""
342 return cast("list[PlayerProvider]", self.mass.get_providers(ProviderType.PLAYER))
343
344 def iter_players(
345 self,
346 return_unavailable: bool = True,
347 return_disabled: bool = False,
348 provider_filter: str | None = None,
349 return_protocol_players: bool = False,
350 ) -> Iterator[Player]:
351 """
352 Iterate over all registered players, regardless of who is asking.
353
354 Use this for internal logic - state derivation, bookkeeping and topology
355 lookups - which must stay correct no matter which user's command happened
356 to trigger it. Use :meth:`all_players` for anything presented to a user.
357
358 :param return_unavailable [bool]: Include unavailable players.
359 :param return_disabled [bool]: Include disabled players.
360 :param provider_filter [str]: Optional filter by provider lookup key.
361 :param return_protocol_players [bool]: Include protocol players (hidden by default).
362 """
363 for player in list(self._players.values()):
364 if not (player.state.available or return_unavailable):
365 continue
366 if not (player.state.enabled or return_disabled):
367 continue
368 if not player.initialized.is_set():
369 continue
370 if provider_filter is not None and player.provider.instance_id != provider_filter:
371 continue
372 if not return_protocol_players and player.state.type == PlayerType.PROTOCOL:
373 continue
374 yield player
375
376 def all_players(
377 self,
378 return_unavailable: bool = True,
379 return_disabled: bool = False,
380 provider_filter: str | None = None,
381 return_protocol_players: bool = False,
382 ) -> list[Player]:
383 """
384 Return the registered players the current user is allowed to see.
385
386 Note that this applies user filters for players (for non admin users),
387 which makes it unsuitable for internal logic - use :meth:`iter_players` there.
388
389 :param return_unavailable [bool]: Include unavailable players.
390 :param return_disabled [bool]: Include disabled players.
391 :param provider_filter [str]: Optional filter by provider lookup key.
392 :param return_protocol_players [bool]: Include protocol players (hidden by default).
393
394 :return: List of Player objects.
395 """
396 current_user = get_current_user()
397 user_filter = (
398 current_user.player_filter
399 if current_user and not has_scope(current_user, Scope.ALL)
400 else None
401 )
402 current_sendspin_player = get_sendspin_player_id()
403 return [
404 player
405 for player in self.iter_players(
406 return_unavailable=return_unavailable,
407 return_disabled=return_disabled,
408 provider_filter=provider_filter,
409 return_protocol_players=return_protocol_players,
410 )
411 if not user_filter
412 or player.player_id in user_filter
413 or player.player_id == current_sendspin_player
414 ]
415
416 @api_command("players/all", required_scope=Scope.PLAYERS_READ)
417 def all_player_states(
418 self,
419 return_unavailable: bool = True,
420 return_disabled: bool = False,
421 provider_filter: str | None = None,
422 return_protocol_players: bool = False,
423 ) -> list[PlayerState]:
424 """
425 Return PlayerState for all registered players.
426
427 :param return_unavailable [bool]: Include unavailable players.
428 :param return_disabled [bool]: Include disabled players.
429 :param provider_filter [str]: Optional filter by provider lookup key.
430 :param return_protocol_players [bool]: Include protocol players (hidden by default).
431
432 :return: List of PlayerState objects.
433 """
434 return [
435 player.state
436 for player in self.all_players(
437 return_unavailable=return_unavailable,
438 return_disabled=return_disabled,
439 provider_filter=provider_filter,
440 return_protocol_players=return_protocol_players,
441 )
442 ]
443
444 def get_player(
445 self,
446 player_id: str,
447 raise_unavailable: bool = False,
448 ) -> Player | None:
449 """
450 Return Player by player_id.
451
452 :param player_id [str]: ID of the player.
453 :param raise_unavailable [bool]: Raise if player is unavailable.
454
455 :raises PlayerUnavailableError: If player is unavailable and raise_unavailable is True.
456 :return: Player object or None.
457 """
458 if player := self._players.get(player_id):
459 if (not player.state.available or not player.state.enabled) and raise_unavailable:
460 msg = f"Player {player_id} is not available"
461 raise PlayerUnavailableError(msg)
462 return player
463 if raise_unavailable:
464 msg = f"Player {player_id} is not available"
465 raise PlayerUnavailableError(msg)
466 return None
467
468 @api_command("players/get", required_scope=Scope.PLAYERS_READ)
469 def get_player_state(
470 self,
471 player_id: str,
472 raise_unavailable: bool = False,
473 ) -> PlayerState | None:
474 """
475 Return PlayerState by player_id.
476
477 :param player_id [str]: ID of the player.
478 :param raise_unavailable [bool]: Raise if player is unavailable.
479
480 :raises PlayerUnavailableError: If player is unavailable and raise_unavailable is True.
481 :return: Player object or None.
482 """
483 current_user = get_current_user()
484 user_filter = (
485 current_user.player_filter
486 if current_user and not has_scope(current_user, Scope.ALL)
487 else None
488 )
489 current_sendspin_player = get_sendspin_player_id()
490 if (
491 current_user
492 and user_filter
493 and player_id not in user_filter
494 and player_id != current_sendspin_player
495 ):
496 msg = f"{current_user.username} does not have access to player {player_id}"
497 raise InsufficientPermissions(msg)
498 if player := self.get_player(player_id, raise_unavailable):
499 return player.state
500 return None
501
502 def get_player_by_name(self, name: str) -> Player | None:
503 """
504 Return Player by name.
505
506 Performs case-insensitive matching against the player's state name
507 (the final name visible in clients and API).
508 If multiple players match, logs a warning and returns the first match.
509
510 :param name: Name of the player.
511 :return: Player object or None.
512 """
513 name_normalized = name.strip().lower()
514 matches: list[Player] = []
515
516 for player in list(self._players.values()):
517 if player.state.name.strip().lower() == name_normalized:
518 matches.append(player)
519
520 if not matches:
521 return None
522
523 if len(matches) > 1:
524 player_ids = [p.player_id for p in matches]
525 self.logger.warning(
526 "players/get_by_name: Multiple players found with name '%s': %s - "
527 "returning first match (%s). "
528 "Consider using the players/get API with player_id instead "
529 "for unambiguous lookups.",
530 name,
531 player_ids,
532 matches[0].player_id,
533 )
534
535 return matches[0]
536
537 @api_command("players/get_by_name", required_scope=Scope.PLAYERS_READ)
538 def get_player_state_by_name(self, name: str) -> PlayerState | None:
539 """
540 Return PlayerState by name.
541
542 :param name: Name of the player.
543 :return: PlayerState object or None.
544 """
545 current_user = get_current_user()
546 user_filter = (
547 current_user.player_filter
548 if current_user and not has_scope(current_user, Scope.ALL)
549 else None
550 )
551 current_sendspin_player = get_sendspin_player_id()
552 if player := self.get_player_by_name(name):
553 if (
554 current_user
555 and user_filter
556 and player.player_id not in user_filter
557 and player.player_id != current_sendspin_player
558 ):
559 msg = f"{current_user.username} does not have access to player {player.player_id}"
560 raise InsufficientPermissions(msg)
561 return player.state
562 return None
563
564 @api_command("players/player_controls", required_scope=Scope.PLAYERS_READ)
565 def player_controls(
566 self,
567 ) -> list[PlayerControl]:
568 """Return all registered playercontrols."""
569 return list(self._controls.values())
570
571 @api_command("players/player_control", required_scope=Scope.PLAYERS_READ)
572 def get_player_control(
573 self,
574 control_id: str,
575 ) -> PlayerControl | None:
576 """
577 Return PlayerControl by control_id.
578
579 :param control_id: ID of the player control.
580 :return: PlayerControl object or None.
581 """
582 if control := self._controls.get(control_id):
583 return control
584 return None
585
586 @api_command("players/sleep_timer/get", required_scope=Scope.PLAYERS_READ)
587 def get_sleep_timer(self, player_id: str) -> float | None:
588 """
589 Return the active sleep timer expiry timestamp for the player.
590
591 :param player_id: Player ID to check.
592 """
593 player = self._get_player_with_redirect(player_id)
594 return player.sleep_timer_expires_at
595
596 @api_command("players/sleep_timer/set", required_scope=Scope.PLAYERS_CONTROL)
597 def set_sleep_timer(self, player_id: str, seconds: int) -> float:
598 """
599 Set a sleep timer for the player.
600
601 :param player_id: Player ID to set the timer for.
602 :param seconds: Delay in seconds before playback is stopped.
603 """
604 if seconds <= 0:
605 msg = "Sleep timer duration must be greater than zero seconds"
606 raise InvalidDataError(msg)
607 player = self._get_player_with_redirect(player_id)
608 try:
609 # guard against absurd durations that overflow the float timestamp math
610 expires_at = time.time() + seconds
611 except OverflowError:
612 msg = "Sleep timer duration is too large to schedule"
613 raise InvalidDataError(msg) from None
614 player.set_sleep_timer_expires_at(expires_at)
615 player.update_state()
616 self._signal_sleep_timer_updated(player, expires_at)
617 self.mass.call_later(
618 seconds,
619 self._handle_sleep_timer_expired,
620 player.player_id,
621 task_id=self._sleep_timer_task_id(player.player_id),
622 )
623 return expires_at
624
625 @api_command("players/sleep_timer/clear", required_scope=Scope.PLAYERS_CONTROL)
626 def clear_sleep_timer(self, player_id: str) -> None:
627 """
628 Clear the active sleep timer for the player.
629
630 :param player_id: Player ID to clear the timer for.
631 """
632 player = self._get_player_with_redirect(player_id)
633 self._clear_sleep_timer(player)
634
635 # Player commands
636
637 @api_command("players/cmd/stop", required_scope=Scope.PLAYERS_CONTROL)
638 @handle_player_command
639 async def cmd_stop(self, player_id: str) -> None:
640 """
641 Send STOP command to given player.
642
643 - player_id: player_id of the player to handle the command.
644 """
645 player = self._get_player_with_redirect(player_id)
646 async with self.get_player_lock(player.player_id, PlayerLockPurpose.PLAYBACK):
647 # Redirect to queue controller if it is active (skip if already in queue command context)
648 if active_queue := self.get_active_queue(player):
649 await self.mass.player_queues.stop(active_queue.queue_id)
650 return
651 # Delegate to internal handler for actual implementation
652 await self._handle_cmd_stop(player.player_id)
653
654 @api_command("players/cmd/play", required_scope=Scope.PLAYERS_CONTROL)
655 @handle_player_command
656 async def cmd_play(self, player_id: str) -> None:
657 """
658 Send PLAY (unpause) command to given player.
659
660 - player_id: player_id of the player to handle the command.
661 """
662 player = self._get_player_with_redirect(player_id)
663 async with self.get_player_lock(player.player_id, PlayerLockPurpose.PLAYBACK):
664 if player.state.playback_state == PlaybackState.PLAYING:
665 self.logger.info(
666 "Ignore PLAY request to player %s: player is already playing",
667 player.state.name,
668 )
669 return
670 # player is not paused: check for queue redirect, then delegate to internal handler
671 if player.state.playback_state != PlaybackState.PAUSED:
672 source = player.state.active_source
673 if active_queue := self.mass.player_queues.get(source or player_id):
674 await self.mass.player_queues.resume(active_queue.queue_id)
675 return
676 # Delegate to internal handler for actual implementation
677 await self._handle_cmd_play(player.player_id)
678
679 @api_command("players/cmd/pause", required_scope=Scope.PLAYERS_CONTROL)
680 @handle_player_command
681 async def cmd_pause(self, player_id: str) -> None:
682 """
683 Send PAUSE command to given player.
684
685 - player_id: player_id of the player to handle the command.
686 """
687 player = self._get_player_with_redirect(player_id)
688 # Redirect to queue controller if it is active (skip if already in queue command context)
689 if active_queue := self.get_active_queue(player):
690 await self.mass.player_queues.pause(active_queue.queue_id)
691 return
692 # Delegate to internal handler for actual implementation
693 await self._handle_cmd_pause(player.player_id)
694
695 @api_command("players/cmd/play_pause", required_scope=Scope.PLAYERS_CONTROL)
696 async def cmd_play_pause(self, player_id: str) -> None:
697 """
698 Toggle play/pause on given player.
699
700 - player_id: player_id of the player to handle the command.
701 """
702 player = self._get_player_with_redirect(player_id)
703 if player.state.playback_state == PlaybackState.PLAYING:
704 await self.cmd_pause(player.player_id)
705 else:
706 await self.cmd_play(player.player_id)
707
708 @api_command("players/cmd/resume", required_scope=Scope.PLAYERS_CONTROL)
709 @handle_player_command
710 async def cmd_resume(
711 self, player_id: str, source: str | None = None, media: PlayerMedia | None = None
712 ) -> None:
713 """
714 Send RESUME command to given player.
715
716 Resume (or restart) playback on the player.
717
718 :param player_id: player_id of the player to handle the command.
719 :param source: Optional source to resume.
720 :param media: Optional media to resume.
721 """
722 player = self._get_player_with_redirect(player_id)
723 async with self.get_player_lock(player.player_id, PlayerLockPurpose.PLAYBACK):
724 await self._handle_cmd_resume(player.player_id, source, media)
725
726 @api_command("players/cmd/seek", required_scope=Scope.PLAYERS_CONTROL)
727 @handle_player_command
728 async def cmd_seek(self, player_id: str, position: int) -> None:
729 """
730 Handle SEEK command for given player.
731
732 - player_id: player_id of the player to handle the command.
733 - position: position in seconds to seek to in the current playing item.
734 """
735 player = self._get_player_with_redirect(player_id)
736 if await self._forward_to_external_source(player, SourceControl.SEEK, position):
737 return
738 # Redirect to queue controller if it is active
739 if active_queue := self.get_active_queue(player):
740 await self.mass.player_queues.seek(active_queue.queue_id, position)
741 return
742 # handle command on player/source directly
743 active_source = next(
744 (x for x in player.state.source_list if x.id == player.state.active_source), None
745 )
746 if active_source and not active_source.can_seek:
747 msg = (
748 f"The active source ({active_source.name}) on player "
749 f"{player.display_name} does not support seeking"
750 )
751 raise PlayerCommandFailed(msg)
752 if PlayerFeature.SEEK not in player.state.supported_features:
753 msg = f"Player {player.display_name} does not support seeking"
754 raise UnsupportedFeaturedException(msg)
755 # handle command on player directly
756 await player.seek(position)
757
758 @api_command("players/cmd/shuffle", required_scope=Scope.PLAYERS_CONTROL)
759 @handle_player_command
760 async def cmd_shuffle(
761 self, player_id: str, shuffle_enabled: bool, source_id: str | None = None
762 ) -> None:
763 """
764 Handle SHUFFLE command for given player.
765
766 Applies to whatever the player is playing: a live external source orders its
767 own session, a source the device runs itself orders its own content, and
768 Music Assistant's queue orders its own items.
769
770 :param player_id: player_id of the player to handle the command.
771 :param shuffle_enabled: Whether to play the current content shuffled.
772 :param source_id: Optional source (id) the command is aimed at, as listed in the
773 player's source_list. Given one, the command is refused when that source is
774 no longer playing, so it can never land on whatever took the player since.
775 """
776 player = self._get_player_with_redirect(player_id)
777 active_source_id = self._resolve_command_target(player, source_id)
778 if await self._forward_to_external_source(player, SourceControl.SHUFFLE, shuffle_enabled):
779 return
780 if active_queue := self.get_active_queue(player):
781 await self.mass.player_queues.set_shuffle(active_queue.queue_id, shuffle_enabled)
782 return
783 if active_source := next(
784 (x for x in player.state.source_list if x.id == active_source_id), None
785 ):
786 # the source belongs to the player itself (its own Spotify Connect, a device input)
787 if not active_source.can_shuffle:
788 msg = "This action is (currently) unavailable for this source."
789 raise PlayerCommandFailed(msg)
790 await player.set_shuffle(shuffle_enabled)
791 return
792 msg = f"There is nothing playing on {player.state.name} to shuffle."
793 raise PlayerCommandFailed(msg)
794
795 @api_command("players/cmd/repeat", required_scope=Scope.PLAYERS_CONTROL)
796 @handle_player_command
797 async def cmd_repeat(
798 self, player_id: str, repeat_mode: RepeatMode, source_id: str | None = None
799 ) -> None:
800 """
801 Handle REPEAT command for given player.
802
803 Applies to whatever the player is playing: a live external source repeats
804 within its own session, a source the device runs itself repeats its own
805 content, and Music Assistant's queue repeats its own items.
806
807 :param player_id: player_id of the player to handle the command.
808 :param repeat_mode: The repeat mode to apply.
809 :param source_id: Optional source (id) the command is aimed at, as listed in the
810 player's source_list. Given one, the command is refused when that source is
811 no longer playing, so it can never land on whatever took the player since.
812 """
813 if repeat_mode == RepeatMode.UNKNOWN:
814 # not a mode to set: it is what a source reports when it cannot say
815 raise InvalidCommand("Cannot set an unknown repeat mode")
816 player = self._get_player_with_redirect(player_id)
817 active_source_id = self._resolve_command_target(player, source_id)
818 if await self._forward_to_external_source(player, SourceControl.REPEAT, repeat_mode):
819 return
820 if active_queue := self.get_active_queue(player):
821 await self.mass.player_queues.set_repeat(active_queue.queue_id, repeat_mode)
822 return
823 if active_source := next(
824 (x for x in player.state.source_list if x.id == active_source_id), None
825 ):
826 # the source belongs to the player itself (its own Spotify Connect, a device input)
827 if not active_source.can_repeat:
828 msg = "This action is (currently) unavailable for this source."
829 raise PlayerCommandFailed(msg)
830 await player.set_repeat(repeat_mode)
831 return
832 msg = f"There is nothing playing on {player.state.name} to repeat."
833 raise PlayerCommandFailed(msg)
834
835 @api_command("players/cmd/next", required_scope=Scope.PLAYERS_CONTROL)
836 @handle_player_command
837 async def cmd_next_track(self, player_id: str) -> None:
838 """Handle NEXT TRACK command for given player."""
839 player = self._get_player_with_redirect(player_id)
840 active_source_id = player.state.active_source or player.player_id
841 if await self._forward_to_external_source(player, SourceControl.NEXT):
842 return
843 # Redirect to queue controller if it is active
844 if active_queue := self.get_active_queue(player):
845 await self.mass.player_queues.next(active_queue.queue_id)
846 return
847 if PlayerFeature.NEXT_PREVIOUS in player.state.supported_features:
848 # player has some other source active and native next/previous support
849 active_source = next(
850 (x for x in player.state.source_list if x.id == active_source_id), None
851 )
852 if active_source and active_source.can_next_previous:
853 await player.next_track()
854 return
855 msg = "This action is (currently) unavailable for this source."
856 raise PlayerCommandFailed(msg)
857 # Player does not support next/previous feature
858 msg = f"Player {player.state.name} does not support skipping to the next track."
859 raise UnsupportedFeaturedException(msg)
860
861 @api_command("players/cmd/previous", required_scope=Scope.PLAYERS_CONTROL)
862 @handle_player_command
863 async def cmd_previous_track(self, player_id: str) -> None:
864 """Handle PREVIOUS TRACK command for given player."""
865 player = self._get_player_with_redirect(player_id)
866 active_source_id = player.state.active_source or player.player_id
867 if await self._forward_to_external_source(player, SourceControl.PREVIOUS):
868 return
869 # Redirect to queue controller if it is active
870 if active_queue := self.get_active_queue(player):
871 await self.mass.player_queues.previous(active_queue.queue_id)
872 return
873 if PlayerFeature.NEXT_PREVIOUS in player.state.supported_features:
874 # player has some other source active and native next/previous support
875 active_source = next(
876 (x for x in player.state.source_list if x.id == active_source_id), None
877 )
878 if active_source and active_source.can_next_previous:
879 await player.previous_track()
880 return
881 msg = "This action is (currently) unavailable for this source."
882 raise PlayerCommandFailed(msg)
883 # Player does not support next/previous feature
884 msg = f"Player {player.state.name} does not support skipping to the previous track."
885 raise UnsupportedFeaturedException(msg)
886
887 @api_command("players/cmd/power", required_scope=Scope.PLAYERS_CONTROL)
888 @handle_player_command(lock=PlayerLockPurpose.PLAYBACK)
889 async def cmd_power(self, player_id: str, powered: bool) -> None:
890 """
891 Send POWER command to given player.
892
893 :param player_id: player_id of the player to handle the command.
894 :param powered: bool if player should be powered on or off.
895 """
896 # Power is serialized with PLAYBACK because powering on a sync/group player
897 # forms the group (and powering off dissolves it) - this must not race with
898 # play_media / cmd_resume / cmd_set_members on the same player.
899 await self._handle_cmd_power(player_id, powered)
900
901 @api_command("players/cmd/volume_set", required_scope=Scope.PLAYERS_CONTROL)
902 @handle_player_command
903 async def cmd_volume_set(self, player_id: str, volume_level: int) -> None:
904 """
905 Send VOLUME_SET command to given player.
906
907 :param player_id: player_id of the player to handle the command.
908 :param volume_level: volume level (0..100) to set on the player.
909 """
910 volume_level = max(0, min(100, volume_level))
911 # record the level and invalidate the group volume state up front, before waiting
912 # for the volume lock: a command that is still queued would otherwise undo what a
913 # command issued after it already recorded.
914 # skip for group players since _handle_cmd_volume_set redirects those to
915 # set_group_volume which creates/uses the snapshot itself
916 if (player := self.get_player(player_id)) and player.type != PlayerType.GROUP:
917 self._record_volume_target(player, volume_level)
918 self._invalidate_group_volume_snapshot(player_id)
919 async with self.get_player_lock(player_id, PlayerLockPurpose.VOLUME):
920 await self._handle_cmd_volume_set(player_id, volume_level, record_target=False)
921
922 @api_command("players/cmd/volume_up", required_scope=Scope.PLAYERS_CONTROL)
923 @handle_player_command
924 async def cmd_volume_up(self, player_id: str) -> None:
925 """
926 Send VOLUME_UP command to given player.
927
928 - player_id: player_id of the player to handle the command.
929 """
930 if not (player := self.get_player(player_id)):
931 return
932 if player.type == PlayerType.GROUP:
933 await self.cmd_group_volume_up(player_id)
934 return
935 current_volume = self._volume_nudge_base(player) or 0
936 new_volume = min(100, current_volume + self._get_volume_step(current_volume))
937 await self.cmd_volume_set(player_id, new_volume)
938
939 @api_command("players/cmd/volume_down", required_scope=Scope.PLAYERS_CONTROL)
940 @handle_player_command
941 async def cmd_volume_down(self, player_id: str) -> None:
942 """
943 Send VOLUME_DOWN command to given player.
944
945 - player_id: player_id of the player to handle the command.
946 """
947 if not (player := self.get_player(player_id)):
948 return
949 if player.type == PlayerType.GROUP:
950 await self.cmd_group_volume_down(player_id)
951 return
952 current_volume = self._volume_nudge_base(player) or 0
953 new_volume = max(0, current_volume - self._get_volume_step(current_volume))
954 await self.cmd_volume_set(player_id, new_volume)
955
956 @api_command("players/cmd/group_volume", required_scope=Scope.PLAYERS_CONTROL)
957 @handle_player_command
958 async def cmd_group_volume(
959 self,
960 player_id: str,
961 volume_level: int,
962 ) -> None:
963 """
964 Handle adjusting the overall/group volume to a playergroup (or synced players).
965
966 Will set a new (overall) volume level to a group player or syncgroup.
967
968 :param player_id: Player ID of group player or syncleader to handle the command.
969 :param volume_level: Volume level (0..100) to set to the group.
970 """
971 player = self.get_player(player_id, True)
972 assert player is not None # for type checker
973 group_player = self._resolve_group_volume_player(player)
974 if group_player is None:
975 # treat as normal player volume change
976 await self.cmd_volume_set(player_id, volume_level)
977 return
978 async with self.get_player_lock(group_player.player_id, PlayerLockPurpose.GROUP_VOLUME):
979 await self.set_group_volume(group_player, volume_level)
980
981 @api_command("players/cmd/group_volume_up", required_scope=Scope.PLAYERS_CONTROL)
982 @handle_player_command
983 async def cmd_group_volume_up(self, player_id: str) -> None:
984 """
985 Send VOLUME_UP command to given playergroup.
986
987 - player_id: player_id of the player to handle the command.
988 """
989 player = self.get_player(player_id, True)
990 assert player is not None # for type checker
991 # step from the volume of the group as a whole, which is not the volume of the
992 # addressed player when the command is addressed to one of its synced members
993 group_player = self._resolve_group_volume_player(player) or player
994 async with self.get_player_lock(group_player.player_id, PlayerLockPurpose.GROUP_VOLUME):
995 cur_volume = self._group_volume_nudge_base(group_player)
996 if cur_volume is None:
997 return
998 new_volume = min(100, cur_volume + self._get_volume_step(cur_volume))
999 await self.cmd_group_volume(player_id, new_volume)
1000
1001 @api_command("players/cmd/group_volume_down", required_scope=Scope.PLAYERS_CONTROL)
1002 @handle_player_command
1003 async def cmd_group_volume_down(self, player_id: str) -> None:
1004 """
1005 Send VOLUME_DOWN command to given playergroup.
1006
1007 - player_id: player_id of the player to handle the command.
1008 """
1009 player = self.get_player(player_id, True)
1010 assert player is not None # for type checker
1011 group_player = self._resolve_group_volume_player(player) or player
1012 async with self.get_player_lock(group_player.player_id, PlayerLockPurpose.GROUP_VOLUME):
1013 cur_volume = self._group_volume_nudge_base(group_player)
1014 if cur_volume is None:
1015 return
1016 new_volume = max(0, cur_volume - self._get_volume_step(cur_volume))
1017 await self.cmd_group_volume(player_id, new_volume)
1018
1019 @api_command("players/cmd/group_volume_mute", required_scope=Scope.PLAYERS_CONTROL)
1020 @handle_player_command
1021 async def cmd_group_volume_mute(self, player_id: str, muted: bool) -> None:
1022 """
1023 Handle muting a playergroup (or synced players) as a whole.
1024
1025 A group player or syncleader mutes all of its members, a synced player is
1026 redirected to its syncleader and an ungrouped player is muted on its own.
1027
1028 :param player_id: Player ID of the player to handle the command.
1029 :param muted: bool if the group should be muted.
1030 """
1031 player = self.get_player(player_id, True)
1032 assert player is not None # for type checker
1033 if player.state.type == PlayerType.GROUP or player.state.group_members:
1034 # dedicated group player or sync leader
1035 await self._mute_group_members(player, muted)
1036 return
1037 if player.state.synced_to and (sync_leader := self.get_player(player.state.synced_to)):
1038 # redirect to sync leader
1039 await self._mute_group_members(sync_leader, muted)
1040 return
1041 # treat as normal player mute
1042 await self.cmd_volume_mute(player_id, muted)
1043
1044 @api_command("players/cmd/volume_mute", required_scope=Scope.PLAYERS_CONTROL)
1045 @handle_player_command(lock=PlayerLockPurpose.VOLUME)
1046 async def cmd_volume_mute(self, player_id: str, muted: bool) -> None:
1047 """
1048 Send VOLUME_MUTE command to given player.
1049
1050 - player_id: player_id of the player to handle the command.
1051 - muted: bool if player should be muted.
1052 """
1053 player = self.get_player(player_id, True)
1054 assert player
1055
1056 if player.type == PlayerType.GROUP:
1057 # redirect to special group mute control
1058 await self.cmd_group_volume_mute(player_id, muted)
1059 return
1060
1061 # clearing the mute lock may not depend on mute support, otherwise a lock set
1062 # while the player still had a mute control would outlive a control change
1063 if not muted:
1064 player.extra_data.pop(ATTR_MUTE_LOCK, None)
1065
1066 mute_control = player.mute_control
1067 if mute_control == PLAYER_CONTROL_NONE:
1068 raise UnsupportedFeaturedException(
1069 f"Player {player.state.name} does not support muting"
1070 )
1071
1072 # Set mute lock for players in a group
1073 # This prevents auto-unmute when group volume changes
1074 had_mute_lock = ATTR_MUTE_LOCK in player.extra_data
1075 if muted and self._is_in_group(player.state):
1076 player.extra_data[ATTR_MUTE_LOCK] = True
1077
1078 try:
1079 await self._handle_cmd_volume_mute(player, mute_control, muted)
1080 except Exception:
1081 # a mute that did not happen may not leave a lock behind, but a lock
1082 # earned by an earlier successful mute must survive
1083 if not had_mute_lock:
1084 player.extra_data.pop(ATTR_MUTE_LOCK, None)
1085 raise
1086
1087 @handle_player_command
1088 async def play_media(self, player_id: str, media: PlayerMedia) -> None:
1089 """
1090 Handle PLAY MEDIA on given player.
1091
1092 :param player_id: player_id of the player to handle the command.
1093 :param media: The Media that needs to be played on the player.
1094 """
1095 # An explicit play_media on a captured player honors the player's
1096 # CONF_PLAY_MEDIA_OVERRIDES_GROUP preference (default: True) â the
1097 # player is released from its group/sync first, then plays the media
1098 # standalone. With the preference off, behavior falls back to the
1099 # legacy "redirect to group leader" path below.
1100 # Note: the release step runs outside the PLAYBACK lock to avoid an
1101 # AB-BA cycle with cmd_set_members(group), which acquires lock(group)
1102 # then lock(sync_leader) via the sync_group provider.
1103 target_player = self.get_player(player_id, True)
1104 if target_player is not None and (
1105 target_player.state.synced_to or target_player.state.active_group
1106 ):
1107 override = bool(
1108 self.mass.config.get_raw_player_config_value(
1109 target_player.player_id,
1110 CONF_PLAY_MEDIA_OVERRIDES_GROUP,
1111 True,
1112 )
1113 )
1114 if override:
1115 await self._release_player_for_play_media(target_player)
1116 async with self.get_player_lock(
1117 target_player.player_id, PlayerLockPurpose.PLAYBACK
1118 ):
1119 await self._handle_play_media(target_player.player_id, media)
1120 return
1121 player = self._get_player_with_redirect(player_id)
1122 async with self.get_player_lock(player.player_id, PlayerLockPurpose.PLAYBACK):
1123 await self._handle_play_media(player.player_id, media)
1124
1125 @api_command("players/cmd/select_sound_mode", required_scope=Scope.PLAYERS_CONTROL)
1126 @handle_player_command
1127 async def select_sound_mode(self, player_id: str, sound_mode: str) -> None:
1128 """
1129 Handle SELECT SOUND MODE command on given player.
1130
1131 - player_id: player_id of the player to handle the command
1132 - sound_mode: The ID of the sound mode that needs to be activated/selected.
1133 """
1134 player = self.get_player(player_id, True)
1135 assert player is not None # for type checking
1136
1137 if PlayerFeature.SELECT_SOUND_MODE not in player.supported_features:
1138 raise UnsupportedFeaturedException(
1139 f"Player {player.display_name} does not support sound mode selection"
1140 )
1141
1142 prev_sound_mode = player.active_sound_mode
1143 if sound_mode == prev_sound_mode:
1144 return
1145
1146 # basic check if sound mode is valid for player
1147 if not any(x for x in player.sound_mode_list if x.id == sound_mode):
1148 raise PlayerCommandFailed(
1149 f"{sound_mode} is an invalid sound_mode for player {player.display_name}"
1150 )
1151
1152 # forward to player
1153 await player.select_sound_mode(sound_mode)
1154
1155 @api_command("players/cmd/set_option", required_scope=Scope.PLAYERS_CONTROL)
1156 @handle_player_command
1157 async def set_option(
1158 self, player_id: str, option_key: str, option_value: PlayerOptionValueType
1159 ) -> None:
1160 """
1161 Handle SET_OPTION command on given player.
1162
1163 - player_id: player_id of the player to handle the command
1164 - option_key: The key of the player option that needs to be activated/selected.
1165 - option_value: The new value of the player option.
1166 """
1167 player = self.get_player(player_id, True)
1168 assert player is not None # for type checking
1169
1170 if PlayerFeature.OPTIONS not in player.supported_features:
1171 raise UnsupportedFeaturedException(
1172 f"Player {player.display_name} does not support set_option"
1173 )
1174
1175 prev_player_option = next((x for x in player.options if x.key == option_key), None)
1176 if not prev_player_option:
1177 return
1178 if prev_player_option.value == option_value:
1179 return
1180
1181 if prev_player_option.read_only:
1182 raise UnsupportedFeaturedException(
1183 f"Player {player.display_name} option {option_key} is read-only"
1184 )
1185
1186 # forward to player
1187 await player.set_option(option_key=option_key, option_value=option_value)
1188
1189 @api_command("players/cmd/select_source", required_scope=Scope.PLAYERS_CONTROL)
1190 @handle_player_command
1191 async def select_source(self, player_id: str, source: str | None) -> None:
1192 """
1193 Handle SELECT SOURCE command on given player.
1194
1195 - player_id: player_id of the player to handle the command.
1196 - source: The ID of the source that needs to be activated/selected.
1197 """
1198 if source is None:
1199 source = player_id # default to MA queue source
1200 player = self.get_player(player_id, True)
1201 assert player is not None # for type checking
1202 # If player is currently grouped, handle it so the source switch can proceed.
1203 # This allows external sources (e.g. Spotify Connect, AirPlay) to take over a grouped player.
1204 if player.state.active_group and (
1205 group_player := self.get_player(player.state.active_group)
1206 ):
1207 if player_id in group_player.state.static_group_members:
1208 # player is a static member of a permanent group - stop the group
1209 # and power it off if supported, rather than removing the member
1210 await self._handle_cmd_stop(group_player.player_id)
1211 if group_player.state.power_control != PLAYER_CONTROL_NONE:
1212 await self._handle_cmd_power(group_player.player_id, False)
1213 else:
1214 await self.cmd_ungroup(player_id)
1215 elif player.state.synced_to:
1216 await self.cmd_ungroup(player_id)
1217 # Delegate to internal handler for actual implementation
1218 async with self.get_player_lock(player_id, PlayerLockPurpose.PLAYBACK):
1219 await self._handle_select_source(player_id, source)
1220
1221 async def deselect_source(
1222 self,
1223 player_id: str,
1224 stop_playback: bool = True,
1225 provider_instance_id: str | None = None,
1226 source_id: str | None = None,
1227 playback_session_id: str | None = None,
1228 ) -> None:
1229 """
1230 Give up the source a player was playing, and stop it.
1231
1232 Call this from a plugin when its session ends â the player has nothing to play
1233 any more, so it goes back to reporting its own queue rather than a source that
1234 has gone. Pausing is not this: a paused source keeps the player, so that its
1235 session survives being resumed.
1236
1237 :param player_id: player_id of the player to give the source up on.
1238 :param stop_playback: Whether to stop the player as well. Pass False when the
1239 caller has already stopped it, or is about to.
1240 :param provider_instance_id: Optional provider instance that owns the source session.
1241 :param source_id: Optional provider-scoped source id that owns the source session.
1242 :param playback_session_id: Optional playback session expected to own the player.
1243 """
1244 async with self.get_player_lock(player_id, PlayerLockPurpose.PLAYBACK):
1245 player = self.get_player(player_id, raise_unavailable=False)
1246 if not player:
1247 return
1248 session = self._source_sessions.get(player_id)
1249 active_provider_instance_id = session.provider_instance_id if session else None
1250 active_source_id = session.source_id if session else None
1251 active_playback_session_id = session.playback_session_id if session else None
1252 if provider_instance_id is not None and (
1253 active_provider_instance_id != provider_instance_id
1254 or (source_id is not None and active_source_id != source_id)
1255 or playback_session_id is None
1256 or active_playback_session_id != playback_session_id
1257 ):
1258 self.logger.debug(
1259 "Ignoring source release for provider %s source %s session %s on player %s: "
1260 "active source is provider %s source %s session %s",
1261 provider_instance_id,
1262 source_id,
1263 playback_session_id,
1264 player_id,
1265 active_provider_instance_id,
1266 active_source_id,
1267 active_playback_session_id,
1268 )
1269 return
1270 try:
1271 if stop_playback:
1272 with suppress(PlayerCommandFailed, PlayerUnavailableError, RuntimeError):
1273 await self._handle_cmd_stop(player_id)
1274 finally:
1275 if session is not None:
1276 current_session = self._source_sessions.get(player_id)
1277 if (
1278 current_session is session
1279 and current_session.playback_session_id == active_playback_session_id
1280 ):
1281 await self._release_audio_source(player_id)
1282 else:
1283 self.logger.debug(
1284 "Not releasing provider %s source %s session %s on player %s: "
1285 "the source changed while playback was stopping",
1286 provider_instance_id,
1287 source_id,
1288 playback_session_id,
1289 player_id,
1290 )
1291
1292 async def release_provider_sources(self, provider_instance_id: str) -> None:
1293 """
1294 Give up the sources a plugin owns on every player playing one.
1295
1296 Call this when the plugin goes away: a session outliving its provider leaves
1297 the player naming a source that can no longer be streamed nor handed back,
1298 with its own queue held inactive behind it.
1299
1300 :param provider_instance_id: Instance id of the plugin that is going away.
1301 """
1302 sessions = [
1303 (player_id, session.source_id, session.playback_session_id)
1304 for player_id, session in self._source_sessions.items()
1305 if session.provider_instance_id == provider_instance_id
1306 ]
1307 for player_id, source_id, playback_session_id in sessions:
1308 self.logger.debug(
1309 "Provider %s is unloading, releasing its source on player %s",
1310 provider_instance_id,
1311 player_id,
1312 )
1313 await self.deselect_source(
1314 player_id,
1315 provider_instance_id=provider_instance_id,
1316 source_id=source_id,
1317 playback_session_id=playback_session_id,
1318 )
1319
1320 @handle_player_command(lock=PlayerLockPurpose.PLAYBACK)
1321 async def enqueue_next_media(self, player_id: str, media: PlayerMedia) -> None:
1322 """
1323 Handle enqueuing of a next media item on the player.
1324
1325 :param player_id: player_id of the player to handle the command.
1326 :param media: The Media that needs to be enqueued on the player.
1327 :raises UnsupportedFeaturedException: if the player does not support enqueueing.
1328 :raises PlayerUnavailableError: if the player is not available.
1329 """
1330 # Note: No group redirect needed here as enqueue doesn't use _get_player_with_redirect
1331 # Delegate to internal handler for actual implementation
1332 await self._handle_enqueue_next_media(player_id, media)
1333
1334 @api_command("players/cmd/set_members", required_scope=Scope.PLAYERS_CONTROL)
1335 async def cmd_set_members(
1336 self,
1337 target_player: str,
1338 player_ids_to_add: list[str] | None = None,
1339 player_ids_to_remove: list[str] | None = None,
1340 ) -> None:
1341 """
1342 Join/unjoin given player(s) to/from target player.
1343
1344 Will add the given player(s) to the target player (sync leader or group player).
1345
1346 :param target_player: player_id of the syncgroup leader or group player.
1347 :param player_ids_to_add: List of player_id's to add to the target player.
1348 :param player_ids_to_remove: List of player_id's to remove from the target player.
1349
1350 :raises UnsupportedFeaturedException: if the target player does not support grouping.
1351 :raises PlayerUnavailableError: if the target player is not available.
1352 """
1353 parent_player: Player | None = self.get_player(target_player, True)
1354 assert parent_player is not None # for type checking
1355 if PlayerFeature.SET_MEMBERS not in parent_player.state.supported_features:
1356 msg = f"Player {parent_player.name} does not support group commands"
1357 raise UnsupportedFeaturedException(msg)
1358
1359 # if the target player is a member of an active group player (e.g. a syncgroup),
1360 # redirect the command to that group player so it can manage the member change
1361 if (
1362 parent_player.type != PlayerType.GROUP
1363 and parent_player.state.active_group
1364 and (group_player := self.get_player(parent_player.state.active_group))
1365 and group_player.type == PlayerType.GROUP
1366 and PlayerFeature.SET_MEMBERS in group_player.state.supported_features
1367 ):
1368 self.logger.debug(
1369 "Redirecting set_members from %s to its group player %s",
1370 parent_player.name,
1371 group_player.name,
1372 )
1373 await self.cmd_set_members(
1374 parent_player.state.active_group, player_ids_to_add, player_ids_to_remove
1375 )
1376 return
1377
1378 if parent_player.synced_to:
1379 # handle edge case: target player is already synced itself to another player
1380 # automatically ungroup it first and wait for state to propagate
1381 await self._auto_ungroup_if_synced(parent_player, "setting members")
1382
1383 # Use lock for playback commands to prevent protocol switches from
1384 # racing with concurrent play_media / play_index / resume calls.
1385 async with self.get_player_lock(parent_player.player_id, PlayerLockPurpose.PLAYBACK):
1386 await self._handle_set_members(parent_player, player_ids_to_add, player_ids_to_remove)
1387
1388 @api_command("players/cmd/group", required_scope=Scope.PLAYERS_CONTROL)
1389 @handle_player_command
1390 async def cmd_group(self, player_id: str, target_player: str) -> None:
1391 """
1392 Handle GROUP command for given player.
1393
1394 Join/add the given player(id) to the given (leader) player/sync group.
1395 If the target player itself is already synced to another player, this may fail.
1396 If the player can not be synced with the given target player, this may fail.
1397
1398 NOTE: This is a convenience helper for cmd_set_members.
1399
1400 :param player_id: player_id of the player to handle the command.
1401 :param target_player: player_id of the syncgroup leader or group player.
1402
1403 :raises UnsupportedFeaturedException: if the target player does not support grouping.
1404 :raises PlayerCommandFailed: if the target player is already synced to another player.
1405 :raises PlayerUnavailableError: if the target player is not available.
1406 :raises PlayerCommandFailed: if the player is already grouped to another player.
1407 """
1408 await self.cmd_set_members(target_player, player_ids_to_add=[player_id])
1409
1410 @api_command("players/cmd/group_many", required_scope=Scope.PLAYERS_CONTROL)
1411 async def cmd_group_many(self, target_player: str, child_player_ids: list[str]) -> None:
1412 """
1413 Join given player(s) to target player.
1414
1415 Will add the given player(s) to the target player (sync leader or group player).
1416 This is a (deprecated) alias for cmd_set_members.
1417 """
1418 await self.cmd_set_members(target_player, player_ids_to_add=child_player_ids)
1419
1420 @api_command("players/cmd/ungroup", required_scope=Scope.PLAYERS_CONTROL)
1421 @handle_player_command
1422 async def cmd_ungroup(self, player_id: str) -> None:
1423 """
1424 Handle UNGROUP command for given player.
1425
1426 Remove the given player from any (sync)groups it currently is synced to.
1427 If the player is not currently grouped to any other player,
1428 this will silently be ignored.
1429 """
1430 if not (player := self.get_player(player_id)):
1431 self.logger.warning("Player %s is not available", player_id)
1432 return
1433
1434 # Ungroup on a group player is interpreted as 'release the captured
1435 # session entirely'. This avoids the "Cannot remove static member"
1436 # error path when transfer_queue or HA's unjoin asks us to release a
1437 # group that has static members.
1438 if player.state.type == PlayerType.GROUP:
1439 if player.state.power_control != PLAYER_CONTROL_NONE:
1440 await self._handle_cmd_power(player.player_id, False)
1441 else:
1442 await self._handle_cmd_stop(player.player_id)
1443 return
1444
1445 if player.state.active_group:
1446 group = self.get_player(player.state.active_group)
1447 is_static_member = group is not None and player_id in group.state.static_group_members
1448 if is_static_member:
1449 # Static members can't be released individually â recurse so
1450 # the group-player branch above stops/dissolves the session.
1451 if group is not None:
1452 await self.cmd_ungroup(group.player_id)
1453 return
1454 # dynamic or non-static member â remove just this player
1455 await self.cmd_set_members(player.state.active_group, player_ids_to_remove=[player_id])
1456 return
1457
1458 if player.state.synced_to:
1459 # player is a sync member
1460 await self.cmd_set_members(player.state.synced_to, player_ids_to_remove=[player_id])
1461 return
1462
1463 if player.state.group_members:
1464 # player is a sync leader (a non-group player with synced followers).
1465 # Remove only the leader itself: _handle_set_members will either transfer
1466 # leadership to a remaining member (keeping playback alive) or, when no
1467 # members remain / nothing is playing, dissolve the group and stop.
1468 await self.cmd_set_members(player.player_id, player_ids_to_remove=[player.player_id])
1469 return
1470 # unjoin from any dynamic sync groups if we're currently in one (edge case)
1471 # this is in particular used for the Home Assistant integration which does
1472 # not have a set_members command and only supports a single unjoin command
1473 for player in self.iter_players(False):
1474 if not player.state.group_members or player.state.synced_to:
1475 continue
1476 if PlayerFeature.SET_MEMBERS not in player.state.supported_features:
1477 continue
1478 if player_id in player.state.static_group_members:
1479 continue
1480 if player_id in player.state.group_members:
1481 await self.cmd_set_members(player.player_id, player_ids_to_remove=[player_id])
1482 return
1483
1484 @api_command("players/cmd/ungroup_many", required_scope=Scope.PLAYERS_CONTROL)
1485 async def cmd_ungroup_many(self, player_ids: list[str]) -> None:
1486 """Handle UNGROUP command for all the given players."""
1487 for player_id in list(player_ids):
1488 await self.cmd_ungroup(player_id)
1489
1490 @api_command("players/create_group_player", required_scope=Scope.CONFIG_PLAYERS_WRITE)
1491 async def create_group_player(
1492 self, provider: str, name: str, members: list[str], dynamic: bool = True
1493 ) -> Player:
1494 """
1495 Create a new (permanent) Group Player.
1496
1497 :param provider: The provider (id) to create the group player for.
1498 :param name: Name of the new group player.
1499 :param members: List of player ids to add to the group.
1500 :param dynamic: Whether the group is dynamic (members can change).
1501 """
1502 if not (provider_instance := self.mass.get_provider(provider)):
1503 raise ProviderUnavailableError(f"Provider {provider} not found")
1504 provider_instance = cast("PlayerProvider", provider_instance)
1505 if ProviderFeature.CREATE_GROUP_PLAYER not in provider_instance.supported_features:
1506 raise UnsupportedFeaturedException(
1507 f"Provider {provider} does not support creating group players"
1508 )
1509 return await provider_instance.create_group_player(name, members, dynamic)
1510
1511 @api_command("players/remove_group_player", required_scope=Scope.CONFIG_PLAYERS_WRITE)
1512 async def remove_group_player(self, player_id: str) -> None:
1513 """Remove a group player."""
1514 if not (player := self.get_player(player_id)):
1515 # we simply permanently delete the player by wiping its config
1516 self.mass.config.remove(f"players/{player_id}")
1517 return
1518 if player.state.type != PlayerType.GROUP:
1519 raise UnsupportedFeaturedException(f"Player {player.state.name} is not a group player")
1520 player.provider.check_feature(ProviderFeature.REMOVE_GROUP_PLAYER)
1521 await player.provider.remove_group_player(player_id)
1522
1523 @api_command("players/add_currently_playing_to_favorites", required_scope=Scope.LIBRARY_WRITE)
1524 async def add_currently_playing_to_favorites(self, player_id: str) -> None:
1525 """
1526 Add the currently playing item/track on given player to the favorites.
1527
1528 This tries to resolve the currently playing media to an actual media item
1529 and add that to the favorites in the library. Will raise an error if the
1530 player is not currently playing anything or if the currently playing media
1531 can not be resolved to a media item.
1532 """
1533 player = self._get_player_with_redirect(player_id)
1534 # handle mass player queue active
1535 if mass_queue := self.get_active_queue(player):
1536 if not (current_item := mass_queue.current_item) or not current_item.media_item:
1537 raise PlayerCommandFailed("No current item to add to favorites")
1538 # if we're playing a radio station, try to resolve the currently playing track
1539 if current_item.media_item.media_type == MediaType.RADIO:
1540 if not (
1541 (streamdetails := mass_queue.current_item.streamdetails)
1542 and (stream_title := streamdetails.stream_title)
1543 and " - " in stream_title
1544 ):
1545 # no stream title available, so we can't resolve the track
1546 # this can happen if the radio station does not provide metadata
1547 # or there's a commercial break
1548 # Possible future improvement could be to actually detect the song with a
1549 # shazam-like approach.
1550 raise PlayerCommandFailed("No current item to add to favorites")
1551 # send the streamtitle into a global search query
1552 search_artist, search_title_title = stream_title.split(" - ", 1)
1553 # strip off any additional comments in the title (such as from Radio Paradise)
1554 search_title_title = search_title_title.split(" | ")[0].strip()
1555 if track := await self.mass.music.get_track_by_name(
1556 search_title_title, search_artist
1557 ):
1558 # we found a track, so add it to the favorites
1559 await self.mass.music.add_item_to_favorites(track)
1560 return
1561 # we could not resolve the track, so raise an error
1562 raise PlayerCommandFailed("No current item to add to favorites")
1563
1564 # else: any other media item, just add it to the favorites directly
1565 await self.mass.music.add_item_to_favorites(current_item.media_item)
1566 return
1567
1568 # guard for player with no active source
1569 if not player.state.active_source:
1570 raise PlayerCommandFailed("Player has no active source")
1571 # handle other source active using the current_media with uri
1572 if current_media := player.state.current_media:
1573 # prefer the uri of the current media item
1574 if current_media.uri:
1575 with suppress(MusicAssistantError):
1576 await self.mass.music.add_item_to_favorites(current_media.uri)
1577 return
1578 # fallback to search based on artist and title (and album if available)
1579 if current_media.artist and current_media.title:
1580 if track := await self.mass.music.get_track_by_name(
1581 current_media.title,
1582 current_media.artist,
1583 current_media.album,
1584 ):
1585 # we found a track, so add it to the favorites
1586 await self.mass.music.add_item_to_favorites(track)
1587 return
1588 # if we reach here, we could not resolve the currently playing item
1589 raise PlayerCommandFailed("No current item to add to favorites")
1590
1591 async def register(self, player: Player) -> None:
1592 """Register a player on the Player Controller."""
1593 if self._teardown_in_progress(player):
1594 return
1595
1596 # Use lock to prevent race conditions during concurrent player registrations
1597 async with self._register_lock:
1598 player_id = player.player_id
1599
1600 if player_id in self._players:
1601 msg = f"Player {player_id} is already registered!"
1602 raise AlreadyRegisteredError(msg)
1603
1604 # ignore disabled players
1605 if not player.state.enabled:
1606 return
1607
1608 if player.type not in (PlayerType.GROUP, PlayerType.STEREO_PAIR):
1609 await self._resolve_mac_addresses(player)
1610
1611 # restore 'fake' power state from cache if available.
1612 # Group players intentionally do NOT restore their fake-power
1613 # state across restarts: at boot there is no sync session yet, so
1614 # a restored 'powered=True' would put the group in an inconsistent
1615 # 'active without captured session' state where children appear
1616 # owned by a group that has no leader. Users who want their
1617 # 'group captured' state preserved across restarts would need
1618 # explicit session restoration which is out of scope here.
1619 if player.type != PlayerType.GROUP:
1620 cached_value = await self.mass.cache.get(
1621 key=player.player_id,
1622 provider=self.domain,
1623 category=CACHE_CATEGORY_PLAYER_POWER,
1624 default=False,
1625 )
1626 if cached_value is not None:
1627 player.extra_data[ATTR_FAKE_POWER] = cached_value
1628
1629 # _registration_aborted below only works once the player is in the registry;
1630 # until then the unregister pass of a provider unload cannot see it, so re-check
1631 # the guard from the top of this method, which the awaits above may have staled
1632 if self._teardown_in_progress(player):
1633 return
1634
1635 # finally actually register it
1636
1637 # Despite the fact that the player is not fully ready yet
1638 # (config not loaded, protocol links not evaluated),
1639 # we already add it to the _players dict here because we
1640 # want to make sure the player is available in the controller
1641 # during the rest of the registration process
1642 # (such as when fetching config or evaluating protocol links).
1643 # We use the 'initialized' attribute to indicate that the player
1644 # is still in the process of being registered so we can filter it out where needed.
1645 self._players[player_id] = player
1646 try:
1647 # update state to ensure player.state reflects the final attributes
1648 # (e.g. player type) set after super().__init__() in the player subclass,
1649 # before we fetch config (which relies on state.type for entry resolution)
1650 player.update_state(signal_event=False)
1651 # ensure we fetch and set the latest/full config for the player
1652 player_config = await self.mass.config.get_player_config(player_id)
1653 if self._registration_aborted(player):
1654 return
1655 player.set_config(player_config)
1656 # update state again now that config is loaded
1657 player.update_state(signal_event=False)
1658 self._save_underlying_player_id(player)
1659 # call hook after the player is registered and config is set
1660 await player.on_config_updated()
1661 if self._registration_aborted(player):
1662 return
1663
1664 # Handle protocol linking
1665 self._evaluate_protocol_links(player)
1666 except Exception, asyncio.CancelledError:
1667 # a player whose setup failed never becomes initialized, which hides it
1668 # everywhere while it keeps blocking every later registration of the same id.
1669 # Cancellation counts too: a re-triggered provider discovery aborts the task
1670 # this runs in. Only roll back while the player is still ours: an unregister
1671 # may have dropped it already, and it unloads the player itself.
1672 if self._players.get(player_id) is player:
1673 del self._players[player_id]
1674 # players claim resources in their constructor (event subscriptions,
1675 # connections) that only on_unload releases. Best-effort, so a failing
1676 # teardown cannot mask the error that got us here.
1677 try:
1678 await player.on_unload()
1679 except Exception:
1680 self.logger.exception("Error unloading player %s", player.name)
1681 raise
1682
1683 # now we're ready to signal the player is added and available
1684 player.set_initialized()
1685 self.logger.info(
1686 "Player (type %s) registered: %s/%s",
1687 player.state.type.value,
1688 player_id,
1689 player.state.name,
1690 )
1691 # signal event that a player was added
1692 if player.state.type != PlayerType.PROTOCOL:
1693 self.mass.signal_event(
1694 EventType.PLAYER_ADDED, object_id=player.player_id, data=player
1695 )
1696 # register playerqueue for this player (if not a protocol player)
1697 if player.state.type != PlayerType.PROTOCOL:
1698 await self.mass.player_queues.on_player_register(player)
1699 if self._registration_aborted(player):
1700 # the queue restore outlived the unregister that already cleaned it up,
1701 # so drop the queue we just recreated for a player that is gone
1702 self.mass.player_queues.on_player_remove(player_id, permanent=False)
1703
1704 # Schedule debounced update of all players since can_group_with values may change
1705 # when a new player is added (provider IDs expand to include the new player)
1706 self._schedule_update_all_players(2)
1707
1708 async def register_or_update(self, player: Player) -> None:
1709 """Register a new player on the controller or update existing one."""
1710 if self._teardown_in_progress(player):
1711 return
1712
1713 # the register lock ensures a replacement is never swapped in while register()
1714 # is still setting the player up
1715 async with self._register_lock:
1716 if (existing := self._players.get(player.player_id)) is not None:
1717 # a protocol player is hidden behind its parent and owns no queue, every
1718 # other player does. Reading the role the player is leaving off that
1719 # published reality keeps it independent of when the player's state was
1720 # last recalculated, which providers cannot control (they flip the type
1721 # before this call).
1722 was_protocol = self.mass.player_queues.get(player.player_id) is None
1723 becomes_protocol = player.type == PlayerType.PROTOCOL
1724 role_changed = becomes_protocol != was_protocol
1725 if role_changed:
1726 # release the topology of the role the player is leaving
1727 self._cleanup_player_type_transition(
1728 existing, becomes_protocol=becomes_protocol
1729 )
1730 self._players[player.player_id] = player
1731 if existing is not player:
1732 # a fresh instance starts out with a base config only, so it needs
1733 # the config the registration resolved before it can be used
1734 player.set_config(existing.config)
1735 await player.on_config_updated()
1736 if self._registration_aborted(player):
1737 return
1738 # the replacement takes over the identity of an already registered
1739 # player, so it must be marked initialized as well
1740 player.set_initialized()
1741 player.update_state()
1742 # the derived-transport edge may have been set/revoked after the
1743 # initial registration (e.g. via a bridge claim)
1744 self._save_underlying_player_id(player)
1745 if role_changed:
1746 await self._finish_player_type_transition(player)
1747 # Also schedule update when replacing existing player
1748 self._schedule_update_all_players()
1749 return
1750
1751 await self.register(player)
1752
1753 def trigger_player_update(
1754 self, player_id: str, force_update: bool = False, debounce_delay: float = 0.25
1755 ) -> None:
1756 """Trigger a (debounced) update for the given player."""
1757 if self.mass.closing:
1758 return
1759 if not (player := self.get_player(player_id)):
1760 return
1761 # mark dirty right away (not at execution): a trigger means state the player
1762 # derives from changed, and a direct update_state call may come in before
1763 # the debounced one runs
1764 player.mark_state_dirty()
1765 task_id = f"player_update_state_{player_id}"
1766 self.mass.call_later(
1767 debounce_delay,
1768 player.update_state,
1769 force_update=force_update,
1770 task_id=task_id,
1771 )
1772
1773 async def unregister(
1774 self,
1775 player_id: str,
1776 permanent: bool = False,
1777 replacement_player_id: str | None = None,
1778 ) -> None:
1779 """
1780 Unregister a player from the player controller.
1781
1782 Called (by a PlayerProvider) when a player is removed or no longer available
1783 (for a longer period of time). This will remove the player from the player
1784 controller and optionally remove the player's config from the mass config.
1785 If the player is not registered, this will silently be ignored.
1786
1787 :param player_id: Player ID of the player to unregister.
1788 :param permanent: If True, remove the player permanently by deleting its config.
1789 If False, the player config will not be removed.
1790 :param replacement_player_id: Player ID that takes this player's place, only
1791 used for a permanent removal.
1792 """
1793 player = self._players.get(player_id)
1794 if player is None:
1795 return
1796 # a player that is going away is done with any live source it was playing,
1797 # so let the owning plugin release an upstream session pointing at us
1798 await self._release_audio_source(player_id)
1799 del self._players[player_id]
1800 # clean up all lock entries for this player
1801 for prefix in [p.value for p in PlayerLockPurpose]:
1802 self._player_command_locks.pop(f"{prefix}_{player_id}", None)
1803 if handle := self._pending_protocol_evaluations.pop(player_id, None):
1804 handle.cancel()
1805 self._clear_sleep_timer(player)
1806 self.mass.player_queues.on_player_remove(player_id, permanent=permanent)
1807 # teardown is best-effort: a provider that fails to release its player must not
1808 # strand the other players of that provider, nor the provider unload itself
1809 try:
1810 await player.on_unload()
1811 except Exception:
1812 self.logger.exception("Error unloading player %s", player.name)
1813 if permanent:
1814 # player permanent removal: cleanup protocol links, delete config
1815 # and signal PLAYER_REMOVED event.
1816 # No group detach is issued here: the player is already out of the registry,
1817 # so it is filtered out of every group's live member list, and its persisted
1818 # membership is settled by delete_player_config below.
1819 self._cleanup_protocol_links(player)
1820 self.delete_player_config(player_id, replacement_player_id)
1821 self.logger.info("Player removed: %s", player.name)
1822 if player.state.type != PlayerType.PROTOCOL:
1823 self.mass.signal_event(EventType.PLAYER_REMOVED, player_id)
1824 else:
1825 # temporary unavailable: mark player as unavailable
1826 # note: the player will be re-registered later if it comes back online
1827 player.state.available = False
1828 self.logger.info("Player unavailable: %s", player.name)
1829 if player.state.type != PlayerType.PROTOCOL:
1830 self.mass.signal_event(
1831 EventType.PLAYER_UPDATED, object_id=player.player_id, data=player.state
1832 )
1833 # Schedule debounced update of all players since can_group_with values may change
1834 self._schedule_update_all_players()
1835
1836 @api_command("players/remove", required_scope=Scope.CONFIG_PLAYERS_WRITE)
1837 async def remove(self, player_id: str) -> None:
1838 """
1839 Remove a player from a provider.
1840
1841 Can only be called when a PlayerProvider supports ProviderFeature.REMOVE_PLAYER.
1842 """
1843 player = self.get_player(player_id)
1844 if player is None:
1845 # we simply permanently delete the player config since it is not registered
1846 self.delete_player_config(player_id)
1847 return
1848 if player.state.type == PlayerType.GROUP:
1849 # Handle group player removal
1850 player.provider.check_feature(ProviderFeature.REMOVE_GROUP_PLAYER)
1851 await player.provider.remove_group_player(player_id)
1852 return
1853 player.provider.check_feature(ProviderFeature.REMOVE_PLAYER)
1854 await player.provider.remove_player(player_id)
1855 # check for group memberships that need to be updated
1856 if player.state.active_group and (
1857 group_player := self.mass.players.get_player(player.state.active_group)
1858 ):
1859 # try to remove from the group
1860 with suppress(UnsupportedFeaturedException, PlayerCommandFailed):
1861 await group_player.set_members(
1862 player_ids_to_remove=[player_id],
1863 )
1864 # We removed the player and can now clean up its config
1865 self.delete_player_config(player_id)
1866
1867 def delete_player_config(
1868 self, player_id: str, replacement_player_id: str | None = None
1869 ) -> None:
1870 """
1871 Permanently delete a player's configuration, including its DSP and queue settings.
1872
1873 The saved queue of a player that is no longer registered is dropped along with it,
1874 so a device that returns under the same id starts out fresh. The player itself is
1875 not unregistered.
1876 The config of a linked protocol player is wiped along with it, so the device
1877 returns as a brand new player once it is discovered again. Protocol players that
1878 are still registered or that already moved to another parent keep their config;
1879 registered ones are detached from the removed player and re-evaluated.
1880 Any group that lists the player as a member follows the replacement, or loses
1881 the member when there is none.
1882
1883 :param player_id: Player ID of the player to delete the configuration of.
1884 :param replacement_player_id: Player ID that takes this player's place, so users
1885 restricted to it and groups it belongs to follow
1886 the replacement.
1887 """
1888 self._detach_protocol_children(player_id)
1889 self._update_group_memberships(player_id, replacement_player_id)
1890 player_ids = [
1891 protocol_id
1892 for protocol_id in self.mass.config.get(CONF_PLAYERS, {})
1893 if self._get_cached_protocol_parent_id(protocol_id) == player_id
1894 and self.get_player(protocol_id) is None
1895 ]
1896 player_ids.append(player_id)
1897 for pid in player_ids:
1898 for key in (
1899 f"{CONF_PLAYERS}/{pid}",
1900 f"{CONF_PLAYER_DSP}/{pid}",
1901 f"{CONF_PLAYER_QUEUES}/{pid}",
1902 ):
1903 self.mass.config.remove(key)
1904 if self.get_player(pid) is None:
1905 self.mass.player_queues.purge_saved_queue(pid)
1906 # a user access filter is an allow-list of player ids, so it must not be left
1907 # pointing at a player whose config was just wiped: a replaced player hands its
1908 # entries over to its replacement, a removed one has them dropped
1909 if replacement_player_id:
1910 self.mass.create_task(
1911 self.mass.webserver.auth.replace_player_in_user_filters(
1912 player_id, replacement_player_id, removed_player_ids=player_ids
1913 )
1914 )
1915 else:
1916 self.mass.create_task(
1917 self.mass.webserver.auth.remove_from_user_filters(player_ids=player_ids)
1918 )
1919
1920 def scale_volume_to_device(self, player_id: str, logical_volume: int) -> int:
1921 """Scale logical volume (0-100) to device volume (min_volume-max_volume)."""
1922 min_volume, max_volume = self._get_volume_limits(player_id)
1923 if min_volume == 0 and max_volume == 100:
1924 return logical_volume
1925 # Scale: logical 0 -> min_volume, logical 100 -> max_volume
1926 return min_volume + (logical_volume * (max_volume - min_volume)) // 100
1927
1928 def scale_volume_from_device(self, player_id: str, device_volume: int) -> int:
1929 """Scale device volume (min_volume-max_volume) to logical volume (0-100)."""
1930 min_volume, max_volume = self._get_volume_limits(player_id)
1931 if min_volume == 0 and max_volume == 100:
1932 return device_volume
1933 volume_range = max_volume - min_volume
1934 if volume_range == 0:
1935 return 0
1936 # Scale to 0-100 without clamping so that out-of-range device volumes
1937 # produce distinct logical values, ensuring state change detection triggers
1938 # volume limit enforcement
1939 return ((device_volume - min_volume) * 100) // volume_range
1940
1941 def on_player_position_jumped(self, player: Player) -> None:
1942 """
1943 Handle a discrete jump of a player's corrected playback position.
1944
1945 Called by a Player when its corrected position moved significantly
1946 outside regular playback progression (seek or buffer correction). This
1947 is not an event by itself: it re-bases the active queue's timing on the
1948 fresh position and nudges related players so derived positions stay in
1949 sync; current_media then re-anchors from the corrected queue time on
1950 the follow-up update, which emits the actual update event.
1951 """
1952 if self.mass.closing:
1953 return
1954 self.mass.player_queues.on_player_elapsed_time_corrected(player)
1955 self.trigger_player_update(player.player_id)
1956 self._forward_state_update(player, {})
1957
1958 def signal_player_state_update(
1959 self,
1960 player: Player,
1961 changed_values: dict[str, tuple[Any, Any]],
1962 force_update: bool = False,
1963 skip_forward: bool = False,
1964 media_position_jumped: bool = False,
1965 ) -> None:
1966 """
1967 Signal a player state update.
1968
1969 Called by a Player when its state has changed.
1970 This will update the player state in the controller and signal the event bus.
1971 """
1972 player_id = player.player_id
1973 if self.mass.closing:
1974 return
1975
1976 # ignore updates for disabled players
1977 if not player.state.enabled and ATTR_ENABLED not in changed_values:
1978 return
1979
1980 # The current_media position anchor only changes on discrete events
1981 # (play/pause/seek/track change/buffer correction), so a change set holding
1982 # only anchor keys represents a position correction rather than a regular
1983 # state change.
1984 non_anchor_keys = changed_values.keys() - POSITION_ANCHOR_KEYS
1985 if len(non_anchor_keys) == 0 and not force_update:
1986 if not media_position_jumped:
1987 # anchor adoption without a significant corrected-position change
1988 return
1989 # current_media's corrected position jumped (seek or buffer correction
1990 # reached the current media): emit the full player update below so
1991 # consumers see the fresh position
1992
1993 if self.logger.isEnabledFor(VERBOSE_LOG_LEVEL):
1994 self.logger.log(
1995 VERBOSE_LOG_LEVEL,
1996 "Player state updated for %s: changed fields: %s",
1997 player.name,
1998 ", ".join(changed_values.keys()),
1999 )
2000
2001 # signal update to the playerqueue
2002 if player.state.type != PlayerType.PROTOCOL:
2003 self.mass.call_later(
2004 0.5,
2005 self.mass.player_queues.on_player_update,
2006 player,
2007 changed_values,
2008 task_id=f"queue_on_player_update_{player.player_id}",
2009 )
2010
2011 # Kick async palette extraction on cold cache. On transition prefetch
2012 # the next queue item too. Skip players that mirror another player's media
2013 # (grouped/synced members, protocol children): their current_media - palette
2014 # included - is taken wholesale from the owner, so resolving it per member is
2015 # wasted work that also produces duplicate state updates across the group.
2016 if (
2017 not self._mirrors_parent_media(player)
2018 and (current_media := player.state.current_media)
2019 and current_media.image_url
2020 ):
2021 if current_media.palette is None:
2022 self._schedule_palette_fetch(player_id, current_media.image_url)
2023 if "current_media.image_url" in changed_values or "current_media" in changed_values:
2024 self._schedule_next_queue_item_palette_prefetch(player_id, current_media)
2025
2026 # handle DSP reload of the leader when grouping/ungrouping
2027 if ATTR_GROUP_MEMBERS in changed_values:
2028 prev_group_members, new_group_members = changed_values[ATTR_GROUP_MEMBERS]
2029 self._handle_group_dsp_change(player, prev_group_members or [], new_group_members)
2030 # Removed group members also need to be updated since they are no longer part
2031 # of this group and are available for playback again
2032 removed_members = set(prev_group_members or []) - set(new_group_members or [])
2033 for _removed_player_id in removed_members:
2034 if removed_player := self.get_player(_removed_player_id):
2035 removed_player.refresh_state()
2036
2037 # detect when active_source changes to
2038 # something external while we have a grouped protocol active
2039 if ATTR_ACTIVE_SOURCE in changed_values:
2040 task_id = f"external_source_takeover_{player_id}"
2041 self.mass.call_later(
2042 5,
2043 self._check_external_source_takeover,
2044 player,
2045 task_id=task_id,
2046 )
2047 # only steer into the (relatively expensive) membership cleanup when a field
2048 # that can require an unsync actually changed - this runs on every state tick
2049 if changed_values.keys() & {ATTR_AVAILABLE, ATTR_ENABLED, ATTR_POWERED}:
2050 self._handle_membership_cleanup_on_state_change(player, changed_values)
2051 self._handle_external_power_off(player, changed_values)
2052
2053 # enforce volume limits when volume changes externally
2054 if "volume_level" in changed_values:
2055 corrected = self._enforce_volume_limits(player)
2056 # a level set on the device itself makes the reference a group volume change
2057 # interpolates from obsolete. a member on its way to a level we did send
2058 # reports levels too, and a group only ever reports what its members are at,
2059 # so neither of those counts. a correction always is the device's own doing:
2060 # the levels we command never fall outside the configured range
2061 if player.state.type != PlayerType.GROUP and (
2062 corrected or self._unexpired_volume_target(player) is None
2063 ):
2064 self._invalidate_group_volume_snapshot(player_id)
2065 # dispatch to internal state update subscribers (with changed_values)
2066 self._dispatch_state_update_subscribers(player, changed_values)
2067
2068 # signal player update on the eventbus
2069 if player.state.type != PlayerType.PROTOCOL:
2070 self.mass.signal_event(EventType.PLAYER_UPDATED, object_id=player_id, data=player)
2071
2072 # signal a separate PlayerOptionsUpdated event
2073 if options := changed_values.get("options"):
2074 self.mass.signal_event(
2075 EventType.PLAYER_OPTIONS_UPDATED, object_id=player_id, data=options
2076 )
2077 # signal player config update event if playerfeatures changed
2078 # this is temporary needed for the Home Assistant integration which only
2079 # re-evalues the entity's supported features on a PLAYER_CONFIG_UPDATED event.
2080 # TODO: Remove this temporary workaround once the HA integration is updated to
2081 # also re-evaluate supported features on PLAYER_UPDATED events.
2082 if changed_values.keys() & {
2083 ATTR_SUPPORTED_FEATURES,
2084 ATTR_MUTE_CONTROL,
2085 ATTR_VOLUME_CONTROL,
2086 ATTR_POWER_CONTROL,
2087 }:
2088 self.mass.signal_event(
2089 EventType.PLAYER_CONFIG_UPDATED, object_id=player_id, data=player.config
2090 )
2091
2092 if not skip_forward or force_update:
2093 self._forward_state_update(player, changed_values)
2094
2095 # trigger update of all players in a provider if group related fields changed
2096 # this ensures that calculated fields like can_group_with are updated on all players
2097 if any(key in changed_values for key in ("group_members", "synced_to", "available")):
2098 for prov_player in player.provider.players:
2099 self.trigger_player_update(prov_player.player_id, debounce_delay=2)
2100
2101 async def register_player_control(self, player_control: PlayerControl) -> None:
2102 """Register a new PlayerControl on the controller."""
2103 if self.mass.closing:
2104 return
2105 control_id = player_control.id
2106
2107 if control_id in self._controls:
2108 msg = f"PlayerControl {control_id} is already registered"
2109 raise AlreadyRegisteredError(msg)
2110
2111 # make sure that the playercontrol's provider is set to the instance_id
2112 prov = self.mass.get_provider(player_control.provider)
2113 if not prov or prov.instance_id != player_control.provider:
2114 raise RuntimeError(f"Invalid provider ID given: {player_control.provider}")
2115
2116 self._controls[control_id] = player_control
2117
2118 self.logger.info(
2119 "PlayerControl registered: %s/%s",
2120 control_id,
2121 player_control.name,
2122 )
2123
2124 # always call update to update any attached players etc.
2125 self.update_player_control(player_control.id, include_configured=True)
2126
2127 async def register_or_update_player_control(self, player_control: PlayerControl) -> None:
2128 """Register a new playercontrol on the controller or update existing one."""
2129 if self.mass.closing:
2130 return
2131 if player_control.id in self._controls:
2132 self._controls[player_control.id] = player_control
2133 self.update_player_control(player_control.id, include_configured=True)
2134 return
2135 await self.register_player_control(player_control)
2136
2137 def update_player_control(self, control_id: str, include_configured: bool = False) -> None:
2138 """
2139 Refresh the players that use the given player control.
2140
2141 :param control_id: The control whose state or availability changed.
2142 :param include_configured: Also refresh the players that select this control in their
2143 config but do not currently resolve to it. Needed when a control (re)appears,
2144 because such a player has already fallen back to another control and would
2145 otherwise never pick this one back up.
2146 """
2147 if self.mass.closing:
2148 return
2149 # update all players that are using this control
2150 for player in list(self._players.values()):
2151 if control_id in (
2152 player.state.power_control,
2153 player.state.volume_control,
2154 player.state.mute_control,
2155 ) or (
2156 include_configured and control_id in self._configured_control_ids(player.player_id)
2157 ):
2158 self.mass.loop.call_soon(player.refresh_state)
2159
2160 def remove_player_control(self, control_id: str) -> None:
2161 """Remove a player_control from the player manager."""
2162 control = self._controls.pop(control_id, None)
2163 if control is None:
2164 return
2165 self.logger.info("PlayerControl removed: %s", control.name)
2166 # players configured to use this control still resolve to it until they are
2167 # refreshed, so let them fall back to their remaining options right away
2168 self.update_player_control(control_id)
2169
2170 def get_player_provider(self, player_id: str) -> PlayerProvider:
2171 """Return PlayerProvider for given player."""
2172 player = self._players[player_id]
2173 assert player # for type checker
2174 return player.provider
2175
2176 def get_active_queue(self, player: Player) -> PlayerQueue | None:
2177 """Return the current active queue for a player (if any)."""
2178 # account for player that is synced (sync child)
2179 if player.state.synced_to and player.state.synced_to != player.player_id:
2180 if sync_leader := self.get_player(player.state.synced_to):
2181 return self.get_active_queue(sync_leader)
2182 # handle active group player
2183 if player.state.active_group and player.state.active_group != player.player_id:
2184 if group_player := self.get_player(player.state.active_group):
2185 return self.get_active_queue(group_player)
2186 # active_source may be filled queue id (or None)
2187 active_source = player.state.active_source or player.player_id
2188 if active_queue := self.mass.player_queues.get(active_source):
2189 return active_queue
2190 # handle active protocol player with parent player queue
2191 if player.type == PlayerType.PROTOCOL and player.protocol_parent_id:
2192 if parent_player := self.mass.players.get_player(player.protocol_parent_id):
2193 return self.get_active_queue(parent_player)
2194 return None
2195
2196 async def set_group_volume(self, group_player: Player, volume_level: int) -> None:
2197 """
2198 Set the overall volume for a player group or synced players.
2199
2200 Uses interpolation to adjust all child volumes while preserving their
2201 relative balance. A snapshot of child volumes is cached on first call and
2202 used as the reference point for subsequent adjustments.
2203
2204 :param group_player: The group player or sync leader.
2205 :param volume_level: Target volume level (0..100).
2206 """
2207 cur_volume = group_player.state.group_volume
2208 if cur_volume is None:
2209 return
2210
2211 children: list[Player] = []
2212 for child_player in self.iter_group_members(
2213 group_player, only_powered=True, exclude_self=False
2214 ):
2215 if child_player.state.volume_control == PLAYER_CONTROL_NONE:
2216 continue
2217 children.append(child_player)
2218 if not children:
2219 return
2220
2221 # cache a snapshot of child volumes on the group player as reference for interpolation.
2222 # scaling up: each child interpolates from its snapshot value toward 100.
2223 # scaling down: each child interpolates from its snapshot value toward 0.
2224 # this ensures the relative balance is preserved and all children converge
2225 # to 0 and 100 at the extremes. the snapshot is invalidated when a child's
2226 # individual volume or the group membership changes, and rebuilt when the
2227 # children it holds are no longer the ones being adjusted.
2228 # the levels a nudge steps from are the ones the members were last commanded, so
2229 # the snapshot has to read the same source, or a change a member has not confirmed
2230 # yet puts the reference above the level being set and turns a step up into one down
2231 snapshot: dict[str, int] | None = group_player.extra_data.get(ATTR_GROUP_VOLUME_SNAPSHOT)
2232 if snapshot is None or snapshot.keys() != {c.player_id for c in children}:
2233 snapshot = {c.player_id: self._volume_nudge_base(c) or 0 for c in children}
2234 group_player.extra_data[ATTR_GROUP_VOLUME_SNAPSHOT] = snapshot
2235
2236 base_group = max(snapshot.values())
2237
2238 coros = []
2239 for child_player in children:
2240 child_base = snapshot.get(child_player.player_id, 0)
2241 if volume_level >= base_group:
2242 # scaling up: interpolate each child from snapshot toward 100
2243 if base_group >= 100:
2244 new_child_volume = child_base
2245 else:
2246 progress = (volume_level - base_group) / (100 - base_group)
2247 new_child_volume = round(child_base + (100 - child_base) * progress)
2248 elif base_group == 0:
2249 new_child_volume = 0
2250 else:
2251 # scaling down: interpolate each child from snapshot toward 0
2252 progress = volume_level / base_group
2253 new_child_volume = round(child_base * progress)
2254 new_child_volume = max(0, min(100, new_child_volume))
2255 coros.append(self._set_member_volume(child_player.player_id, new_child_volume))
2256 await asyncio.gather(*coros)
2257
2258 # notify active AudioSource once at the group level to prevent
2259 # feedback loops from per-child callbacks with different volume values
2260 await self._notify_source_volume_change(group_player, volume_level)
2261
2262 def iter_group_members(
2263 self,
2264 group_player: Player,
2265 only_powered: bool = False,
2266 only_playing: bool = False,
2267 active_only: bool = False,
2268 exclude_self: bool = True,
2269 ) -> Iterator[Player]:
2270 """Get (child) players attached to a group player or syncgroup."""
2271 for child_id in list(group_player.state.group_members):
2272 if child_player := self.get_player(child_id, False):
2273 if not child_player.state.available or not child_player.state.enabled:
2274 continue
2275 if only_powered and child_player.state.powered is False:
2276 continue
2277 if active_only and child_player.state.active_group != group_player.player_id:
2278 continue
2279 if exclude_self and child_player.player_id == group_player.player_id:
2280 continue
2281 if only_playing and child_player.state.playback_state not in (
2282 PlaybackState.PLAYING,
2283 PlaybackState.PAUSED,
2284 ):
2285 continue
2286 yield child_player
2287
2288 def subscribe_player_state_update(
2289 self,
2290 callback: Callable[[Player, dict[str, tuple[Any, Any]]], None],
2291 ) -> Callable[[], None]:
2292 """
2293 Subscribe to player state update notifications.
2294
2295 The callback receives the Player and a dict of changed values
2296 (mapping attribute name to a (previous, new) tuple).
2297
2298 :param callback: Function to invoke for each player state update.
2299 :return: An unsubscribe function.
2300 """
2301 self._state_update_subscribers.append(callback)
2302
2303 def _unsub() -> None:
2304 with suppress(ValueError):
2305 self._state_update_subscribers.remove(callback)
2306
2307 return _unsub
2308
2309 @contextlib.asynccontextmanager
2310 async def wait_for_player_update(
2311 self,
2312 player_id: str,
2313 attribute_name: str | None = None,
2314 attribute_value: Any = _SENTINEL,
2315 timeout: float = 5.0,
2316 ) -> AsyncIterator[None]:
2317 """
2318 Async context manager that waits for a player state update.
2319
2320 Subscribes to player state updates on entry, runs the body (typically
2321 the action that triggers the expected update), then waits for a
2322 matching update on exit. If ``attribute_name`` and ``attribute_value``
2323 are both provided and the current value already matches at entry, the
2324 wait is skipped.
2325
2326 Example::
2327
2328 async with mass.players.wait_for_player_update(
2329 player_id, attribute_name="playback_state",
2330 attribute_value=PlaybackState.IDLE, timeout=5,
2331 ):
2332 await mass.players._handle_cmd_stop(player_id)
2333
2334 :param player_id: The player ID to wait for.
2335 :param attribute_name: Optional state attribute to watch for changes
2336 (e.g. ``"playback_state"``). If omitted, any state change satisfies
2337 the wait.
2338 :param attribute_value: Optional value the watched attribute must reach.
2339 Only meaningful in combination with ``attribute_name``.
2340 :param timeout: Maximum time to wait in seconds.
2341 """
2342 update_event = asyncio.Event()
2343
2344 def _on_state_update(player: Player, changed_values: dict[str, tuple[Any, Any]]) -> None:
2345 if player.player_id != player_id:
2346 return
2347 if attribute_name is None:
2348 update_event.set()
2349 return
2350 if attribute_name not in changed_values:
2351 return
2352 if attribute_value is _SENTINEL:
2353 update_event.set()
2354 return
2355 _prev, new_val = changed_values[attribute_name]
2356 if new_val == attribute_value:
2357 update_event.set()
2358
2359 # short-circuit when the desired value is already the current state
2360 already_satisfied = (
2361 attribute_name is not None
2362 and attribute_value is not _SENTINEL
2363 and (player := self.get_player(player_id)) is not None
2364 and getattr(player.state, attribute_name, _SENTINEL) == attribute_value
2365 )
2366
2367 unsub = self.subscribe_player_state_update(_on_state_update)
2368 try:
2369 yield
2370 if already_satisfied:
2371 return
2372 try:
2373 async with asyncio.timeout(timeout):
2374 await update_event.wait()
2375 except TimeoutError:
2376 self.logger.debug(
2377 "Timed out waiting for player update on %s (attr=%s value=%s)",
2378 player_id,
2379 attribute_name,
2380 attribute_value,
2381 )
2382 finally:
2383 unsub()
2384
2385 async def on_player_config_change(self, config: PlayerConfig, changed_keys: set[str]) -> None:
2386 """Call (by config manager) when the configuration of a player changes."""
2387 min_vol_changed = f"values/{CONF_MIN_VOLUME}" in changed_keys
2388 max_vol_changed = f"values/{CONF_MAX_VOLUME}" in changed_keys
2389 if min_vol_changed or max_vol_changed:
2390 raw_min = config.get_value(CONF_MIN_VOLUME)
2391 raw_max = config.get_value(CONF_MAX_VOLUME)
2392 min_vol = int(cast("int", raw_min)) if raw_min is not None else 0
2393 max_vol = int(cast("int", raw_max)) if raw_max is not None else 100
2394 if min_vol > max_vol:
2395 msg = "Minimum volume cannot exceed maximum volume"
2396 raise InvalidDataError(msg)
2397 player = self.get_player(config.player_id)
2398 player_provider = self.mass.get_provider(config.provider)
2399 player_disabled = ATTR_ENABLED in changed_keys and not config.enabled
2400 player_enabled = ATTR_ENABLED in changed_keys and config.enabled
2401
2402 if player_disabled and player and player.state.available:
2403 # edge case: ensure that the player is powered off if the player gets disabled
2404 if player.state.power_control != PLAYER_CONTROL_NONE:
2405 await self._handle_cmd_power(config.player_id, False)
2406 elif player.state.playback_state != PlaybackState.IDLE:
2407 await self.cmd_stop(config.player_id)
2408
2409 # signal player provider that the player got enabled/disabled
2410 if (player_enabled or player_disabled) and player_provider:
2411 assert isinstance(player_provider, PlayerProvider) # for type checking
2412 # Collect linked protocol IDs to cascade the enable/disable to.
2413 # Without this, a disabled native parent leaves its linked protocols
2414 # registered after restart; they then fail to find their parent and
2415 # get wrapped in a fresh Universal Player.
2416 cascade_protocol_ids: list[str] = []
2417 parent_is_protocol = player.state.type == PlayerType.PROTOCOL if player else False
2418 if not parent_is_protocol:
2419 if player and player.linked_output_protocols:
2420 cascade_protocol_ids = [
2421 link.output_protocol_id for link in player.linked_output_protocols
2422 ]
2423 else:
2424 cascade_protocol_ids = self._get_cached_protocol_ids(config.player_id)
2425 if player_disabled:
2426 player_provider.on_player_disabled(config.player_id)
2427 elif player_enabled:
2428 player_provider.on_player_enabled(config.player_id)
2429 for protocol_id in cascade_protocol_ids:
2430 protocol_raw = self.mass.config.get(f"{CONF_PLAYERS}/{protocol_id}")
2431 if not protocol_raw:
2432 continue
2433 if bool(protocol_raw.get("enabled", True)) == bool(player_enabled):
2434 continue
2435 self.mass.create_task(
2436 self.mass.config.save_player_config(
2437 protocol_id, {ATTR_ENABLED: bool(player_enabled)}
2438 )
2439 )
2440 return # enabling/disabling a player will be handled by the provider
2441
2442 if not player:
2443 return # guard against player not being registered (yet)
2444
2445 resume_queue: PlayerQueue | None = (
2446 self.mass.player_queues.get(player.state.active_source)
2447 if player.state.active_source
2448 else None
2449 )
2450
2451 # ensure player state gets updated with any updated config
2452 player.set_config(config)
2453 await player.on_config_updated()
2454 player.update_state()
2455 # if the PlayerQueue was playing, restart playback
2456 if resume_queue and resume_queue.state == PlaybackState.PLAYING:
2457 requires_restart = any(
2458 v.requires_reload
2459 for v in config.values.values()
2460 if f"values/{v.key}" in changed_keys
2461 )
2462 if requires_restart:
2463 # always stop first to ensure the player uses the new config
2464 await self.mass.player_queues.stop(resume_queue.queue_id)
2465 self.mass.call_later(
2466 1, self.mass.player_queues.resume, resume_queue.queue_id, False
2467 )
2468
2469 async def on_player_dsp_change(self, player_id: str) -> None:
2470 """Call (by config manager) when the DSP settings of a player change."""
2471 # signal player provider that the config changed
2472 if not (player := self.get_player(player_id)):
2473 return
2474 if player.state.playback_state == PlaybackState.PLAYING:
2475 self.logger.info("Restarting playback of Player %s after DSP change", player_id)
2476 # this will restart the queue stream/playback
2477 if self.get_active_queue(player):
2478 self.mass.call_later(
2479 0, self.mass.player_queues.resume, player.state.active_source, False
2480 )
2481 return
2482 # if the player is not using a queue, we need to stop and start playback
2483 await self.cmd_stop(player_id)
2484 await self.cmd_play(player_id)
2485
2486 def schedule_active_output_protocol_clear(self, player: Player) -> None:
2487 """
2488 Clear the player's active output protocol once it stops playing.
2489
2490 A device may keep reporting PLAYING for a short while after a stop
2491 command, so the clear is deferred until the player reports IDLE (with a
2492 timeout as fallback). Starting a new session cancels the pending clear
2493 (see Player.set_active_output_protocol).
2494
2495 :param player: The player whose active output protocol must be cleared.
2496 """
2497 # Deduplicated per player via task_id: if a clear is already pending we
2498 # keep it, so the single tracked task stays cancellable by a new session.
2499 self.mass.create_task(
2500 self._clear_active_output_protocol_when_idle(player),
2501 task_id=f"clear_active_protocol_{player.player_id}",
2502 )
2503
2504 def __iter__(self) -> Iterator[Player]:
2505 """Iterate over all players."""
2506 return iter(self._players.values())
2507
2508 async def _resolve_mac_addresses(self, player: Player) -> None:
2509 """
2510 Resolve and persist the MAC addresses used to match the player against protocols.
2511
2512 :param player: The player to resolve the MAC address(es) for.
2513 """
2514 conf_base = f"{CONF_PLAYERS}/{player.player_id}/values"
2515 # Save the original MAC reported by the provider (before ARP enrichment)
2516 reported_mac = player.device_info.identifiers.get(IdentifierType.MAC_ADDRESS)
2517
2518 # Try to use cached ARP MAC from config for fast matching on restart.
2519 # This allows protocol linking to work immediately even if ARP is slow/fails.
2520 cached_arp_mac: str | None = self.mass.config.get(
2521 f"{conf_base}/{CONF_CACHED_ARP_MAC}", None
2522 )
2523 if cached_arp_mac and is_valid_mac_address(cached_arp_mac):
2524 player.device_info.add_identifier(IdentifierType.MAC_ADDRESS, cached_arp_mac)
2525
2526 # Enrich device MAC address via ARP if needed
2527 # (handles invalid MACs, locally-administered MACs, and missing MACs)
2528 await enrich_device_mac_address(player.device_info, self.logger)
2529
2530 # Cache the resolved MAC for fast matching on subsequent restarts
2531 current_mac = player.device_info.identifiers.get(IdentifierType.MAC_ADDRESS)
2532 if current_mac and is_valid_mac_address(current_mac) and current_mac != cached_arp_mac:
2533 self.mass.config.set(f"{conf_base}/{CONF_CACHED_ARP_MAC}", current_mac)
2534
2535 # Store original reported MAC if it differs from the resolved MAC.
2536 # This enables multi-MAC matching for devices with multiple interfaces
2537 # (e.g., WiFi + Ethernet) where ARP resolves one interface but the
2538 # protocol reports the other.
2539 if reported_mac and is_valid_mac_address(reported_mac) and current_mac:
2540 if reported_mac.upper() != current_mac.upper():
2541 player.extra_data["reported_mac"] = reported_mac
2542 self.mass.config.set(f"{conf_base}/{CONF_REPORTED_MAC}", reported_mac)
2543 else:
2544 # Provider's reported MAC matches the resolved MAC; clear any stale
2545 # stored reported MAC to avoid false-positive multi-MAC matches.
2546 self.mass.config.set(f"{conf_base}/{CONF_REPORTED_MAC}", None)
2547 elif not reported_mac or not is_valid_mac_address(reported_mac):
2548 # Restore reported MAC from config on restart only when the provider
2549 # did not supply a usable MAC address.
2550 cached_reported_mac: str | None = self.mass.config.get(
2551 f"{conf_base}/{CONF_REPORTED_MAC}", None
2552 )
2553 if cached_reported_mac and is_valid_mac_address(cached_reported_mac):
2554 if current_mac and cached_reported_mac.upper() == current_mac.upper():
2555 # Cached value matches the resolved MAC; clear stale entry.
2556 self.mass.config.set(f"{conf_base}/{CONF_REPORTED_MAC}", None)
2557 else:
2558 player.extra_data["reported_mac"] = cached_reported_mac
2559
2560 def _teardown_in_progress(self, player: Player) -> bool:
2561 """
2562 Return True if the server or this player's provider is shutting down.
2563
2564 :param player: The player that is in the process of being registered.
2565 """
2566 return self.mass.closing or player.provider.unloading
2567
2568 def _registration_aborted(self, player: Player) -> bool:
2569 """
2570 Return True if the given player is no longer the registered player for its ID.
2571
2572 :param player: The player that is in the process of being registered.
2573 """
2574 # registration awaits provider I/O while the player is already in the registry,
2575 # so an unregister (e.g. a provider unload or a device disconnect) can drop or
2576 # replace it in the meantime, after which registration must stop
2577 if self._players.get(player.player_id) is player:
2578 return False
2579 self.logger.debug(
2580 "Registration of player %s aborted: it was unregistered while setting up",
2581 player.player_id,
2582 )
2583 return True
2584
2585 async def _finish_player_type_transition(self, player: Player) -> None:
2586 """
2587 Publish a registered player that moved in or out of the protocol role.
2588
2589 :param player: The player, with its new type already applied to its state.
2590 """
2591 self._evaluate_protocol_links(player)
2592 if player.state.type == PlayerType.PROTOCOL:
2593 # the player is hidden behind its parent from now on and no longer owns a queue.
2594 # only the queue is dropped, never the playback: the player either just became a
2595 # (hidden) bridge client with nothing playing on it, or is already serving its
2596 # parent, where a stop would cut that parent's stream short. A protocol player
2597 # has no active group of its own either, so there is nothing to detach here.
2598 self.mass.signal_event(EventType.PLAYER_REMOVED, player.player_id)
2599 self.mass.player_queues.on_player_remove(player.player_id, permanent=False)
2600 return
2601 # the player surfaces on its own, which leaves it unusable without a queue
2602 self.mass.signal_event(EventType.PLAYER_ADDED, object_id=player.player_id, data=player)
2603 await self.mass.player_queues.on_player_register(player)
2604 if self._registration_aborted(player):
2605 # the queue restore outlived the unregister that already cleaned it up,
2606 # so drop the queue we just recreated for a player that is gone
2607 self.mass.player_queues.on_player_remove(player.player_id, permanent=False)
2608
2609 async def _release_player_for_play_media(self, player: Player) -> None:
2610 """
2611 Release a captured player so a play_media command can target it directly.
2612
2613 :param player: The captured player to release.
2614 """
2615 # Strategy is picked from how the player is currently captured:
2616 # synced_to â unsync this player (cmd_ungroup)
2617 # dynamic group member â remove from group via cmd_set_members
2618 # static group member â dissolve the whole group (power off if it
2619 # has a real power control, otherwise stop)
2620 # In every branch we wait for the relevant state attribute to actually
2621 # clear before returning. Providers (Sonos in particular) reject a
2622 # play_media on a player whose synced_to/active_group is still set
2623 # locally even though the release command has been acknowledged.
2624 if player.state.synced_to:
2625 self.logger.debug(
2626 "Unsyncing %s from %s to honor explicit play_media target",
2627 player.state.name,
2628 player.state.synced_to,
2629 )
2630 async with self.wait_for_player_update(
2631 player.player_id,
2632 attribute_name="synced_to",
2633 attribute_value=None,
2634 timeout=5,
2635 ):
2636 await self.cmd_ungroup(player.player_id)
2637 return
2638 if not player.state.active_group:
2639 return
2640 group = self.get_player(player.state.active_group)
2641 if group is None:
2642 return
2643 is_dynamic_member = (
2644 PlayerFeature.SET_MEMBERS in group.state.supported_features
2645 and player.player_id not in group.state.static_group_members
2646 )
2647 if is_dynamic_member:
2648 self.logger.debug(
2649 "Removing %s from dynamic group %s to honor explicit play_media target",
2650 player.state.name,
2651 group.state.name,
2652 )
2653 async with self.wait_for_player_update(
2654 player.player_id,
2655 attribute_name="active_group",
2656 attribute_value=None,
2657 timeout=5,
2658 ):
2659 await self.cmd_set_members(group.player_id, player_ids_to_remove=[player.player_id])
2660 return
2661 # static member: a single member can't be released, so the whole
2662 # group must dissolve. Prefer cmd_power when an explicit power
2663 # control is set so the user-visible state stays consistent.
2664 async with self.wait_for_player_update(
2665 player.player_id,
2666 attribute_name="active_group",
2667 attribute_value=None,
2668 timeout=5,
2669 ):
2670 if group.state.power_control != PLAYER_CONTROL_NONE and group.state.powered:
2671 self.logger.debug(
2672 "Powering off %s to honor explicit play_media target on %s",
2673 group.state.name,
2674 player.state.name,
2675 )
2676 await self._handle_cmd_power(group.player_id, False)
2677 else:
2678 self.logger.debug(
2679 "Stopping %s to honor explicit play_media target on %s",
2680 group.state.name,
2681 player.state.name,
2682 )
2683 await self._handle_cmd_stop(group.player_id)
2684
2685 def _mirrors_parent_media(self, player: Player) -> bool:
2686 """
2687 Return True if the player's current_media is taken from another player.
2688
2689 Grouped/synced members and protocol children mirror their parent's
2690 current_media (palette included), so they must not resolve it themselves.
2691
2692 :param player: The player to check.
2693 """
2694 state = player.state
2695 # a self-referential active_group/synced_to is not a real parent (mirror the
2696 # != self guard in Player.__final_current_media), so it must not skip resolution
2697 parent_id = state.active_group or state.synced_to
2698 if parent_id and parent_id != player.player_id:
2699 return True
2700 return state.type == PlayerType.PROTOCOL and player.protocol_parent_id is not None
2701
2702 def _schedule_palette_fetch(
2703 self, player_id: str, image_url: str | None, *, trigger_update: bool = True
2704 ) -> None:
2705 """
2706 Kick off an async palette extraction for an image URL.
2707
2708 :param player_id: Player the palette is scoped to (used for task dedup).
2709 :param image_url: Image URL to extract from. No-op when empty or already cached.
2710 :param trigger_update: When True, re-emit player state once palette is ready
2711 (current track). When False, only warm the cache (prefetch).
2712 """
2713 if not image_url:
2714 return
2715 # Key the task on the image (not just the player) so a track change always
2716 # schedules a fetch for the new image instead of being dropped by an in-flight
2717 # fetch for the previous one; repeated schedules for the same image still dedupe.
2718 slot = "current" if trigger_update else "next"
2719 self.mass.create_task(
2720 self._fetch_palette(player_id, image_url, trigger_update=trigger_update),
2721 task_id=f"palette_fetch_{player_id}_{slot}_{image_url}",
2722 abort_existing=False,
2723 )
2724
2725 async def _fetch_palette(self, player_id: str, image_url: str, *, trigger_update: bool) -> None:
2726 palette = await get_palette_for_url(self.mass, image_url)
2727 if palette is None or not trigger_update:
2728 return # prefetch only warms the cache controller; nothing to attach
2729 player = self.get_player(player_id)
2730 if player is None:
2731 return
2732 current = player.state.current_media
2733 if current is None or current.image_url != image_url:
2734 return # media changed while fetching
2735 # Carry the palette on player state so the (sync) serialization reads it back.
2736 player.set_resolved_palette(image_url, palette)
2737 # Avoid trigger_player_update so a concurrent state-change debounce
2738 # doesn't cancel our timer via the shared player_update_state task_id.
2739 self.mass.call_later(
2740 0,
2741 player.update_state,
2742 force_update=True,
2743 task_id=f"palette_player_update_{player_id}",
2744 )
2745
2746 def _schedule_next_queue_item_palette_prefetch(
2747 self, player_id: str, current_media: PlayerMedia
2748 ) -> None:
2749 """Warm the palette cache for the next queue item so it's hot at transition."""
2750 queue_id, item_id = current_media.source_id, current_media.queue_item_id
2751 if not queue_id or not item_id:
2752 return
2753 next_item = self.mass.player_queues.get_next_item(queue_id, item_id)
2754 if next_item is None or not next_item.image:
2755 return
2756 next_url = self.mass.metadata.get_image_url(
2757 next_item.image, size=512, prefer_stream_server=True
2758 )
2759 self._schedule_palette_fetch(player_id, next_url, trigger_update=False)
2760
2761 def _configured_control_ids(self, player_id: str) -> set[str]:
2762 """Return the player control ids the given player's config selects."""
2763 return {
2764 str(value)
2765 for conf_key in (CONF_POWER_CONTROL, CONF_VOLUME_CONTROL, CONF_MUTE_CONTROL)
2766 if (value := self.mass.config.get_raw_player_config_value(player_id, conf_key))
2767 }
2768
2769 def _get_volume_step(self, current_volume: int) -> int:
2770 """
2771 Return the step size for a single volume increment at the given level.
2772
2773 A configured (non-zero) `volume_step` is a flat step. The default of 0 keeps the
2774 adaptive ladder, which takes finer steps near the ends of the range.
2775 """
2776 if configured := self.get_config_value(CONF_VOLUME_STEP, 0, return_type=int):
2777 return configured
2778 if current_volume < 10 or current_volume > 90:
2779 return 1
2780 if current_volume < 30 or current_volume > 70:
2781 return 2
2782 return 3
2783
2784 def _get_volume_limits(self, player_id: str) -> tuple[int, int]:
2785 """Get the configured min/max volume limits for a player."""
2786 min_volume = int(
2787 cast(
2788 "int",
2789 self.mass.config.get_raw_player_config_value(
2790 player_id, CONF_MIN_VOLUME, CONF_ENTRY_MIN_VOLUME.default_value
2791 ),
2792 )
2793 )
2794 max_volume = int(
2795 cast(
2796 "int",
2797 self.mass.config.get_raw_player_config_value(
2798 player_id, CONF_MAX_VOLUME, CONF_ENTRY_MAX_VOLUME.default_value
2799 ),
2800 )
2801 )
2802 return min_volume, max_volume
2803
2804 def _enforce_volume_limits(self, player: Player) -> bool:
2805 """
2806 Clamp device volume to min/max range when changed externally.
2807
2808 :param player: The player to check the volume of.
2809 :return: True if the volume was outside the configured range and got corrected.
2810 """
2811 player_id = player.player_id
2812 min_volume, max_volume = self._get_volume_limits(player_id)
2813 if min_volume == 0 and max_volume == 100:
2814 return False
2815 # state.volume_level is the resolved logical volume, available for all
2816 # volume control types; a device volume outside the configured range
2817 # surfaces here as a value outside 0-100 (scaling does not clamp)
2818 logical_volume = player.state.volume_level
2819 if logical_volume is None or 0 <= logical_volume <= 100:
2820 return False
2821 clamped = max(0, min(100, logical_volume))
2822 # correct via the regular volume-set path so scaling and redirection apply
2823 self.mass.create_task(self._handle_cmd_volume_set(player_id, clamped))
2824 return True
2825
2826 def _forward_state_update(
2827 self, player: Player, changed_values: dict[str, tuple[Any, Any]]
2828 ) -> None:
2829 """Forward a player state update to related players (groups, sync parent, protocols)."""
2830 # TODO: make this fan-out change-aware (skip relatives that derive nothing from
2831 # the changed fields) once reverse indexes for synced_to/active_group exist.
2832 # Propagate group or sync-leader updates to child players.
2833 if player.state.group_members:
2834 for child_player in self.iter_group_members(player, exclude_self=True):
2835 if player.type == PlayerType.GROUP:
2836 child_player.on_group_updated(player, changed_values)
2837 else:
2838 child_player.on_sync_parent_updated(player, changed_values)
2839 # update/signal group player(s) when a member updates. A sync leader is a member of the
2840 # group player that formed the sync group and gaining members of its own does not change
2841 # that: a group player mirrors its leader, so it depends on exactly these updates.
2842 for group_player in self._get_player_groups(player):
2843 group_player.on_group_member_updated(player, changed_values)
2844
2845 # update/signal manually sync-parent player when child updates
2846 if (_sync_parent_id := player.state.synced_to) and (
2847 _sync_parent := self.get_player(_sync_parent_id)
2848 ):
2849 self.trigger_player_update(_sync_parent.player_id)
2850 # If this is a protocol player, forward the state update to the parent player
2851 if (
2852 player.type == PlayerType.PROTOCOL
2853 and player.protocol_parent_id
2854 and (_protocol_parent := self.mass.players.get_player(player.protocol_parent_id))
2855 ):
2856 _protocol_parent.on_protocol_player_updated(player, changed_values)
2857 # If this is a parent player with linked protocols, forward state updates
2858 # to linked protocol players so their state reflects parent dependencies
2859 if player.state.type != PlayerType.PROTOCOL and player.linked_output_protocols:
2860 for linked in player.linked_output_protocols:
2861 if protocol_player := self.mass.players.get_player(linked.output_protocol_id):
2862 protocol_player.on_protocol_parent_updated(player, changed_values)
2863
2864 def _invalidate_group_volume_snapshot(self, player_id: str) -> None:
2865 """Clear the cached group volume snapshot for all groups this player belongs to."""
2866 player = self.get_player(player_id)
2867 if not player:
2868 return
2869 if player.state.group_members:
2870 player.extra_data.pop(ATTR_GROUP_VOLUME_SNAPSHOT, None)
2871 for group_player in self._get_player_groups(player):
2872 group_player.extra_data.pop(ATTR_GROUP_VOLUME_SNAPSHOT, None)
2873 if player.state.synced_to and (leader := self.get_player(player.state.synced_to)):
2874 leader.extra_data.pop(ATTR_GROUP_VOLUME_SNAPSHOT, None)
2875
2876 def _record_volume_target(self, player: Player, volume_level: int) -> None:
2877 """Remember the volume level just commanded, as the base for the next nudge."""
2878 if self._stays_silent_on_volume_change(player):
2879 volume_level = 0
2880 player.extra_data[ATTR_VOLUME_TARGET] = (volume_level, time.monotonic())
2881
2882 def _volume_nudge_base(self, player: Player) -> int | None:
2883 """Return the volume level a volume nudge for the given player steps from."""
2884 target = self._unexpired_volume_target(player)
2885 if target is not None:
2886 return target
2887 return player.state.volume_level
2888
2889 def _group_volume_nudge_base(self, group_player: Player) -> int | None:
2890 """Return the volume level a group volume nudge for the given group steps from."""
2891 if not group_player.state.group_members:
2892 # an ungrouped player is stepped through its own volume, so it is that
2893 # volume the command lands on and that a following nudge steps from
2894 return self._volume_nudge_base(group_player)
2895 # mirrors Player.group_volume, but steps from the level last commanded to each
2896 # member instead of the level it reports, so the group is not held back by a
2897 # member that has not confirmed the previous nudge yet
2898 base: int | None = None
2899 for child_player in self.iter_group_members(
2900 group_player, only_powered=True, exclude_self=group_player.type != PlayerType.PLAYER
2901 ):
2902 if child_player.state.volume_control == PLAYER_CONTROL_NONE:
2903 continue
2904 if (child_volume := self._volume_nudge_base(child_player)) is None:
2905 continue
2906 if base is None or child_volume > base:
2907 base = child_volume
2908 return base
2909
2910 def _unexpired_volume_target(self, player: Player) -> int | None:
2911 """Return the volume level last commanded, or None once it is too old to trust."""
2912 if (target := player.extra_data.get(ATTR_VOLUME_TARGET)) is None:
2913 return None
2914 volume_level, issued_at = target
2915 if time.monotonic() - issued_at < VOLUME_TARGET_EXPIRY:
2916 return cast("int", volume_level)
2917 del player.extra_data[ATTR_VOLUME_TARGET]
2918 return None
2919
2920 def _dispatch_state_update_subscribers(
2921 self, player: Player, changed_values: dict[str, tuple[Any, Any]]
2922 ) -> None:
2923 """Notify all internal subscribers of a player state update."""
2924 for subscriber in list(self._state_update_subscribers):
2925 try:
2926 subscriber(player, changed_values)
2927 except Exception:
2928 self.logger.exception(
2929 "Error in player state update subscriber for %s", player.player_id
2930 )
2931
2932 async def _wait_for_playback_state(
2933 self,
2934 player: Player,
2935 wanted_state: PlaybackState,
2936 timeout: float,
2937 minimal_time: float = 0,
2938 ) -> None:
2939 """Wait for a player to reach a playback state, with optional minimum wait time."""
2940 start_timestamp = time.time()
2941 async with self.wait_for_player_update(
2942 player.player_id,
2943 attribute_name="playback_state",
2944 attribute_value=wanted_state,
2945 timeout=timeout,
2946 ):
2947 pass
2948 elapsed = time.time() - start_timestamp
2949 if elapsed < minimal_time:
2950 await asyncio.sleep(minimal_time - elapsed)
2951
2952 async def _clear_active_output_protocol_when_idle(self, player: Player) -> None:
2953 """Wait for the player to stop playing, then clear its active output protocol."""
2954 await self._wait_for_playback_state(player, PlaybackState.IDLE, timeout=10)
2955 player.set_active_output_protocol(None)
2956
2957 def _handle_membership_cleanup_on_state_change(
2958 self, player: Player, changed_values: dict[str, tuple[Any, Any]]
2959 ) -> None:
2960 """Detach a player from its (sync)groups when a state change requires it."""
2961 # A player that became unavailable or disabled can no longer be commanded,
2962 # so we drop it from its parent group/leader directly.
2963 became_inactive = (
2964 ATTR_AVAILABLE in changed_values and changed_values[ATTR_AVAILABLE][1] is False
2965 ) or (ATTR_ENABLED in changed_values and changed_values[ATTR_ENABLED][1] is False)
2966 if became_inactive and (player.state.active_group or player.state.synced_to):
2967 self.mass.create_task(self._cleanup_player_memberships(player.player_id))
2968
2969 # A player whose power was turned off outside of an MA power command (e.g. its
2970 # linked power control was switched off directly) must be unsynced too. We act
2971 # only on an explicit on->off transition, leaving players without power control
2972 # (powered == None) untouched. The player is still reachable here, so we route
2973 # through cmd_ungroup which also transfers leadership when it is a sync leader.
2974 if (
2975 changed_values.get(ATTR_POWERED) == (True, False)
2976 and player.state.type in UNGROUP_ON_POWER_OFF_TYPES
2977 and (player.state.synced_to or player.state.active_group or player.state.group_members)
2978 ):
2979 self.mass.create_task(self.cmd_ungroup(player.player_id))
2980
2981 def _handle_external_power_off(
2982 self, player: Player, changed_values: dict[str, tuple[Any, Any]]
2983 ) -> None:
2984 """End the queue of a player whose power was turned off outside of MA."""
2985 if (
2986 changed_values.get(ATTR_POWERED) != (True, False)
2987 or player.state.type not in PLAYBACK_TARGET_TYPES
2988 ):
2989 return
2990 if player.state.synced_to or player.state.active_group or player.state.group_members:
2991 # a grouped player is detached from its group instead, which ends the
2992 # group's queue through the group's own power off
2993 return
2994 # a device that powers itself off may report its stop in this very update, so
2995 # judge on the playback state as it was before it - which is also the snapshot
2996 # an MA power off works from
2997 prev_playback_state = (
2998 changed_values["playback_state"][0]
2999 if "playback_state" in changed_values
3000 else player.state.playback_state
3001 )
3002 if prev_playback_state not in (PlaybackState.PLAYING, PlaybackState.PAUSED):
3003 return
3004 self.mass.call_later(
3005 EXTERNAL_POWER_OFF_STOP_DELAY,
3006 self._stop_queue_on_external_power_off,
3007 player.player_id,
3008 task_id=f"external_power_off_stop_{player.player_id}",
3009 )
3010
3011 async def _stop_queue_on_external_power_off(self, player_id: str) -> None:
3012 """
3013 End the queue of a player that is still powered off.
3014
3015 :param player_id: The player whose power was turned off outside of MA.
3016 """
3017 # hold the playback lock across the checks: a power on that overlaps the wait
3018 # holds it while it resumes the queue, and reading the power state before that
3019 # completes would stop the playback it just started (the lock is re-entrant per
3020 # task, so the stop below re-acquiring it is a no-op)
3021 async with self.get_player_lock(player_id, PlayerLockPurpose.PLAYBACK):
3022 if not (player := self.get_player(player_id)) or player.state.powered is not False:
3023 # the power came back on while we were waiting it out
3024 return
3025 # only the player's own queue: get_active_queue resolves to another player's
3026 # queue as soon as this one is hearing someone else's audio
3027 active_queue = self.get_active_queue(player)
3028 if active_queue is None or active_queue.queue_id != player_id:
3029 return
3030 # a player gone unavailable along with its power cannot be told to stop,
3031 # but the queue teardown that matters here runs regardless
3032 with suppress(PlayerUnavailableError):
3033 await self.mass.player_queues._handle_stop(player_id)
3034
3035 async def _cleanup_player_memberships(self, player_id: str) -> None:
3036 """Ensure a player is detached from any groups or syncgroups."""
3037 if not (player := self.get_player(player_id)):
3038 return
3039 with suppress(UnsupportedFeaturedException, PlayerCommandFailed, PlayerUnavailableError):
3040 if parent_id := (player.state.active_group or player.state.synced_to):
3041 # the player is part of a (permanent) groupplayer and the user tries to ungroup
3042 if parent_player := self.get_player(parent_id):
3043 await self._handle_set_members(parent_player, player_ids_to_remove=[player_id])
3044 return
3045
3046 def _get_player_with_redirect(self, player_id: str) -> Player:
3047 """Get player with check if playback related command should be redirected."""
3048 player = self.get_player(player_id, True)
3049 assert player is not None # for type checking
3050 if player.state.synced_to and (sync_leader := self.get_player(player.state.synced_to)):
3051 self.logger.info(
3052 "Player %s is synced to %s and can not accept "
3053 "playback related commands itself, "
3054 "redirected the command to the sync leader.",
3055 player.name,
3056 sync_leader.name,
3057 )
3058 return sync_leader
3059 if player.state.active_group and (
3060 active_group := self.get_player(player.state.active_group)
3061 ):
3062 self.logger.info(
3063 "Player %s is part of a playergroup and can not accept "
3064 "playback related commands itself, "
3065 "redirected the command to the group leader.",
3066 player.name,
3067 )
3068 return active_group
3069 return player
3070
3071 def _get_active_audio_source(self, player: Player) -> tuple[AudioSource, PluginProvider] | None:
3072 """
3073 Return the live AudioSource a player is playing, and its owning PluginProvider.
3074
3075 A player hearing its group's or sync leader's audio is playing that player's
3076 source, so the owner is resolved the same way its active queue is. Returns
3077 None when no source is playing on it, or when the owning plugin is gone.
3078
3079 :param player: The player whose source to resolve.
3080 """
3081 return self.get_player_audio_source(self._audio_source_owner(player).player_id)
3082
3083 def _audio_source_owner(self, player: Player) -> Player:
3084 """
3085 Return the player whose source the given player is hearing.
3086
3087 Mirrors ``get_active_queue``: a sync child hears its leader, a group member
3088 hears its group, and a protocol player hears its parent.
3089
3090 :param player: The player to resolve the owner for.
3091 """
3092 if player.state.synced_to and player.state.synced_to != player.player_id:
3093 if sync_leader := self.get_player(player.state.synced_to):
3094 return self._audio_source_owner(sync_leader)
3095 if player.state.active_group and player.state.active_group != player.player_id:
3096 if group_player := self.get_player(player.state.active_group):
3097 return self._audio_source_owner(group_player)
3098 if player.type == PlayerType.PROTOCOL and player.protocol_parent_id:
3099 if parent_player := self.get_player(player.protocol_parent_id):
3100 return self._audio_source_owner(parent_player)
3101 return player
3102
3103 def _get_player_groups(self, player: Player) -> Iterator[Player]:
3104 """
3105 Return all group players the given player is a member of.
3106
3107 :param player: The player to look up the group memberships for.
3108 """
3109 # A group player mirrors its members, so it is also included while unavailable -
3110 # skipping it there is exactly how its state goes stale.
3111 player_id = player.player_id
3112 for _player in self.iter_players():
3113 if _player.player_id == player_id:
3114 continue
3115 if _player.state.type != PlayerType.GROUP:
3116 continue
3117 if player_id in _player.state.group_members:
3118 yield _player
3119
3120 # Protocol linking methods are provided by ProtocolLinkingMixin (protocol_linking.py)
3121
3122 def _repair_protocol_parent_links(self) -> None:
3123 """
3124 Repair protocol parent links in player configs on startup.
3125
3126 Scans player configs with a protocol_parent_id set and clears parent_ids
3127 that point to player configs that no longer exist (e.g., deleted universal
3128 players). A valid parent link also proves the player is a protocol child,
3129 so a stale player_type (left behind by an aborted registration) is healed.
3130 """
3131 all_player_configs = self.mass.config.get(CONF_PLAYERS, {})
3132 for player_id, player_config in all_player_configs.items():
3133 values = player_config.get("values") or {}
3134 parent_id = values.get(CONF_PROTOCOL_PARENT_ID)
3135 if not parent_id:
3136 continue
3137 # Check if parent config still exists
3138 parent_config = all_player_configs.get(parent_id)
3139 if not parent_config:
3140 self.logger.debug(
3141 "Clearing stale protocol_parent_id %s for %s (parent config deleted)",
3142 parent_id,
3143 player_id,
3144 )
3145 conf_key = f"{CONF_PLAYERS}/{player_id}/values/{CONF_PROTOCOL_PARENT_ID}"
3146 self.mass.config.set(conf_key, None)
3147 continue
3148 if player_config.get("player_type") != PlayerType.PROTOCOL.value:
3149 self.logger.info(
3150 "Repairing player type of %s - linked as protocol child of %s",
3151 player_id,
3152 parent_id,
3153 )
3154 self.mass.config.set_player_type(player_id, PlayerType.PROTOCOL)
3155
3156 async def _fix_group_member_configs(self) -> None:
3157 """
3158 Fix stale protocol player IDs in sync group member configs.
3159
3160 When a sync group references a protocol player ID instead of
3161 the parent player ID, correct it using the cached protocol parent mapping.
3162 """
3163 all_player_configs = self.mass.config.get(CONF_PLAYERS, {})
3164 total_fixes = 0
3165 fixed_groups: list[str] = []
3166
3167 for group_id, group_config in list(all_player_configs.items()):
3168 if group_config.get("provider") != "sync_group":
3169 continue
3170 old_members: list[str] = group_config.get("values", {}).get(CONF_GROUP_MEMBERS, [])
3171 if not old_members:
3172 continue
3173
3174 new_members: list[str] = []
3175 changes = 0
3176 for member_id in old_members:
3177 parent_id = self._get_cached_protocol_parent_id(member_id)
3178 corrected_id = parent_id or member_id
3179 if corrected_id != member_id:
3180 changes += 1
3181 self.logger.debug(
3182 "Sync group %s: corrected member %s -> %s",
3183 group_id,
3184 member_id,
3185 corrected_id,
3186 )
3187 if corrected_id not in new_members:
3188 new_members.append(corrected_id)
3189
3190 if changes:
3191 self.mass.config.set_raw_player_config_value(
3192 group_id, CONF_GROUP_MEMBERS, new_members
3193 )
3194 total_fixes += changes
3195 fixed_groups.append(group_id)
3196
3197 for group_id in fixed_groups:
3198 if (group_player := self.get_player(group_id)) and group_player.available:
3199 await group_player.on_config_updated()
3200
3201 if total_fixes:
3202 self.logger.info(
3203 "Fixed %d stale member reference(s) across %d sync group(s)",
3204 total_fixes,
3205 len(fixed_groups),
3206 )
3207
3208 async def _poll_players(self) -> None:
3209 """Background task that polls players for updates."""
3210 while True:
3211 for player in list(self._players.values()):
3212 # if the player is playing, update elapsed time every tick
3213 # to ensure the queue has accurate details
3214 player_playing = player.state.playback_state == PlaybackState.PLAYING
3215 if player_playing and player.type != PlayerType.PROTOCOL:
3216 self.mass.call_later(
3217 0.5,
3218 self.mass.player_queues.on_player_update,
3219 player,
3220 {"corrected_elapsed_time": (None, player.state.corrected_elapsed_time)},
3221 task_id=f"queue_on_player_update_{player.player_id}",
3222 )
3223 # Poll player;
3224 if not player.needs_poll:
3225 continue
3226 try:
3227 last_poll: float = player.extra_data[ATTR_LAST_POLL]
3228 except KeyError:
3229 last_poll = 0.0
3230 if (self.mass.loop.time() - last_poll) < player.poll_interval:
3231 continue
3232 player.extra_data[ATTR_LAST_POLL] = self.mass.loop.time()
3233 try:
3234 await player.poll()
3235 except Exception as err:
3236 self.logger.warning(
3237 "Error while requesting latest state from player %s: %s",
3238 player.state.name,
3239 str(err),
3240 exc_info=err if self.logger.isEnabledFor(10) else None,
3241 )
3242 # Yield to event loop to prevent blocking
3243 await asyncio.sleep(0)
3244 await asyncio.sleep(1)
3245
3246 def _handle_group_dsp_change(
3247 self, player: Player, prev_group_members: list[str], new_group_members: list[str]
3248 ) -> None:
3249 """Handle DSP reload when group membership changes."""
3250 # reset cached group volume snapshot since membership changed
3251 player.extra_data.pop(ATTR_GROUP_VOLUME_SNAPSHOT, None)
3252 prev_child_count = len(prev_group_members)
3253 new_child_count = len(new_group_members)
3254 is_player_group = player.state.type == PlayerType.GROUP
3255
3256 # handle special case for PlayerGroups: since there are no leaders,
3257 # DSP still always work with a single player in the group.
3258 multi_device_dsp_threshold = 1 if is_player_group else 0
3259
3260 prev_is_multiple_devices = prev_child_count > multi_device_dsp_threshold
3261 new_is_multiple_devices = new_child_count > multi_device_dsp_threshold
3262
3263 if prev_is_multiple_devices == new_is_multiple_devices:
3264 return # no change in multi-device status
3265
3266 supports_multi_device_dsp = (
3267 PlayerFeature.MULTI_DEVICE_DSP in player.state.supported_features
3268 )
3269
3270 dsp_enabled: bool
3271 if player.state.type == PlayerType.GROUP:
3272 # Since player groups do not have leaders, we will use the only child
3273 # that was in the group before and after the change
3274 if prev_is_multiple_devices:
3275 if childs := new_group_members:
3276 # We shrank the group from multiple players to a single player
3277 # So the now only child will control the DSP
3278 dsp_enabled = self.mass.config.get_player_dsp_config(childs[0]).enabled
3279 else:
3280 dsp_enabled = False
3281 elif childs := prev_group_members:
3282 # We grew the group from a single player to multiple players,
3283 # let's see if the previous single player had DSP enabled
3284 dsp_enabled = self.mass.config.get_player_dsp_config(childs[0]).enabled
3285 else:
3286 dsp_enabled = False
3287 else:
3288 dsp_enabled = self.mass.config.get_player_dsp_config(player.player_id).enabled
3289
3290 if dsp_enabled and not supports_multi_device_dsp:
3291 # We now know that the group configuration has changed so:
3292 # - multi-device DSP is not supported
3293 # - we switched from a group with multiple players to a single player
3294 # (or vice versa)
3295 # - the leader has DSP enabled
3296 self.mass.create_task(self.mass.players.on_player_dsp_change(player.player_id))
3297
3298 def _check_external_source_takeover(self, player: Player) -> None:
3299 """
3300 Handle when an external source takes over playback on a player.
3301
3302 When a player has an active grouped output protocol (e.g., AirPlay group) and
3303 an external source (e.g., Spotify Connect, TV input) takes over playback,
3304 we need to clear the active output protocol and ungroup the protocol players.
3305
3306 This prevents the situation where the player appears grouped via protocol
3307 but is actually playing from a different source.
3308
3309 :param player: The player whose active_source changed.
3310 """
3311 # Only relevant for non-protocol players
3312 if player.type == PlayerType.PROTOCOL:
3313 return
3314
3315 # Not a takeover if the player is not actively playing
3316 if player.playback_state != PlaybackState.PLAYING:
3317 return
3318
3319 # Only relevant if we have an active output protocol (not native)
3320 if not player.active_output_protocol or player.active_output_protocol == "native":
3321 return
3322
3323 new_source = player.state.active_source
3324
3325 # Check if new source is external (not MA-managed)
3326 if self._is_ma_managed_source(player, new_source):
3327 return
3328
3329 # Get the active protocol player
3330 protocol_player = self.get_player(player.active_output_protocol)
3331 if not protocol_player:
3332 return
3333
3334 # If the source matches the active protocol's domain, it's expected - not a takeover
3335 # e.g., source "airplay" when using AirPlay protocol is normal
3336 if new_source and new_source.lower() == protocol_player.provider.domain.lower():
3337 return
3338
3339 if (
3340 new_source
3341 and new_source.lower() in ("airplay", "cast", "chromecast", "network")
3342 and protocol_player.provider.domain.lower() == "sendspin"
3343 ):
3344 # Special case for Sendspin bridge: if the new source matches cast or airplay and the
3345 # active protocol is Sendspin, we consider this a normal behavior and not a takeover
3346 return
3347
3348 # Confirmed external source takeover
3349 self.logger.info(
3350 "External source '%s' took over on %s while playing via protocol %s - "
3351 "clearing active output protocol and ungrouping",
3352 new_source,
3353 player.display_name,
3354 protocol_player.provider.domain,
3355 )
3356
3357 # Set active output protocol to native
3358 player.set_active_output_protocol("native")
3359
3360 # Ungroup the protocol player (async task)
3361 self.mass.create_task(protocol_player.ungroup())
3362
3363 def _is_ma_managed_source(self, player: Player, source: str | None) -> bool:
3364 """
3365 Check if a source is managed by Music Assistant.
3366
3367 MA-managed sources include:
3368 - None (=autodetect, no source explicitly set by player)
3369 - The player's own ID (MA queue)
3370 - Any active queue ID
3371 - Any live AudioSource session
3372
3373 :param player: The player to check.
3374 :param source: The source ID to check.
3375 :return: True if the source is MA-managed, False if external.
3376 """
3377 if source is None:
3378 return True
3379
3380 # Player's own ID means MA queue is active
3381 if source == player.player_id:
3382 return True
3383
3384 # A live AudioSource (e.g. Spotify Connect) is streamed by MA itself, so it is
3385 # MA that put it on the player rather than something taking the player over
3386 if self.is_live_audio_source(source):
3387 return True
3388
3389 # Check if it's a known queue ID
3390 return self.mass.player_queues.get(source) is not None
3391
3392 def _schedule_update_all_players(self, delay: float = 2.0) -> None:
3393 """
3394 Schedule a debounced update of all players' state.
3395
3396 Used when a new player is registered to ensure all existing players
3397 update their dynamic properties (like can_group_with) that may have changed.
3398
3399 :param delay: Delay in seconds before triggering updates (default 2.0).
3400 """
3401 if self.mass.closing:
3402 return
3403
3404 for player in self.all_players(
3405 return_unavailable=True,
3406 return_disabled=False,
3407 return_protocol_players=True,
3408 ):
3409 self.trigger_player_update(player.player_id, debounce_delay=delay)
3410
3411 async def _auto_ungroup_if_synced(self, player: Player, log_context: str) -> None:
3412 """
3413 Automatically ungroup a player if it's synced to another player.
3414
3415 :param player: The player to check and potentially ungroup.
3416 :param log_context: Additional context for the log message (e.g., target player name).
3417 """
3418 if not player.state.synced_to and not player.state.active_group:
3419 return
3420 self.logger.info(
3421 "Player %s is already synced to %s, ungrouping it first before %s",
3422 player.name,
3423 player.state.synced_to or player.state.active_group,
3424 log_context,
3425 )
3426 # Use internal _handle_set_members to avoid deadlocking on the play lock
3427 # (we're already inside a cmd_set_members chain that holds a play lock).
3428 synced_to = player.state.synced_to or player.state.active_group
3429 if synced_to and (parent := self.get_player(synced_to)):
3430 try:
3431 async with self.wait_for_player_update(player.player_id, timeout=5):
3432 await self._handle_set_members(parent, player_ids_to_remove=[player.player_id])
3433 except asyncio.CancelledError:
3434 raise
3435 except Exception:
3436 self.logger.warning(
3437 "Failed to auto-ungroup %s from %s, proceeding anyway",
3438 player.name,
3439 synced_to,
3440 )
3441
3442 async def _dissolve_own_group(self, player: Player, target_name: str) -> bool:
3443 """
3444 Dissolve the group a player leads before it joins another group.
3445
3446 Only a player whose members ride its own stream has a group to give up: it stops
3447 rendering that stream the moment it joins the other group, which would leave its
3448 members silent while they still show up as grouped. A group that is still playing
3449 is refused instead, so the player stays out rather than silencing its members.
3450
3451 :param player: The player about to join another group.
3452 :param target_name: Name of the group being joined, for the log messages.
3453 :return: False when the group is still in place, so the player must not join.
3454 """
3455 if not player.native_grouping_requires_own_stream:
3456 return True
3457 members = [
3458 member_id for member_id in player.state.group_members if member_id != player.player_id
3459 ]
3460 if not members:
3461 return True
3462 if player.state.playback_state in (PlaybackState.PLAYING, PlaybackState.PAUSED):
3463 # Grouping never offers a rendering leader as a target, so reaching this means
3464 # the caller worked from a can_group_with snapshot taken before the playback
3465 # started. Tearing the group down now would cut its members off mid-track.
3466 self.logger.warning(
3467 "Player %s is still serving its own group, leaving it out of %s",
3468 player.name,
3469 target_name,
3470 )
3471 return False
3472 self.logger.info(
3473 "Player %s leads a group of its own, dissolving it before it joins %s",
3474 player.name,
3475 target_name,
3476 )
3477 # Removing the members rather than the leader keeps this out of the leadership
3478 # transfer path, and the internal handler avoids deadlocking on the play lock
3479 # (we're already inside a cmd_set_members chain that holds it).
3480 try:
3481 await self._handle_set_members(player, player_ids_to_remove=members)
3482 except asyncio.CancelledError:
3483 raise
3484 except Exception:
3485 # Joining on top of a group it still leads is the silent-member state this
3486 # dissolve exists to prevent, and one the player can no longer be talked out of.
3487 self.logger.warning(
3488 "Could not dissolve the group of %s, leaving it out of %s",
3489 player.name,
3490 target_name,
3491 )
3492 return False
3493 return True
3494
3495 async def _handle_set_members(
3496 self,
3497 parent_player: Player,
3498 player_ids_to_add: list[str] | None = None,
3499 player_ids_to_remove: list[str] | None = None,
3500 ) -> None:
3501 """
3502 Handle the actual set_members logic.
3503
3504 Skips permission checks and locking (internal use only).
3505
3506 :param parent_player: The parent player to add/remove members to/from.
3507 :param player_ids_to_add: List of player_id's to add to the parent player.
3508 :param player_ids_to_remove: List of player_id's to remove from the parent player.
3509 """
3510 target_player = parent_player.player_id
3511 # handle the sync leader being removed from itself: either transfer leadership
3512 # to a remaining member (keeping playback alive) or dissolve the group entirely
3513 should_stop = False
3514 if player_ids_to_remove and target_player in player_ids_to_remove:
3515 remaining_members = [
3516 m
3517 for m in parent_player.state.group_members
3518 if m != target_player
3519 and m not in player_ids_to_remove
3520 and (member := self.get_player(m))
3521 and member.state.available
3522 ]
3523 # a new leader must be able to render audio: a group with only display,
3524 # visualizer or lighting members left has no playback heir and dissolves
3525 has_playback_heir = any(
3526 (member := self.get_player(m)) and member.state.type in PLAYBACK_TARGET_TYPES
3527 for m in remaining_members
3528 )
3529 active_queue = self.get_active_queue(parent_player)
3530 if has_playback_heir and active_queue and active_queue.state != PlaybackState.IDLE:
3531 # transfer leadership to a remaining member instead of dissolving
3532 await self._transfer_ad_hoc_leadership(parent_player, remaining_members)
3533 return
3534 self.logger.info(
3535 "Dissolving sync group of player %s as it is being removed from itself",
3536 parent_player.name,
3537 )
3538 player_ids_to_add = None
3539 player_ids_to_remove = [
3540 x for x in parent_player.state.group_members if x != target_player
3541 ]
3542 should_stop = True
3543 # filter all player ids on compatibility and availability
3544 final_player_ids_to_add: list[str] = []
3545 for child_player_id in player_ids_to_add or []:
3546 if child_player_id == target_player:
3547 continue
3548 if child_player_id in final_player_ids_to_add:
3549 continue
3550 if (
3551 not (child_player := self.get_player(child_player_id))
3552 or not child_player.state.available
3553 ):
3554 self.logger.warning("Player %s is not available", child_player_id)
3555 continue
3556
3557 # check if player can be synced/grouped with the target player
3558 # state.can_group_with already handles all expansion and translation
3559 if child_player_id not in parent_player.state.can_group_with:
3560 self.logger.warning(
3561 "Player %s can not be grouped with %s",
3562 child_player.name,
3563 parent_player.name,
3564 )
3565 continue
3566
3567 if (
3568 child_player.state.synced_to
3569 and child_player.state.synced_to == target_player
3570 and child_player_id in parent_player.state.group_members
3571 ):
3572 continue # already synced to this target
3573
3574 # also skip if the child is part of this group via its sync leader
3575 # (e.g. synced to the sync leader of this syncgroup)
3576 if (
3577 child_player.state.active_group == target_player
3578 and child_player_id in parent_player.state.group_members
3579 ):
3580 continue
3581
3582 # handle edge case: child player is synced to a different player
3583 # automatically ungroup it first and wait for state to propagate
3584 # but not if the child is already part of this group (via its sync leader)
3585 if child_player.state.synced_to and target_player not in {
3586 child_player.state.synced_to,
3587 child_player.state.active_group,
3588 }:
3589 await self._auto_ungroup_if_synced(child_player, f"joining {parent_player.name}")
3590
3591 # handle edge case: the child leads a native group of its own, which it cannot
3592 # keep serving from inside this one
3593 if not await self._dissolve_own_group(child_player, parent_player.state.name):
3594 continue
3595
3596 # power on the player if needed
3597 if (
3598 not child_player.state.powered
3599 and child_player.state.power_control != PLAYER_CONTROL_NONE
3600 ):
3601 await self._handle_cmd_power(child_player.player_id, True)
3602 # if we reach here, all checks passed
3603 final_player_ids_to_add.append(child_player_id)
3604
3605 # process player ids to remove and filter out invalid/unavailable players and edge cases
3606 final_player_ids_to_remove: list[str] = []
3607 if player_ids_to_remove:
3608 for child_player_id in player_ids_to_remove:
3609 if child_player_id in parent_player.state.group_members:
3610 final_player_ids_to_remove.append(child_player_id)
3611 continue
3612 # also accept the removal if the child player itself reports
3613 # being synced to this parent - handles race conditions where the
3614 # parent's group_members state is stale/not yet updated. The
3615 # native synced_to is checked as well: a protocol child's state
3616 # value is translated to the visible parent, which would reject
3617 # a removal correctly addressed at its native sync leader.
3618 child_player = self.get_player(child_player_id)
3619 if child_player and target_player in (
3620 child_player.state.synced_to,
3621 child_player.synced_to,
3622 ):
3623 final_player_ids_to_remove.append(child_player_id)
3624 continue
3625
3626 # Forward command to the appropriate player after all (base) sanity checks
3627 # GROUP players (sync_group, universal_group) manage their own members internally
3628 # and don't need protocol translation - call their set_members directly
3629 if (
3630 parent_player.type == PlayerType.GROUP
3631 and PlayerFeature.SET_MEMBERS in parent_player.state.supported_features
3632 ):
3633 await parent_player.set_members(
3634 player_ids_to_add=final_player_ids_to_add,
3635 player_ids_to_remove=final_player_ids_to_remove,
3636 )
3637 return
3638 # For regular players, handle protocol selection and translation
3639 await self._handle_set_members_with_protocols(
3640 parent_player, final_player_ids_to_add, final_player_ids_to_remove
3641 )
3642
3643 if should_stop:
3644 await self._stop_player_or_its_queue(parent_player)
3645
3646 async def _handle_set_members_with_protocols(
3647 self,
3648 parent_player: Player,
3649 player_ids_to_add: list[str],
3650 player_ids_to_remove: list[str],
3651 ) -> None:
3652 """
3653 Handle set_members considering protocol and native members.
3654
3655 Skips permission checks, locking, and all redirect logic (internal use only).
3656 Translates visible player IDs to protocol player IDs when appropriate,
3657 and forwards to the correct player's set_members.
3658
3659 :param parent_player: The parent player to add/remove members to/from.
3660 :param player_ids_to_add: List of visible player IDs to add as members.
3661 :param player_ids_to_remove: List of visible player IDs to remove from members.
3662 """
3663 # Get parent's active protocol domain and player if available
3664 parent_protocol_domain = None
3665 parent_protocol_player = None
3666 if (
3667 parent_player.active_output_protocol
3668 and parent_player.active_output_protocol != "native"
3669 ):
3670 parent_protocol_player = self.get_player(parent_player.active_output_protocol)
3671 if parent_protocol_player:
3672 parent_protocol_domain = parent_protocol_player.provider.domain
3673
3674 self.logger.debug(
3675 "set_members on %s: active_protocol=%s, adding=%s, removing=%s",
3676 parent_player.state.name,
3677 parent_protocol_domain or "none",
3678 player_ids_to_add,
3679 player_ids_to_remove,
3680 )
3681
3682 # Translate members to add
3683 (
3684 protocol_members_to_add,
3685 native_members_to_add,
3686 parent_protocol_player,
3687 parent_protocol_domain,
3688 ) = self._translate_members_for_protocols(
3689 parent_player, player_ids_to_add, parent_protocol_player, parent_protocol_domain
3690 )
3691
3692 self.logger.debug(
3693 "Translated members: protocol=%s (domain=%s), native=%s",
3694 protocol_members_to_add,
3695 parent_protocol_domain,
3696 native_members_to_add,
3697 )
3698
3699 # Translate members to remove
3700 protocol_members_to_remove, native_members_to_remove = (
3701 self._translate_members_to_remove_for_protocols(
3702 parent_player, player_ids_to_remove, parent_protocol_player, parent_protocol_domain
3703 )
3704 )
3705
3706 # Forward protocol members to protocol player's set_members
3707 if (protocol_members_to_add or protocol_members_to_remove) and parent_protocol_player:
3708 await self._forward_protocol_set_members(
3709 parent_player,
3710 parent_protocol_player,
3711 protocol_members_to_add,
3712 protocol_members_to_remove,
3713 )
3714
3715 # Forward native members to parent player's set_members
3716 if native_members_to_add or native_members_to_remove:
3717 filtered_native_add = self._filter_native_members(native_members_to_add, parent_player)
3718 # For removal, allow protocol players if they're actually in the parent's group_members
3719 # This handles native protocol players (e.g., native AirPlay) where group_members
3720 # contains protocol player IDs
3721 filtered_native_remove = [
3722 pid
3723 for pid in native_members_to_remove
3724 if (p := self.get_player(pid))
3725 and (p.type != PlayerType.PROTOCOL or pid in parent_player.group_members)
3726 ]
3727 self.logger.debug(
3728 "Native grouping on %s: filtered_add=%s, filtered_remove=%s",
3729 parent_player.state.name,
3730 filtered_native_add,
3731 filtered_native_remove,
3732 )
3733 if filtered_native_add or filtered_native_remove:
3734 if PlayerFeature.SET_MEMBERS not in parent_player.state.supported_features:
3735 return
3736 self.logger.info(
3737 "Calling set_members on native player %s with add=%s, remove=%s",
3738 parent_player.state.name,
3739 filtered_native_add,
3740 filtered_native_remove,
3741 )
3742 await parent_player.set_members(
3743 player_ids_to_add=filtered_native_add or None,
3744 player_ids_to_remove=filtered_native_remove or None,
3745 )
3746
3747 async def _transfer_ad_hoc_leadership(
3748 self, leader: Player, remaining_members: list[str]
3749 ) -> None:
3750 """
3751 Transfer leadership of an ad-hoc sync group to a remaining member.
3752
3753 Called when the sync leader of an ad-hoc group is unjoined while other
3754 members remain and playback is active. The queue is moved to a newly
3755 selected leader, the remaining members are regrouped under it and playback
3756 resumes at the saved position (accepting a brief audio gap).
3757
3758 :param leader: The current sync leader being removed from the group.
3759 :param remaining_members: Available group members (excluding the leader)
3760 that should keep playing under a new leader.
3761 """
3762 active_queue = self.get_active_queue(leader)
3763 was_playing = active_queue is not None and active_queue.state == PlaybackState.PLAYING
3764 new_leader_id = self._select_ad_hoc_leader(leader, remaining_members)
3765 self.logger.info(
3766 "Transferring leadership of %s to %s (%s remaining member(s))",
3767 leader.name,
3768 new_leader_id,
3769 len(remaining_members),
3770 )
3771 # Move the queue to the new leader. transfer_queue frees the new leader from
3772 # the old leader's group and stops the old leader; the playback position
3773 # survives because stop() stores it in resume_pos.
3774 await self.mass.player_queues.transfer_queue(
3775 leader.player_id, new_leader_id, auto_play=False
3776 )
3777 # regroup the other remaining members under the new leader
3778 other_members = [m for m in remaining_members if m != new_leader_id]
3779 if other_members:
3780 await self.cmd_set_members(new_leader_id, player_ids_to_add=other_members)
3781 if was_playing:
3782 await self.mass.player_queues.resume(new_leader_id)
3783
3784 def _select_ad_hoc_leader(self, leader: Player, remaining_members: list[str]) -> str:
3785 """
3786 Pick the new leader for an ad-hoc sync group leadership transfer.
3787
3788 Prefers a remaining member that can currently be reached on the protocol the
3789 group is playing on, so the other members can be regrouped under it; falls back
3790 to the first remaining member. The members' own ``can_group_with`` is unusable
3791 here because it is empty while they are still synced to the old leader.
3792
3793 :param leader: The current sync leader being removed.
3794 :param remaining_members: Candidate member player_ids, already filtered for
3795 availability. Must contain at least one audio-capable member.
3796 """
3797 # non-audio members (display/visualizer/lighting) stay in the group as followers
3798 # but can never inherit the queue
3799 candidates = [
3800 m
3801 for m in remaining_members
3802 if (member := self.get_player(m)) and member.state.type in PLAYBACK_TARGET_TYPES
3803 ]
3804 active_domain: str | None = None
3805 if leader.active_output_protocol and leader.active_output_protocol != "native":
3806 if protocol_player := self.get_player(leader.active_output_protocol):
3807 active_domain = protocol_player.provider.domain
3808 if active_domain:
3809 for member_id in candidates:
3810 member = self.get_player(member_id)
3811 if member is None:
3812 continue
3813 if active_domain in member.playback_domains:
3814 return member_id
3815 return candidates[0]
3816
3817 async def _stop_player_or_its_queue(self, player: Player) -> None:
3818 """
3819 Stop the player, ending its queue when it is playing one of its own.
3820
3821 :param player: The player to stop.
3822 """
3823 # End the queue itself, exactly as a stop command does: stopping only the device
3824 # leaves the queue session open, so its preloading keeps pulling audio and a
3825 # provider streaming a live session (Spotify) stays tethered for another track or
3826 # two. Restricted to the player's own queue: get_active_queue resolves a protocol
3827 # player to its parent, and stopping that parent's queue would come straight back
3828 # here. The permission-free handler, because both callers act on behalf of the
3829 # server rather than a user that can address the player.
3830 if (
3831 active_queue := self.get_active_queue(player)
3832 ) and active_queue.queue_id == player.player_id:
3833 await self.mass.player_queues._handle_stop(player.player_id)
3834 return
3835 await self._handle_cmd_stop(player.player_id)
3836
3837 def _clear_sleep_timer(self, player: Player) -> None:
3838 """
3839 Clear the active sleep timer for the player.
3840
3841 :param player: Player to clear the timer for.
3842 """
3843 self.mass.cancel_timer(self._sleep_timer_task_id(player.player_id))
3844 if player.sleep_timer_expires_at is not None:
3845 player.set_sleep_timer_expires_at(None)
3846 player.update_state()
3847 self._signal_sleep_timer_updated(player, None)
3848
3849 async def _handle_sleep_timer_expired(self, player_id: str) -> None:
3850 """
3851 Stop playback when a player's sleep timer expires.
3852
3853 :param player_id: Player ID whose sleep timer expired.
3854 """
3855 player = self.get_player(player_id)
3856 if player is None or player.sleep_timer_expires_at is None:
3857 return
3858 player.set_sleep_timer_expires_at(None)
3859 player.update_state()
3860 self._signal_sleep_timer_updated(player, None)
3861 await self.cmd_stop(player_id)
3862
3863 def _signal_sleep_timer_updated(self, player: Player, expires_at: float | None) -> None:
3864 """
3865 Signal a sleep timer change for the player on the event bus.
3866
3867 :param player: Player whose sleep timer changed.
3868 :param expires_at: New expiry timestamp, or None when the timer was cleared.
3869 """
3870 if player.state.type == PlayerType.PROTOCOL:
3871 return
3872 self.mass.signal_event(
3873 EventType.PLAYER_SLEEP_TIMER_UPDATED,
3874 object_id=player.player_id,
3875 data=expires_at,
3876 )
3877
3878 @staticmethod
3879 def _sleep_timer_task_id(player_id: str) -> str:
3880 """
3881 Return the scheduled task ID for a player's sleep timer.
3882
3883 :param player_id: Player ID to build the task ID for.
3884 """
3885 return f"player_sleep_timer_{player_id}"
3886
3887 # Private command handlers (no permission checks)
3888
3889 async def _handle_cmd_resume(
3890 self, player_id: str, source: str | None = None, media: PlayerMedia | None = None
3891 ) -> None:
3892 """
3893 Handle resume playback command.
3894
3895 Skips permission checks and locking (internal use only).
3896 """
3897 player = self._get_player_with_redirect(player_id)
3898 source = source or player.state.active_source
3899 media = media or player.state.current_media
3900 # power on the player if needed
3901 if not player.state.powered and player.state.power_control != PLAYER_CONTROL_NONE:
3902 await self._handle_cmd_power(player.player_id, True)
3903 # Redirect to queue controller if it is active
3904 if active_queue := self.mass.player_queues.get(source or player_id):
3905 await self.mass.player_queues.resume(active_queue.queue_id)
3906 return
3907 # try to handle command on player directly
3908 # TODO: check if player has an active source with native resume support
3909 active_source = next((x for x in player.state.source_list if x.id == source), None)
3910 if (
3911 player.state.playback_state in (PlaybackState.IDLE, PlaybackState.PAUSED)
3912 and active_source
3913 and active_source.can_play_pause
3914 and PlayerFeature.PAUSE in player.state.supported_features
3915 ):
3916 # player has some other source active and native resume support
3917 await player.play()
3918 return
3919 if active_source and not active_source.passive:
3920 await self.select_source(player_id, active_source.id)
3921 return
3922 if media:
3923 # try to re-play the current media item
3924 await player.play_media(media)
3925 return
3926 # fallback: just try to resume queue playback
3927 await self.mass.player_queues.resume(player.player_id)
3928
3929 async def _handle_cmd_power(
3930 self, player_id: str, powered: bool, skip_auto_play: bool = False
3931 ) -> None:
3932 """
3933 Handle player power on/off command.
3934
3935 Skips permission checks and locking (internal use only).
3936
3937 :param player_id: The player ID to power on/off.
3938 :param powered: True to power on, False to power off.
3939 :param skip_auto_play: If True, skip auto-play on power on.
3940 """
3941 player = self.get_player(player_id, True)
3942 assert player is not None # for type checking
3943 player_state = player.state
3944
3945 if player_state.powered == powered:
3946 self.logger.debug(
3947 "Ignoring power %s command for player %s: already in state %s",
3948 "ON" if powered else "OFF",
3949 player_state.name,
3950 "ON" if player_state.powered else "OFF",
3951 )
3952 return # nothing to do
3953
3954 # ungroup player at power off
3955 player_was_sync_child = bool(player.state.synced_to or player.state.active_group)
3956 if (
3957 (player_was_sync_child or player.group_members)
3958 and player.type in UNGROUP_ON_POWER_OFF_TYPES
3959 and not powered
3960 ):
3961 # ungroup player if it is synced (or is a sync leader itself)
3962 await self.cmd_ungroup(player_id)
3963
3964 # always stop player at power off
3965 if (
3966 not powered
3967 and not player_was_sync_child
3968 and player_state.playback_state in (PlaybackState.PLAYING, PlaybackState.PAUSED)
3969 ):
3970 # wait for the stop command to process and prevent race conditions
3971 async with self.wait_for_player_update(player_id, timeout=5):
3972 await self._stop_player_or_its_queue(player)
3973
3974 # power off all synced childs when player is a sync leader
3975 elif (
3976 not powered
3977 and player_state.type in UNGROUP_ON_POWER_OFF_TYPES
3978 and player_state.group_members
3979 ):
3980 async with TaskManager(self.mass) as tg:
3981 for member in self.iter_group_members(player, True):
3982 if member.power_control == PLAYER_CONTROL_NONE:
3983 continue
3984 tg.create_task(self._handle_cmd_power(member.player_id, False))
3985
3986 # handle actual power command
3987 if player_state.power_control == PLAYER_CONTROL_NONE:
3988 self.logger.debug(
3989 "Player %s does not support power control, ignoring power command",
3990 player_state.name,
3991 )
3992 return
3993 if player_state.power_control == PLAYER_CONTROL_NATIVE:
3994 # player supports power command natively: forward to player provider
3995 await player.power(powered)
3996 if powered:
3997 await wait_for_power_on(self.logger, player)
3998 elif player_state.power_control == PLAYER_CONTROL_FAKE:
3999 # user wants to use fake power control - so we (optimistically) update the state
4000 # and store the state in the cache
4001 player.extra_data[ATTR_FAKE_POWER] = powered
4002 # Group players need to actively form/dissolve their session when the
4003 # user toggles fake power â otherwise the toggle would only update the
4004 # cosmetic state without ever capturing or releasing the members.
4005 if player_state.type == PlayerType.GROUP:
4006 await player.power(powered)
4007 player.update_state() # trigger update of the player state
4008 if player_state.type != PlayerType.GROUP:
4009 # see register(): group fake-power is intentionally not persisted
4010 # because there is no session to restore at boot.
4011 await self.mass.cache.set(
4012 key=player_id,
4013 data=powered,
4014 provider=self.domain,
4015 category=CACHE_CATEGORY_PLAYER_POWER,
4016 )
4017 # handle external player control
4018 elif player_control := self._controls.get(player.state.power_control):
4019 control_name = player_control.name
4020 self.logger.debug("Redirecting power command to PlayerControl %s", control_name)
4021 if not player_control.supports_power:
4022 raise UnsupportedFeaturedException(
4023 f"Player control {control_name} is not available"
4024 )
4025 if powered:
4026 assert player_control.power_on is not None # for type checking
4027 await player_control.power_on()
4028 await wait_for_power_on(self.logger, player, player_control)
4029 else:
4030 assert player_control.power_off is not None # for type checking
4031 await player_control.power_off()
4032 # always trigger a state update to update the UI
4033 player.refresh_state()
4034
4035 # handle 'auto play on power on' feature
4036 if (
4037 not skip_auto_play
4038 and not player_state.active_group
4039 and not player_state.synced_to
4040 and powered
4041 and player.config.get_value(CONF_AUTO_PLAY)
4042 and player_state.active_source in (None, player_id)
4043 and not player.extra_data.get(ATTR_ANNOUNCEMENT_IN_PROGRESS)
4044 ):
4045 await self.mass.player_queues.resume(player_id)
4046
4047 def _resolve_group_volume_player(self, player: Player) -> Player | None:
4048 """
4049 Return the player whose group a group volume command applies to.
4050
4051 Returns None if the given player is not grouped at all. Commands addressed to a
4052 synced member and to its sync leader resolve to the same player, so they read
4053 and guard one and the same group.
4054
4055 :param player: The player the command was addressed to.
4056 """
4057 # the group volume lock this resolves to may not share the VOLUME purpose:
4058 # set_group_volume sets the volume of the members concurrently and a sync leader
4059 # is a member of its own group, so a group command would wait on its own lock.
4060 if player.state.type == PlayerType.GROUP or player.state.group_members:
4061 # dedicated group player or sync leader
4062 return player
4063 if player.state.synced_to:
4064 # a synced player follows its sync leader
4065 return self.get_player(player.state.synced_to)
4066 return None
4067
4068 async def _set_member_volume(self, player_id: str, volume_level: int) -> None:
4069 """
4070 Set the volume of a single member as part of a group volume change.
4071
4072 :param player_id: player_id of the member to handle the command.
4073 :param volume_level: logical volume level (0..100) to set on the member.
4074 """
4075 # record before waiting for the lock, for the same reason as cmd_volume_set
4076 if member := self.get_player(player_id):
4077 self._record_volume_target(member, volume_level)
4078 # take the volume lock of the member itself, so a group volume change and an
4079 # individual volume command for that member can not overtake one another
4080 async with self.get_player_lock(player_id, PlayerLockPurpose.VOLUME):
4081 await self._handle_cmd_volume_set(player_id, volume_level, record_target=False)
4082
4083 async def _handle_cmd_volume_set(
4084 self, player_id: str, volume_level: int, *, record_target: bool = True
4085 ) -> None:
4086 """
4087 Handle Player volume set command.
4088
4089 Skips permission checks and locking (internal use only).
4090
4091 :param player_id: player_id of the player to handle the command.
4092 :param volume_level: logical volume level (0..100) to set on the player.
4093 :param record_target: Set to False when the caller already recorded the level as
4094 the base for the next volume nudge, before it waited for the volume lock.
4095 """
4096 player = self.get_player(player_id, True)
4097 assert player is not None # for type checker
4098
4099 # Clamp logical volume to 0-100
4100 volume_level = max(0, min(100, volume_level))
4101
4102 if player.type == PlayerType.GROUP:
4103 # redirect to special group volume control
4104 await self.cmd_group_volume(player_id, volume_level)
4105 return
4106
4107 # A muted player stays muted: only an explicit unmute lifts it, and the level
4108 # set here is the one it plays at once that happens. Fake mute is the exception,
4109 # because it is simulated with the volume itself.
4110 if self._stays_silent_on_volume_change(player):
4111 # a locked player stays silent, the volume it holds is the one
4112 # that gets restored once it is unmuted again
4113 volume_level = 0
4114 # the lock may have been earned after the caller recorded the level it asked
4115 # for, which is then not the level this player ends up at
4116 record_target = True
4117 else:
4118 player.extra_data.pop(ATTR_FAKE_MUTE, None)
4119
4120 if record_target:
4121 self._record_volume_target(player, volume_level)
4122
4123 # Scale logical volume (0-100) to device volume (min_volume-max_volume)
4124 device_volume = self.scale_volume_to_device(player_id, volume_level)
4125
4126 await self._notify_source_volume_change(player, volume_level)
4127
4128 # Handle native volume control support
4129 if player.volume_control == PLAYER_CONTROL_NATIVE:
4130 # player supports volume command natively: forward to player
4131 await player.volume_set(device_volume)
4132 return
4133 # Handle fake volume control support
4134 if player.volume_control == PLAYER_CONTROL_FAKE:
4135 # user wants to use fake volume control - so we (optimistically) update the state
4136 # and store the state in the cache. Fake volume uses the logical volume (no scaling).
4137 player.extra_data[ATTR_FAKE_VOLUME] = volume_level
4138 player.update_state()
4139 return
4140 # player has no volume support at all
4141 if player.volume_control == PLAYER_CONTROL_NONE:
4142 raise UnsupportedFeaturedException(
4143 f"Player {player.state.name} does not support volume control"
4144 )
4145 # handle external player control
4146 if player_control := self._controls.get(player.state.volume_control):
4147 control_name = player_control.name
4148 self.logger.debug("Redirecting volume command to PlayerControl %s", control_name)
4149 if not player_control.supports_volume:
4150 raise UnsupportedFeaturedException(
4151 f"Player control {control_name} is not available"
4152 )
4153 assert player_control.volume_set is not None
4154 # forward the already-scaled device volume; the external control sets the
4155 # raw device volume and does not apply min/max scaling of its own
4156 await player_control.volume_set(device_volume)
4157 return
4158 if protocol_player := self.get_player(player.state.volume_control):
4159 # forward the already-scaled device volume: the limits configured on this
4160 # (user-facing) player are the only ones that apply to the command
4161 self.logger.debug(
4162 "Redirecting volume command to protocol player %s",
4163 protocol_player.provider.manifest.name,
4164 )
4165 await protocol_player.volume_set(device_volume)
4166 return
4167
4168 @staticmethod
4169 def _is_in_group(state: PlayerState) -> bool:
4170 """Check if the player with the given state is currently grouped with other players."""
4171 # a sync leader has neither synced_to nor active_group set, but it does lead its
4172 # own group_members, which stays empty for a player that is not grouped at all
4173 return bool(state.synced_to or state.active_group or state.group_members)
4174
4175 def _has_active_mute_lock(self, player: Player) -> bool:
4176 """
4177 Check if the given player holds a mute lock that still applies to it.
4178
4179 A lock is only earned inside a group and only holds for as long as the player
4180 is still grouped, so it can not outlive the group it was earned in.
4181
4182 :param player: The player to check, which may be a protocol player.
4183 """
4184 if player.extra_data.get(ATTR_MUTE_LOCK) and self._is_in_group(player.state):
4185 return True
4186 # cmd_volume_mute stores the lock on the parent player, while the volume command
4187 # may arrive with the protocol player ID (e.g. during group volume changes)
4188 if player.protocol_parent_id and (parent := self.get_player(player.protocol_parent_id)):
4189 return bool(parent.extra_data.get(ATTR_MUTE_LOCK)) and self._is_in_group(parent.state)
4190 return False
4191
4192 def _stays_silent_on_volume_change(self, player: Player) -> bool:
4193 """Check if a volume command for the given player lands at 0 to keep it silent."""
4194 return (
4195 self._has_active_mute_lock(player)
4196 and player.mute_control == PLAYER_CONTROL_FAKE
4197 and bool(player.extra_data.get(ATTR_FAKE_MUTE))
4198 )
4199
4200 async def _mute_group_members(self, group_player: Player, muted: bool) -> None:
4201 """
4202 Mute or unmute all mute capable members of a player group or synced players.
4203
4204 :param group_player: The group player or sync leader.
4205 :param muted: bool if the group should be muted.
4206 """
4207 coros = []
4208 for child_player in self.iter_group_members(
4209 group_player, only_powered=True, exclude_self=False
4210 ):
4211 if child_player.mute_control == PLAYER_CONTROL_NONE:
4212 # members without a mute control are left alone, just like the
4213 # group mute state itself is calculated from the capable members only
4214 continue
4215 coros.append(self.cmd_volume_mute(child_player.player_id, muted))
4216 await asyncio.gather(*coros)
4217
4218 async def _handle_cmd_volume_mute(self, player: Player, mute_control: str, muted: bool) -> None:
4219 """
4220 Send the mute command to the given player's mute control.
4221
4222 Skips permission checks, locking and mute lock bookkeeping (internal use only).
4223
4224 :param player: the player to handle the command.
4225 :param mute_control: the already resolved mute control of the player.
4226 :param muted: bool if player should be muted.
4227 """
4228 if mute_control == PLAYER_CONTROL_NATIVE:
4229 # player supports mute command natively: forward to player
4230 await player.volume_mute(muted)
4231 return
4232 if mute_control == PLAYER_CONTROL_FAKE:
4233 # user wants to use fake mute control - so we use volume instead
4234 self.logger.debug(
4235 "Using volume for muting for player %s",
4236 player.state.name,
4237 )
4238 if muted:
4239 already_muted = bool(player.extra_data.get(ATTR_FAKE_MUTE))
4240 if not already_muted:
4241 # on a repeated mute command the volume is already 0
4242 player.extra_data[ATTR_PREVIOUS_VOLUME] = player.state.volume_level
4243 await self._handle_cmd_volume_set(player.player_id, 0)
4244 # set the flag after the volume command, as that clears it
4245 player.extra_data[ATTR_FAKE_MUTE] = True
4246 player.update_state()
4247 else:
4248 was_muted = bool(player.extra_data.get(ATTR_FAKE_MUTE))
4249 player.extra_data[ATTR_FAKE_MUTE] = False
4250 player.update_state()
4251 if not was_muted:
4252 # the volume is the one the user is listening at, restoring
4253 # anything here would turn a no-op unmute into a volume change
4254 return
4255 stored_volume: int | None = player.extra_data.pop(ATTR_PREVIOUS_VOLUME, None)
4256 # the volume was still unknown at mute time, so pick a low volume
4257 # rather than blasting the speaker at some assumed level
4258 await self._handle_cmd_volume_set(
4259 player.player_id, 1 if stored_volume is None else stored_volume
4260 )
4261 return
4262
4263 # handle external player control
4264 if player_control := self._controls.get(mute_control):
4265 control_name = player_control.name
4266 self.logger.debug("Redirecting mute command to PlayerControl %s", control_name)
4267 if not player_control.supports_mute:
4268 raise UnsupportedFeaturedException(
4269 f"Player control {control_name} is not available"
4270 )
4271 assert player_control.mute_set is not None
4272 await player_control.mute_set(muted)
4273 return
4274
4275 # handle to protocol player as volume_mute control
4276 if protocol_player := self.get_player(mute_control):
4277 self.logger.debug(
4278 "Redirecting mute command to protocol player %s",
4279 protocol_player.provider.manifest.name,
4280 )
4281 await protocol_player.volume_mute(muted)
4282 return
4283
4284 # the configured control disappeared after the mute control was resolved
4285 raise UnsupportedFeaturedException(f"Player {player.state.name} does not support muting")
4286
4287 async def _handle_play_media(self, player_id: str, media: PlayerMedia) -> None:
4288 """
4289 Handle play media command without group redirect.
4290
4291 Skips permission checks, locking, and all redirect logic (internal use only).
4292
4293 :param player_id: player_id of the player to handle the command.
4294 :param media: The Media that needs to be played on the player.
4295 """
4296 player = self.get_player(player_id, raise_unavailable=True)
4297 assert player is not None
4298 # media that is not the live source itself takes the player away from it. An
4299 # announcement is the exception: it interrupts the player and hands it straight
4300 # back, so releasing the source would tear down a session that is about to
4301 # resume â and one that cannot be re-selected once its plugin has let go.
4302 if media.media_type not in (MediaType.AUDIO_SOURCE, MediaType.ANNOUNCEMENT):
4303 await self._release_audio_source(player_id)
4304 # set active source if media has a source_id (e.g. plugin source or mass queue source)
4305 if media.source_id:
4306 player.set_active_mass_source(media.source_id)
4307
4308 # Determine output protocol to use:
4309 # While a session is active (playing/paused), keep using the already active
4310 # protocol so mid-session commands stay on the same output.
4311 # On a fresh start always (re)select: a leftover active protocol from a
4312 # previous session must not overrule user preference, a grouped protocol
4313 # or native playback (and it may point at a player that is gone by now).
4314 target_player: Player | None = None
4315 output_protocol: OutputProtocol | None = None
4316 if (
4317 player.state.playback_state in (PlaybackState.PLAYING, PlaybackState.PAUSED)
4318 and player.active_output_protocol
4319 and player.active_output_protocol != "native"
4320 and (protocol_player := self.get_player(player.active_output_protocol))
4321 ):
4322 # Use the already-set protocol directly
4323 output_protocol = player.get_linked_protocol(player.active_output_protocol)
4324 if output_protocol is not None:
4325 target_player = protocol_player
4326 if target_player is None:
4327 target_player, output_protocol = self._select_best_output_protocol(player)
4328
4329 if target_player.player_id != player.player_id:
4330 # Playing via linked protocol - update active output protocol
4331 # output_protocol is guaranteed to be non-None when target_player != player
4332 assert output_protocol is not None
4333 self.logger.debug(
4334 "Starting playback on %s via protocol %s (target=%s), group_members=%s",
4335 player.state.name,
4336 output_protocol.name,
4337 target_player.display_name,
4338 target_player.state.group_members,
4339 )
4340 player.set_active_output_protocol(output_protocol.output_protocol_id)
4341 elif player.type != PlayerType.GROUP:
4342 # Native playback - group players don't have output protocols of their own
4343 # (they delegate to a sync leader / member which manages its own protocol)
4344 self.logger.debug(
4345 "Starting playback on %s via native, group_members=%s",
4346 player.state.name,
4347 player.state.group_members,
4348 )
4349 player.set_active_output_protocol("native")
4350
4351 # power on the player if needed (skip auto-play since we're about to start playback)
4352 if not player.state.powered and player.state.power_control != PLAYER_CONTROL_NONE:
4353 await self._handle_cmd_power(player.player_id, True, skip_auto_play=True)
4354 await target_player.play_media(media)
4355 if target_player.player_id != player.player_id:
4356 # notify the native player that protocol playback started
4357 assert output_protocol is not None
4358 await player.on_protocol_playback(output_protocol=output_protocol)
4359
4360 async def _handle_enqueue_next_media(self, player_id: str, media: PlayerMedia) -> None:
4361 """
4362 Handle enqueue next media command without group redirect.
4363
4364 Skips permission checks, locking, and all redirect logic (internal use only).
4365
4366 :param player_id: player_id of the player to handle the command.
4367 :param media: The Media that needs to be enqueued on the player.
4368 """
4369 player = self.get_player(player_id, raise_unavailable=True)
4370 assert player is not None
4371 if target_player := self._get_control_target(
4372 player,
4373 required_feature=PlayerFeature.ENQUEUE,
4374 require_active=True,
4375 ):
4376 self.logger.debug(
4377 "Redirecting enqueue command to protocol player %s",
4378 target_player.provider.manifest.name,
4379 )
4380 await target_player.enqueue_next_media(media)
4381 return
4382
4383 if PlayerFeature.ENQUEUE not in player.state.supported_features:
4384 raise UnsupportedFeaturedException(
4385 f"Player {player.state.name} does not support enqueueing"
4386 )
4387 await player.enqueue_next_media(media)
4388
4389 async def _notify_source_volume_change(self, player: Player, volume_level: int) -> None:
4390 """
4391 Tell the source playing on a player that its volume changed.
4392
4393 Only the player the source is actually playing on notifies, never one that
4394 merely hears it as a group member â otherwise a group volume change would
4395 fire the callback once per child, each with a different value.
4396
4397 :param player: The player whose volume changed.
4398 :param volume_level: The new volume, 0-100.
4399 """
4400 if (session := self.get_audio_source_session(player.player_id)) is None:
4401 return
4402 provider = self.mass.get_provider(session.provider_instance_id)
4403 if not isinstance(provider, PluginProvider):
4404 return
4405 await provider.on_volume_change(session.source_id, volume_level)
4406
4407 def _resolve_command_target(self, player: Player, source_id: str | None) -> str:
4408 """
4409 Return the source (id) a command issued to a player applies to.
4410
4411 :param player: The player the command was issued to.
4412 :param source_id: The source the caller aimed the command at, if it named one.
4413 :return: The id of the player's active source, which is the id of Music
4414 Assistant's own queue when nothing else is playing on it.
4415 :raises PlayerCommandFailed: When the caller named a source that is no longer
4416 the one playing.
4417 """
4418 active_source_id = player.state.active_source or player.player_id
4419 if source_id is not None and source_id != active_source_id:
4420 msg = f"The source this was meant for is no longer playing on {player.state.name}."
4421 raise PlayerCommandFailed(msg)
4422 return active_source_id
4423
4424 async def _forward_to_external_source(
4425 self,
4426 player: Player,
4427 action: SourceControl,
4428 value: SourceControlValue = None,
4429 ) -> bool:
4430 """
4431 Hand a control action to the external source playing on a player.
4432
4433 Covers the external sources Music Assistant provides itself, which own a
4434 session it can talk to. A source belonging to the player (its line-in, TV
4435 input, or its own Spotify Connect) has no such session, so this reports that
4436 it did not take the action and the caller goes on to the player itself.
4437
4438 The per-action transport flags gate what the source advertises it can do, so
4439 a client is refused rather than left waiting. Ordering is not gated here: the
4440 session decides what reordering means for its own content. Most sources do not
4441 implement it at all, though, so a client should ask the source whether it can
4442 before offering the control - handing it one that quietly does nothing is
4443 worse than not offering it.
4444
4445 :param player: The player the action was issued to.
4446 :param action: The control action to hand over.
4447 :param value: The action's argument, where it takes one.
4448 :return: True when an external source took the action.
4449 """
4450 if (active := self._get_active_audio_source(player)) is None:
4451 return False
4452 audio_source, provider = active
4453 supported = {
4454 SourceControl.PLAY: audio_source.can_play_pause,
4455 SourceControl.PAUSE: audio_source.can_play_pause,
4456 SourceControl.SEEK: audio_source.can_seek,
4457 SourceControl.NEXT: audio_source.can_next_previous,
4458 SourceControl.PREVIOUS: audio_source.can_next_previous,
4459 }.get(action, True)
4460 if not supported:
4461 msg = (
4462 f"The active source ({audio_source.name}) on player "
4463 f"{player.display_name} does not support this action"
4464 )
4465 raise PlayerCommandFailed(msg)
4466 try:
4467 await provider.on_source_control(audio_source.item_id, action, value)
4468 except NotImplementedError as err:
4469 # a source with no control surface at all (vban_receiver) reaches the base
4470 # implementation; a caller deserves a refusal rather than a server error
4471 msg = (
4472 f"The active source ({audio_source.name}) on player "
4473 f"{player.display_name} can not be controlled"
4474 )
4475 raise PlayerCommandFailed(msg) from err
4476 return True
4477
4478 async def _release_audio_source(self, player_id: str) -> None:
4479 """
4480 Let go of the live source a player was playing, if it had one.
4481
4482 Tells the owning plugin so an upstream session still pointing at Music
4483 Assistant is released. A plugin that raises must not stop the player from
4484 moving on, so failures are logged rather than propagated.
4485
4486 :param player_id: The player that is done with its source.
4487 """
4488 if (session := self._end_audio_source_session(player_id)) is None:
4489 return
4490 self.trigger_player_update(player_id)
4491 provider = self.mass.get_provider(session.provider_instance_id)
4492 if not isinstance(provider, PluginProvider):
4493 return
4494 try:
4495 await provider.on_source_released(session.source_id, player_id)
4496 except Exception:
4497 self.logger.warning(
4498 "on_source_released raised for provider %s source %s player %s",
4499 provider.instance_id,
4500 session.source_id,
4501 player_id,
4502 exc_info=True,
4503 )
4504
4505 async def _release_unclaimed_audio_source(
4506 self, player_id: str, session: AudioSourceSession, playback_session_id: str
4507 ) -> None:
4508 """
4509 Release a source whose renderer never requested the stream.
4510
4511 The play command returned without error, so the late-start release in the
4512 streams controller never fires: no stream request means no failed stream
4513 request either. Without this the player would keep publishing a source
4514 that never started, with its own queue held inactive behind it.
4515
4516 :param player_id: The player the source was started on.
4517 :param session: The session that was started for it.
4518 :param playback_session_id: Playback session active when it was started.
4519 """
4520 current = self.get_audio_source_session(player_id)
4521 if (
4522 current is not session
4523 or current.playback_session_id != playback_session_id
4524 or current.stream_session_id is not None
4525 ):
4526 return
4527 self.logger.info(
4528 "AudioSource %s was never streamed by player %s, releasing it",
4529 session.source_id,
4530 player_id,
4531 )
4532 await self.deselect_source(
4533 player_id,
4534 provider_instance_id=session.provider_instance_id,
4535 source_id=session.source_id,
4536 playback_session_id=playback_session_id,
4537 )
4538
4539 async def _resolve_audio_source_uri(
4540 self, source: str
4541 ) -> tuple[AudioSource, PluginProvider] | None:
4542 """
4543 Resolve a source string to a live AudioSource, if that is what it names.
4544
4545 :param source: The source string a select names.
4546 :return: The source and its owning plugin, or None when the string names
4547 something else (a queue, a player-native source).
4548 """
4549 if "://" not in source:
4550 return None
4551 try:
4552 item = await self.mass.music.get_item_by_uri(source)
4553 except MusicAssistantError as err:
4554 # not resolvable as media, so it is something else (a queue id, a
4555 # player-native source) â logged because a provider being unavailable
4556 # or unauthenticated also lands here
4557 self.logger.debug("Could not resolve %s as an audio source: %s", source, err)
4558 return None
4559 if not isinstance(item, AudioSource):
4560 return None
4561 provider = self.mass.get_provider(item.provider)
4562 if not isinstance(provider, PluginProvider):
4563 return None
4564 if ProviderFeature.AUDIO_SOURCE not in provider.supported_features:
4565 return None
4566 return item, provider
4567
4568 async def _start_audio_source(
4569 self, player: Player, audio_source: AudioSource, provider: PluginProvider
4570 ) -> None:
4571 """
4572 Start a live external source on a player.
4573
4574 The player's queue is left exactly as it is: it simply stops being the
4575 active source, so it is still there to resume when the source ends.
4576
4577 :param player: The player to play the source on.
4578 :param audio_source: The source that was selected.
4579 :param provider: The plugin exposing that source.
4580 """
4581 # a player outputs one source at a time, so another one already on it has to be
4582 # handed back first: replacing the session silently would leave its plugin
4583 # holding an upstream session that still points at this player
4584 if (current := self.get_audio_source_session(player.player_id)) is not None and (
4585 current.source_id != audio_source.item_id
4586 or current.provider_instance_id != provider.instance_id
4587 ):
4588 await self._release_audio_source(player.player_id)
4589 session = self._start_audio_source_session(
4590 player.player_id, audio_source, provider.instance_id
4591 )
4592 try:
4593 await self._handle_play_media(
4594 player.player_id,
4595 PlayerMedia(
4596 uri=audio_source.uri or audio_source.item_id,
4597 media_type=MediaType.AUDIO_SOURCE,
4598 title=audio_source.name,
4599 # the session's owner, which its stream url is keyed on
4600 source_id=player.player_id,
4601 queue_session_id=session.playback_session_id,
4602 ),
4603 )
4604 except Exception:
4605 # the source never started, so the player must not go on publishing it:
4606 # a session left behind holds the queue inactive with nothing playing it
4607 if self.get_audio_source_session(player.player_id) is session:
4608 await self._release_audio_source(player.player_id)
4609 raise
4610 # the play command returning does not mean the renderer ever fetched the
4611 # stream url: until a stream request claims the session nothing will evict
4612 # the player the source may be moving from, and nothing else would ever
4613 # clear a session that is never streamed
4614 self.mass.call_later(
4615 AUDIO_SOURCE_CLAIM_TIMEOUT,
4616 self._release_unclaimed_audio_source,
4617 player.player_id,
4618 session,
4619 session.playback_session_id,
4620 task_id=f"release_unclaimed_audio_source_{player.player_id}",
4621 )
4622
4623 async def _handle_select_source(self, player_id: str, source: str | None) -> None:
4624 """
4625 Handle select source command without group redirect.
4626
4627 Skips permission checks, locking, and all redirect logic (internal use only).
4628
4629 :param player_id: player_id of the player to handle the command.
4630 :param source: The ID of the source that needs to be activated/selected.
4631 """
4632 if source is None:
4633 source = player_id # default to MA queue source
4634 player = self.get_player(player_id, True)
4635 assert player is not None
4636 # check if player is already playing and source is different
4637 # in that case we need to stop the player first
4638 prev_source = player.state.active_source
4639 if prev_source and source != prev_source:
4640 with suppress(PlayerCommandFailed, RuntimeError):
4641 # just try to stop (regardless of state) and let it settle, so the
4642 # new source does not race the teardown. A player that already
4643 # reports idle has nothing to tear down and does not wait at all.
4644 async with self.wait_for_player_update(
4645 player_id,
4646 attribute_name="playback_state",
4647 attribute_value=PlaybackState.IDLE,
4648 timeout=5,
4649 ):
4650 await self._handle_cmd_stop(player_id)
4651 # an audio source uri selects the live source itself, which plays on the
4652 # player while its queue keeps its own items and goes inactive
4653 if (resolved := await self._resolve_audio_source_uri(source)) is not None:
4654 await self._start_audio_source(player, *resolved)
4655 return
4656 # anything else takes the player away from a live source it was playing
4657 await self._release_audio_source(player_id)
4658 # check if source is a mass queue
4659 # this can be used to restore the queue after a source switch
4660 if self.mass.player_queues.get(source):
4661 player.set_active_mass_source(source)
4662 return
4663 # Legacy compatibility: the old plugin-source API used the
4664 # plugin's instance_id directly as the source string. The refactor
4665 # moved plugin sources to first-class AudioSource MediaItems played
4666 # via player_queues.play_media. Translate a legacy plugin-instance-id
4667 # source into the new flow so old frontends, third-party scripts,
4668 # and HA automations keep working â but only when the provider
4669 # exposes EXACTLY ONE AudioSource (it was always a 1:1 mapping under
4670 # the old API; multi-source providers have to use the explicit URI).
4671 if (legacy_prov := self.mass.get_provider(source)) and isinstance(
4672 legacy_prov, PluginProvider
4673 ):
4674 if ProviderFeature.AUDIO_SOURCE not in legacy_prov.supported_features:
4675 raise PlayerCommandFailed(f"Provider {source} does not expose AudioSources")
4676 sources = await legacy_prov.get_audio_sources()
4677 if len(sources) == 1:
4678 self.logger.debug(
4679 "Translating legacy select_source(%s) to play_media(%s)",
4680 source,
4681 sources[0].uri,
4682 )
4683 await self.mass.player_queues.play_media(player_id, str(sources[0].uri))
4684 return
4685 raise UnsupportedFeaturedException(
4686 f"Provider {source} exposes {len(sources)} AudioSources; the legacy "
4687 "select_source(plugin_instance_id) API only supported 1:1 mappings. "
4688 "Use player_queues.play_media with an explicit AudioSource URI."
4689 )
4690 # basic check if player supports source selection
4691 if PlayerFeature.SELECT_SOURCE not in player.state.supported_features:
4692 raise UnsupportedFeaturedException(
4693 f"Player {player.state.name} does not support source selection"
4694 )
4695 # basic check if source is valid for player
4696 if not any(x for x in player.state.source_list if x.id == source):
4697 raise PlayerCommandFailed(
4698 f"{source} is an invalid source for player {player.state.name}"
4699 )
4700 # forward to player
4701 await player.select_source(source)
4702
4703 async def _handle_cmd_stop(self, player_id: str) -> None:
4704 """
4705 Handle stop command without any redirects.
4706
4707 Skips permission checks, locking, and all redirect logic (internal use only).
4708
4709 :param player_id: player_id of the player to handle the command.
4710 """
4711 player = self.get_player(player_id, raise_unavailable=True)
4712 assert player is not None
4713 protocol_player: Player | None = None
4714 if player.active_output_protocol and player.active_output_protocol != "native":
4715 protocol_player = self.get_player(player.active_output_protocol)
4716 if player.state.playback_state == PlaybackState.IDLE:
4717 # The player already reports idle but an output protocol is still marked
4718 # active: the protocol player may never have received a stop at all
4719 # (e.g. the source stream ended on its own before this stop command
4720 # arrived). Forward an (idempotent) stop and schedule the protocol clear
4721 # so no stale session lingers on the device and the next playback
4722 # (re)selects the output protocol.
4723 if protocol_player is not None:
4724 await protocol_player.stop()
4725 if len(protocol_player.group_members) <= 1:
4726 self.schedule_active_output_protocol_clear(player)
4727 return
4728 player.mark_stop_called()
4729 # Delegate to active protocol player if one is active
4730 target_player = player
4731 if protocol_player is not None:
4732 target_player = protocol_player
4733 if PlayerFeature.POWER in target_player.supported_features:
4734 # if protocol player supports/requires power,
4735 # we power it off instead of just stopping (which also stops playback)
4736 # this is rare as most protocols do not support power control (except for cast)
4737 await self._handle_cmd_power(target_player.player_id, False)
4738 return
4739
4740 # handle command on player(protocol) directly
4741 await target_player.stop()
4742 # Only clear active protocol if the protocol player has no remaining group members.
4743 # If there are still protocol group members, keep the protocol active so that
4744 # when playback resumes it continues on the same protocol.
4745 if target_player.player_id == player.player_id or len(target_player.group_members) <= 1:
4746 self.schedule_active_output_protocol_clear(player)
4747
4748 async def _handle_cmd_play(self, player_id: str) -> None:
4749 """
4750 Handle play command without group redirect.
4751
4752 Skips permission checks, locking, and all redirect logic (internal use only).
4753
4754 :param player_id: player_id of the player to handle the command.
4755 """
4756 player = self.get_player(player_id, raise_unavailable=True)
4757 assert player is not None
4758 if player.state.playback_state == PlaybackState.PLAYING:
4759 self.logger.info(
4760 "Ignore PLAY request to player %s: player is already playing", player.state.name
4761 )
4762 return
4763 # If an AudioSource is the active queue item, proxy play to the plugin
4764 if active := self._get_active_audio_source(player):
4765 audio_source, plugin_prov = active
4766 if audio_source.can_play_pause:
4767 await plugin_prov.on_source_control(audio_source.item_id, SourceControl.PLAY)
4768 return
4769 # handle unpause (=play if player is paused)
4770 if player.state.playback_state == PlaybackState.PAUSED:
4771 active_source = next(
4772 (x for x in player.state.source_list if x.id == player.state.active_source), None
4773 )
4774 # raise if active source does not support play/pause
4775 if active_source and not active_source.can_play_pause:
4776 msg = (
4777 f"The active source ({active_source.name}) on player "
4778 f"{player.state.name} does not support play/pause"
4779 )
4780 raise PlayerCommandFailed(msg)
4781 # Delegate to active protocol player if one is active
4782 if target_player := self._get_control_target(
4783 player, PlayerFeature.PAUSE, require_active=True
4784 ):
4785 await target_player.play()
4786 return
4787 # No active protocol target: if the player rendering the audio supports pause and
4788 # the active (external) source can be paused, unpause it directly instead of
4789 # restarting the source.
4790 output_player = player.resolve_output_player()
4791 if (
4792 active_source
4793 and active_source.can_play_pause
4794 and PlayerFeature.PAUSE in output_player.supported_features
4795 ):
4796 await output_player.play()
4797 return
4798
4799 # player is not paused: try to resume the player
4800 # Note: We handle resume inline here without calling _handle_cmd_resume
4801 active_source = next(
4802 (x for x in player.state.source_list if x.id == player.state.active_source), None
4803 )
4804 media = player.state.current_media
4805 # power on the player if needed
4806 if not player.state.powered and player.state.power_control != PLAYER_CONTROL_NONE:
4807 await self._handle_cmd_power(player.player_id, True)
4808 if active_source and not active_source.passive:
4809 await self._handle_select_source(player_id, active_source.id)
4810 return
4811 if media:
4812 # try to re-play the current media item
4813 await player.play_media(media)
4814 return
4815 # fallback: just send play command - which will fail if nothing can be played
4816 await player.play()
4817
4818 async def _handle_cmd_pause(self, player_id: str) -> None:
4819 """
4820 Handle pause command without any redirects.
4821
4822 Skips permission checks, locking, and all redirect logic (internal use only).
4823
4824 :param player_id: player_id of the player to handle the command.
4825 """
4826 player = self.get_player(player_id, raise_unavailable=True)
4827 assert player is not None
4828 if player.state.playback_state == PlaybackState.IDLE:
4829 return
4830 # If an AudioSource is the active queue item, proxy pause to the plugin
4831 if active := self._get_active_audio_source(player):
4832 audio_source, plugin_prov = active
4833 if audio_source.can_play_pause:
4834 await plugin_prov.on_source_control(audio_source.item_id, SourceControl.PAUSE)
4835 return
4836 # handle command on player/source directly
4837 active_source = next(
4838 (x for x in player.state.source_list if x.id == player.state.active_source), None
4839 )
4840 if active_source and not active_source.can_play_pause:
4841 # raise if active source does not support play/pause
4842 msg = (
4843 f"The active source ({active_source.name}) on player "
4844 f"{player.state.name} does not support play/pause"
4845 )
4846 raise PlayerCommandFailed(msg)
4847 # Delegate to active protocol player if one is active
4848 if target_player := self._get_control_target(
4849 player, PlayerFeature.PAUSE, require_active=True
4850 ):
4851 await target_player.pause()
4852 return
4853 # No active protocol target: if the player rendering the audio supports pause and the
4854 # active (external) source can be paused, forward the command to it instead of stopping
4855 # it (mirrors the external-source handling in cmd_seek/cmd_next_track).
4856 output_player = player.resolve_output_player()
4857 if (
4858 active_source
4859 and active_source.can_play_pause
4860 and PlayerFeature.PAUSE in output_player.supported_features
4861 ):
4862 await output_player.pause()
4863 return
4864 # player/protocol does not support pause: fall back to stop
4865 self.logger.debug(
4866 "Player/protocol %s does not support pause, using STOP instead",
4867 player.state.name,
4868 )
4869 await self._handle_cmd_stop(player.player_id)
4870