Libsoundtouch’s documentation¶
This Python 2.7+/3.4+ library allows you to control Bose Soundtouch devices .
Features¶
- Discovery
- power on/power off
- play/pause
- next/previous track
- volume setting (mute/set volume/volume up/volume down)
- repeat one/all/off
- shuffle on/off
- select preset (bookmark)
- playback selected music
- play HTTP URL (not HTTPS)
- Multi room (zones)
- Websocket notifications
Usage¶
Installation¶
pip install libsoundtouch
Discovery¶
Soundtouch devices support mDNS discovery protocol.
from libsoundtouch import discover_devices
devices = discover_devices(timeout=2) # Default timeout is 5 seconds
for device in devices:
print(device.config.name + " - " + device.config.type)
Basic Usage¶
from libsoundtouch import soundtouch_device
from libsoundtouch.utils import Source, Type
device = soundtouch_device('192.168.1.1') # Manual configuration
device.power_on()
# Config object
print(device.config.name)
# Status object
# device.status() will do an HTTP request.
# Try to cache this value if needed.
status = device.status()
print(status.source)
print(status.artist+ " - "+ status.track)
device.pause()
device.next_track()
device.play()
# Media Playback
# device.play_media(source, location, account, media_type)
# account and media_type are optionals
# Radio
device.play_media(Source.INTERNET_RADIO, '4712') # Studio Brussel
# Spotify
spot_user_id = '' # Should be filled in with your Spotify userID
# This userID can be found by playing Spotify on the
# connected SoundTouch speaker, and calling
# device.status().content_item.source_account
device.play_media(Source.SPOTIFY,
'spotify:track:5J59VOgvclrhLDYUoH5OaW',
spot_user_id) # Bazart - Goud
# Local music (Windows media player, Itunes)
# Account ID can be found by playing local music on the
# connected Soundtouch speaker, and calling
# device.status().content_item.source_account
account_id = device.status().content_item.source_account
device.play_media(Source.LOCAL_MUSIC,
'album:1',
account_id,
Type.ALBUM)
# Play an HTTP URL (not HTTPS)
device.play_url('http://fqdn/file.mp3')
# Volume object
# device.volume() will do an HTTP request.
# Try to cache this value if needed.
volume = device.volume()
print(volume.actual)
print(volume.muted)
device.set_volume(30) # 0..100
# Presets object
# device.presets() will do an HTTP request.
# Try to cache this value if needed.
presets = device.presets()
print(presets[0].name)
print(presets[0].source)
# Play preset 0
device.select_preset(presets[0])
# ZoneStatus object
# device.zone_status() will do an HTTP request.
# Try to cache this value if needed.
zone_status = device.zone_status()
print(zone_status.master_id)
print(len(zone_status.slaves))
Multi-room¶
Soundtouch devices supports multi-room features called zones.
from libsoundtouch import soundtouch_device
master = soundtouch_device('192.168.18.1')
slave1 = soundtouch_device('192.168.18.2')
slave2 = soundtouch_device('192.168.18.3')
# Create a new zone
master.create_zone([slave1, slave2])
# Remove a slave
master.remove_zone_slave([slave2])
# Add a slave
master.add_zone_slave([slave2])
Websocket¶
Soundtouch devices support Websocket notifications in order to prevent pulling and to get immediate updates.
from libsoundtouch import soundtouch_device
import time
# Events listeners
# Volume updated
def volume_listener(volume):
print(volume.actual)
# Status updated
def status_listener(status):
print(status.track)
# Presets updated
def preset_listener(presets):
for preset in presets:
print(preset.name)
# Zone updated
def zone_status_listener(zone_status):
if zone_status:
print(zone_status.master_id)
else:
print('no Zone')
device = soundtouch_device('192.168.18.1')
device.add_volume_listener(volume_listener)
device.add_status_listener(status_listener)
device.add_presets_listener(preset_listener)
device.add_zone_status_listener(zone_status_listener)
# Start websocket thread. Not started by default
device.start_notification()
time.sleep(600) # Wait for events
API Documentation¶
If you are looking for information on a specific function, class, or method, this part of the documentation is for you.
Developer Interface¶
This part of the documentation covers all the interfaces of Libsoundtouch.
Main Interface¶
Classes¶
Bose Soundtouch Device.
-
class
libsoundtouch.device.SoundTouchDevice(host, port=8090, ws_port=8080, dlna_port=8091)[source]¶ Bose SoundTouch Device.
-
add_zone_slave(slaves)[source]¶ Add slave(s) to and existing zone (multi-room).
Zone must already exist and slaves array can not be empty.
Parameters: slaves – List of slaves. Can not be empty
-
config¶ Get config object.
-
create_zone(slaves)[source]¶ Create a zone (multi-room) on a master and play on specified slaves.
Parameters: slaves – List of slaves. Can not be empty
-
device_info_updated_listeners¶ Return Device Info Updated listeners.
-
dlna_port¶ Return DLNA port.
-
host¶ Host of the device.
-
play_media(source, location, source_acc=None, media_type=<Type.URI: 'uri'>)[source]¶ Start music playback from a chosen source.
Parameters: - source – Source from which to play. Elements of Source enum.
- location – A unique uri or identifier. Represents the requested music from the source.
- source_acc – Source account. Imperative for some sources. For Spotify, this can be found by playing Spotify on the connected SoundTouch speaker, and calling: device.status().content_item.source_account
- media_type – Type of the requested music. Typical values are: “uri”, “track”, “album”, “playlist”. This can be found in device.status().content_item.type
-
play_url(url)[source]¶ Start music playback from an HTTP URL.
Warning: HTTPS is not supported.
Parameters: url – HTTP URL to play.
-
port¶ Return API port of the device.
-
presets_updated_listeners¶ Return Presets Updated listeners.
-
remove_zone_slave(slaves)[source]¶ Remove slave(s) from and existing zone (multi-room).
Zone must already exist and slaves list can not be empty. Note: If removing last slave, the zone will be deleted and you’ll have to create a new one. You will not be able to add a new slave anymore.
Parameters: slaves – List of slaves to remove
-
status(refresh=True)[source]¶ Get status object.
Parameters: refresh – Force refresh, else return old data.
-
status_updated_listeners¶ Return Status Updated listeners.
-
volume(refresh=True)[source]¶ Get volume object.
Parameters: refresh – Force refresh, else return old data.
-
volume_updated_listeners¶ Return Volume Updated listeners.
-
ws_port¶ Return Web Socket port.
-
zone_status(refresh=True)[source]¶ Get Zone Status.
Parameters: refresh – Force refresh, else return old data.
-
zone_status_updated_listeners¶ Return Zone Status Updated listeners.
-
-
class
libsoundtouch.device.Config(xml_dom)[source]¶ Soundtouch device configuration.
-
account_uuid¶ Account UUID.
-
components¶ Components.
-
country_code¶ Country code.
-
device_id¶ Device ID.
-
device_ip¶ Ip.
-
mac_address¶ Mac address.
-
module_type¶ Return module type.
-
name¶ Device name.
-
networks¶ Network.
-
region_code¶ Region code.
-
type¶ Device type.
-
variant¶ Variant.
-
variant_mode¶ Variant mode.
-
-
class
libsoundtouch.device.Network(network_dom)[source]¶ Soundtouch network configuration.
-
ip_address¶ IP Address.
-
mac_address¶ Mac Address.
-
type¶ Type.
-
-
class
libsoundtouch.device.Component(component_dom)[source]¶ Soundtouch component.
-
category¶ Category.
-
serial_number¶ Return serial number.
-
software_version¶ Software version.
-
-
class
libsoundtouch.device.Status(xml_dom)[source]¶ Soundtouch device status.
-
album¶ Album name.
-
artist¶ Artist.
-
content_item¶ Content item.
-
description¶ Description.
-
duration¶ Duration.
-
image¶ Image URL.
-
play_status¶ Status.
-
position¶ Position.
-
repeat_setting¶ Repeat setting.
-
shuffle_setting¶ Shuffle setting.
-
source¶ Source.
-
station_location¶ Station location.
-
station_name¶ Station name.
-
stream_type¶ Stream type.
-
track¶ Track.
-
track_id¶ Track id.
-
-
class
libsoundtouch.device.ContentItem(xml_dom)[source]¶ Content item.
-
is_presetable¶ Return true if presetable.
-
location¶ Location.
-
name¶ Name.
-
source¶ Source.
-
source_account¶ Source account.
-
type¶ Type.
-
-
class
libsoundtouch.device.Volume(xml_dom)[source]¶ Volume configuration.
-
actual¶ Actual volume level.
-
muted¶ Return True if volume is muted.
-
target¶ Target volume level.
-
-
class
libsoundtouch.device.Preset(preset_dom)[source]¶ Preset.
-
is_presetable¶ Return True if is presetable.
-
location¶ Location.
-
name¶ Name.
-
preset_id¶ Id.
-
source¶ Source.
-
source_account¶ Source account.
-
source_xml¶ XML source.
-
type¶ Type.
-
Releases¶
Versions¶
Version 0.7.2¶
| Date: | 2017/07/05
|
|---|
Version 0.7.1¶
| Date: | 2017/07/05
|
|---|
Version 0.7.0¶
| Date: | 2017/07/05
|
|---|
Version 0.6.2¶
| Date: | 2017/06/21
|
|---|
Version 0.6.1¶
| Date: | 2017/06/19
|
|---|
Version 0.6.0¶
| Date: | 2017/06/17
|
|---|
Version 0.3.0¶
| Date: | 2017/04/09 |
|---|
- Allow playing local computer media
- Fix issue with non ASCII characters
About Libsoundtouch¶
This library has been created in order to create a component for the Home Assistant project but is totally independent.
Contributors¶
Thanks to all the wonderful folks who have contributed to Libsoundtouch:
- jeanregisser <https://github.com/jeanregisser> (Use enum-compat instead of enum34 directly)
- Tyzer34 <https://github.com/Tyzer34> (add play_media support)
- wanderor <https://github.com/wanderor> (add local computer media support)
- obadz <https://github.com/obadz> (add Bluetooth source)
