From c3e3391db6a4babf5aeb4905c08c133385cc4adc Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Sat, 4 Jul 2026 15:54:46 +0200 Subject: [PATCH] docs: add Downloads page + telnet re-migration workaround for #493 Address the two docs follow-ups from #493 (radio sources not mounting after an in-place migration). Troubleshooting: the "Radio sources never activate after an in-place migration" entry now leads with the confirmed non-destructive fix, re-running migration via the telnet method so all four service URLs (incl. bmxRegistryUrl / statsServerUrl) land on the speaker's runtime: soundtouch-cli --host setup migrate --method telnet --service-url http://:8000 Factory reset is kept as the fallback for models without a reachable telnet port. The cause text is updated to the diagnosed BMX-registry explanation, and notes why pointing the service at http://bose:8000 with a server-side /etc/hosts entry does not help. Downloads: new top-level docs section (docs/content/docs/downloads/) structured by tool (service / player / cli / backup) x OS/arch, using the real release asset naming (soundtouch--v--), plus install-script, Docker, and go-install routes. Sibling section weights bumped so Downloads leads the sidebar. README, the release-notes template, and the key install guides now point here. Also fixes the stale, never-produced .tar.gz/.zip filenames in SELF-HOSTING.md. refs #493 Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/release.yml | 2 + README.md | 4 +- docs/content/docs/analysis/_index.md | 2 +- docs/content/docs/architecture/_index.md | 2 +- docs/content/docs/concepts/_index.md | 2 +- docs/content/docs/downloads/_index.md | 123 ++++++++++++++++++ .../docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md | 2 +- .../docs/guides/EXTERNAL-HOST-WALKTHROUGH.md | 6 +- docs/content/docs/guides/MIGRATION-GUIDE.md | 6 +- docs/content/docs/guides/RASPBERRY-PI.md | 3 + docs/content/docs/guides/SELF-HOSTING.md | 16 +-- docs/content/docs/guides/TROUBLESHOOTING.md | 22 +++- docs/content/docs/guides/_index.md | 2 +- docs/content/docs/reference/_index.md | 2 +- 14 files changed, 169 insertions(+), 25 deletions(-) create mode 100644 docs/content/docs/downloads/_index.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ed25150..982cd69 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -362,6 +362,8 @@ jobs: - **soundtouch-cli**: command-line control of any device: playback, presets, sources, multiroom zones, discovery, and migration. Good for scripting and home automation. - **soundtouch-backup**: back up your Bose cloud account and each speaker's local state. \`soundtouch-backup all\` captures everything in one step. + Not sure which file to grab? The [Downloads page](https://gesellix.github.io/Bose-SoundTouch/docs/downloads/) explains which tool you need and which \`-\` build matches your computer. + ## Documentation Full guides, setup walkthroughs, and troubleshooting: https://gesellix.github.io/Bose-SoundTouch/ diff --git a/README.md b/README.md index 5a22c6d..9a5c92d 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ 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](https://gesellix.github.io/Bose-SoundTouch/docs/guides/SURVIVAL-GUIDE/) for the full picture. +See the [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/SURVIVAL-GUIDE/) for the full picture, or jump straight to [Downloads](https://gesellix.github.io/Bose-SoundTouch/docs/downloads/) to get the tools. [![AfterTouch docs homepage](media/docs-homepage.png)](https://gesellix.github.io/Bose-SoundTouch/) @@ -66,7 +66,7 @@ See the [soundtouch-backup README](cmd/soundtouch-backup/README.md) for usage. 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](https://gesellix.github.io/Bose-SoundTouch/docs/guides/CLI-REFERENCE/) for full usage. +See the [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/docs/guides/CLI-REFERENCE/) for full usage, and the [Downloads page](https://gesellix.github.io/Bose-SoundTouch/docs/downloads/) to get the `soundtouch-cli` build for your OS. --- diff --git a/docs/content/docs/analysis/_index.md b/docs/content/docs/analysis/_index.md index 6d25dba..126b2c4 100644 --- a/docs/content/docs/analysis/_index.md +++ b/docs/content/docs/analysis/_index.md @@ -1,4 +1,4 @@ --- title: "Analysis & Research" -weight: 4 +weight: 5 --- diff --git a/docs/content/docs/architecture/_index.md b/docs/content/docs/architecture/_index.md index ee24f72..9340f28 100644 --- a/docs/content/docs/architecture/_index.md +++ b/docs/content/docs/architecture/_index.md @@ -1,6 +1,6 @@ --- title: "Architecture" -weight: 5 +weight: 6 --- Architecture notes and analyses: diff --git a/docs/content/docs/concepts/_index.md b/docs/content/docs/concepts/_index.md index 53b4d91..3fcf54b 100644 --- a/docs/content/docs/concepts/_index.md +++ b/docs/content/docs/concepts/_index.md @@ -1,4 +1,4 @@ --- title: "Concepts" -weight: 3 +weight: 4 --- diff --git a/docs/content/docs/downloads/_index.md b/docs/content/docs/downloads/_index.md new file mode 100644 index 0000000..c46e5cf --- /dev/null +++ b/docs/content/docs/downloads/_index.md @@ -0,0 +1,123 @@ +--- +title: "Downloads" +weight: 1 +sidebar: + open: true +--- + +# Downloads + +Everything AfterTouch ships is on the +**[GitHub releases page](https://github.com/gesellix/Bose-SoundTouch/releases/latest)**. +This page helps you pick the right file: choose **which tool** you need, +then **which build** matches your computer. + +## 1. Which tool do I need? + +AfterTouch is a small set of separate programs. Most people run one or +two of them. + +| Tool | What it does | You want this if… | +|----------------------|-----------------------------------------------------------------------------------------------|----------------------------------------------------------| +| `soundtouch-service` | The local cloud replacement ("AfterTouch"). Runs always-on and takes over from the Bose cloud. | You are migrating speakers off the Bose cloud. | +| `soundtouch-player` | A browser control panel (radio browsing, device control). | You want a web UI to browse radio and control speakers. | +| `soundtouch-cli` | Command-line control and setup (status, play, presets, groups, **migration**, …). | You want to script things, or run a migration by hand. | +| `soundtouch-backup` | Backs up your Bose cloud account and each speaker's local state. | You are preparing before a shutdown / factory reset. | + +> Running a migration from the command line (for example the telnet +> re-migration in the +> [troubleshooting guide](../guides/TROUBLESHOOTING.md#radio-sources-after-migration)) +> uses **`soundtouch-cli`**. + +## 2. Which build matches my computer? + +Release assets are named: + +``` +soundtouch--v--[.exe] +``` + +Pick the `-` suffix for your system: + +| Your system | `-` suffix | +|--------------------------------------|----------------------| +| Raspberry Pi (64-bit) / ARM64 Linux | `linux-arm64` | +| Raspberry Pi (32-bit) / ARMv7 | `linux-armv7` | +| Linux (64-bit PC) | `linux-amd64` | +| macOS (Apple Silicon: M1/M2/M3/…) | `darwin-arm64` | +| macOS (Intel) | `darwin-amd64` | +| Windows (64-bit) | `windows-amd64.exe` | +| FreeBSD (64-bit) | `freebsd-amd64` | + +**Example.** To control speakers from a Raspberry Pi 4, download the CLI +build `soundtouch-cli-vX.Y.Z-linux-arm64`. On an Apple Silicon Mac you +would take `soundtouch-cli-vX.Y.Z-darwin-arm64` instead. + +The download is a single executable, ready to run (no archive to extract). +Each asset ships with `.sha256` and `.sha512` checksum files, and every +release also has combined `checksums.sha256` / `checksums.sha512` if you +want to verify the download. + +> **macOS / Windows note:** because these binaries are not code-signed, +> the OS may warn on first launch (Gatekeeper on macOS, SmartScreen on +> Windows). Approve it in the security prompt, or use the Docker or +> install-script routes below. + +## 3. Other ways to install + +### Install scripts (Linux / Raspberry Pi) + +These download the latest release for you and set up a background service. + +- **Service** (`soundtouch-service`): + + ```bash + curl -fsSL -o install.sh \ + https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/raspberry-pi/install.sh + sudo bash install.sh + ``` + +- **Player** (`soundtouch-player`): + + ```bash + curl -fsSL -o install-player.sh \ + https://raw.githubusercontent.com/gesellix/Bose-SoundTouch/main/scripts/raspberry-pi/install-player.sh + sudo bash install-player.sh + ``` + +There is also an **on-device** installer that runs AfterTouch directly on +the speaker; see the +[On-Device Install Walkthrough](../guides/ON-DEVICE-INSTALL-WALKTHROUGH.md). + +### Docker + +```bash +# AfterTouch service +docker pull ghcr.io/gesellix/bose-soundtouch:latest + +# Web player +docker pull ghcr.io/gesellix/bose-soundtouch-player:latest +``` + +Both images are multi-arch (`linux/amd64`, `linux/arm64`, `linux/arm/v7`). +See the [Deployment Guide](../guides/DEPLOYMENT.md) for Docker Compose +examples. + +### Go toolchain + +If you have Go installed you can build from source: + +```bash +go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-cli@latest +go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest +go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-player@latest +go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-backup@latest +``` + +## 4. Not sure how to deploy? + +The [Deployment Overview](../guides/DEPLOYMENT-OVERVIEW.md) compares +running AfterTouch on a Raspberry Pi / always-on host against running it +directly on the speaker, with step-by-step walkthroughs for each path. +For the full migration story, start with the +[Migration Guide](../guides/MIGRATION-GUIDE.md). diff --git a/docs/content/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md b/docs/content/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md index 82d993d..0b74f07 100644 --- a/docs/content/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md +++ b/docs/content/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md @@ -160,7 +160,7 @@ migration must be driven from `soundtouch-cli` **running on your own machine on the same LAN as the speaker**. Download `soundtouch-cli` for your OS from the -[Releases page](https://github.com/gesellix/Bose-SoundTouch/releases). +[Downloads page](../downloads/_index.md). ### Check the migration plan first diff --git a/docs/content/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md b/docs/content/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md index d5a2fa0..0282086 100644 --- a/docs/content/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md +++ b/docs/content/docs/guides/EXTERNAL-HOST-WALKTHROUGH.md @@ -55,7 +55,7 @@ installer defaults to port 80, not 8000) — open it in a browser. ### Other Linux hosts (systemd) Download the binary for your architecture from the -[Releases page](https://github.com/gesellix/Bose-SoundTouch/releases), then +[Downloads page](../downloads/_index.md), then install it as a systemd service — see [DEPLOYMENT.md](DEPLOYMENT.md) for the unit file template. @@ -205,7 +205,7 @@ For configuration, service management, updates, and removal see the ### Installing soundtouch-player on other hosts Download the binary for your OS and architecture from the -[Releases page](https://github.com/gesellix/Bose-SoundTouch/releases) +[Downloads page](../downloads/_index.md) and run it directly: ```bash @@ -239,7 +239,7 @@ slot. ### Alternatively — storing presets via soundtouch-cli (any machine on the LAN) Download the CLI for your machine from the -[Releases page](https://github.com/gesellix/Bose-SoundTouch/releases), then: +[Downloads page](../downloads/_index.md), then: ```bash # Play a custom radio stream on the speaker diff --git a/docs/content/docs/guides/MIGRATION-GUIDE.md b/docs/content/docs/guides/MIGRATION-GUIDE.md index eea99c7..13c41d5 100644 --- a/docs/content/docs/guides/MIGRATION-GUIDE.md +++ b/docs/content/docs/guides/MIGRATION-GUIDE.md @@ -22,9 +22,9 @@ Choose the option that fits your setup. ### Download a pre-built binary (no Go required) -Download the latest release for your platform from the -[GitHub releases page](https://github.com/gesellix/Bose-SoundTouch/releases). -Unzip, make executable, and run: +Download the `soundtouch-service` build for your platform from the +[Downloads page](../downloads/_index.md) (it explains which file to pick). +Make it executable and run: ```bash # Linux / macOS example diff --git a/docs/content/docs/guides/RASPBERRY-PI.md b/docs/content/docs/guides/RASPBERRY-PI.md index dfa10bf..21e8363 100644 --- a/docs/content/docs/guides/RASPBERRY-PI.md +++ b/docs/content/docs/guides/RASPBERRY-PI.md @@ -17,6 +17,9 @@ Run without a version argument, they install the **latest release** (resolved from GitHub's `releases/latest` redirect); pass a tag to pin a specific version. Each installer has a matching uninstaller (`uninstall.sh`, `uninstall-player.sh`). +Prefer to grab a binary by hand, or need `soundtouch-cli` / `soundtouch-backup` +too? See the [Downloads page](../downloads/_index.md). + For a complete install-through-migration walkthrough see [EXTERNAL-HOST-WALKTHROUGH.md](EXTERNAL-HOST-WALKTHROUGH.md). Not sure whether to use a Pi or run AfterTouch on the speaker itself? See diff --git a/docs/content/docs/guides/SELF-HOSTING.md b/docs/content/docs/guides/SELF-HOSTING.md index 96e3e9a..ace0c28 100644 --- a/docs/content/docs/guides/SELF-HOSTING.md +++ b/docs/content/docs/guides/SELF-HOSTING.md @@ -21,18 +21,18 @@ Good choices: a Raspberry Pi, a NAS (like Synology or QNAP), an always-on PC or ## Step 1: Get the software -Go to the [AfterTouch releases page](https://github.com/gesellix/Bose-SoundTouch/releases) and download the latest release for your operating system: +See the **[Downloads page](../downloads/_index.md)** for the full list of builds and how to pick the right one for your system. You want the `soundtouch-service` tool; download the build whose suffix matches your computer: | Your system | File to download | |-----------------------|------------------------------------------| -| Raspberry Pi (64-bit) | `soundtouch-service_linux_arm64.tar.gz` | -| Raspberry Pi (32-bit) | `soundtouch-service_linux_arm.tar.gz` | -| Linux (64-bit PC) | `soundtouch-service_linux_amd64.tar.gz` | -| macOS (Apple Silicon) | `soundtouch-service_darwin_arm64.tar.gz` | -| macOS (Intel) | `soundtouch-service_darwin_amd64.tar.gz` | -| Windows | `soundtouch-service_windows_amd64.zip` | +| Raspberry Pi (64-bit) | `soundtouch-service-vX.Y.Z-linux-arm64` | +| Raspberry Pi (32-bit) | `soundtouch-service-vX.Y.Z-linux-armv7` | +| Linux (64-bit PC) | `soundtouch-service-vX.Y.Z-linux-amd64` | +| macOS (Apple Silicon) | `soundtouch-service-vX.Y.Z-darwin-arm64` | +| macOS (Intel) | `soundtouch-service-vX.Y.Z-darwin-amd64` | +| Windows | `soundtouch-service-vX.Y.Z-windows-amd64.exe` | -Extract the archive. You will find a single file called `soundtouch-service` (or `soundtouch-service.exe` on Windows). +(`X.Y.Z` is the current release version.) The download is a single ready-to-run executable called `soundtouch-service` (or `soundtouch-service.exe` on Windows) — no archive to extract. ### Alternative: Docker diff --git a/docs/content/docs/guides/TROUBLESHOOTING.md b/docs/content/docs/guides/TROUBLESHOOTING.md index 9734430..bd6a381 100644 --- a/docs/content/docs/guides/TROUBLESHOOTING.md +++ b/docs/content/docs/guides/TROUBLESHOOTING.md @@ -517,11 +517,27 @@ If `soundtouch-cli source content --source TUNEIN ...` returns `1005` on a reset **Cause:** -Not fully understood. After an in-place migration the firmware does not activate the radio source **types** in its runtime, even though the entries exist in the speaker's persisted `Sources.xml`. This is firmware behaviour and we have not confirmed the exact trigger. (If you hit this, an encrypted diagnostic report taken **before** you reset the speaker is very helpful, and now includes the speaker's on-device `Sources.xml`. See the "Getting More Help" section below.) +After some in-place migrations the speaker's **runtime** `bmxRegistryUrl` (and often `statsServerUrl`) are still pointing at the dead Bose cloud (`content.api.bose.io` / `events.api.bosecm.com`), even though the persisted config and `Sources.xml` look correct. Radio sources (TUNEIN, RADIO_BROWSER, LOCAL_INTERNET_RADIO, …) are published through the **BMX registry**, so while `bmxRegistryUrl` points at the dead cloud the speaker can't fetch them and they never mount. On some models a full reboot reconciles all four service URLs from the stored config; on others it does not. (If you hit this, an encrypted diagnostic report taken **before** you reset the speaker is very helpful, and now includes the speaker's on-device `Sources.xml`. See the "Getting More Help" section below.) -**Workaround (confirmed by users):** +**Workaround (preferred — non-destructive):** -Factory reset the speaker, then re-migrate it: +Re-run the migration with the **telnet** method, which writes all four service URLs directly onto the speaker's runtime. No factory reset, no DNS, no SSH: + +```bash +soundtouch-cli --host setup migrate --method telnet --service-url http://:8000 +``` + +Then reboot the speaker (or use "Refresh sources"). Afterwards the Migration tab's cross-check should show `bmxRegistryUrl` / `statsServerUrl` on AfterTouch, and the radio sources activate. + +Notes: + +- This needs the speaker's telnet diagnostic port (`17000`) to be reachable. Most SoundTouch models expose it; some hardened firmware builds do not, in which case use the factory-reset fallback below. +- It writes AfterTouch's address (`http://:8000`) **straight onto the speaker**, so there is no `bose:8000` hostname for the speaker to resolve. That is why pointing the service at `http://bose:8000` and adding a `bose` entry to your server's `/etc/hosts` does **not** help: the speaker is a separate device and never reads that file. If you prefer to redirect in the network instead of writing on the device, enable AfterTouch's built-in DNS (Settings) and have the speaker use AfterTouch as its resolver — see the FRITZ!Box + AdGuard guide. +- Get `soundtouch-cli` from the [Downloads page](../downloads/_index.md) if you don't already have it. + +**Workaround (fallback — factory reset):** + +If the telnet method isn't available for your model, factory reset the speaker, then re-migrate it: 1. Factory reset (on most models: hold `1` + `−` for ~10 seconds). 2. Reconnect the speaker to your network. diff --git a/docs/content/docs/guides/_index.md b/docs/content/docs/guides/_index.md index 43ec3df..7a84df6 100644 --- a/docs/content/docs/guides/_index.md +++ b/docs/content/docs/guides/_index.md @@ -1,6 +1,6 @@ --- title: "User Guides" -weight: 1 +weight: 2 sidebar: open: true --- diff --git a/docs/content/docs/reference/_index.md b/docs/content/docs/reference/_index.md index ddf62ea..3d50a35 100644 --- a/docs/content/docs/reference/_index.md +++ b/docs/content/docs/reference/_index.md @@ -1,4 +1,4 @@ --- title: "Technical Reference" -weight: 2 +weight: 3 ---