soco.discovery module

This module contains methods for discovering Sonos devices on the network.

soco.discovery.discover(timeout=5, include_invisible=False, interface_addr=None, household_id='Sonos', allow_network_scan=False, **network_scan_kwargs)[source]

Discover Sonos zones on the local network.

Return a set of SoCo instances for each zone found. Include invisible zones (bridges and slave zones in stereo pairs if include_invisible is True. Will block for up to timeout seconds, after which return None if no zones found.

Note that the presence of a SoCo object in the returned set is not a guarantee that the associated Sonos player is currently contactable. This is because the set of SoCo objects is generated by interrogating the first discovered player to determine the current set of players, and this data can lag the actual state of the system, e.g., if a speaker has been recently switched off.

Parameters

  • timeout (int, optional) – block for this many seconds, at most. Defaults to 5.

  • include_invisible (bool, optional) – include invisible zones in the return set. Defaults to False.

  • interface_addr (str or None) – Discovery operates by sending UDP multicast datagrams. interface_addr is a string (dotted quad) representation of the network interface address to use as the source of the datagrams (i.e., it is a value for socket.IP_MULTICAST_IF). If None or not specified, the system default interface(s) for UDP multicast messages will be used. This is probably what you want to happen. Defaults to None.

  • household_id (str) – Supply a Sonos Household ID to restrict discovery to a specific household. Useful in multi-household networks. In the default case the first player to respond will be used.

  • allow_network_scan (bool, optional) – If normal discovery fails, fall back to a scan of the attached network(s) to detect Sonos devices.

  • **network_scan_kwargs – Arguments for the scan_network function. See its docstring for details.

Returns

a set of SoCo instances, one for each zone found, or else None.

Return type

set

soco.discovery.any_soco(allow_network_scan=False, **network_scan_kwargs)[source]

Return any visible soco device, for when it doesn’t matter which.

Try to obtain an existing instance, or use discover if necessary. Note that this assumes that the existing instance has not left the network.

Parameters

  • allow_network_scan (bool, optional) – If normal discovery fails, fall back to a scan of the attached network(s) to detect Sonos devices.

  • **network_scan_kwargs – Arguments for the scan_network function. See its docstring for details.

Returns

A SoCo instance (or subclass if config.SOCO_CLASS is set), or None if no instances are found.

Return type

SoCo

soco.discovery.by_name(name, allow_network_scan=False, **network_scan_kwargs)[source]

Return a device by name.

Parameters

  • name (str) – The name of the device to return.

  • allow_network_scan (bool, optional) – If normal discovery fails, fall back to a scan of the attached network(s) to detect Sonos devices.

  • **network_scan_kwargs – Arguments for the scan_network function. See its docstring for details.

Returns

A SoCo instance (or subclass if config.SOCO_CLASS is set), or None if no instances are found.

Return type

SoCo

soco.discovery.scan_network(include_invisible=False, multi_household=False, max_threads=256, scan_timeout=0.5, min_netmask=24, networks_to_scan=None)[source]

Scan all attached networks for Sonos devices.

This function scans the IPv4 networks to which this node is attached, searching for Sonos devices. Multiple parallel threads are used to scan IP addresses in parallel for faster discovery.

Public, loopback and link local IP ranges are excluded from the scan, and the scope of the search can be controlled by setting a minimum netmask.

Alternatively, a list of networks to scan can be provided.

This function is intended for use when the usual discovery function is not working, perhaps due to multicast problems on the network to which the SoCo host is attached. The function can also be used to find a complete list of speakers when there are multiple Sonos households present. For example, this is the case where there are ‘split’ S1/S2 Sonos systems on the network.

Note that this call may fail to find speakers present on the network, and this can be due to ARP cache misses and ARP requests that don’t complete within the timeout. The call can be retried with longer values for scan_timeout if necessary.

Note also that the presence of a SoCo object in the returned set is not a guarantee that the associated Sonos player is currently contactable. This is because the set of SoCo objects is partly generated by interrogating discovered players to determine the current set(s) of players, and this can lag the actual state of the system, e.g., if a speaker has been recently switched off.

Parameters

  • include_invisible (bool, optional) – Whether to include invisible Sonos devices in the set of devices returned.

  • multi_household (bool, optional) – Whether to find all the speakers on the network exhaustively. If set to False, discovery will stop as soon as at least one speaker is found. In the case of multiple households on the attached networks, this means that only the speakers from the first-discovered household will be returned. If set to True, discovery will proceed until all speakers, from all households, have been found.

  • max_threads (int, optional) – The maximum number of threads to use when scanning the network.

  • scan_timeout (float, optional) – The network timeout in seconds to use when checking each IP address for a Sonos device.

  • min_netmask (int, optional) – The minimum number of netmask bits. Used to constrain the network search space.

  • networks_to_scan (list, optional) – A list of IPv4 networks to search, each a str of form “192.168.0.1/24”. Only the specified networks will be searched. The ‘min_netmask’ option (if supplied) is ignored.

Returns

A set of SoCo instances, one for each zone found, or else None.

Return type

set

soco.discovery.scan_network_by_household_id(household_id, include_invisible=False, **network_scan_kwargs)[source]

Convenience function to find the zones in a specific Sonos household.

Parameters

  • household_id (str) – The Sonos household ID to search for. IDs take the form ‘Sonos_XXXXXXXXXXXXXXXXXXXXXXXXXX’.

  • include_invisible (bool, optional) – Whether to include invisible Sonos devices in the set of devices returned.

  • **network_scan_kwargs – Arguments for the scan_network function. See its docstring for details. (Note that the argument ‘multi_household’ is forced to True when this function is called.)

Returns

A set of SoCo instances, one for each zone found, or else None.

Return type

set

soco.discovery.scan_network_get_household_ids(**network_scan_kwargs)[source]

Convenience function to find the all Sonos households on the attached networks.

Parameters

**network_scan_kwargs – Arguments for the scan_network function. See its docstring for details. (Note that the argument ‘multi_household’ is forced to True when this function is called.)

Returns

A set of Sonos household IDs, each in the form of a str like ‘Sonos_XXXXXXXXXXXXXXXXXXXXXXXXXX’.

Return type

set

soco.discovery.scan_network_get_by_name(name, household_id=None, **network_scan_kwargs)[source]

Convenience function to use scan_network to find a zone by its name.

Note that if there are multiple zones with the same name, then only one of the zones will be returned. Optionally, the search can be constrained to a specific household.

Parameters

  • name (str) – The name of the zone to find.

  • household_id (str, optional) – Use this to find the zone in a specific Sonos household.

  • **network_scan_kwargs – Arguments for the scan_network function. See its docstring for details. (Note that the argument ‘multi_household’ is forced to True when this function is called.)

Returns

A SoCo instance representing the zone, or None if no matching zone is found. Only returns visible zones.

Return type

SoCo

soco.discovery.scan_network_any_soco(household_id=None, **network_scan_kwargs)[source]

Convenience function to use scan_network to find any zone, optionally specifying a Sonos household.

Parameters

  • household_id (str, optional) – Use this to find a zone in a specific Sonos household.

  • **network_scan_kwargs – Arguments for the scan_network function. See its docstring for details.

Returns

A SoCo instance representing the zone, or None if no zone is found (or no zone is found that matches a supplied household_id).

Return type

SoCo

soco.discovery.contactable(speakers)[source]

Find only contactable players in a set of SoCo objects.

This function checks a set of SoCo objects to ensure that each associated Sonos player is currently contactable. A new set is returned containing only contactable players.

If there are non-contactable players, the function return will be delayed until at least one network timeout has expired (several seconds). Contact attempts run in parallel threads to minimise delays.

Parameters

speakers (set) – A set of SoCo objects.

Returns

A set of SoCo objects, all of which have been confirmed to be currently contactable. An empty set is returned if no speakers are contactable.

Return type

set