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 AUX/Bluetooth inputs
- select preset (bookmark)
- playback selected music
- allow snapshot and restore playing content
- 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)
# Snapshot current playing
device.snapshot()
# Select AUX input
device.select_source_aux()
# Select Bluetooth input
device.select_source_bluetooth()
# Restore previous snapshot
device.restore()
# 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.
Releases¶
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)
- luca-angemi <https://github.com/luca-angemi> (Fix new firmware error)
- vanto <https://github.com/vanto> (Fix device names with UTF-8 characters)