soundtouch

package module
v0.71.2 Latest Latest
Warning

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

 Go to latest Published: May 7, 2026 License: MIT Imports: 0 Imported by: 0

README

Bose SoundTouch Toolkit

Go Reference Go Report Card

Independent project. Not affiliated with or endorsed by Bose Corporation.

Context: Cloud Shutdown

Bose is shutting down SoundTouch cloud services on May 6, 2026. After that, music service browsing, preset sync, and the official SoundTouch app stop working. This toolkit lets you keep your speakers fully functional.

See the Survival Guide for the full picture.

Tools

soundtouch-service — AfterTouch

A local server that replaces the Bose cloud ("AfterTouch"). Once your speaker is redirected to it, you have full control without any Bose cloud dependency. The built-in web UI at http://localhost:8000 handles all setup — no config files needed to get started.

Two scenarios:

Before shutdown — migrate your existing setup While the Bose cloud is still running, use soundtouch-backup to save your account data. The local service web UI then helps with the migration so your speaker keeps its presets and credentials.

After shutdown or factory reset — start fresh Create a local account, configure your speakers, and start using them immediately. No Bose infrastructure required.

Redirecting your speaker

The service needs a stable address on your local network (e.g. soundtouch.fritz.box or soundtouch.local). The speaker must then be redirected to resolve the Bose cloud hostnames to that address. Two supported methods:

Method How it works Notes
XML redirect Upload a config XML via the Web API Surgical; covers only registered endpoints; best for testing
DNS/DHCP Serve custom DNS on your network Covers all devices at once; requires port 53 and TLS

The web UI walks you through each method. DNS redirect requires HTTPS — the service manages its own CA certificate and the web UI guides you through trusting it on each speaker.

Note: A hosts-file method (direct SSH edits to /etc/hosts) also exists in the codebase but is deprecated and not exposed in the web UI.

Enabling SSH via USB stick

Some setup steps require SSH access to the speaker. Enable it once per device: create a file named remote_services on a FAT-formatted USB drive (the drive may need its bootable flag set — see SoundCork issue #172), and insert it while the speaker is powered on. After reboot, root SSH is available with no password.

See Device Initial Setup and Migration Guide for step-by-step instructions.

soundtouch-backup

Backs up your Bose cloud account (presets, paired devices, music sources) and each speaker's local state before the shutdown. Run soundtouch-backup all to capture everything in one step; it authenticates with the Bose cloud, then polls each paired speaker over the local network.

See the soundtouch-backup README for usage.

soundtouch-cli

Command-line control of any SoundTouch device: play/pause/volume, presets, source selection, multiroom zones, device discovery, and more. Works entirely over the local network — no cloud dependency. Well-suited for scripting and home automation.

See the CLI Reference for full usage.

soundtouch-web

A standalone web UI for device control — play, pause, volume, preset selection, real-time status — served from a local Go binary. Complements soundtouch-service when you want a dedicated device-control interface separate from the setup/admin UI.

See the soundtouch-web README for usage.

Go library

pkg/client provides a Go API for all SoundTouch device endpoints: media control, volume, presets, sources, zones, real-time WebSocket events, and device discovery. Use it to build your own integrations.

go get github.com/gesellix/bose-soundtouch

See the API Reference and pkg.go.dev for documentation.

Documentation

  • SoundCork (Deborah Kaplan et al.) — Python service interception; pioneered the cloud emulation approach this project builds on
  • SoundCork Stockholm App — Companion app for SoundCork
  • SoundTouch Plus (Todd Lucas) — Home Assistant integration; extensive undocumented API documentation
  • ÜberBöse API (Julius) — API research and advanced endpoint discovery
  • Bose SoundTouch Hook (Adrian Böckenkamp) — LD_PRELOAD hooking for reverse engineering device internals

Support

Star this project ⭐ if you find it useful!

License

MIT — see LICENSE.

SoundTouch is a trademark of Bose Corporation.

Documentation

Overview

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

This project 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.

It also provides a local service (`soundtouch-service`) that can emulate the Bose Cloud, allowing for offline control and enhanced debugging through HTTP interaction recording.

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

SoundTouch Service

The `soundtouch-service` provides several advanced features:

  • Bose Cloud Emulation: Allows speakers to work without an internet connection.
  • HTTP Interaction Recording: Captures all traffic as IntelliJ-compatible .http files.
  • Speaker Migration: Automated tools to redirect speakers to the local service.
  • Web Interface: A management dashboard for proxy settings and speaker setup.

Install the service: 

go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest

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

Supported Features

  • ✅ Device Information & Capabilities
  • ✅ Playback, Volume, Bass, and Balance Control
  • ✅ Source Selection & Preset Management
  • ✅ Real-time WebSocket Events
  • ✅ Multiroom Zone Management
  • ✅ Device Discovery (UPnP/SSDP and mDNS)
  • ✅ Local Cloud Emulation (soundtouch-service)
  • ✅ HTTP Traffic Recording & Sanitization
  • ✅ Automated Speaker Migration & Revert

Package Structure

  • client: HTTP client for SoundTouch Web API
  • discovery: Device discovery using UPnP/SSDP and mDNS
  • models: Data structures for API requests/responses
  • service: Core logic for the soundtouch-service (proxy, recording, setup)
  • cmd/soundtouch-cli: Command-line interface tool
  • cmd/soundtouch-service: Local cloud emulation service

Implementation Notes

This project is an independent effort to preserve the functionality of Bose SoundTouch devices and provide enhanced debugging and control capabilities. It 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
debug-consolidation command
Package main provides a debug tool for analyzing device consolidation and migration scenarios.
 Package main provides a debug tool for analyzing device consolidation and migration scenarios.
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.
favicon-gen command
Package main provides a utility to generate PNG and ICO favicons from SVG source files.
 Package main provides a utility to generate PNG and ICO favicons from SVG source files.
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.
mock-amazon command
Package main provides a mock Amazon LWA server for testing purposes.
 Package main provides a mock Amazon LWA server for testing purposes.
mock-spotify command
Package main provides a mock Spotify server for testing purposes.
 Package main provides a mock Spotify server for testing purposes.
soundtouch-backup command
Package main implements the soundtouch-backup tool for backing up Bose SoundTouch cloud account data and local speaker filesystem files.
 Package main implements the soundtouch-backup tool for backing up Bose SoundTouch cloud account data and local speaker filesystem files.
soundtouch-cli command
Package main provides the soundtouch-cli balance control commands.
 Package main provides the soundtouch-cli balance control commands.
soundtouch-service command
Package main provides the SoundTouch service daemon that acts as a proxy and management interface for Bose SoundTouch devices, providing Marge service emulation and device discovery.
 Package main provides the SoundTouch service daemon that acts as a proxy and management interface for Bose SoundTouch devices, providing Marge service emulation and device discovery.
soundtouch-web command
Package main provides a web UI for controlling Bose SoundTouch devices.
 Package main provides a web UI for controlling Bose SoundTouch devices.
soundtouch-web/handlers
Package handlers contains HTTP handlers for the SoundTouch web UI.
 Package handlers contains HTTP handlers for the SoundTouch web UI.
soundtouch-web/webtypes
Package webtypes contains type definitions for the SoundTouch web UI.
 Package webtypes contains type definitions for the SoundTouch web UI.
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.
Package main demonstrates the new recording filename format that includes date information.
 Package main demonstrates the new recording filename format that includes date information.
account-management command
Package main demonstrates music service account management functionality for Bose SoundTouch devices.
 Package main demonstrates music service account management functionality for Bose SoundTouch devices.
advanced-audio-controls command
Package main provides an example of using advanced audio controls.
 Package main provides an example of using advanced audio controls.
content-selection command
Package main demonstrates content selection functionality for Bose SoundTouch devices.
 Package main demonstrates content selection functionality for Bose SoundTouch devices.
introspect command
Package main demonstrates introspect functionality for Bose SoundTouch devices.
 Package main demonstrates introspect functionality for Bose SoundTouch devices.
recents command
Package main demonstrates recent content functionality for Bose SoundTouch devices.
 Package main demonstrates recent content functionality for Bose SoundTouch devices.
service-availability command
Package main demonstrates service availability checking for SoundTouch devices
 Package main demonstrates service availability checking for SoundTouch devices
service-demo command
Package main provides a demo client for the SoundTouch service API, demonstrating how to interact with devices and retrieve media information.
 Package main provides a demo client for the SoundTouch service API, demonstrating how to interact with devices and retrieve media information.
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 music service account management on Bose SoundTouch devices.
 Package models provides data structures and types for music service account management on Bose SoundTouch devices.
service/amazon
Package amazon provides Amazon Music (Login with Amazon) OAuth integration and token management for the SoundTouch service.
 Package amazon provides Amazon Music (Login with Amazon) OAuth integration and token management for the SoundTouch service.
service/bmx
Package bmx implements minimal helper calls to public TuneIn endpoints and wraps them into Bose-compatible response models.
 Package bmx implements minimal helper calls to public TuneIn endpoints and wraps them into Bose-compatible response models.
service/certmanager
Package certmanager provides tools for managing Root CAs and generating SSL certificates.
 Package certmanager provides tools for managing Root CAs and generating SSL certificates.
service/constants
Package constants defines file names, directories, and common values used by the service layer.
 Package constants defines file names, directories, and common values used by the service layer.
service/datastore
Package datastore provides a simple XML-based datastore for SoundTouch devices.
 Package datastore provides a simple XML-based datastore for SoundTouch devices.
service/handlers
Package handlers provides HTTP handlers for the SoundTouch service.
 Package handlers provides HTTP handlers for the SoundTouch service.
service/marge
Package marge provides XML generation and data management for the Marge service, which handles SoundTouch device configuration, presets, recents, and account management.
 Package marge provides XML generation and data management for the Marge service, which handles SoundTouch device configuration, presets, recents, and account management.
service/proxy
Package proxy provides a logging reverse proxy used for speaker traffic debugging.
 Package proxy provides a logging reverse proxy used for speaker traffic debugging.
service/setup
Package setup contains speaker migration and configuration helpers.
 Package setup contains speaker migration and configuration helpers.
service/spotify
Package spotify provides Spotify OAuth integration and token management for the SoundTouch service, ported from soundcork's Python implementation.
 Package spotify provides Spotify OAuth integration and token management for the SoundTouch service, ported from soundcork's Python implementation.
service/zeroconf
Package zeroconf implements the Spotify Connect ZeroConf DH key exchange protocol used to push OAuth credentials to SoundTouch speakers.
 Package zeroconf implements the Spotify Connect ZeroConf DH key exchange protocol used to push OAuth credentials to SoundTouch speakers.
ssh
Package ssh provides simple SSH operations for SoundTouch speakers.
 Package ssh provides simple SSH operations for SoundTouch speakers.
testutils/amazon
Package amazon provides shared handlers for mocking the Amazon LWA API.
 Package amazon provides shared handlers for mocking the Amazon LWA API.
testutils/spotify
Package spotify provides shared handlers for mocking the Spotify API.
 Package spotify provides shared handlers for mocking the Spotify API.
scripts
extract-log-interactions command
extract-ws command
http-diff command
tests
integration/mocks
Package mocks provides mock implementations for external services during testing.
 Package mocks provides mock implementations for external services during testing.

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.