music-assistant-server
73.9 KB•PY
config.py
73.9 KB • 1,804 lines • python
1"""Logic to handle storage of persistent (configuration) settings."""
2
3from __future__ import annotations
4
5import asyncio
6import base64
7import contextlib
8import logging
9import os
10from copy import deepcopy
11from typing import TYPE_CHECKING, Any, Literal, TypeVar, cast, overload
12from uuid import uuid4
13
14import aiofiles
15import shortuuid
16from aiofiles.os import wrap
17from cryptography.fernet import Fernet, InvalidToken
18from music_assistant_models import config_entries
19from music_assistant_models.config_entries import (
20 MULTI_VALUE_SPLITTER,
21 ConfigEntry,
22 ConfigValueOption,
23 ConfigValueType,
24 CoreConfig,
25 PlayerConfig,
26 ProviderConfig,
27)
28from music_assistant_models.constants import (
29 PLAYER_CONTROL_FAKE,
30 PLAYER_CONTROL_NATIVE,
31 PLAYER_CONTROL_NONE,
32)
33from music_assistant_models.dsp import DSPConfig, DSPConfigPreset
34from music_assistant_models.enums import (
35 ConfigEntryType,
36 EventType,
37 PlayerFeature,
38 PlayerType,
39 ProviderFeature,
40 ProviderType,
41)
42from music_assistant_models.errors import (
43 ActionUnavailable,
44 InvalidDataError,
45 UnsupportedFeaturedException,
46)
47
48from music_assistant.constants import (
49 CONF_CORE,
50 CONF_ENTRY_ANNOUNCE_VOLUME,
51 CONF_ENTRY_ANNOUNCE_VOLUME_MAX,
52 CONF_ENTRY_ANNOUNCE_VOLUME_MIN,
53 CONF_ENTRY_ANNOUNCE_VOLUME_STRATEGY,
54 CONF_ENTRY_AUTO_PLAY,
55 CONF_ENTRY_CROSSFADE_DURATION,
56 CONF_ENTRY_ENABLE_ICY_METADATA,
57 CONF_ENTRY_FLOW_MODE,
58 CONF_ENTRY_HTTP_PROFILE,
59 CONF_ENTRY_LIBRARY_SYNC_ALBUM_TRACKS,
60 CONF_ENTRY_LIBRARY_SYNC_ALBUMS,
61 CONF_ENTRY_LIBRARY_SYNC_ARTISTS,
62 CONF_ENTRY_LIBRARY_SYNC_AUDIOBOOKS,
63 CONF_ENTRY_LIBRARY_SYNC_BACK,
64 CONF_ENTRY_LIBRARY_SYNC_PLAYLIST_TRACKS,
65 CONF_ENTRY_LIBRARY_SYNC_PLAYLISTS,
66 CONF_ENTRY_LIBRARY_SYNC_PODCASTS,
67 CONF_ENTRY_LIBRARY_SYNC_RADIOS,
68 CONF_ENTRY_LIBRARY_SYNC_TRACKS,
69 CONF_ENTRY_OUTPUT_CHANNELS,
70 CONF_ENTRY_OUTPUT_CODEC,
71 CONF_ENTRY_OUTPUT_LIMITER,
72 CONF_ENTRY_PLAYER_ICON,
73 CONF_ENTRY_PLAYER_ICON_GROUP,
74 CONF_ENTRY_PROVIDER_SYNC_INTERVAL_ALBUMS,
75 CONF_ENTRY_PROVIDER_SYNC_INTERVAL_ARTISTS,
76 CONF_ENTRY_PROVIDER_SYNC_INTERVAL_AUDIOBOOKS,
77 CONF_ENTRY_PROVIDER_SYNC_INTERVAL_PLAYLISTS,
78 CONF_ENTRY_PROVIDER_SYNC_INTERVAL_PODCASTS,
79 CONF_ENTRY_PROVIDER_SYNC_INTERVAL_RADIOS,
80 CONF_ENTRY_PROVIDER_SYNC_INTERVAL_TRACKS,
81 CONF_ENTRY_SAMPLE_RATES,
82 CONF_ENTRY_SMART_FADES_MODE,
83 CONF_ENTRY_TTS_PRE_ANNOUNCE,
84 CONF_ENTRY_VOLUME_NORMALIZATION,
85 CONF_ENTRY_VOLUME_NORMALIZATION_TARGET,
86 CONF_EXPOSE_PLAYER_TO_HA,
87 CONF_HIDE_IN_UI,
88 CONF_MUTE_CONTROL,
89 CONF_ONBOARD_DONE,
90 CONF_PLAYER_DSP,
91 CONF_PLAYER_DSP_PRESETS,
92 CONF_PLAYERS,
93 CONF_POWER_CONTROL,
94 CONF_PRE_ANNOUNCE_CHIME_URL,
95 CONF_PROVIDERS,
96 CONF_SERVER_ID,
97 CONF_SMART_FADES_MODE,
98 CONF_VOLUME_CONTROL,
99 CONFIGURABLE_CORE_CONTROLLERS,
100 DEFAULT_CORE_CONFIG_ENTRIES,
101 DEFAULT_PROVIDER_CONFIG_ENTRIES,
102 ENCRYPT_SUFFIX,
103 NON_HTTP_PROVIDERS,
104 SYNCGROUP_PREFIX,
105)
106from music_assistant.helpers.api import api_command
107from music_assistant.helpers.json import JSON_DECODE_EXCEPTIONS, async_json_dumps, async_json_loads
108from music_assistant.helpers.util import load_provider_module, validate_announcement_chime_url
109from music_assistant.models import ProviderModuleType
110from music_assistant.models.music_provider import MusicProvider
111
112if TYPE_CHECKING:
113 from music_assistant import MusicAssistant
114 from music_assistant.models.core_controller import CoreController
115 from music_assistant.models.player import Player
116
117LOGGER = logging.getLogger(__name__)
118DEFAULT_SAVE_DELAY = 5
119
120BASE_KEYS = ("enabled", "name", "available", "default_name", "provider", "type")
121
122# TypeVar for config value type inference
123_ConfigValueT = TypeVar("_ConfigValueT", bound=ConfigValueType)
124
125isfile = wrap(os.path.isfile)
126remove = wrap(os.remove)
127rename = wrap(os.rename)
128
129
130class ConfigController:
131 """Controller that handles storage of persistent configuration settings."""
132
133 _fernet: Fernet | None = None
134
135 def __init__(self, mass: MusicAssistant) -> None:
136 """Initialize storage controller."""
137 self.mass = mass
138 self.initialized = False
139 self._data: dict[str, Any] = {}
140 self.filename = os.path.join(self.mass.storage_path, "settings.json")
141 self._timer_handle: asyncio.TimerHandle | None = None
142
143 async def setup(self) -> None:
144 """Async initialize of controller."""
145 await self._load()
146 self.initialized = True
147 # create default server ID if needed (also used for encrypting passwords)
148 self.set_default(CONF_SERVER_ID, uuid4().hex)
149 server_id: str = self.get(CONF_SERVER_ID)
150 assert server_id
151 fernet_key = base64.urlsafe_b64encode(server_id.encode()[:32])
152 self._fernet = Fernet(fernet_key)
153 config_entries.ENCRYPT_CALLBACK = self.encrypt_string
154 config_entries.DECRYPT_CALLBACK = self.decrypt_string
155 if not self.onboard_done:
156 self.mass.register_api_command(
157 "config/onboard_complete",
158 self.set_onboard_complete,
159 authenticated=True,
160 alias=True, # hide from public API docs
161 )
162 LOGGER.debug("Started.")
163
164 @property
165 def onboard_done(self) -> bool:
166 """Return True if onboarding is done."""
167 return bool(self.get(CONF_ONBOARD_DONE, False))
168
169 async def set_onboard_complete(self) -> None:
170 """
171 Mark onboarding as complete.
172
173 This is called by the frontend after the user has completed the onboarding wizard.
174 Only available when onboarding is not yet complete.
175 """
176 if self.onboard_done:
177 msg = "Onboarding already completed"
178 raise InvalidDataError(msg)
179
180 self.set(CONF_ONBOARD_DONE, True)
181 self.save(immediate=True)
182 LOGGER.info("Onboarding completed")
183
184 async def close(self) -> None:
185 """Handle logic on server stop."""
186 if not self._timer_handle:
187 # no point in forcing a save when there are no changes pending
188 return
189 await self._async_save()
190 LOGGER.debug("Stopped.")
191
192 def get(self, key: str, default: Any = None) -> Any:
193 """Get value(s) for a specific key/path in persistent storage."""
194 assert self.initialized, "Not yet (async) initialized"
195 # we support a multi level hierarchy by providing the key as path,
196 # with a slash (/) as splitter. Sort that out here.
197 parent = self._data
198 subkeys = key.split("/")
199 for index, subkey in enumerate(subkeys):
200 if index == (len(subkeys) - 1):
201 value = parent.get(subkey, default)
202 if value is None:
203 # replace None with default
204 return default
205 return value
206 if subkey not in parent:
207 # requesting subkey from a non existing parent
208 return default
209 parent = parent[subkey]
210 return default
211
212 def set(self, key: str, value: Any) -> None:
213 """Set value(s) for a specific key/path in persistent storage."""
214 assert self.initialized, "Not yet (async) initialized"
215 # we support a multi level hierarchy by providing the key as path,
216 # with a slash (/) as splitter.
217 parent = self._data
218 subkeys = key.split("/")
219 for index, subkey in enumerate(subkeys):
220 if index == (len(subkeys) - 1):
221 parent[subkey] = value
222 else:
223 parent.setdefault(subkey, {})
224 parent = parent[subkey]
225 self.save()
226
227 def set_default(self, key: str, default_value: Any) -> None:
228 """Set default value(s) for a specific key/path in persistent storage."""
229 assert self.initialized, "Not yet (async) initialized"
230 cur_value = self.get(key, "__MISSING__")
231 if cur_value == "__MISSING__":
232 self.set(key, default_value)
233
234 def remove(
235 self,
236 key: str,
237 ) -> None:
238 """Remove value(s) for a specific key/path in persistent storage."""
239 assert self.initialized, "Not yet (async) initialized"
240 parent = self._data
241 subkeys = key.split("/")
242 for index, subkey in enumerate(subkeys):
243 if subkey not in parent:
244 return
245 if index == (len(subkeys) - 1):
246 parent.pop(subkey)
247 else:
248 parent.setdefault(subkey, {})
249 parent = parent[subkey]
250
251 self.save()
252
253 @api_command("config/providers")
254 async def get_provider_configs(
255 self,
256 provider_type: ProviderType | None = None,
257 provider_domain: str | None = None,
258 include_values: bool = False,
259 ) -> list[ProviderConfig]:
260 """Return all known provider configurations, optionally filtered by ProviderType."""
261 raw_values = self.get(CONF_PROVIDERS, {})
262 prov_entries = {x.domain for x in self.mass.get_provider_manifests()}
263 return [
264 await self.get_provider_config(prov_conf["instance_id"])
265 if include_values
266 else cast("ProviderConfig", ProviderConfig.parse([], prov_conf))
267 for prov_conf in raw_values.values()
268 if (provider_type is None or prov_conf["type"] == provider_type)
269 and (provider_domain is None or prov_conf["domain"] == provider_domain)
270 # guard for deleted providers
271 and prov_conf["domain"] in prov_entries
272 ]
273
274 @api_command("config/providers/get")
275 async def get_provider_config(self, instance_id: str) -> ProviderConfig:
276 """Return configuration for a single provider."""
277 if raw_conf := self.get(f"{CONF_PROVIDERS}/{instance_id}", {}):
278 config_entries = await self.get_provider_config_entries(
279 raw_conf["domain"],
280 instance_id=instance_id,
281 values=raw_conf.get("values"),
282 )
283 for prov in self.mass.get_provider_manifests():
284 if prov.domain == raw_conf["domain"]:
285 break
286 else:
287 msg = f"Unknown provider domain: {raw_conf['domain']}"
288 raise KeyError(msg)
289 return cast("ProviderConfig", ProviderConfig.parse(config_entries, raw_conf))
290 msg = f"No config found for provider id {instance_id}"
291 raise KeyError(msg)
292
293 @overload
294 async def get_provider_config_value(
295 self,
296 instance_id: str,
297 key: str,
298 *,
299 default: _ConfigValueT,
300 return_type: type[_ConfigValueT] = ...,
301 ) -> _ConfigValueT: ...
302
303 @overload
304 async def get_provider_config_value(
305 self,
306 instance_id: str,
307 key: str,
308 *,
309 default: ConfigValueType = ...,
310 return_type: type[_ConfigValueT] = ...,
311 ) -> _ConfigValueT: ...
312
313 @overload
314 async def get_provider_config_value(
315 self,
316 instance_id: str,
317 key: str,
318 *,
319 default: ConfigValueType = ...,
320 return_type: None = ...,
321 ) -> ConfigValueType: ...
322
323 @api_command("config/providers/get_value")
324 async def get_provider_config_value(
325 self,
326 instance_id: str,
327 key: str,
328 *,
329 default: ConfigValueType = None,
330 return_type: type[_ConfigValueT | ConfigValueType] | None = None,
331 ) -> _ConfigValueT | ConfigValueType:
332 """
333 Return single configentry value for a provider.
334
335 :param instance_id: The provider instance ID.
336 :param key: The config key to retrieve.
337 :param default: Optional default value to return if key is not found.
338 :param return_type: Optional type hint for type inference (e.g., str, int, bool).
339 Note: This parameter is used purely for static type checking and does not
340 perform runtime type validation. Callers are responsible for ensuring the
341 specified type matches the actual config value type.
342 """
343 # prefer stored value so we don't have to retrieve all config entries every time
344 if (raw_value := self.get_raw_provider_config_value(instance_id, key)) is not None:
345 return raw_value
346 conf = await self.get_provider_config(instance_id)
347 if key not in conf.values:
348 if default is not None:
349 return default
350 msg = f"Config key {key} not found for provider {instance_id}"
351 raise KeyError(msg)
352 return (
353 conf.values[key].value
354 if conf.values[key].value is not None
355 else conf.values[key].default_value
356 )
357
358 @api_command("config/providers/get_entries")
359 async def get_provider_config_entries( # noqa: PLR0915
360 self,
361 provider_domain: str,
362 instance_id: str | None = None,
363 action: str | None = None,
364 values: dict[str, ConfigValueType] | None = None,
365 ) -> list[ConfigEntry]:
366 """
367 Return Config entries to setup/configure a provider.
368
369 provider_domain: (mandatory) domain of the provider.
370 instance_id: id of an existing provider instance (None for new instance setup).
371 action: [optional] action key called from config entries UI.
372 values: the (intermediate) raw values for config entries sent with the action.
373 """
374 # lookup provider manifest and module
375 prov_mod: ProviderModuleType | None
376 for manifest in self.mass.get_provider_manifests():
377 if manifest.domain == provider_domain:
378 try:
379 prov_mod = await load_provider_module(provider_domain, manifest.requirements)
380 except Exception as e:
381 msg = f"Failed to load provider module for {provider_domain}: {e}"
382 LOGGER.exception(msg)
383 return []
384 break
385 else:
386 msg = f"Unknown provider domain: {provider_domain}"
387 LOGGER.exception(msg)
388 return []
389
390 # add dynamic optional config entries that depend on features
391 if instance_id and (provider := self.mass.get_provider(instance_id)):
392 supported_features = provider.supported_features
393 else:
394 provider = None
395 supported_features = getattr(prov_mod, "SUPPORTED_FEATURES", set())
396 extra_entries: list[ConfigEntry] = []
397 if manifest.type == ProviderType.MUSIC:
398 # library sync settings
399 if ProviderFeature.LIBRARY_ARTISTS in supported_features:
400 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_ARTISTS)
401 if ProviderFeature.LIBRARY_ALBUMS in supported_features:
402 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_ALBUMS)
403 if (
404 provider
405 and isinstance(provider, MusicProvider)
406 and provider.is_streaming_provider
407 ):
408 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_ALBUM_TRACKS)
409 if ProviderFeature.LIBRARY_TRACKS in supported_features:
410 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_TRACKS)
411 if ProviderFeature.LIBRARY_PLAYLISTS in supported_features:
412 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_PLAYLISTS)
413 if (
414 provider
415 and isinstance(provider, MusicProvider)
416 and provider.is_streaming_provider
417 ):
418 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_PLAYLIST_TRACKS)
419 if ProviderFeature.LIBRARY_AUDIOBOOKS in supported_features:
420 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_AUDIOBOOKS)
421 if ProviderFeature.LIBRARY_PODCASTS in supported_features:
422 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_PODCASTS)
423 if ProviderFeature.LIBRARY_RADIOS in supported_features:
424 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_RADIOS)
425 # sync interval settings
426 if ProviderFeature.LIBRARY_ARTISTS in supported_features:
427 extra_entries.append(CONF_ENTRY_PROVIDER_SYNC_INTERVAL_ARTISTS)
428 if ProviderFeature.LIBRARY_ALBUMS in supported_features:
429 extra_entries.append(CONF_ENTRY_PROVIDER_SYNC_INTERVAL_ALBUMS)
430 if ProviderFeature.LIBRARY_TRACKS in supported_features:
431 extra_entries.append(CONF_ENTRY_PROVIDER_SYNC_INTERVAL_TRACKS)
432 if ProviderFeature.LIBRARY_PLAYLISTS in supported_features:
433 extra_entries.append(CONF_ENTRY_PROVIDER_SYNC_INTERVAL_PLAYLISTS)
434 if ProviderFeature.LIBRARY_AUDIOBOOKS in supported_features:
435 extra_entries.append(CONF_ENTRY_PROVIDER_SYNC_INTERVAL_AUDIOBOOKS)
436 if ProviderFeature.LIBRARY_PODCASTS in supported_features:
437 extra_entries.append(CONF_ENTRY_PROVIDER_SYNC_INTERVAL_PODCASTS)
438 if ProviderFeature.LIBRARY_RADIOS in supported_features:
439 extra_entries.append(CONF_ENTRY_PROVIDER_SYNC_INTERVAL_RADIOS)
440 # sync export settings
441 if supported_features.intersection(
442 {
443 ProviderFeature.LIBRARY_ARTISTS_EDIT,
444 ProviderFeature.LIBRARY_ALBUMS_EDIT,
445 ProviderFeature.LIBRARY_TRACKS_EDIT,
446 ProviderFeature.LIBRARY_PLAYLISTS_EDIT,
447 ProviderFeature.LIBRARY_AUDIOBOOKS_EDIT,
448 ProviderFeature.LIBRARY_PODCASTS_EDIT,
449 ProviderFeature.LIBRARY_RADIOS_EDIT,
450 }
451 ):
452 extra_entries.append(CONF_ENTRY_LIBRARY_SYNC_BACK)
453
454 all_entries = [
455 *DEFAULT_PROVIDER_CONFIG_ENTRIES,
456 *extra_entries,
457 *await prov_mod.get_config_entries(
458 self.mass, instance_id=instance_id, action=action, values=values
459 ),
460 ]
461 if action and values is not None:
462 # set current value from passed values for config entries
463 # only do this if we're passed values (e.g. during an action)
464 # deepcopy here to avoid modifying original entries
465 all_entries = [deepcopy(entry) for entry in all_entries]
466 for entry in all_entries:
467 if entry.value is None:
468 entry.value = values.get(entry.key, entry.default_value)
469 return all_entries
470
471 @api_command("config/providers/save", required_role="admin")
472 async def save_provider_config(
473 self,
474 provider_domain: str,
475 values: dict[str, ConfigValueType],
476 instance_id: str | None = None,
477 ) -> ProviderConfig:
478 """
479 Save Provider(instance) Config.
480
481 provider_domain: (mandatory) domain of the provider.
482 values: the raw values for config entries that need to be stored/updated.
483 instance_id: id of an existing provider instance (None for new instance setup).
484 """
485 if instance_id is not None:
486 config = await self._update_provider_config(instance_id, values)
487 else:
488 config = await self._add_provider_config(provider_domain, values)
489 # return full config, just in case
490 return await self.get_provider_config(config.instance_id)
491
492 @api_command("config/providers/remove", required_role="admin")
493 async def remove_provider_config(self, instance_id: str) -> None:
494 """Remove ProviderConfig."""
495 conf_key = f"{CONF_PROVIDERS}/{instance_id}"
496 existing = self.get(conf_key)
497 if not existing:
498 msg = f"Provider {instance_id} does not exist"
499 raise KeyError(msg)
500 prov_manifest = self.mass.get_provider_manifest(existing["domain"])
501 if prov_manifest.builtin:
502 msg = f"Builtin provider {prov_manifest.name} can not be removed."
503 raise RuntimeError(msg)
504 self.remove(conf_key)
505 await self.mass.unload_provider(instance_id, True)
506 if existing["type"] == "music":
507 # cleanup entries in library
508 await self.mass.music.cleanup_provider(instance_id)
509 if existing["type"] == "player":
510 # all players should already be removed by now through unload_provider
511 for player in list(self.mass.players):
512 if player.provider.instance_id != instance_id:
513 continue
514 self.mass.players.delete_player_config(player.player_id)
515 # cleanup remaining player configs
516 for player_conf in list(self.get(CONF_PLAYERS, {}).values()):
517 if player_conf["provider"] == instance_id:
518 self.remove(f"{CONF_PLAYERS}/{player_conf['player_id']}")
519
520 async def remove_provider_config_value(self, instance_id: str, key: str) -> None:
521 """Remove/reset single Provider config value."""
522 conf_key = f"{CONF_PROVIDERS}/{instance_id}/values/{key}"
523 existing = self.get(conf_key)
524 if not existing:
525 return
526 self.remove(conf_key)
527
528 def set_provider_default_name(self, instance_id: str, default_name: str) -> None:
529 """Set (or update) the default name for a provider."""
530 conf_key = f"{CONF_PROVIDERS}/{instance_id}/default_name"
531 self.set(conf_key, default_name)
532
533 @api_command("config/players")
534 async def get_player_configs(
535 self,
536 provider: str | None = None,
537 include_values: bool = False,
538 include_unavailable: bool = True,
539 include_disabled: bool = True,
540 ) -> list[PlayerConfig]:
541 """Return all known player configurations, optionally filtered by provider id."""
542 result: list[PlayerConfig] = []
543 for raw_conf in list(self.get(CONF_PLAYERS, {}).values()):
544 # optional provider filter
545 if provider is not None and raw_conf["provider"] != provider:
546 continue
547 # filter out unavailable players
548 # (unless disabled, otherwise there is no way to re-enable them)
549 # note that we only check for missing players in the player controller,
550 # and we do allow players that are temporary unavailable (player.available = false)
551 # because this can also mean that the player needs additional configuration
552 # such as airplay devices that need pairing.
553 player = self.mass.players.get(raw_conf["player_id"], False)
554 if not include_unavailable and player is None and raw_conf.get("enabled", True):
555 continue
556 # filter out disabled players
557 if not include_disabled and not raw_conf.get("enabled", True):
558 continue
559 if include_values:
560 result.append(await self.get_player_config(raw_conf["player_id"]))
561 else:
562 raw_conf["default_name"] = (
563 player.display_name if player else raw_conf.get("default_name")
564 )
565 raw_conf["available"] = player.available if player else False
566 result.append(cast("PlayerConfig", PlayerConfig.parse([], raw_conf)))
567 return result
568
569 @api_command("config/players/get")
570 async def get_player_config(
571 self,
572 player_id: str,
573 action: str | None = None,
574 values: dict[str, ConfigValueType] | None = None,
575 ) -> PlayerConfig:
576 """Return (full) configuration for a single player."""
577 raw_conf: dict[str, Any]
578 if raw_conf := self.get(f"{CONF_PLAYERS}/{player_id}"):
579 if player := self.mass.players.get(player_id, False):
580 raw_conf["default_name"] = player.display_name
581 raw_conf["provider"] = player.provider.instance_id
582 # pass action and values to get_config_entries
583 if values is None:
584 values = raw_conf.get("values", {})
585 conf_entries = await self.get_player_config_entries(
586 player_id, action=action, values=values
587 )
588 else:
589 # handle unavailable player and/or provider
590 conf_entries = []
591 raw_conf["available"] = False
592 raw_conf["default_name"] = raw_conf.get("default_name") or raw_conf["player_id"]
593 return cast("PlayerConfig", PlayerConfig.parse(conf_entries, raw_conf))
594 msg = f"No config found for player id {player_id}"
595 raise KeyError(msg)
596
597 @api_command("config/players/get_entries")
598 async def get_player_config_entries(
599 self,
600 player_id: str,
601 action: str | None = None,
602 values: dict[str, ConfigValueType] | None = None,
603 ) -> list[ConfigEntry]:
604 """
605 Return Config entries to configure a player.
606
607 player_id: id of an existing player instance.
608 action: [optional] action key called from config entries UI.
609 values: the (intermediate) raw values for config entries sent with the action.
610 """
611 if not (player := self.mass.players.get(player_id, False)):
612 msg = f"Player {player_id} not found"
613 raise KeyError(msg)
614 # get player(protocol) specific entries
615 player_entries = await self._get_player_config_entries(player, action=action, values=values)
616 # get default entries which are common for all players
617 default_entries = self._get_default_player_config_entries(player)
618 player_entries_keys = {entry.key for entry in player_entries}
619 all_entries = [
620 # ignore default entries that were overridden by the player specific ones
621 *[x for x in default_entries if x.key not in player_entries_keys],
622 *player_entries,
623 ]
624 if action and values is not None:
625 # set current value from passed values for config entries
626 # only do this if we're passed values (e.g. during an action)
627 # deepcopy here to avoid modifying original entries
628 all_entries = [deepcopy(entry) for entry in all_entries]
629 for entry in all_entries:
630 if entry.value is None:
631 entry.value = values.get(entry.key, entry.default_value)
632 return all_entries
633
634 @overload
635 async def get_player_config_value(
636 self,
637 player_id: str,
638 key: str,
639 unpack_splitted_values: Literal[True],
640 *,
641 default: ConfigValueType = ...,
642 return_type: type[_ConfigValueT] | None = ...,
643 ) -> tuple[str, ...] | list[tuple[str, ...]]: ...
644
645 @overload
646 async def get_player_config_value(
647 self,
648 player_id: str,
649 key: str,
650 unpack_splitted_values: Literal[False] = False,
651 *,
652 default: _ConfigValueT,
653 return_type: type[_ConfigValueT] = ...,
654 ) -> _ConfigValueT: ...
655
656 @overload
657 async def get_player_config_value(
658 self,
659 player_id: str,
660 key: str,
661 unpack_splitted_values: Literal[False] = False,
662 *,
663 default: ConfigValueType = ...,
664 return_type: type[_ConfigValueT] = ...,
665 ) -> _ConfigValueT: ...
666
667 @overload
668 async def get_player_config_value(
669 self,
670 player_id: str,
671 key: str,
672 unpack_splitted_values: Literal[False] = False,
673 *,
674 default: ConfigValueType = ...,
675 return_type: None = ...,
676 ) -> ConfigValueType: ...
677
678 @api_command("config/players/get_value")
679 async def get_player_config_value(
680 self,
681 player_id: str,
682 key: str,
683 unpack_splitted_values: bool = False,
684 *,
685 default: ConfigValueType = None,
686 return_type: type[_ConfigValueT | ConfigValueType] | None = None,
687 ) -> _ConfigValueT | ConfigValueType | tuple[str, ...] | list[tuple[str, ...]]:
688 """
689 Return single configentry value for a player.
690
691 :param player_id: The player ID.
692 :param key: The config key to retrieve.
693 :param unpack_splitted_values: Whether to unpack multi-value config entries.
694 :param default: Optional default value to return if key is not found.
695 :param return_type: Optional type hint for type inference (e.g., str, int, bool).
696 Note: This parameter is used purely for static type checking and does not
697 perform runtime type validation. Callers are responsible for ensuring the
698 specified type matches the actual config value type.
699 """
700 # prefer stored value so we don't have to retrieve all config entries every time
701 if (raw_value := self.get_raw_player_config_value(player_id, key)) is not None:
702 if not unpack_splitted_values:
703 return raw_value
704 conf = await self.get_player_config(player_id)
705 if key not in conf.values:
706 if default is not None:
707 return default
708 msg = f"Config key {key} not found for player {player_id}"
709 raise KeyError(msg)
710 if unpack_splitted_values:
711 return conf.values[key].get_splitted_values()
712 return (
713 conf.values[key].value
714 if conf.values[key].value is not None
715 else conf.values[key].default_value
716 )
717
718 if TYPE_CHECKING:
719 # Overload for when default is provided - return type matches default type
720 @overload
721 def get_raw_player_config_value(
722 self, player_id: str, key: str, default: _ConfigValueT
723 ) -> _ConfigValueT: ...
724
725 # Overload for when no default is provided - return ConfigValueType | None
726 @overload
727 def get_raw_player_config_value(
728 self, player_id: str, key: str, default: None = None
729 ) -> ConfigValueType | None: ...
730
731 def get_raw_player_config_value(
732 self, player_id: str, key: str, default: ConfigValueType = None
733 ) -> ConfigValueType:
734 """
735 Return (raw) single configentry value for a player.
736
737 Note that this only returns the stored value without any validation or default.
738 """
739 return cast(
740 "ConfigValueType",
741 self.get(
742 f"{CONF_PLAYERS}/{player_id}/values/{key}",
743 self.get(f"{CONF_PLAYERS}/{player_id}/{key}", default),
744 ),
745 )
746
747 def get_base_player_config(self, player_id: str, provider: str) -> PlayerConfig:
748 """
749 Return base PlayerConfig for a player.
750
751 This is used to get the base config for a player, without any provider specific values,
752 for initialization purposes.
753 """
754 if not (raw_conf := self.get(f"{CONF_PLAYERS}/{player_id}")):
755 raw_conf = {
756 "player_id": player_id,
757 "provider": provider,
758 }
759 return cast("PlayerConfig", PlayerConfig.parse([], raw_conf))
760
761 @api_command("config/players/save", required_role="admin")
762 async def save_player_config(
763 self, player_id: str, values: dict[str, ConfigValueType]
764 ) -> PlayerConfig:
765 """Save/update PlayerConfig."""
766 config = await self.get_player_config(player_id)
767 old_config = deepcopy(config)
768 changed_keys = config.update(values)
769 if not changed_keys:
770 # no changes
771 return config
772 # store updated config first (to prevent issues with enabling/disabling players)
773 conf_key = f"{CONF_PLAYERS}/{player_id}"
774 self.set(conf_key, config.to_raw())
775 try:
776 # validate/handle the update in the player manager
777 await self.mass.players.on_player_config_change(config, changed_keys)
778 except Exception:
779 # rollback on error
780 self.set(conf_key, old_config.to_raw())
781 raise
782 # send config updated event
783 self.mass.signal_event(
784 EventType.PLAYER_CONFIG_UPDATED,
785 object_id=config.player_id,
786 data=config,
787 )
788 # return full player config (just in case)
789 return await self.get_player_config(player_id)
790
791 @api_command("config/players/remove", required_role="admin")
792 async def remove_player_config(self, player_id: str) -> None:
793 """Remove PlayerConfig."""
794 conf_key = f"{CONF_PLAYERS}/{player_id}"
795 dsp_conf_key = f"{CONF_PLAYER_DSP}/{player_id}"
796 player_config = self.get(conf_key)
797 if not player_config:
798 msg = f"Player configuration for {player_id} does not exist"
799 raise KeyError(msg)
800 if self.mass.players.get(player_id):
801 try:
802 await self.mass.players.remove(player_id)
803 except UnsupportedFeaturedException:
804 # removing a player config while it is active is not allowed
805 # unless the provider reports it has the remove_player feature
806 raise ActionUnavailable("Can not remove config for an active player!")
807 # tell the player manager to remove the player if its lingering around
808 # set permanent to false otherwise we end up in an infinite loop
809 await self.mass.players.unregister(player_id, permanent=False)
810 # remove the actual config if all of the above passed
811 self.remove(conf_key)
812 # Also remove the DSP config if it exists
813 self.remove(dsp_conf_key)
814
815 def set_player_default_name(self, player_id: str, default_name: str) -> None:
816 """Set (or update) the default name for a player."""
817 conf_key = f"{CONF_PLAYERS}/{player_id}/default_name"
818 self.set(conf_key, default_name)
819
820 def set_player_type(self, player_id: str, player_type: PlayerType) -> None:
821 """Set (or update) the type for a player."""
822 conf_key = f"{CONF_PLAYERS}/{player_id}/player_type"
823 self.set(conf_key, player_type)
824
825 def create_default_player_config(
826 self,
827 player_id: str,
828 provider: str,
829 player_type: PlayerType,
830 name: str | None = None,
831 enabled: bool = True,
832 values: dict[str, ConfigValueType] | None = None,
833 ) -> None:
834 """
835 Create default/empty PlayerConfig.
836
837 This is meant as helper to create default configs when a player is registered.
838 Called by the player manager on player register.
839 """
840 # return early if the config already exists
841 if existing_conf := self.get(f"{CONF_PLAYERS}/{player_id}"):
842 # update default name if needed
843 if name and name != existing_conf.get("default_name"):
844 self.set(f"{CONF_PLAYERS}/{player_id}/default_name", name)
845 # update player_type if needed
846 if existing_conf.get("player_type") != player_type:
847 self.set(f"{CONF_PLAYERS}/{player_id}/player_type", player_type.value)
848 return
849 # config does not yet exist, create a default one
850 conf_key = f"{CONF_PLAYERS}/{player_id}"
851 default_conf = PlayerConfig(
852 values={},
853 provider=provider,
854 player_id=player_id,
855 enabled=enabled,
856 name=name,
857 default_name=name,
858 player_type=player_type,
859 )
860 default_conf_raw = default_conf.to_raw()
861 if values is not None:
862 default_conf_raw["values"] = values
863 self.set(
864 conf_key,
865 default_conf_raw,
866 )
867
868 @api_command("config/players/dsp/get")
869 def get_player_dsp_config(self, player_id: str) -> DSPConfig:
870 """
871 Return the DSP Configuration for a player.
872
873 In case the player does not have a DSP configuration, a default one is returned.
874 """
875 if raw_conf := self.get(f"{CONF_PLAYER_DSP}/{player_id}"):
876 return DSPConfig.from_dict(raw_conf)
877 # return default DSP config
878 dsp_config = DSPConfig()
879 # The DSP config does not do anything by default, so we disable it
880 dsp_config.enabled = False
881 return dsp_config
882
883 @api_command("config/players/dsp/save", required_role="admin")
884 async def save_dsp_config(self, player_id: str, config: DSPConfig) -> DSPConfig:
885 """
886 Save/update DSPConfig for a player.
887
888 This method will validate the config and apply it to the player.
889 """
890 # validate the new config
891 config.validate()
892
893 # Save and apply the new config to the player
894 self.set(f"{CONF_PLAYER_DSP}/{player_id}", config.to_dict())
895 await self.mass.players.on_player_dsp_change(player_id)
896 # send the dsp config updated event
897 self.mass.signal_event(
898 EventType.PLAYER_DSP_CONFIG_UPDATED,
899 object_id=player_id,
900 data=config,
901 )
902 return config
903
904 @api_command("config/dsp_presets/get")
905 async def get_dsp_presets(self) -> list[DSPConfigPreset]:
906 """Return all user-defined DSP presets."""
907 raw_presets = self.get(CONF_PLAYER_DSP_PRESETS, {})
908 return [DSPConfigPreset.from_dict(preset) for preset in raw_presets.values()]
909
910 @api_command("config/dsp_presets/save", required_role="admin")
911 async def save_dsp_presets(self, preset: DSPConfigPreset) -> DSPConfigPreset:
912 """
913 Save/update a user-defined DSP presets.
914
915 This method will validate the config before saving it to the persistent storage.
916 """
917 preset.validate()
918
919 if preset.preset_id is None:
920 # Generate a new preset_id if it does not exist
921 preset.preset_id = shortuuid.random(8).lower()
922
923 # Save the preset to the persistent storage
924 self.set(f"{CONF_PLAYER_DSP_PRESETS}/preset_{preset.preset_id}", preset.to_dict())
925
926 all_presets = await self.get_dsp_presets()
927
928 self.mass.signal_event(
929 EventType.DSP_PRESETS_UPDATED,
930 data=all_presets,
931 )
932
933 return preset
934
935 @api_command("config/dsp_presets/remove", required_role="admin")
936 async def remove_dsp_preset(self, preset_id: str) -> None:
937 """Remove a user-defined DSP preset."""
938 self.mass.config.remove(f"{CONF_PLAYER_DSP_PRESETS}/preset_{preset_id}")
939
940 all_presets = await self.get_dsp_presets()
941
942 self.mass.signal_event(
943 EventType.DSP_PRESETS_UPDATED,
944 data=all_presets,
945 )
946
947 async def create_builtin_provider_config(self, provider_domain: str) -> None:
948 """
949 Create builtin ProviderConfig.
950
951 This is meant as helper to create default configs for builtin providers.
952 Called by the server initialization code which load all providers at startup.
953 """
954 for _ in await self.get_provider_configs(provider_domain=provider_domain):
955 # return if there is already any config
956 return
957 for prov in self.mass.get_provider_manifests():
958 if prov.domain == provider_domain:
959 manifest = prov
960 break
961 else:
962 msg = f"Unknown provider domain: {provider_domain}"
963 raise KeyError(msg)
964 config_entries = await self.get_provider_config_entries(provider_domain)
965 if manifest.multi_instance:
966 instance_id = f"{manifest.domain}--{shortuuid.random(8)}"
967 else:
968 instance_id = manifest.domain
969 default_config = cast(
970 "ProviderConfig",
971 ProviderConfig.parse(
972 config_entries,
973 {
974 "type": manifest.type.value,
975 "domain": manifest.domain,
976 "instance_id": instance_id,
977 "name": manifest.name,
978 # note: this will only work for providers that do
979 # not have any required config entries or provide defaults
980 "values": {},
981 },
982 ),
983 )
984 default_config.validate()
985 conf_key = f"{CONF_PROVIDERS}/{default_config.instance_id}"
986 self.set_default(conf_key, default_config.to_raw())
987
988 @api_command("config/core")
989 async def get_core_configs(self, include_values: bool = False) -> list[CoreConfig]:
990 """Return all core controllers config options."""
991 return [
992 await self.get_core_config(core_controller)
993 if include_values
994 else cast(
995 "CoreConfig",
996 CoreConfig.parse(
997 [],
998 self.get(f"{CONF_CORE}/{core_controller}", {"domain": core_controller}),
999 ),
1000 )
1001 for core_controller in CONFIGURABLE_CORE_CONTROLLERS
1002 ]
1003
1004 @api_command("config/core/get")
1005 async def get_core_config(self, domain: str) -> CoreConfig:
1006 """Return configuration for a single core controller."""
1007 raw_conf = self.get(f"{CONF_CORE}/{domain}", {"domain": domain})
1008 config_entries = await self.get_core_config_entries(domain)
1009 return cast("CoreConfig", CoreConfig.parse(config_entries, raw_conf))
1010
1011 @overload
1012 async def get_core_config_value(
1013 self,
1014 domain: str,
1015 key: str,
1016 *,
1017 default: _ConfigValueT,
1018 return_type: type[_ConfigValueT] = ...,
1019 ) -> _ConfigValueT: ...
1020
1021 @overload
1022 async def get_core_config_value(
1023 self,
1024 domain: str,
1025 key: str,
1026 *,
1027 default: ConfigValueType = ...,
1028 return_type: type[_ConfigValueT] = ...,
1029 ) -> _ConfigValueT: ...
1030
1031 @overload
1032 async def get_core_config_value(
1033 self,
1034 domain: str,
1035 key: str,
1036 *,
1037 default: ConfigValueType = ...,
1038 return_type: None = ...,
1039 ) -> ConfigValueType: ...
1040
1041 @api_command("config/core/get_value")
1042 async def get_core_config_value(
1043 self,
1044 domain: str,
1045 key: str,
1046 *,
1047 default: ConfigValueType = None,
1048 return_type: type[_ConfigValueT | ConfigValueType] | None = None,
1049 ) -> _ConfigValueT | ConfigValueType:
1050 """
1051 Return single configentry value for a core controller.
1052
1053 :param domain: The core controller domain.
1054 :param key: The config key to retrieve.
1055 :param default: Optional default value to return if key is not found.
1056 :param return_type: Optional type hint for type inference (e.g., str, int, bool).
1057 Note: This parameter is used purely for static type checking and does not
1058 perform runtime type validation. Callers are responsible for ensuring the
1059 specified type matches the actual config value type.
1060 """
1061 # prefer stored value so we don't have to retrieve all config entries every time
1062 if (raw_value := self.get_raw_core_config_value(domain, key)) is not None:
1063 return raw_value
1064 conf = await self.get_core_config(domain)
1065 if key not in conf.values:
1066 if default is not None:
1067 return default
1068 msg = f"Config key {key} not found for core controller {domain}"
1069 raise KeyError(msg)
1070 return (
1071 conf.values[key].value
1072 if conf.values[key].value is not None
1073 else conf.values[key].default_value
1074 )
1075
1076 @api_command("config/core/get_entries")
1077 async def get_core_config_entries(
1078 self,
1079 domain: str,
1080 action: str | None = None,
1081 values: dict[str, ConfigValueType] | None = None,
1082 ) -> list[ConfigEntry]:
1083 """
1084 Return Config entries to configure a core controller.
1085
1086 core_controller: name of the core controller
1087 action: [optional] action key called from config entries UI.
1088 values: the (intermediate) raw values for config entries sent with the action.
1089 """
1090 controller: CoreController = getattr(self.mass, domain)
1091 all_entries = list(
1092 await controller.get_config_entries(action=action, values=values)
1093 + DEFAULT_CORE_CONFIG_ENTRIES
1094 )
1095 if action and values is not None:
1096 # set current value from passed values for config entries
1097 # only do this if we're passed values (e.g. during an action)
1098 # deepcopy here to avoid modifying original entries
1099 all_entries = [deepcopy(entry) for entry in all_entries]
1100 for entry in all_entries:
1101 if entry.value is None:
1102 entry.value = values.get(entry.key, entry.default_value)
1103 return all_entries
1104
1105 @api_command("config/core/save", required_role="admin")
1106 async def save_core_config(
1107 self,
1108 domain: str,
1109 values: dict[str, ConfigValueType],
1110 ) -> CoreConfig:
1111 """Save CoreController Config values."""
1112 config = await self.get_core_config(domain)
1113 prev_config = config.to_raw()
1114 changed_keys = config.update(values)
1115 # validate the new config
1116 config.validate()
1117 if not changed_keys:
1118 # no changes
1119 return config
1120 # save the config first before reloading to avoid issues on reload
1121 # for example when reloading the webserver we might be cancelled here
1122 conf_key = f"{CONF_CORE}/{domain}"
1123 self.set(conf_key, config.to_raw())
1124 self.save(immediate=True)
1125 try:
1126 controller: CoreController = getattr(self.mass, domain)
1127 await controller.update_config(config, changed_keys)
1128 except asyncio.CancelledError:
1129 pass
1130 except Exception:
1131 # revert to previous config on error
1132 self.set(conf_key, prev_config)
1133 self.save(immediate=True)
1134 raise
1135 # reload succeeded; clear last_error and persist the final state
1136 config.last_error = None
1137 # return full config
1138 return await self.get_core_config(domain)
1139
1140 if TYPE_CHECKING:
1141 # Overload for when default is provided - return type matches default type
1142 @overload
1143 def get_raw_core_config_value(
1144 self, core_module: str, key: str, default: _ConfigValueT
1145 ) -> _ConfigValueT: ...
1146
1147 # Overload for when no default is provided - return ConfigValueType | None
1148 @overload
1149 def get_raw_core_config_value(
1150 self, core_module: str, key: str, default: None = None
1151 ) -> ConfigValueType | None: ...
1152
1153 def get_raw_core_config_value(
1154 self, core_module: str, key: str, default: ConfigValueType = None
1155 ) -> ConfigValueType:
1156 """
1157 Return (raw) single configentry value for a core controller.
1158
1159 Note that this only returns the stored value without any validation or default.
1160 """
1161 return cast(
1162 "ConfigValueType",
1163 self.get(
1164 f"{CONF_CORE}/{core_module}/values/{key}",
1165 self.get(f"{CONF_CORE}/{core_module}/{key}", default),
1166 ),
1167 )
1168
1169 if TYPE_CHECKING:
1170 # Overload for when default is provided - return type matches default type
1171 @overload
1172 def get_raw_provider_config_value(
1173 self, provider_instance: str, key: str, default: _ConfigValueT
1174 ) -> _ConfigValueT: ...
1175
1176 # Overload for when no default is provided - return ConfigValueType | None
1177 @overload
1178 def get_raw_provider_config_value(
1179 self, provider_instance: str, key: str, default: None = None
1180 ) -> ConfigValueType | None: ...
1181
1182 def get_raw_provider_config_value(
1183 self, provider_instance: str, key: str, default: ConfigValueType = None
1184 ) -> ConfigValueType:
1185 """
1186 Return (raw) single config(entry) value for a provider.
1187
1188 Note that this only returns the stored value without any validation or default.
1189 """
1190 return cast(
1191 "ConfigValueType",
1192 self.get(
1193 f"{CONF_PROVIDERS}/{provider_instance}/values/{key}",
1194 self.get(f"{CONF_PROVIDERS}/{provider_instance}/{key}", default),
1195 ),
1196 )
1197
1198 def set_raw_provider_config_value(
1199 self,
1200 provider_instance: str,
1201 key: str,
1202 value: ConfigValueType,
1203 encrypted: bool = False,
1204 ) -> None:
1205 """
1206 Set (raw) single config(entry) value for a provider.
1207
1208 Note that this only stores the (raw) value without any validation or default.
1209 """
1210 if not self.get(f"{CONF_PROVIDERS}/{provider_instance}"):
1211 # only allow setting raw values if main entry exists
1212 msg = f"Invalid provider_instance: {provider_instance}"
1213 raise KeyError(msg)
1214 if encrypted:
1215 if not isinstance(value, str):
1216 msg = f"Cannot encrypt non-string value for key {key}"
1217 raise ValueError(msg)
1218 value = self.encrypt_string(value)
1219 if key in BASE_KEYS:
1220 self.set(f"{CONF_PROVIDERS}/{provider_instance}/{key}", value)
1221 return
1222 self.set(f"{CONF_PROVIDERS}/{provider_instance}/values/{key}", value)
1223
1224 def set_raw_core_config_value(self, core_module: str, key: str, value: ConfigValueType) -> None:
1225 """
1226 Set (raw) single config(entry) value for a core controller.
1227
1228 Note that this only stores the (raw) value without any validation or default.
1229 """
1230 if not self.get(f"{CONF_CORE}/{core_module}"):
1231 # create base object first if needed
1232 self.set(f"{CONF_CORE}/{core_module}", CoreConfig({}, core_module).to_raw())
1233 self.set(f"{CONF_CORE}/{core_module}/values/{key}", value)
1234
1235 def set_raw_player_config_value(self, player_id: str, key: str, value: ConfigValueType) -> None:
1236 """
1237 Set (raw) single config(entry) value for a player.
1238
1239 Note that this only stores the (raw) value without any validation or default.
1240 """
1241 if not self.get(f"{CONF_PLAYERS}/{player_id}"):
1242 # only allow setting raw values if main entry exists
1243 msg = f"Invalid player_id: {player_id}"
1244 raise KeyError(msg)
1245 if key in BASE_KEYS:
1246 self.set(f"{CONF_PLAYERS}/{player_id}/{key}", value)
1247 else:
1248 self.set(f"{CONF_PLAYERS}/{player_id}/values/{key}", value)
1249
1250 def save(self, immediate: bool = False) -> None:
1251 """Schedule save of data to disk."""
1252 if self._timer_handle is not None:
1253 self._timer_handle.cancel()
1254 self._timer_handle = None
1255
1256 if immediate:
1257 self.mass.loop.create_task(self._async_save())
1258 else:
1259 # schedule the save for later
1260 self._timer_handle = self.mass.loop.call_later(
1261 DEFAULT_SAVE_DELAY, self.mass.create_task, self._async_save
1262 )
1263
1264 def encrypt_string(self, str_value: str) -> str:
1265 """Encrypt a (password)string with Fernet."""
1266 if str_value.startswith(ENCRYPT_SUFFIX):
1267 return str_value
1268 assert self._fernet is not None
1269 return ENCRYPT_SUFFIX + self._fernet.encrypt(str_value.encode()).decode()
1270
1271 def decrypt_string(self, encrypted_str: str) -> str:
1272 """Decrypt a (password)string with Fernet."""
1273 if not encrypted_str:
1274 return encrypted_str
1275 if not encrypted_str.startswith(ENCRYPT_SUFFIX):
1276 return encrypted_str
1277 assert self._fernet is not None
1278 try:
1279 return self._fernet.decrypt(encrypted_str.replace(ENCRYPT_SUFFIX, "").encode()).decode()
1280 except InvalidToken as err:
1281 msg = "Password decryption failed"
1282 raise InvalidDataError(msg) from err
1283
1284 async def _load(self) -> None:
1285 """Load data from persistent storage."""
1286 assert not self._data, "Already loaded"
1287
1288 for filename in (self.filename, f"{self.filename}.backup"):
1289 try:
1290 async with aiofiles.open(filename, encoding="utf-8") as _file:
1291 self._data = await async_json_loads(await _file.read())
1292 LOGGER.debug("Loaded persistent settings from %s", filename)
1293 await self._migrate()
1294 return
1295 except FileNotFoundError:
1296 pass
1297 except JSON_DECODE_EXCEPTIONS:
1298 LOGGER.exception("Error while reading persistent storage file %s", filename)
1299 LOGGER.debug("Started with empty storage: No persistent storage file found.")
1300
1301 async def _migrate(self) -> None: # noqa: PLR0915
1302 changed = False
1303
1304 # some type hints to help with the code below
1305 instance_id: str
1306 provider_config: dict[str, Any]
1307 player_config: dict[str, Any]
1308
1309 # Older versions of MA can create corrupt entries with no domain if retrying
1310 # logic runs after a provider has been removed. Remove those corrupt entries.
1311 for instance_id, provider_config in {**self._data.get(CONF_PROVIDERS, {})}.items():
1312 if "domain" not in provider_config:
1313 self._data[CONF_PROVIDERS].pop(instance_id, None)
1314 LOGGER.warning("Removed corrupt provider configuration: %s", instance_id)
1315 changed = True
1316
1317 # migrate manual_ips to new format
1318 for instance_id, provider_config in self._data.get(CONF_PROVIDERS, {}).items():
1319 if not (values := provider_config.get("values")):
1320 continue
1321 if not (ips := values.get("ips")):
1322 continue
1323 values["manual_discovery_ip_addresses"] = ips.split(",")
1324 del values["ips"]
1325 changed = True
1326
1327 # migrate sample_rates config entry
1328 for player_config in self._data.get(CONF_PLAYERS, {}).values():
1329 if not (values := player_config.get("values")):
1330 continue
1331 if not (sample_rates := values.get("sample_rates")):
1332 continue
1333 if not isinstance(sample_rates, list):
1334 del player_config["values"]["sample_rates"]
1335 if not any(isinstance(x, list) for x in sample_rates):
1336 continue
1337 player_config["values"]["sample_rates"] = [
1338 f"{x[0]}{MULTI_VALUE_SPLITTER}{x[1]}" if isinstance(x, list) else x
1339 for x in sample_rates
1340 ]
1341 changed = True
1342
1343 # migrate player_group entries
1344 ugp_found = False
1345 for player_config in self._data.get(CONF_PLAYERS, {}).values():
1346 provider = player_config.get("provider")
1347 if (
1348 not provider
1349 or not isinstance(provider, str)
1350 or not provider.startswith("player_group")
1351 ):
1352 continue
1353 if not (values := player_config.get("values")):
1354 continue
1355 if (group_type := values.pop("group_type", None)) is None:
1356 continue
1357 # this is a legacy player group, migrate the values
1358 changed = True
1359 if group_type == "universal":
1360 player_config["provider"] = "universal_group"
1361 ugp_found = True
1362 else:
1363 player_config["provider"] = group_type
1364 for provider_config in list(self._data.get(CONF_PROVIDERS, {}).values()):
1365 instance_id = provider_config["instance_id"]
1366 if not instance_id.startswith("player_group"):
1367 continue
1368 # this is the legacy player_group provider, migrate into 'universal_group'
1369 changed = True
1370 self._data[CONF_PROVIDERS].pop(instance_id, None)
1371 if not ugp_found:
1372 continue
1373 provider_config["domain"] = "universal_group"
1374 provider_config["instance_id"] = "universal_group"
1375 self._data[CONF_PROVIDERS]["universal_group"] = provider_config
1376
1377 # Migrate resonate provider to sendspin (renamed in 2.7 beta 19)
1378 for instance_id, provider_config in list(self._data.get(CONF_PROVIDERS, {}).items()):
1379 if provider_config.get("domain") == "resonate":
1380 self._data[CONF_PROVIDERS].pop(instance_id, None)
1381 provider_config["domain"] = "sendspin"
1382 provider_config["instance_id"] = "sendspin"
1383 self._data[CONF_PROVIDERS]["sendspin"] = provider_config
1384 changed = True
1385
1386 # Migrate smart_fades mode value to smart_crossfade
1387 for player_config in self._data.get(CONF_PLAYERS, {}).values():
1388 if not (values := player_config.get("values")):
1389 continue
1390 if values.get(CONF_SMART_FADES_MODE) == "smart_fades":
1391 # Update old 'smart_fades' value to new 'smart_crossfade' value
1392 values[CONF_SMART_FADES_MODE] = "smart_crossfade"
1393 changed = True
1394
1395 # Remove obsolete builtin_player configurations (provider was deleted in 2.7)
1396 for player_id, player_config in list(self._data.get(CONF_PLAYERS, {}).items()):
1397 if player_config.get("provider") != "builtin_player":
1398 continue
1399 self._data[CONF_PLAYERS].pop(player_id, None)
1400 # Also remove any DSP config for this player
1401 if CONF_PLAYER_DSP in self._data:
1402 self._data[CONF_PLAYER_DSP].pop(player_id, None)
1403 LOGGER.warning("Removed obsolete builtin_player configuration: %s", player_id)
1404 changed = True
1405
1406 # Remove corrupt player configurations that are missing the required 'provider' key
1407 for player_id, player_config in list(self._data.get(CONF_PLAYERS, {}).items()):
1408 if "provider" in player_config:
1409 continue
1410 self._data[CONF_PLAYERS].pop(player_id, None)
1411 # Also remove any DSP config for this player
1412 if CONF_PLAYER_DSP in self._data:
1413 self._data[CONF_PLAYER_DSP].pop(player_id, None)
1414 LOGGER.warning("Removed corrupt player configuration (missing provider): %s", player_id)
1415 changed = True
1416
1417 # migrate player configs: always use instance_id for provider
1418 for player_config in self._data.get(CONF_PLAYERS, {}).values():
1419 if "provider" not in player_config:
1420 continue
1421 player_provider = player_config["provider"]
1422 try:
1423 if not (prov := self.mass.get_provider(player_provider)):
1424 continue
1425 except KeyError:
1426 # removed provider
1427 continue
1428 if player_config["provider"] == prov.instance_id:
1429 continue
1430 player_config["provider"] = prov.instance_id
1431 changed = True
1432
1433 # Migrate AirPlay legacy credentials (ap_credentials) to protocol-specific keys
1434 # The old key was used for both RAOP and AirPlay, now we have separate keys
1435 for player_id, player_config in self._data.get(CONF_PLAYERS, {}).items():
1436 if player_config.get("provider") != "airplay":
1437 continue
1438 if not (values := player_config.get("values")):
1439 continue
1440 if "ap_credentials" not in values:
1441 continue
1442 # Migrate to raop_credentials (RAOP is the default/fallback protocol)
1443 # The new code will use the correct key based on the protocol
1444 old_creds = values.pop("ap_credentials")
1445 if old_creds and "raop_credentials" not in values:
1446 values["raop_credentials"] = old_creds
1447 LOGGER.info("Migrated AirPlay credentials for player %s", player_id)
1448 changed = True
1449
1450 if changed:
1451 await self._async_save()
1452
1453 async def _async_save(self) -> None:
1454 """Save persistent data to disk."""
1455 filename_backup = f"{self.filename}.backup"
1456 # make backup before we write a new file
1457 if await isfile(self.filename):
1458 with contextlib.suppress(FileNotFoundError):
1459 await remove(filename_backup)
1460 await rename(self.filename, filename_backup)
1461
1462 async with aiofiles.open(self.filename, "w", encoding="utf-8") as _file:
1463 await _file.write(await async_json_dumps(self._data, indent=True))
1464 LOGGER.debug("Saved data to persistent storage")
1465
1466 @api_command("config/providers/reload", required_role="admin")
1467 async def _reload_provider(self, instance_id: str) -> None:
1468 """Reload provider."""
1469 try:
1470 config = await self.get_provider_config(instance_id)
1471 except KeyError:
1472 # Edge case: Provider was removed before we could reload it
1473 return
1474 await self.mass.load_provider_config(config)
1475
1476 async def _update_provider_config(
1477 self, instance_id: str, values: dict[str, ConfigValueType]
1478 ) -> ProviderConfig:
1479 """Update ProviderConfig."""
1480 config = await self.get_provider_config(instance_id)
1481 changed_keys = config.update(values)
1482 prov_instance = self.mass.get_provider(instance_id)
1483 available = prov_instance.available if prov_instance else False
1484 if not changed_keys and (config.enabled == available):
1485 # no changes
1486 return config
1487 # validate the new config
1488 config.validate()
1489 # save the config first to prevent issues when the
1490 # provider wants to manipulate the config during load
1491 conf_key = f"{CONF_PROVIDERS}/{config.instance_id}"
1492 raw_conf = config.to_raw()
1493 self.set(conf_key, raw_conf)
1494 if config.enabled and prov_instance is None:
1495 await self.mass.load_provider_config(config)
1496 if config.enabled and prov_instance and available:
1497 # update config for existing/loaded provider instance
1498 await prov_instance.update_config(config, changed_keys)
1499 # push instance name to config (to persist it if it was autogenerated)
1500 if prov_instance.default_name != config.default_name:
1501 self.set_provider_default_name(
1502 prov_instance.instance_id, prov_instance.default_name
1503 )
1504 elif config.enabled:
1505 # provider is enabled but not available, try to load it
1506 await self.mass.load_provider_config(config)
1507 else:
1508 # disable provider
1509 prov_manifest = self.mass.get_provider_manifest(config.domain)
1510 if not prov_manifest.allow_disable:
1511 msg = "Provider can not be disabled."
1512 raise RuntimeError(msg)
1513 # also unload any other providers dependent of this provider
1514 for dep_prov in self.mass.providers:
1515 if dep_prov.manifest.depends_on == config.domain:
1516 await self.mass.unload_provider(dep_prov.instance_id)
1517 await self.mass.unload_provider(config.instance_id)
1518 # For player providers, unload_provider should have removed all its players by now
1519 return config
1520
1521 async def _add_provider_config(
1522 self,
1523 provider_domain: str,
1524 values: dict[str, ConfigValueType],
1525 ) -> ProviderConfig:
1526 """
1527 Add new Provider (instance).
1528
1529 params:
1530 - provider_domain: domain of the provider for which to add an instance of.
1531 - values: the raw values for config entries.
1532
1533 Returns: newly created ProviderConfig.
1534 """
1535 # lookup provider manifest and module
1536 for prov in self.mass.get_provider_manifests():
1537 if prov.domain == provider_domain:
1538 manifest = prov
1539 break
1540 else:
1541 msg = f"Unknown provider domain: {provider_domain}"
1542 raise KeyError(msg)
1543 if prov.depends_on and not self.mass.get_provider(prov.depends_on):
1544 msg = f"Provider {manifest.name} depends on {prov.depends_on}"
1545 raise ValueError(msg)
1546 # create new provider config with given values
1547 existing = {
1548 x.instance_id for x in await self.get_provider_configs(provider_domain=provider_domain)
1549 }
1550 # determine instance id based on previous configs
1551 if existing and not manifest.multi_instance:
1552 msg = f"Provider {manifest.name} does not support multiple instances"
1553 raise ValueError(msg)
1554 if manifest.multi_instance:
1555 instance_id = f"{manifest.domain}--{shortuuid.random(8)}"
1556 else:
1557 instance_id = manifest.domain
1558 # all checks passed, create config object
1559 config_entries = await self.get_provider_config_entries(
1560 provider_domain=provider_domain, instance_id=instance_id, values=values
1561 )
1562 config = cast(
1563 "ProviderConfig",
1564 ProviderConfig.parse(
1565 config_entries,
1566 {
1567 "type": manifest.type.value,
1568 "domain": manifest.domain,
1569 "instance_id": instance_id,
1570 "default_name": manifest.name,
1571 "values": values,
1572 },
1573 ),
1574 )
1575 # validate the new config
1576 config.validate()
1577 # save the config first to prevent issues when the
1578 # provider wants to manipulate the config during load
1579 conf_key = f"{CONF_PROVIDERS}/{config.instance_id}"
1580 self.set(conf_key, config.to_raw())
1581 # try to load the provider
1582 try:
1583 await self.mass.load_provider_config(config)
1584 except Exception:
1585 # loading failed, remove config
1586 self.remove(conf_key)
1587 raise
1588 if not self.onboard_done:
1589 # mark onboard as complete as soon as the first provider is added
1590 await self.set_onboard_complete()
1591 if manifest.type == ProviderType.MUSIC:
1592 # correct any multi-instance provider mappings
1593 self.mass.create_task(self.mass.music.correct_multi_instance_provider_mappings())
1594 return config
1595
1596 async def _get_player_config_entries(
1597 self,
1598 player: Player,
1599 action: str | None = None,
1600 values: dict[str, ConfigValueType] | None = None,
1601 ) -> list[ConfigEntry]:
1602 """
1603 Return Player(protocol) specific config entries, without any default entries.
1604
1605 In general this returns entries that are specific to this provider/player type only,
1606 and includes audio related entries that are not part of the default set.
1607
1608 player: the player instance
1609 action: [optional] action key called from config entries UI.
1610 values: the (intermediate) raw values for config entries sent with the action.
1611 """
1612 default_entries: list[ConfigEntry]
1613 is_dedicated_group_player = player.type in (
1614 PlayerType.GROUP,
1615 PlayerType.STEREO_PAIR,
1616 ) and not player.player_id.startswith(("universal_", SYNCGROUP_PREFIX))
1617 is_http_based_player_protocol = player.provider.domain not in NON_HTTP_PROVIDERS
1618 if player.type == PlayerType.GROUP and not is_dedicated_group_player:
1619 # no audio related entries for universal group players or sync group players
1620 default_entries = []
1621 else:
1622 # default output/audio related entries
1623 default_entries = [
1624 # output channel is always configurable per player(protocol)
1625 CONF_ENTRY_OUTPUT_CHANNELS
1626 ]
1627 if is_http_based_player_protocol:
1628 # for http based players we can add the http streaming related entries
1629 default_entries += [
1630 CONF_ENTRY_SAMPLE_RATES,
1631 CONF_ENTRY_OUTPUT_CODEC,
1632 CONF_ENTRY_HTTP_PROFILE,
1633 CONF_ENTRY_ENABLE_ICY_METADATA,
1634 ]
1635 # add flow mode entry for http-based players that do not already enforce it
1636 if not player.requires_flow_mode:
1637 default_entries.append(CONF_ENTRY_FLOW_MODE)
1638 # request player specific entries
1639 player_entries = await player.get_config_entries(action=action, values=values)
1640 players_keys = {entry.key for entry in player_entries}
1641 # filter out any default entries that are already provided by the player
1642 default_entries = [entry for entry in default_entries if entry.key not in players_keys]
1643 return [*player_entries, *default_entries]
1644
1645 def _get_default_player_config_entries(self, player: Player) -> list[ConfigEntry]:
1646 """
1647 Return the default (generic) player config entries.
1648
1649 This does not return audio/protocol specific entries, those are handled elsewhere.
1650 """
1651 entries: list[ConfigEntry] = []
1652 # default protocol-player config entries
1653 if player.type == PlayerType.PROTOCOL:
1654 # protocol players have no generic config entries
1655 # only audio/protocol specific ones
1656 return []
1657
1658 # some base entries for all player types
1659 # note that these may NOT be playback/audio related
1660 entries += [
1661 CONF_ENTRY_SMART_FADES_MODE,
1662 CONF_ENTRY_CROSSFADE_DURATION,
1663 # we allow volume normalization/output limiter here as it is a per-queue(player) setting
1664 CONF_ENTRY_VOLUME_NORMALIZATION,
1665 CONF_ENTRY_OUTPUT_LIMITER,
1666 CONF_ENTRY_VOLUME_NORMALIZATION_TARGET,
1667 CONF_ENTRY_TTS_PRE_ANNOUNCE,
1668 ConfigEntry(
1669 key=CONF_PRE_ANNOUNCE_CHIME_URL,
1670 type=ConfigEntryType.STRING,
1671 label="Custom (pre)announcement chime URL",
1672 description="URL to a custom audio file to play before announcements.\n"
1673 "Leave empty to use the default chime.\n"
1674 "Supports http:// and https:// URLs pointing to "
1675 "audio files (.mp3, .wav, .flac, .ogg, .m4a, .aac).\n"
1676 "Example: http://homeassistant.local:8123/local/audio/custom_chime.mp3",
1677 category="announcements",
1678 required=False,
1679 depends_on=CONF_ENTRY_TTS_PRE_ANNOUNCE.key,
1680 depends_on_value=True,
1681 validate=lambda val: validate_announcement_chime_url(cast("str", val)),
1682 ),
1683 # add player control entries
1684 *self._create_player_control_config_entries(player),
1685 # add entry to hide player in UI
1686 ConfigEntry(
1687 key=CONF_HIDE_IN_UI,
1688 type=ConfigEntryType.BOOLEAN,
1689 label="Hide this player in the user interface",
1690 default_value=player.hidden_by_default,
1691 category="generic",
1692 advanced=True,
1693 ),
1694 # add entry to expose player to HA
1695 ConfigEntry(
1696 key=CONF_EXPOSE_PLAYER_TO_HA,
1697 type=ConfigEntryType.BOOLEAN,
1698 label="Expose this player to Home Assistant",
1699 description="Expose this player to the Home Assistant integration. \n"
1700 "If disabled, this player will not be imported into Home Assistant.",
1701 category="generic",
1702 advanced=True,
1703 default_value=player.expose_to_ha_by_default,
1704 ),
1705 ]
1706 # group-player config entries
1707 if player.type == PlayerType.GROUP:
1708 entries += [
1709 CONF_ENTRY_PLAYER_ICON_GROUP,
1710 ]
1711 return entries
1712 # normal player (or stereo pair) config entries
1713 entries += [
1714 CONF_ENTRY_PLAYER_ICON,
1715 # add default entries for announce feature
1716 CONF_ENTRY_ANNOUNCE_VOLUME_STRATEGY,
1717 CONF_ENTRY_ANNOUNCE_VOLUME,
1718 CONF_ENTRY_ANNOUNCE_VOLUME_MIN,
1719 CONF_ENTRY_ANNOUNCE_VOLUME_MAX,
1720 ]
1721 return entries
1722
1723 def _create_player_control_config_entries(self, player: Player) -> list[ConfigEntry]:
1724 """Create config entries for player controls."""
1725 all_controls = self.mass.players.player_controls()
1726 power_controls = [x for x in all_controls if x.supports_power]
1727 volume_controls = [x for x in all_controls if x.supports_volume]
1728 mute_controls = [x for x in all_controls if x.supports_mute]
1729 # work out player supported features
1730 supports_power = PlayerFeature.POWER in player.supported_features
1731 supports_volume = PlayerFeature.VOLUME_SET in player.supported_features
1732 supports_mute = PlayerFeature.VOLUME_MUTE in player.supported_features
1733 # create base options per control type (and add defaults like native and fake)
1734 base_power_options: list[ConfigValueOption] = [
1735 ConfigValueOption(title="None", value=PLAYER_CONTROL_NONE),
1736 ConfigValueOption(title="Fake power control", value=PLAYER_CONTROL_FAKE),
1737 ]
1738 if supports_power:
1739 base_power_options.append(
1740 ConfigValueOption(title="Native power control", value=PLAYER_CONTROL_NATIVE),
1741 )
1742 base_volume_options: list[ConfigValueOption] = [
1743 ConfigValueOption(title="None", value=PLAYER_CONTROL_NONE),
1744 ]
1745 if supports_volume:
1746 base_volume_options.append(
1747 ConfigValueOption(title="Native volume control", value=PLAYER_CONTROL_NATIVE),
1748 )
1749 base_mute_options: list[ConfigValueOption] = [
1750 ConfigValueOption(title="None", value=PLAYER_CONTROL_NONE),
1751 ConfigValueOption(title="Fake mute control", value=PLAYER_CONTROL_FAKE),
1752 ]
1753 if supports_mute:
1754 base_mute_options.append(
1755 ConfigValueOption(title="Native mute control", value=PLAYER_CONTROL_NATIVE),
1756 )
1757 # return final config entries for all options
1758 return [
1759 # Power control config entry
1760 ConfigEntry(
1761 key=CONF_POWER_CONTROL,
1762 type=ConfigEntryType.STRING,
1763 label="Power Control",
1764 default_value=PLAYER_CONTROL_NATIVE if supports_power else PLAYER_CONTROL_NONE,
1765 required=True,
1766 options=[
1767 *base_power_options,
1768 *(ConfigValueOption(x.name, x.id) for x in power_controls),
1769 ],
1770 category="player_controls",
1771 hidden=player.type == PlayerType.GROUP,
1772 ),
1773 # Volume control config entry
1774 ConfigEntry(
1775 key=CONF_VOLUME_CONTROL,
1776 type=ConfigEntryType.STRING,
1777 label="Volume Control",
1778 default_value=PLAYER_CONTROL_NATIVE if supports_volume else PLAYER_CONTROL_NONE,
1779 required=True,
1780 options=[
1781 *base_volume_options,
1782 *(ConfigValueOption(x.name, x.id) for x in volume_controls),
1783 ],
1784 category="player_controls",
1785 hidden=player.type == PlayerType.GROUP,
1786 ),
1787 # Mute control config entry
1788 ConfigEntry(
1789 key=CONF_MUTE_CONTROL,
1790 type=ConfigEntryType.STRING,
1791 label="Mute Control",
1792 default_value=PLAYER_CONTROL_NATIVE if supports_mute else PLAYER_CONTROL_NONE,
1793 required=True,
1794 options=[
1795 *base_mute_options,
1796 *[ConfigValueOption(x.name, x.id) for x in mute_controls],
1797 ],
1798 category="player_controls",
1799 hidden=player.type == PlayerType.GROUP,
1800 ),
1801 # auto-play on power on control config entry
1802 CONF_ENTRY_AUTO_PLAY,
1803 ]
1804