music.snapcast

`music.snapcast`#

Description#

Plugin to interact with a Snapcast instance, control clients mute status, volume, playback etc.

See badaix/snapcast for further reference about the returned API types.

param poll_seconds:: How often the plugin will poll remote servers for status updates (default: 10 seconds).

Configuration#

music.snapcast:
  # [Optional]
  # Default Snapcast server host.
  # host:   # type=Optional[str]

  # [Optional]
  # Default Snapcast server control port (default: 1705).
  # port: 1705  # type=int

  # [Optional]
  # If specified, then the provided list of Snapcast servers
  # will be monitored, rather than just the one provided on ``host``.
  # This setting can be used either in conjunction with ``host`` (in
  # that case, if the ``host`` is not specified on a request then
  # ``host`` will be used as a fallback), or on its own (in that case
  # requests with no host specified will target the first server in the
  # list). Note however that either ``host`` or ``hosts`` must be
  # provided. Format:
  #
  #     .. code-block:: yaml
  #
  #         hosts:
  #             - host: localhost
  #               port: 1705  # Default port
  #
  #             - host: snapcast.example.com
  #               port: 9999
  # hosts:   # type=Optional[Iterable[dict]]

  # [Optional]
  # How often the `RunnablePlugin.loop <https://docs.platypush.tech/platypush/plugins/.html#platypush.plugins.RunnablePlugin.loop>`_ function should be
  # executed (default: 15 seconds). *NOTE*: For back-compatibility
  # reasons, the `poll_seconds` argument is also supported, but it's
  # deprecated.
  # poll_interval: 10  # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Actions#

music.snapcast.delete_client

music.snapcast.get_playing_streams

music.snapcast.group_set_clients

music.snapcast.group_set_stream

music.snapcast.mute

music.snapcast.set_client_name

music.snapcast.set_group_name

music.snapcast.set_latency

music.snapcast.status

music.snapcast.volume

Module reference#

class platypush.plugins.music.snapcast.MusicSnapcastPlugin(host: str | None = None, port: int = 1705, hosts: Iterable[dict] | None = None, poll_interval: float | None = 10, **kwargs)[source]#

Bases: RunnablePlugin

Plugin to interact with a Snapcast instance, control clients mute status, volume, playback etc.

See badaix/snapcast for further reference about the returned API types.

__init__(host: str | None = None, port: int = 1705, hosts: Iterable[dict] | None = None, poll_interval: float | None = 10, **kwargs)[source]#

Parameters:

host – Default Snapcast server host.
port – Default Snapcast server control port (default: 1705).
hosts –
If specified, then the provided list of Snapcast servers will be monitored, rather than just the one provided on host. This setting can be used either in conjunction with host (in that case, if the host is not specified on a request then host will be used as a fallback), or on its own (in that case requests with no host specified will target the first server in the list). Note however that either host or hosts must be provided. Format:
hosts: - host: localhost port: 1705 # Default port - host: snapcast.example.com port: 9999
poll_seconds – How often the plugin will poll remote servers for status updates (default: 10 seconds).

delete_client(client: str, host: str | None = None, port: int | None = None)[source]#

Delete a client from the Snapcast server

Parameters:

client – Client name or ID
host – Snapcast server (default: default configured host)
port – Snapcast server port (default: default configured port)

get_playing_streams(exclude_local: bool = False)[source]#

Returns the configured remote streams that are currently active and unmuted.

Warning

This action is deprecated and mostly kept for backward-compatibility purposes, as it doesn’t allow the case where multiple Snapcast instances can be running on the same host, nor it provides additional information other that something is playing on a certain host and port. Use status() instead.

Parameters:

exclude_local – Exclude localhost connections (default: False)

Returns:

dict with the host->port mapping. Example:

{
    "hosts": {
        "server_1": 1705,
        "server_2": 1705,
        "server_3": 1705
    }
}

group_set_clients(group: str, clients: Collection[str], host: str | None = None, port: int | None = None)[source]#

Sets the clients for a group on a Snapcast server

Parameters:

group – Group name or ID
clients – List of client names or IDs
host – Snapcast server (default: default configured host)
port – Snapcast server port (default: default configured port)

group_set_stream(group: str, stream_id: str, host: str | None = None, port: int | None = None)[source]#

Sets the active stream for a group.

Parameters:

group – Group name or ID
stream_id – Stream ID
host – Snapcast server (default: default configured host)
port – Snapcast server port (default: default configured port)

main()[source]#: Implementation of the main loop of the plugin.

Set the mute status of a connected client or group

Parameters:

client – Client name or ID to mute
group – Group ID to mute
mute – Mute status. If not set, the mute status of the selected client/group will be toggled.
host – Snapcast server to query (default: default configured host)
port – Snapcast server port (default: default configured port)

set_client_name(client: str, name: str, host: str | None = None, port: int | None = None)[source]#

Set/change the name of a connected client

Parameters:

client – Current client name or ID to rename
name – New name
host – Snapcast server (default: default configured host)
port – Snapcast server port (default: default configured port)

set_group_name(group: str, name: str, host: str | None = None, port: int | None = None)[source]#

Set/change the name of a group

Parameters:

group – Group ID to rename
name – New name
host – Snapcast server (default: default configured host)
port – Snapcast server port (default: default configured port)

set_latency(client: str, latency: float, host: str | None = None, port: int | None = None)[source]#

Set/change the latency of a connected client

Parameters:

client – Client name or ID
latency – New latency in milliseconds
host – Snapcast server (default: default configured host)
port – Snapcast server port (default: default configured port)

start()#: Start the plugin.

status(host: str | None = None, port: int | None = None, client: str | None = None, group: str | None = None)[source]#

Get the current status of a Snapcast server, client or group.

If not host, client or group is specified, the action will return the status of all the Snapcast servers.

Parameters:

host – Snapcast server to query (default: default configured host)
port – Snapcast server port (default: default configured port)
client – Client ID or name (default: None)
group – Group ID or name (default: None)

Returns:

dict. Example:

"output": {
    "host": "localhost",
    "port": 1705,
    "groups": [
        {
        "clients": [
            {
            "config": {
                "instance": 1,
                "latency": 0,
                "name": "",
                "volume": {
                "muted": false,
                "percent": 96
                }
            },
            "connected": true,
            "host": {
                "arch": "x86_64",
                "ip": "YOUR_IP",
                "mac": "YOUR_MAC",
                "name": "YOUR_NAME",
                "os": "YOUR_OS"
            },
            "id": "YOUR_ID",
            "lastSeen": {
                "sec": 1546648311,
                "usec": 86011
            },
            "snapclient": {
                "name": "Snapclient",
                "protocolVersion": 2,
                "version": "0.15.0"
            }
            }
        ],
        "id": "YOUR_ID",
        "muted": false,
        "name": "",
        "stream_id": "mopidy"
        }
    ],
    "server": {
        "host": {
        "arch": "armv7l",
        "ip": "",
        "mac": "",
        "name": "YOUR_NAME",
        "os": "YOUR_OS"
        },
        "snapserver": {
        "controlProtocolVersion": 1,
        "name": "Snapserver",
        "protocolVersion": 1,
        "version": "0.15.0"
        }
    },
    "streams": [
        {
            "id": "mopidy",
            "meta": {
                "STREAM": "mopidy"
            },
            "status": "playing",
            "uri": {
                "fragment": "",
                "host": "",
                "path": "/tmp/snapfifo",
                "query": {
                "buffer_ms": "20",
                "codec": "pcm",
                "name": "mopidy",
                "sampleformat": "48000:16:2"
                },
                "raw": "pipe:////tmp/fifo?buffer_ms=20&codec=pcm&name=mopidy&sampleformat=48000:16:2",
                "scheme": "pipe"
            }
        }
    ]
}

stop()[source]#: Stop the plugin.

Set the volume of a connected client.

Parameters:

client – Client name or ID
volume – Absolute volume to set between 0 and 100
delta – Relative volume change in percentage (e.g. +10 or -10)
mute – Set to true or false if you want to toggle the muted status
host – Snapcast server (default: default configured host)
port – Snapcast server port (default: default configured port)

wait_stop(timeout=None)#: Wait until a stop event is received.

music.snapcast

Platypush documentation

music.snapcast#

Description#

Configuration#

Actions#

Module reference#

`music.snapcast`#