soundtouch

package module
v0.110.2 Latest Latest
Warning

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

 Go to latest Published: Jun 6, 2026 License: MIT Imports: 0 Imported by: 0

README

AfterTouch

Bose SoundTouch Toolkit

Go Reference Go Report Card

Independent project. Not affiliated with, endorsed by, sponsored by, or otherwise connected to Bose Corporation. See Disclaimer for the full statement.

The Bose Cloud Has Shut Down

Bose shut down SoundTouch cloud services on May 6, 2026. Presets, music service browsing, and stereo pairing no longer work through Bose's infrastructure. AfterTouch restores all of these — no Bose infrastructure required.

See the Survival Guide for the full picture.

AfterTouch docs homepage

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.

Not sure which approach fits your situation? See the Deployment Overview — it compares running AfterTouch on a Raspberry Pi or other always-on host against running it directly on the SoundTouch speaker, with links to step-by-step walkthroughs for each path.

Getting started:

Already migrated before May 6 — your presets and credentials are preserved. AfterTouch picks up where the Bose cloud left off.

Starting fresh (or after a factory reset) — create a local account, configure your speakers, and start using them immediately.

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!

Contributing

Issues and pull requests welcome — code, documentation, bug reports, and feature ideas all land in the same place. By submitting a contribution you agree to license it under MIT. For significant changes please open an issue first to discuss the approach. See CONTRIBUTING.md for the full guide.

Support the project

If this toolkit kept a speaker (or several) of yours alive past the Bose cloud shutdown and you want to give back, GitHub Sponsors is open. No expectation — everything in this repo stays MIT regardless.

GitHub Sponsors

Disclaimer

This is an independent open-source project. Bose and SoundTouch are registered trademarks of Bose Corporation in the United States and other countries. This project is not affiliated with, endorsed by, sponsored by, or otherwise connected to Bose Corporation.

The toolkit exists solely to restore functionality of Bose SoundTouch speakers after the official cloud service shutdown on May 6, 2026. Reverse engineering for the sole purpose of interoperability is permitted under EU Directive 2009/24/EC, Article 6 ("Decompilation"), and comparable provisions in other jurisdictions.

The optional Stockholm frontend integration (STOCKHOLM_DIR) requires the user to supply the Stockholm web-app sources themselves; no Bose code is redistributed in this repository.

The software is provided AS IS, without warranty. Use at your own risk.

License

MIT — see LICENSE.

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.0.2.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.0.2.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.
dummy-speaker command
Command dummy-speaker runs an HTTP-only fake SoundTouch speaker and optionally registers it with a running soundtouch-service so the web UI has a device to display.
 Command dummy-speaker runs an HTTP-only fake SoundTouch speaker and optionally registers it with a running soundtouch-service so the web UI has a device to display.
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.
mock-tunein command
Package main provides a mock TuneIn (radiotime.com) server for testing.
 Package main provides a mock TuneIn (radiotime.com) server for testing.
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.
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 music service endpoints like TuneIn and RadioBrowser and wraps them into Bose-compatible response models.
 Package bmx implements minimal helper calls to public music service endpoints like TuneIn and RadioBrowser 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/ding
Package ding renders the AfterTouch "ding" signature sound — a two-chirp tone derived from the braille letters S and T that make up the AfterTouch logo.
 Package ding renders the AfterTouch "ding" signature sound — a two-chirp tone derived from the braille letters S and T that make up the AfterTouch logo.
service/export
Package export provides encryption helpers for the diagnostic export feature.
 Package export provides encryption helpers for the diagnostic export feature.
service/handlers
Package handlers — BMX registry / availability and shared helpers.
 Package handlers — BMX registry / availability and shared helpers.
service/health
Package health provides an extensible registry of operator-facing health checks for the AfterTouch service.
 Package health provides an extensible registry of operator-facing health checks for the AfterTouch service.
service/logbuf
Package logbuf provides a bounded, in-memory ring buffer for log lines.
 Package logbuf provides a bounded, in-memory ring buffer for log lines.
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/soundtouchweb
Package soundtouchweb contains HTTP handlers for the SoundTouch web UI.
 Package soundtouchweb contains HTTP handlers for the SoundTouch web UI.
service/soundtouchweb/webtypes
Package webtypes contains type definitions for the SoundTouch web UI.
 Package webtypes contains type definitions for the SoundTouch web UI.
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/stations
Package stations provides a provider-neutral surface for radio station search, navigation, and playback across TuneIn and Radio Browser.
 Package stations provides a provider-neutral surface for radio station search, navigation, and playback across TuneIn and Radio Browser.
service/stockholm
Package stockholm implements the Stockholm frontend backend: native bridge, HTTP proxy, static file serving, SSDP discovery, and state persistence.
 Package stockholm implements the Stockholm frontend backend: native bridge, HTTP proxy, static file serving, SSDP discovery, and state persistence.
service/testing/fakespeaker
Package fakespeaker runs a minimal HTTP server that impersonates the SoundTouch device's :8090 API surface with sanitized, embedded fixture data.
 Package fakespeaker runs a minimal HTTP server that impersonates the SoundTouch device's :8090 API surface with sanitized, embedded fixture data.
service/tts
Package tts turns text into speaker-playable audio for the local service.
 Package tts turns text into speaker-playable audio for the local service.
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.
speaker
Package speaker holds protocol-level constants for the Bose SoundTouch speaker's local API surface: the well-known HTTP port, the request paths exposed by every device, and the on-device file locations the migration flow needs to know about.
 Package speaker holds protocol-level constants for the Bose SoundTouch speaker's local API surface: the well-known HTTP port, the request paths exposed by every device, and the on-device file locations the migration flow needs to know about.
ssh
Package ssh provides simple SSH operations for SoundTouch speakers.
 Package ssh provides simple SSH operations for SoundTouch speakers.
telnet
Package telnet provides a minimal line-oriented client for the SoundTouch device's diagnostic shell on TCP port 17000.
 Package telnet provides a minimal line-oriented client for the SoundTouch device's diagnostic shell on TCP port 17000.
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.
testutils/tunein
Package tunein provides shared handlers for mocking the TuneIn (radiotime.com) upstream API, so integration tests for the BMX TuneIn endpoints do not depend on the live TuneIn service.
 Package tunein provides shared handlers for mocking the TuneIn (radiotime.com) upstream API, so integration tests for the BMX TuneIn endpoints do not depend on the live TuneIn service.
scripts
extract-log-interactions command
extract-ws command
gen-aftertouch-ding command
Offline generator for the AfterTouch "ding" WAV.
 Offline generator for the AfterTouch "ding" WAV.
http-diff command
screenshots command
Command screenshots drives a headless Chrome via chromedp to capture PNG screenshots of the soundtouch-service web UI for documentation.
 Command screenshots drives a headless Chrome via chromedp to capture PNG screenshots of the soundtouch-service web UI for documentation.
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.