music-assistant-server

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