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#

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)

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

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)

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"
            }
        }
    ]
}

volume(client: str, volume: int | None = None, delta: int | None = None, mute: bool | None = None, host: str | None = None, port: int | None = None)[source]#

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)

Platypush documentation