mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-18 08:36:13 +00:00
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 <ip> setup migrate --method telnet --service-url http://<host>: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-<tool>-v<ver>-<os>-<arch>), 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) <noreply@anthropic.com>
This commit is contained in:
Tobias Gesellchen
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
8695816d36
commit
c3e3391db6
@@ -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 \`<os>-<arch>\` build matches your computer.
|
||||
|
||||
## Documentation
|
||||
|
||||
Full guides, setup walkthroughs, and troubleshooting: https://gesellix.github.io/Bose-SoundTouch/
|
||||
|
||||
@@ -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.
|
||||
|
||||
[](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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
title: "Analysis & Research"
|
||||
weight: 4
|
||||
weight: 5
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: "Architecture"
|
||||
weight: 5
|
||||
weight: 6
|
||||
---
|
||||
|
||||
Architecture notes and analyses:
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
title: "Concepts"
|
||||
weight: 3
|
||||
weight: 4
|
||||
---
|
||||
|
||||
@@ -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-<tool>-v<VERSION>-<os>-<arch>[.exe]
|
||||
```
|
||||
|
||||
Pick the `<os>-<arch>` suffix for your system:
|
||||
|
||||
| Your system | `<os>-<arch>` 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).
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 <speaker-ip> setup migrate --method telnet --service-url http://<aftertouch-host>: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://<aftertouch-host>: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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: "User Guides"
|
||||
weight: 1
|
||||
weight: 2
|
||||
sidebar:
|
||||
open: true
|
||||
---
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
title: "Technical Reference"
|
||||
weight: 2
|
||||
weight: 3
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user