Bose-SoundTouch/docs/CLOUD-SHUTDOWN-GUIDE.md

Bose Cloud Shutdown: Survival Guide for SoundTouch

With Bose's announcement of discontinuing cloud support for SoundTouch devices in May 2026, this project provides the necessary tools to keep your speakers fully functional using a local emulation service.

This guide explains how to set up the soundtouch-service to run your devices independently of Bose's servers.

---

Supported Use Cases

1. Local Service Emulation: The service emulates Bose's BMX (Bose Media eXchange) and Marge services, which handle content registries, presets, recents, and software update checks.
2. Traffic Redirection: Tools are provided to redirect your speakers to this local service instead of *.bose.com.
3. Offline Operation: Once redirected, the speakers function without needing to reach Bose's servers.
4. Preset & Recent Management: Captures and stores presets and "recently played" items locally.

---

Setup Steps

To set up your SoundTouch system for local-only operation, follow these steps:

1. Install and Start the Service

Run the soundtouch-service on a machine that is always on (like a Raspberry Pi or a NAS) within your local network.

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

# Start the service (defaults to http://localhost:8000)
soundtouch-service

2. Access the Management UI

Open your web browser and navigate to the service's web interface: http://<your-server-ip>:8000/, e.g. http://localhost:8000/

Note: The service also supports a /web/ path for management.

3. Enable SSH on Your Speakers

To migrate your speakers, the service needs SSH access. You can enable it by:

1. Creating an empty file named remote_services on a USB stick.
2. Inserting the USB stick into the SoundTouch speaker's service port.
3. Rebooting the speaker. Once enabled, you can log in as root (no password).

4. Discover and Sync Device Data

The web interface handles the entire process in a guided flow across four tabs:

• Step 1: Devices: The service automatically scans for SoundTouch devices on your network. If a device is not found, you can manually add its IP address.
• Step 2: Data Sync: Select your device and click "Start Sync". This will automatically fetch your presets, recents, and configured sources from the speaker and store them in the local data/ directory.
• Step 3: Migration: Choose your redirection method (XML Recommended) and click "Confirm Migration & Reboot".
• Step 4: Settings: Configure global server URLs and proxy behavior (logging, redaction).

5. Verify Your Local Data

Once migrated, your speaker will use the data captured during the Sync step.

• The service stores data in the data/ directory, organized by device serial number (e.g., data/default/devices/<SERIAL>/).
• Automatic Capture: As you use the device (changing presets, playing new music), the service continues to "learn" and update your local files.

---

Comparison with other implementations (soundcork)

Our implementation (soundtouch-service) is largely compatible with the Python-based soundcork project but offers several advantages:

• Web UI: Integrated management interface for discovery and migration.
• Surgical Migration: Uses XML-based redirection by default, which is less invasive than /etc/hosts.
• Automated SSL: Handles Root CA injection automatically for secure communication.
• Proxy Support: Can proxy requests to original Bose servers while "learning" your configuration.

---

Alternative: DNS Redirection (No SSH)

If you prefer not to modify your speakers via SSH, you can use a local DNS server (like Pi-hole, AdGuard Home, or Unbound) to point the following domains to your local server's IP:

• bmx.bose.com
• streaming.bose.com
• updates.bose.com
• stats.bose.com
• content.api.bose.io

Note: DNS redirection for HTTPS services requires the speakers to trust your local service's SSL certificate. The SSH-based migration handles this automatically by injecting the CA.

---