/
/
/
1"""
2DEMO/TEST/DUMMY/TEMPLATE Player Provider for Music Assistant.
3
4This is an empty player provider with a test/demo implementation.
5Its meant to get started developing a new player provider for Music Assistant.
6
7Use it as a reference to discover what methods exists and what they should return.
8Also it is good to look at existing player providers to get a better understanding,
9due to the fact that providers may be flexible and support different features and/or
10ways to discover players on the network.
11
12In general, the actual device communication should reside in a separate library.
13You can then reference your library in the manifest in the requirements section,
14which is a list of (versioned!) python modules (pip syntax) that should be installed
15when the provider is selected by the user.
16
17To add a new player provider to Music Assistant, you need to create a new folder
18in the providers folder with the name of your provider (e.g. 'my_player_provider').
19In that folder you should create (at least) a __init__.py file and a manifest.json file.
20
21Optional is an icon.svg file that will be used as the icon for the provider in the UI,
22but we also support that you specify a material design icon in the manifest.json file.
23
24IMPORTANT NOTE:
25We strongly recommend developing on either macOS or Linux and start your development
26environment by running the setup.sh scripts in the scripts folder of the repository.
27This will create a virtual environment and install all dependencies needed for development.
28
29For all development instructions, please refer to the developer documentation:
30https://developers.music-assistant.io
31"""
32
33from __future__ import annotations
34
35from typing import TYPE_CHECKING
36
37from music_assistant_models.config_entries import ConfigEntry
38from music_assistant_models.enums import ConfigEntryType, ProviderFeature
39
40from .constants import CONF_NUMBER_OF_PLAYERS
41from .provider import DemoPlayerprovider
42
43if TYPE_CHECKING:
44 from music_assistant_models.config_entries import ConfigValueType, ProviderConfig
45 from music_assistant_models.provider import ProviderManifest
46
47 from music_assistant.mass import MusicAssistant
48 from music_assistant.models import ProviderInstanceType
49
50SUPPORTED_FEATURES = {
51 # MANDATORY
52 # this constant should contain a set of provider-level features
53 # that your provider supports or an empty set if none.
54 # see the ProviderFeature enum for all available features
55 ProviderFeature.SYNC_PLAYERS,
56}
57
58
59async def setup(
60 mass: MusicAssistant, manifest: ProviderManifest, config: ProviderConfig
61) -> ProviderInstanceType:
62 """Initialize provider(instance) with given configuration."""
63 # setup is called when the user wants to setup a new provider instance.
64 # you are free to do any preflight checks here and but you must return
65 # an instance of your provider.
66 return DemoPlayerprovider(mass, manifest, config, SUPPORTED_FEATURES)
67
68
69async def get_config_entries(
70 mass: MusicAssistant,
71 instance_id: str | None = None,
72 action: str | None = None,
73 values: dict[str, ConfigValueType] | None = None,
74) -> tuple[ConfigEntry, ...]:
75 """
76 Return Config entries to setup this provider.
77
78 instance_id: id of an existing provider instance (None if new instance setup).
79 action: [optional] action key called from config entries UI.
80 values: the (intermediate) raw values for config entries sent with the action.
81 """
82 # ruff: noqa: ARG001
83 # Config Entries are used to configure the Player Provider if needed.
84 # See the models of ConfigEntry and ConfigValueType for more information what is supported.
85 # The ConfigEntry is a dataclass that represents a single configuration entry.
86 # The ConfigValueType is an Enum that represents the type of value that
87 # can be stored in a ConfigEntry.
88 # If your provider does not need any configuration, you can return an empty tuple.
89 return (
90 # example of a ConfigEntry for the number of players to create
91 ConfigEntry(
92 key=CONF_NUMBER_OF_PLAYERS,
93 type=ConfigEntryType.INTEGER,
94 label="Number of Players",
95 required=True,
96 default_value="2",
97 description="Number of demo players to create.",
98 ),
99 )
100