soundtouch

package module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 1, 2026 License: MIT Imports: 0 Imported by: 0

README

Bose SoundTouch API Client

A comprehensive Go library and CLI tool for controlling Bose SoundTouch devices via their Web API.

Go Reference Go Report Card

Note: This is an independent project based on the official Bose SoundTouch Web API documentation. Not affiliated with or endorsed by Bose Corporation.

Features

  • ✅ Complete API Coverage: All available SoundTouch Web API endpoints implemented
  • 🎵 Media Control: Play, pause, stop, volume, bass, balance, source selection
  • 🏠 Multiroom Support: Create and manage zones across multiple speakers
  • ⚡ Real-time Events: WebSocket connection for live device state monitoring
  • 🔍 Device Discovery: Automatic discovery via UPnP/SSDP and mDNS
  • 📻 Content Navigation: Browse and search TuneIn, Pandora, Spotify, local music
  • 🎙️ Station Management: Add and play radio stations without presets
  • 🖥️ CLI Tool: Comprehensive command-line interface
  • 🔒 Production Ready: Extensive testing with real SoundTouch hardware
  • 🌐 Cross-Platform: Windows, macOS, Linux support

Quick Start

Installation
Install CLI Tool
go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-cli@latest
Add Library to Your Project
go get github.com/gesellix/bose-soundtouch
CLI Usage
Discover Devices
# Find SoundTouch devices on your network
soundtouch-cli discover devices

Control a Device

# Basic device information
soundtouch-cli --host 192.168.1.100 info get

# Media controls
soundtouch-cli --host 192.168.1.100 play start
soundtouch-cli --host 192.168.1.100 volume set --level 50
soundtouch-cli --host 192.168.1.100 source select --source SPOTIFY

# Preset management
soundtouch-cli --host 192.168.1.100 preset list
soundtouch-cli --host 192.168.1.100 preset store-current --slot 1
soundtouch-cli --host 192.168.1.100 preset select --slot 1

# Browse and discover content
soundtouch-cli --host 192.168.1.100 browse tunein
soundtouch-cli --host 192.168.1.100 station search-tunein --query "jazz"
soundtouch-cli --host 192.168.1.100 station add --source TUNEIN --token <token> --name "Jazz Radio"

# Real-time monitoring
soundtouch-cli --host 192.168.1.100 events subscribe
Library Usage
Basic Control
package main

import (
    "fmt"
    "log"
    
    "github.com/gesellix/bose-soundtouch/pkg/client"
)

func main() {
    // Connect to your SoundTouch device
    c := client.NewClient(&client.Config{
        Host: "192.168.1.100",
        Port: 8090,
    })
    
    // Get device information
    info, err := c.GetDeviceInfo()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Device: %s\n", info.Name)
    
    // Control playback
    err = c.Play()
    if err != nil {
        log.Fatal(err)
    }
    
    // Set volume
    err = c.SetVolume(50)
    if err != nil {
        log.Fatal(err)
    }
}
Device Discovery
package main

import (
    "context"
    "fmt"
    "log"
    "time"
    
    "github.com/gesellix/bose-soundtouch/pkg/discovery"
)

func main() {
    // Discover SoundTouch devices
    service := discovery.NewService(5 * time.Second)
    devices, err := service.DiscoverDevices(context.Background())
    if err != nil {
        log.Fatal(err)
    }
    
    for _, device := range devices {
        fmt.Printf("Found: %s at %s:%d\n", 
            device.Name, device.Host, device.Port)
    }
}
Real-time Events
package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/gesellix/bose-soundtouch/pkg/client"
    "github.com/gesellix/bose-soundtouch/pkg/models"
)

func main() {
    c := client.NewClient(&client.Config{
        Host: "192.168.1.100",
        Port: 8090,
    })
    
    // Subscribe to device events
    events, err := c.SubscribeToEvents(context.Background())
    if err != nil {
        log.Fatal(err)
    }
    
    for event := range events {
        switch e := event.(type) {
        case *models.NowPlayingUpdated:
            fmt.Printf("Now playing: %s by %s\n", e.Track, e.Artist)
        case *models.VolumeUpdated:
            fmt.Printf("Volume changed to: %d\n", e.ActualVolume)
        case *models.ConnectionStateUpdated:
            fmt.Printf("Connection state: %s\n", e.State)
        }
    }
}
Preset Management
package main

import (
    "fmt"
    "log"
    
    "github.com/gesellix/bose-soundtouch/pkg/client"
    "github.com/gesellix/bose-soundtouch/pkg/models"
)

func main() {
    c := client.NewClient(&client.Config{
        Host: "192.168.1.100",
        Port: 8090,
    })
    
    // Get current presets
    presets, err := c.GetPresets()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Found %d presets\n", len(presets.Preset))
    
    // Store currently playing content as preset 1
    err = c.StoreCurrentAsPreset(1)
    if err != nil {
        log.Fatal(err)
    }
    
    // Store Spotify playlist as preset 2
    spotifyContent := &models.ContentItem{
        Source:        "SPOTIFY",
        Type:          "uri",
        Location:      "spotify:playlist:37i9dQZF1DXcBWIGoYBM5M",
        SourceAccount: "your_username",
        IsPresetable:  true,
        ItemName:      "Today's Top Hits",
    }
    err = c.StorePreset(2, spotifyContent)
    if err != nil {
        log.Fatal(err)
    }
    
    // Store radio station as preset 3
    radioContent := &models.ContentItem{
        Source:       "TUNEIN",
        Type:         "stationurl",
        Location:     "/v1/playbook/station/s33828",
        IsPresetable: true,
        ItemName:     "K-LOVE Radio",
    }
    err = c.StorePreset(3, radioContent)
    if err != nil {
        log.Fatal(err)
    }
    
    // Select preset 1
    err = c.SelectPreset(1)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println("Preset management complete!")
}
Multiroom Zones
package main

import (
    "log"
    
    "github.com/gesellix/bose-soundtouch/pkg/client"
    "github.com/gesellix/bose-soundtouch/pkg/models"
)

func main() {
    master := client.NewClient(&client.Config{
        Host: "192.168.1.100", // Master speaker
        Port: 8090,
    })
    
    // Create a multiroom zone
    zone := &models.Zone{
        Master: "192.168.1.100",
        Members: []models.ZoneMember{
            {IPAddress: "192.168.1.101"}, // Living room
            {IPAddress: "192.168.1.102"}, // Kitchen
        },
    }
    
    err := master.SetZone(zone)
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println("Multiroom zone created!")
}

Supported Devices

This library supports all Bose SoundTouch-compatible devices, including:

  • SoundTouch 10, 20, 30 series
  • SoundTouch Portable
  • Wave SoundTouch music system
  • SoundTouch-enabled Bose speakers

Tested Hardware:

  • ✅ SoundTouch 10
  • ✅ SoundTouch 20

API Coverage

Feature Status Description
Device Info ✅ Complete Device details, name, capabilities
Media Control ✅ Complete Play/pause/stop, track navigation
Volume & Audio ✅ Complete Volume, bass, balance control
Source Selection ✅ Complete Spotify, Bluetooth, AUX, etc.
Content Navigation ✅ Complete Browse music libraries, radio stations
Station Management ✅ Complete Search, add, remove stations
Preset Management ✅ Complete Store, select, remove presets
Real-time Events ✅ Complete WebSocket event streaming
Multiroom Zones ✅ Complete Zone creation and management
System Settings ✅ Complete Clock, display, network info
Advanced Audio ✅ Complete DSP controls, tone controls

API Limitations: None - all documented SoundTouch Web API functionality is implemented, including endpoints discovered via the comprehensive SoundTouch Plus Wiki.

Documentation

Development

Prerequisites
  • Go 1.25.6 or later
  • Optional: SoundTouch device for testing
Building from Source
# Clone the repository
git clone https://github.com/gesellix/bose-soundtouch.git
cd Bose-SoundTouch

# Install dependencies
go mod download

# Build CLI tool
make build

# Run tests
make test

# Install CLI locally
go install ./cmd/soundtouch-cli
Contributing

We welcome contributions! Please see our Contributing Guide for details on:

  • Setting up your development environment
  • Coding guidelines and best practices
  • Testing with real devices
  • Submitting pull requests

Examples

Check out the examples/ directory for more usage patterns:

  • Basic HTTP Client: Simple device control
  • Preset Management: Store and manage favorite content
  • Navigation & Stations: Browse content and manage radio stations
  • WebSocket Events: Real-time monitoring
  • Device Discovery: Finding devices on your network
  • Multiroom Management: Zone operations
  • Advanced Audio: DSP and tone controls

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This is an independent project based on the official Bose SoundTouch Web API documentation provided by Bose Corporation. It is not affiliated with, endorsed by, or supported by Bose Corporation. Use at your own risk.

SoundTouch is a trademark of Bose Corporation.

SoundTouch End of Life Notice

Important: Bose has announced that SoundTouch cloud support will end on May 6, 2026.

What will continue to work:

  • ✅ Local API control (this library's primary functionality)
  • ✅ Bluetooth, AirPlay, Spotify Connect, and AUX streaming
  • ✅ Remote control features (Play, Pause, Skip, Volume)
  • ✅ Multiroom grouping

What will stop working:

  • ❌ Cloud-based preset sync between devices and SoundTouch app
  • ❌ Browsing music services directly from the SoundTouch app
  • ❌ Cloud-based features and updates

What continues to work:

  • ✅ Local preset management via this API client (store, select, remove)
  • ✅ Direct content playback (stations, playlists, etc.)

This Go library will continue to work as it uses the local Web API for direct device control, which is unaffected by the cloud service discontinuation. The local preset management functionality implemented in this library (discovered through the SoundTouch Plus Wiki) provides an alternative to the cloud-based preset features that will be discontinued.

Community Alternatives: See the Related Projects section below for additional tools like SoundCork that provide cloud service alternatives and the SoundTouch Plus project that offers comprehensive Home Assistant integration.

SoundTouch Plus
SoundCork
  • Project: SoundCork - SoundTouch API Intercept
  • Description: Intercept API for Bose SoundTouch devices after cloud service discontinuation
  • Purpose: Provides a local alternative to cloud-based SoundTouch services post-sunset
  • Compatibility: Complements this Go library by extending functionality beyond the local device API

These projects form a comprehensive ecosystem for SoundTouch device management and provide alternatives to Bose's discontinued cloud services.

Support

Star this project ⭐ if you find it useful!

Documentation

Overview

Package soundtouch provides a comprehensive Go library and CLI tool for controlling Bose SoundTouch devices.

This library implements the complete Bose SoundTouch Web API, enabling programmatic control of SoundTouch speakers including playback control, volume management, source selection, multiroom zone management, and real-time event monitoring via WebSocket connections.

Quick Start

Install the library: 

go get github.com/gesellix/bose-soundtouch

Basic usage example: 

package main

import (
	"fmt"
	"log"

	"github.com/gesellix/bose-soundtouch/pkg/client"
)

func main() {
	// Create a client for your SoundTouch device
	config := &client.Config{
		Host: "192.168.1.100",
		Port: 8090,
	}
	client := client.NewClient(config)

	// Get device information
	info, err := client.GetInfo()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Device: %s\n", info.Name)

	// Control playback
	err = client.Play()
	if err != nil {
		log.Fatal(err)
	}

	// Set volume
	err = client.SetVolume(50)
	if err != nil {
		log.Fatal(err)
	}
}

Device Discovery

Automatically discover SoundTouch devices on your network: 

import "github.com/gesellix/bose-soundtouch/pkg/discovery"

// Discover devices using UPnP/SSDP
service := discovery.NewService(5*time.Second)
devices, err := service.DiscoverDevices(ctx)
if err != nil {
	log.Fatal(err)
}

for _, device := range devices {
	fmt.Printf("Found device: %s at %s\n", device.Name, device.Host)
}

Real-time Events

Monitor device state changes in real-time using WebSocket connections: 

// Subscribe to device events
events, err := client.SubscribeToEvents(ctx)
if err != nil {
	log.Fatal(err)
}

for event := range events {
	switch e := event.(type) {
	case *models.NowPlayingUpdated:
		fmt.Printf("Now playing: %s by %s\n", e.Track, e.Artist)
	case *models.VolumeUpdated:
		fmt.Printf("Volume changed to: %d\n", e.ActualVolume)
	}
}

Multiroom Zone Management

Create and manage multiroom zones: 

// Create a zone with multiple speakers
zone := &models.Zone{
	Master: "192.168.1.100",
	Members: []models.ZoneMember{
		{IPAddress: "192.168.1.101"},
		{IPAddress: "192.168.1.102"},
	},
}
err = client.SetZone(zone)

CLI Tool

The package includes a comprehensive CLI tool for device control: 

# Install the CLI
go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-cli@latest

# Discover devices
soundtouch-cli discover devices

# Control a device
soundtouch-cli --host 192.168.1.100 play start
soundtouch-cli --host 192.168.1.100 volume set --level 50
soundtouch-cli --host 192.168.1.100 source select --source SPOTIFY

Supported Features

  • ✅ Device Information & Capabilities
  • ✅ Playback Control (Play/Pause/Stop/Next/Previous)
  • ✅ Volume, Bass, and Balance Control
  • ✅ Source Selection (Spotify, Bluetooth, AUX, etc.)
  • ✅ Preset Management
  • ✅ Clock/Time Management
  • ✅ Network Information
  • ✅ Real-time WebSocket Events
  • ✅ Multiroom Zone Management
  • ✅ Device Discovery (UPnP/SSDP and mDNS)
  • ✅ Cross-platform Support (Windows, macOS, Linux)

Package Structure

  • client: HTTP client for SoundTouch Web API
  • discovery: Device discovery using UPnP/SSDP and mDNS
  • models: Data structures for API requests/responses
  • config: Configuration management
  • cmd/soundtouch-cli: Command-line interface tool

Hardware Compatibility

This library has been tested with real Bose SoundTouch hardware and supports all SoundTouch-compatible devices including:

  • SoundTouch 10, 20, 30 series
  • SoundTouch Portable
  • Wave SoundTouch music system
  • And other SoundTouch-enabled Bose speakers

Implementation Notes

This implementation is based on the official Bose SoundTouch Web API documentation and provides 90% coverage of all available endpoints. It is an independent project and is not affiliated with or endorsed by Bose Corporation.

For detailed API documentation, examples, and advanced usage patterns, visit: https://pkg.go.dev/github.com/gesellix/bose-soundtouch

Source Files

View all Source files

Directories

Path Synopsis
cmd
example-mdns command
Package main provides an example of discovering SoundTouch devices using mDNS.
 Package main provides an example of discovering SoundTouch devices using mDNS.
example-unified command
Package main provides an example of discovering SoundTouch devices using all three mechanisms.
 Package main provides an example of discovering SoundTouch devices using all three mechanisms.
example-upnp command
Package main provides an example of discovering SoundTouch devices using UPnP.
 Package main provides an example of discovering SoundTouch devices using UPnP.
mdns-scanner command
Package main provides a simple mDNS scanner to discover SoundTouch devices on the network.
 Package main provides a simple mDNS scanner to discover SoundTouch devices on the network.
soundtouch-cli command
Package main provides the soundtouch-cli balance control commands.
 Package main provides the soundtouch-cli balance control commands.
websocket-demo command
Package main provides a demonstration of WebSocket event handling for Bose SoundTouch devices.
 Package main provides a demonstration of WebSocket event handling for Bose SoundTouch devices.
examples
advanced-audio-controls command
Package main provides an example of using advanced audio controls.
 Package main provides an example of using advanced audio controls.
service-availability command
Package main demonstrates service availability checking for SoundTouch devices
 Package main demonstrates service availability checking for SoundTouch devices
zone-slave-operations command
Package main provides an example of using zone slave operations.
 Package main provides an example of using zone slave operations.
pkg
client
Package client provides a comprehensive HTTP client for controlling Bose SoundTouch devices.
 Package client provides a comprehensive HTTP client for controlling Bose SoundTouch devices.
config
Package config provides configuration management for the Bose SoundTouch Go library.
 Package config provides configuration management for the Bose SoundTouch Go library.
discovery
Package discovery provides device discovery functionality for Bose SoundTouch devices using mDNS and UPnP protocols.
 Package discovery provides device discovery functionality for Bose SoundTouch devices using mDNS and UPnP protocols.
models
Package models provides data structures and types for the Bose SoundTouch API.
 Package models provides data structures and types for the Bose SoundTouch API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.