Skip to content
Introduction
Technical Reference
SoundTouch Speaker Endpoint Documentation

SoundTouch Speaker Endpoint Documentation

SoundTouch Speaker Endpoint Documentation

This document describes the implementation of the /speaker endpoint for Bose SoundTouch devices, which enables Text-To-Speech (TTS) notifications and URL content playback.

Overview

The /speaker endpoint is used to play notification content on SoundTouch devices, including:

  • Text-To-Speech messages using Google TTS
  • Audio content from HTTP/HTTPS URLs
  • Notification beeps (via /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.

API Reference

POST /speaker

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>

GET /playNotification

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>

Go Client Library Usage

Text-To-Speech (TTS) 

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.0.2.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)
    }
}

URL Content Playback 

func main() {
    config := &client.Config{
        Host: "192.0.2.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)
    }
}

Custom PlayInfo 

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)
    }
}

Notification Beep 

func main() {
    client := client.NewClient(config)
    
    // Uses GET request (fixed in v2025.02+)
    err := client.PlayNotificationBeep()
    if err != nil {
        log.Fatal(err)
    }
}

CLI Usage

Text-To-Speech 

# Basic TTS (English)
soundtouch-cli speaker tts --text "Hello World" --app-key YOUR_KEY --host 192.0.2.100

# TTS with volume and language
soundtouch-cli speaker tts \
  --text "Bonjour le monde" \
  --app-key YOUR_KEY \
  --volume 70 \
  --language FR \
  --host 192.0.2.100

URL Content Playback 

# Basic URL playback
soundtouch-cli speaker url \
  --url "https://example.com/audio.mp3" \
  --app-key YOUR_KEY \
  --host 192.0.2.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.0.2.100

Notification Beep 

soundtouch-cli speaker beep --host 192.0.2.100

Help 

# 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

Supported Languages for TTS

The following language codes are supported for Google TTS:

CodeLanguage
ENEnglish
DEGerman
ESSpanish
FRFrench
ITItalian
NLDutch
PTPortuguese
RURussian
ZHChinese
JAJapanese
KOKorean
ARArabic
HIHindi
THThai

Behavior Notes

  1. Volume Control: If a volume is specified, the device will:

    • Switch to the specified volume for playback
    • Automatically restore the previous volume after playback completes
    • If volume is 0 or omitted, content plays at current volume

  2. Content Interruption:

    • Currently playing content is paused during notification playback
    • Original content resumes automatically after notification ends
    • If currently playing content is already a notification, you may get an error

  3. Multiroom Behavior:

    • If the device is a zone master, notifications play on all zone members
    • Volume changes affect all devices in the zone

  4. Now Playing Display:

    • Service name appears in the “artist” field
    • Message appears in the “album” field
    • Reason appears in the “track” field
    • Custom artwork can be included in URL-based content

Error Handling

Common errors and their meanings:

  • Device not found: Check host/port configuration
  • Endpoint not supported: Device doesn’t support /speaker endpoint (common with ST-300)
  • Invalid app key: App key is required for TTS and URL playback
  • Network timeout: Check device connectivity
  • Invalid URL: URL must be accessible and contain valid audio content

App Key Requirements

Both TTS and URL playback require an app_key parameter. This appears to be used for:

  • Request authentication/identification
  • Rate limiting
  • Service tracking

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.

Limitations

  1. Device Support: Limited to specific SoundTouch models (primarily ST-10 Series III)
  2. Audio Formats: Supported audio formats depend on device capabilities
  3. URL Requirements: URLs must be publicly accessible (no authentication)
  4. TTS Length: Very long TTS messages may be truncated
  5. Concurrent Playback: Cannot play multiple notifications simultaneously

Integration Examples

Home Automation 

// 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,
)

Development/Testing 

# Test connectivity
soundtouch-cli speaker beep --host 192.0.2.100

# Test TTS functionality  
soundtouch-cli speaker tts --text "Testing TTS functionality" --app-key test-key --host 192.0.2.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.0.2.100

Troubleshooting

  1. Command not found: Ensure you’re using a supported SoundTouch model
  2. No audio output: Check volume levels and device status
  3. TTS not working: Verify internet connectivity for Google TTS service
  4. URL content fails: Ensure URL is accessible and contains valid audio
  5. Volume not restored: May occur if device is powered off during playback

For more information, see the SoundTouch WebServices API documentation.

Last updated on
SoundTouch Device WebSocket API — Pairing & Operation FlowSource Selection Guide