SoundTouch Client ¶

The SoundTouchClient uses the underlying boseapi to communicate with a specified BOSE device. Warning: There are lots of functions that can be used to interact with the device. IT is recommended to read the docs before starting to use a client.

Interface ¶

class boseapi.client.SoundTouchClient(device: BoseDevice, errors: str = 'raise')¶

A simple client to interact with the BOSE WebAPI.

Note: This client is built to communicate with a BOSE device on port 8090, the standard WebAPI port.

The client uses an urllib3.PoolManager instance to delegate the HTTP-requests. Set a custom manager with the manage_traffic() method.

Like the BoseWebSocket, this client can be used in two ways: 1. create a client manually or 2. use the client within a _with_ statement. Additionally, this class implements a dict-like functionality. So, the loaded configuration can be accessed by typing: config = client[<config_name>]

Attributes:

device: BoseDevice: The device to interace with. Some configuration data stored here will be updated if specific methods were called in this client.
errors: str = ‘raise’: Specifies if the client should raise the exceptions returned by the BOSE device. Use ignore to ignore the errors (They will be given as the response object in a SoundTouchMessage).
manager: urllib3.PoolManager: The manager for HTTP requests to the device.
config_manager:: A dict to store the loaded configurations.

action(key_name: Key)¶

Tries to imitate a pressed key.

This method can be used to invoke different actions by using the different keys defined in boseapi.common.keys.

Arguments: key_name: keys

add_zone_slave(slaves: list) → SoundTouchMessage¶: Adds the given zone slaves to the device’s zone.

balance(refresh=True) → Balance¶

Queries the current balance config.

Arguments: refresh: bool = True

Returns: Balance A balance object storing whether it is available to be controlled, its min, max and default value plus the target and actual balance value.

bass(refresh=True) → Bass¶

Queries the current bass config.

Arguments: refresh: bool = True

Returns: Bass A bass object storing the actual and target bass.

bass_capabilities(refresh=True) → BassCapabilities¶

Queries the bass capabilities.

The returned object contains an attribute that states whether these capabilities are available on the target device.

Arguments: refresh: bool = True

Returns: BassCapabilities: An object storing whether bass capabilities are available on the target device.

capabilities(refresh=True) → Capabilities¶

Queries the device’s capabilities.

Note: The returned object has a dict-like implementation and individual capabilities can be accessed by typing: capabilities[‘cap_name’].

Arguments: refresh: bool = True

Returns: Capabilities A capabilities object storing a NetworkConfig object (read docs for information), some hardware capabilities and additional API capabilities (access through dict).

clock_config(refresh=True) → ClockConfig¶

Queries the current clock config.

Arguments: refresh: bool = True

Returns: ClockConfig An object storing the timezone info, if it can be enabled by a user, time format, offset minute, brightness level and the utc time value.

clock_time(refresh=True) → ClockTime¶

Queries the current clock time.

Arguments: refresh: bool = True

Returns: ClockConfig An object storing the current time in xml format. See the docs for ClockConfig for more information about what values are stored.

create_zone(zone: Zone) → SoundTouchMessage¶: Creates a multiroom zone.

dev_create_zone(master: BoseDevice, slaves: list) → Zone¶: Creates a new multiroom zone with the given devices.

dsp_mono(refresh=True) → DSPMonoStereo¶

Queries the current config for the digital signal processor.

Arguments: refresh: bool = True

Returns: DSPMonoStereo An object storing a value that indicates whether mono is enabled.

get(uri: SoundTouchUri) → SoundTouchMessage¶

Makes a GET request to retrieve a stored value.

Use this method when querying for specific nodes. All standard nodes are implemented by this class.

Arguments: uri: SoundTouchUri

Returns: SoundTouchMessage An object storing the request uri, optional a payload that has been sent and the response as an xml.etree.ElementTree.Element.

Raises: ConnectionError:

Example: message = client.get(nodes.volume)

get_property(uri: SoundTouchUri, class_type, refresh=True)¶

Returns a cached property mapped to the given URI.

This method refreshes the property if refresh is set to True.

Parameters:

uri (SoundTouchUri) – the property key
class_type (type) – the config class type
refresh (bool, optional) – whether the property should be refreshed, defaults to True

Returns:

the configuration

Return type:

instance of provided type

language(refresh=True) → SimpleConfig¶

Queries the current language.

Arguments: refresh: bool = True

Returns: SimpleConfig An object storing the system language identifier (usually a number).

listpresets(refresh=True) → PresetList¶

Lists all available presets.

Arguments: refresh: bool = True

Returns: PresetList See PresetList documentation for information about how to use this list object.

listsources(refresh=True) → SourceItemList¶

Lists all available sources.

Arguments: refresh: bool = True

Returns: SourceItemList See SourceItemList documentation for information about how to use this list object.

make_request(method: str, msg: SoundTouchMessage)¶

Performs a generic request by converting the response into the messag object.

Parameters:

method (str) – the preferred HTTP method
msg (SoundTouchMessage) – the altered message object

Raises:

InterruptedError – if an error occurs while requesting content

Returns:

the status code or allowed methods

Return type:

int | list

manage_traffic(manager: PoolManager)¶: Sets the request manager for this client.

media_servers(refresh=True) → MediaServerList¶

Queries all UPnP Media servers found by the BOSE device.

Arguments: refresh: bool = True

Returns: MediaServerList See MediaServerList documentation for information about how to use this list object.

mute()¶: Mute the device.

name(refresh=True) → SimpleConfig¶

Queries the current name and updates the device’s name if possible.

Arguments: refresh: bool = True

Returns: SimpleConfig A config object storing the queried name.

net_info(refresh=True) → NetworkInfo¶

Queries the current network info. (all available interfaces)

Arguments: refresh: bool = True

Returns: NetworkInfo See NetworkInfo documentation for information about how to use this list object.

net_stats(refresh=True) → NetworkStats¶

Queries the current network stats.

Arguments: refresh: bool = True

Returns: NetworkStats See NetworkStats documentation for information about how to use this list object.

options(uri: SoundTouchUri) → list¶

Makes an OPTIONS request and returns the list of available HTTP-Methods.

Use this method when testing whether a node can be accessed.

Arguments: uri: SoundTouchUri

Returns: list[str] A list storing all available HTTP-Methods.

Raises: ConnectionError:

Example: methods = client.options(nodes.volume)

pause()¶: Pause the current media playing.

play(item: ContentItem) → SoundTouchMessage¶: Plays the given ContentItem.

power()¶: Set power on/off.

power_management(refresh=True) → PowerManagement¶

Queries the current power management status.

Arguments: refresh: bool = True

Returns: PowerManagement An object storing the power state in if the battery is capable.

put(uri: SoundTouchUri, body) → SoundTouchMessage¶

Makes a POST request to apply a new value for the given node.

Use this method when setting some configuration related data. All standard operations where a POST request is necessary are implemented by this class.

Arguments: uri: SoundTouchUri

Returns: SoundTouchMessage An object storing the request uri, optional a payload that has been sent and the response as an xml.etree.ElementTree.Element.

Raises: ConnectionError:

Example: message = client.put(nodes.volume, ‘<volume>0</volume>’)

raise_error(element: Element)¶

Raises an error from an incoming message if possible

Parameters:: element (Element) – the element to inspect
Raises:: ConnectionError – if the given element represents an error element

refresh_config(uri: SoundTouchUri, class_type)¶

Refreshes the cached condiguration for the given URI.

Parameters:

uri (SoundTouchUri) – the configuration key
class_type (type) – the config type

Returns:

the updated cached information

Return type:

type

remove_zone_slave(slaves: list) → SoundTouchMessage¶: Removes the given zone slaves from the device’s zone.

request_token(refresh=True) → SimpleConfig¶

Requests a new token generated by the device.

Arguments: refresh: bool = True

Returns: SimpleConfig An object storing the requested token at config.attrib[‘value’].

resume()¶: Resume the current media playing.

select_content_item(item: ContentItem) → SoundTouchMessage¶: Selects the given ContentItem.

select_preset(preset: Preset) → SoundTouchMessage¶: Selects the given preset.

select_source(src: Source) → SoundTouchMessage¶: Selects a new input source.

set_bass(level: int) → SoundTouchMessage¶: Sets the device’s bass to the given value.

set_name(name: str) → SoundTouchMessage¶: Sets a new device name.

set_volume(level: int) → SoundTouchMessage¶: Sets the volume to the given level.

status(refresh=True) → Status¶

Queries the current playing status.

Arguments: refresh: bool = True

Returns: Status A status object storing the current media source, ContentItem, track, artist, album, preview image, duration, position, play status, shuffle and repeat setting, stream type, track ID, station description and the location of the station.

systemtimeout(refresh=True) → SystemTimeout¶

Queries whether power saving is enabled or not.

Arguments: refresh: bool = True

Returns: SystemTimeout An object storing whether power saving is enabled or not.

volume(refresh=True) → Volume¶

Queries the current volume config.

Arguments: refresh: bool = True

Returns: Volume A volume object storing the actual and target volume.

volume_down()¶: Lower the volume of the BOSE device by one.

volume_up()¶: Higher the volume of the BOSE device by one.

wifi_profile(refresh=True) → WirelessProfile¶

Queries the active wireless profile.

Arguments: refresh: bool = True

Returns: WirelessProfile An object storing the ssid of the active wifi profile.

zone_status(refresh=True) → Zone¶

Queries the current multiroom config.

Arguments: refresh: bool = True

Returns: Zone A zone object storing the master ip and device ID as well as the configured slaves as a list of ZoneSlaves.

Usage ¶

Some usage examples and behavior explaination:

from boseapi.all import *

device = new_device('127.0.0.1')

# use the client in a 'with'-statement
with boseapi.SoundTouchClient(device) as client:
  # refresh the volume config
  volume = client.volume()

  # This volume config can be accessed in two ways:
  # 1. use the nodes.volume object
  volume = client[boseapi.nodes.volume]
  # 2. type the uri path
  volume = client['volume']

  # Iterate over all stored configuration objects:
  for config in client:
    # handle them
    print(config)

  # basic functions: mute, pause/resume, volume up/down
  client.mute()
  client.pause()
  client.resume()
  client.volume_up()
  client.volume_down()

  # press defined keys with .action()
  client.action(Key.MUTE)

  # Play specific media
  item = ContentItem(src=Source.INTERNET_RADIO, location='4712')
  client.play(item)

  # Query and select presets. Returns a PresetList instance.
  presetList = client.listpresets()
  assert len(presetList) > 0
  client.select_preset(preseList[0])

  # Multiroom functionality
  master = device
  slave1 = new_device('127.0.0.2')
  slave2 = new_device('127.0.0.3')

  zone = client.dev_create_zone(master, [slave1, slave2])
  # Add and Remove actions:
  client.add_zone_slave([slave2])
  client.remve_zone_slave([slave1])

  # select different sources
  client.select_source(boseapi.source.BLUETOOTH)

SoundTouch Client¶

Interface¶

Usage¶

SoundTouch Client ¶

Interface ¶

Usage ¶