Documentation for controlling and preserving Bose SoundTouch devices
This document describes the implementation of the /speaker endpoint for Bose SoundTouch devices, which enables Text-To-Speech (TTS) notifications and URL content playback.
The /speaker endpoint is used to play notification content on SoundTouch devices, including:
/playNotification endpoint)Important: This functionality is primarily supported by ST-10 (Series III) speakers. ST-300 and other models may not support this endpoint despite it appearing in their supported URLs.
Plays notification content on the speaker.
Request Body:
<play_info>
<url>URL_TO_AUDIO_CONTENT</url>
<app_key>YOUR_APPLICATION_KEY</app_key>
<service>SERVICE_NAME</service>
<message>MESSAGE_DESCRIPTION</message>
<reason>REASON_OR_FILENAME</reason>
<volume>VOLUME_LEVEL</volume> <!-- Optional: 0-100, omit for current volume -->
</play_info>
Response:
<?xml version="1.0" encoding="UTF-8" ?>
<status>/speaker</status>
Plays a simple notification beep sound.
Important: This endpoint requires a GET request, not POST. Earlier versions of this client library incorrectly used POST and would fail with HTTP 400 status.
Response:
<?xml version="1.0" encoding="UTF-8" ?>
<status>/playNotification</status>
package main
import (
"log"
"github.com/gesellix/bose-soundtouch/pkg/client"
"github.com/gesellix/bose-soundtouch/pkg/models"
)
func main() {
config := &client.Config{
Host: "192.168.1.100",
Port: 8090,
}
client := client.NewClient(config)
// Play TTS at current volume (language code "EN", "DE", etc.)
err := client.PlayTTS("Hello, this is a test message", "YOUR_APP_KEY", "EN")
if err != nil {
log.Fatal(err)
}
// Play TTS at specific volume (70)
err = client.PlayTTS("Volume test message", "YOUR_APP_KEY", "EN", 70)
if err != nil {
log.Fatal(err)
}
}
func main() {
config := &client.Config{
Host: "192.168.1.100",
Port: 8090,
}
client := client.NewClient(config)
// Play audio from URL
err := client.PlayURL(
"https://example.com/audio.mp3",
"YOUR_APP_KEY",
"Music Service",
"Song Title",
"Artist Name",
50, // volume level
)
if err != nil {
log.Fatal(err)
}
}
func main() {
client := client.NewClient(config)
// Create custom play info
playInfo := models.NewPlayInfo(
"https://example.com/audio.mp3",
"YOUR_APP_KEY",
"Custom Service",
"Custom Message",
"Custom Reason",
).SetVolume(60)
err := client.PlayCustom(playInfo)
if err != nil {
log.Fatal(err)
}
}
func main() {
client := client.NewClient(config)
// Uses GET request (fixed in v2025.02+)
err := client.PlayNotificationBeep()
if err != nil {
log.Fatal(err)
}
}
# Basic TTS (English)
soundtouch-cli speaker tts --text "Hello World" --app-key YOUR_KEY --host 192.168.1.100
# TTS with volume and language
soundtouch-cli speaker tts \
--text "Bonjour le monde" \
--app-key YOUR_KEY \
--volume 70 \
--language FR \
--host 192.168.1.100
# Basic URL playback
soundtouch-cli speaker url \
--url "https://example.com/audio.mp3" \
--app-key YOUR_KEY \
--host 192.168.1.100
# URL playback with custom metadata
soundtouch-cli speaker url \
--url "https://example.com/song.mp3" \
--app-key YOUR_KEY \
--service "My Music Service" \
--message "Beautiful Song" \
--reason "Artist Name" \
--volume 60 \
--host 192.168.1.100
soundtouch-cli speaker beep --host 192.168.1.100
# General speaker help
soundtouch-cli speaker --help
# Detailed functionality help
soundtouch-cli speaker help
# Command-specific help
soundtouch-cli speaker tts --help
soundtouch-cli speaker url --help
The following language codes are supported for Google TTS:
| Code | Language |
|---|---|
| EN | English |
| DE | German |
| ES | Spanish |
| FR | French |
| IT | Italian |
| NL | Dutch |
| PT | Portuguese |
| RU | Russian |
| ZH | Chinese |
| JA | Japanese |
| KO | Korean |
| AR | Arabic |
| HI | Hindi |
| TH | Thai |
Common errors and their meanings:
/speaker endpoint (common with ST-300)Both TTS and URL playback require an app_key parameter. This appears to be used for:
You’ll need to provide your own application key. The format and generation method for valid app keys is not documented in the official API.
// Doorbell notification
client.PlayTTS("Someone is at the front door", "home-automation-key", "EN", 80)
// Security alert
client.PlayURL(
"https://myserver.com/alerts/security-breach.mp3",
"security-system-key",
"Security System",
"Alert",
"Motion detected in restricted area",
100,
)
# Test connectivity
soundtouch-cli speaker beep --host 192.168.1.100
# Test TTS functionality
soundtouch-cli speaker tts --text "Testing TTS functionality" --app-key test-key --host 192.168.1.100
# Test URL playback
soundtouch-cli speaker url --url "https://www.soundjay.com/misc/sounds/bell-ringing-05.wav" --app-key test-key --host 192.168.1.100
For more information, see the SoundTouch WebServices API documentation.