Bose SoundTouch Toolkit Documentation

Bose shut down the SoundTouch cloud on 6 May 2026. This toolkit, AfterTouch, runs the missing service on a machine in your own home, so your speakers keep their presets, music browsing and stereo pairing.

🚀 Start here

I want my speakers working again

• Getting Started - the short route: run the service, migrate a speaker, get the preset buttons working
• Migration Guide - the full process, one step at a time
• What the shutdown broke - what stopped working, what still works without AfterTouch, and what AfterTouch restores
• Get your preset buttons working again - save stations, library folders and playlists to the six slots
• Troubleshooting - when a speaker will not appear, or a source is missing

I want to build on this

• Quick start: the Go client library - control a speaker from your own Go program
• API Endpoints - the service and speaker HTTP surface
• CLI Reference - every soundtouch-cli command

Running it day to day

• SoundTouch Service Guide - service operation and configuration
• Backup Tool - back up speaker data and, if you still have one, a cloud account export

📋 Essential Documentation

The documentation is organized into three main categories:

1. User Guides - For everyday users migrating and managing devices

2. Technical Reference - For developers and advanced configuration

3. Concept Documentation - For contributors and system architects

🗂 Documentation Structure

🗂 User Guides

Migration & Setup

• Complete Migration Guide - 📖 Main guide for migrating from Bose Cloud
• Cloud Shutdown Survival Guide - What the shutdown broke and what AfterTouch restores
• Migration & Safety Guide - Advanced migration strategies
• Initial Device Setup - First-time device configuration
• Raspberry Pi Setup - Installing on Raspberry Pi

Daily Management

• SoundTouch Service Guide - Service operation and maintenance
• Troubleshooting - Common issues and solutions
• HTTPS Setup - Secure connections
• Deployment Guide - Production deployments

Advanced Features

• MAC Address Mapping - Device identification
• CLI Reference - Command-line tools
• Backup Tool - Cloud account and speaker data backup
• IoT Implementation Guide - IoT integrations
• MQTT Integration Design - MQTT setup

📚 Technical Reference

API Documentation

• API Endpoints - REST API reference
• Spotify Account Addition - Technical requests for Spotify
• WebSocket Events - Real-time events
• Zone Management - Multi-room control
• Preset Management - Preset operations (the user guide is Get your preset buttons working again)

Analysis & Research

• Upstream URLs - Bose service endpoints
• Device Redirect Methods - Migration techniques
• IoT Configuration Analysis - Device configurations
• IoT Config Summary - Configuration summaries

Device Lifecycle & Network Independence

• Device Lifecycle and /power_on Enhancement - Complete analysis of device registration and network independence improvements
• /power_on Implementation Guide - Technical implementation details for enhanced device management

🏗 Concept Documentation

• Spotify Overview — mental model, Spotify Connect vs OAuth-intercept, DNS rewrite gotcha
• Spotify OAuth — flows and management endpoints
• Amazon Music OAuth — companion to Spotify OAuth; same protocol shape, different scopes
• Encrypted Export — .age-encrypted diagnostic bundles
• Request Recording — how the proxy captures live device traffic for parity testing

Older planning artefacts (“Enhanced State Management System”, “Upstream Service Simulation”) live under docs/archive/ — kept for the record, no longer current.

💡 Quick Reference

Common Tasks

• Migrate first device: Follow Migration Guide Step 5
• Check device health: Dashboard → Devices → [Device Name] → Health Status
• Backup configuration: Dashboard → Settings → Backup → Create Backup
• Add new device: Dashboard → Devices → Discover Devices → Register

Getting Help

• Issues & Bugs: GitHub Issues
• Questions & Discussion: GitHub Discussions
• Documentation: Check troubleshooting guides first
• Community: Share experiences and help others
• Direct chat (last resort): There’s a small Discord for the rare case where an email exchange or an issue/discussion thread needs real-time back-and-forth. It’s not a primary support channel: please start with Issues or Discussions. If a conversation genuinely needs it, ask in your thread and I’ll share an invite.

For a complete list of all documents, browse the sections in the sidebar.