The site sets disablePathToLower, so published URLs keep the source
filename's case, but the README link was lowercased and 404'd.
The walkthrough link was wrong in a second way: it used ../../reference/
with no extension, while cross-document links from guides/ resolve as
../reference/NAME.md.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
On-device installs were only reachable through an SSH tunnel, and the
docs blamed it on the service binding loopback-only. That was wrong.
Some SoundTouch chassis carry a BCO ("SMSC") Wi-Fi/Bluetooth
co-processor, and inbound LAN traffic reaches the main Linux SoC only
for a fixed set of Bose's own service ports, a list that appears to be
compiled into the co-processor firmware. AfterTouch's :8000 was never
part of that design, so connections never arrive at the SoC at all.
Confirmed on an ST20: a port sweep from a LAN client showed Bose's
:82/:8080/:8090/:8091/:8200/:17000 all answering while :8000 failed,
and tcpdump on the speaker's own eth0 recorded zero packets for it.
Ruled out along the way: iptables (empty), nft/ebtables (absent), the
router, Wi-Fi isolation, and the binding itself (0.0.0.0 is correct).
The init script now redirects one of the relayed ports to AfterTouch,
so http://<speaker-ip>:17008 works with no tunnel. 17008 is Bose's
software-update listener, whose cloud no longer exists. Only external
traffic is matched, so anything on the speaker still reaches :8000 as
before. Auto-enabled only where has-bco reports the co-processor, and
configurable via AFTERTOUCH_LAN_PORT (auto/none/port) in
aftertouch.conf. The rule is re-applied on every start and removed on
stop and uninstall, so it needs no watchdog; unlike prior art it is not
pinned to the LAN IP, so it also survives DHCP changes.
Credit for the REDIRECT technique goes to the STR / SoundTouch Reborn
project, which documented and shipped it first.
Also de-hardcodes the service port, which was baked independently into
the daemon args, the readiness poll and status, and makes install.sh
print the speaker's real address instead of a <your-device-ip>
placeholder it never filled in.
Adds a model support matrix, since the repo had no per-model
compatibility record and this behaviour is entirely chassis-dependent.
Only the verified ST20 row is filled in; everything else is marked
unknown rather than inferred.
Verified on hardware: auto-detection, idempotency across restarts,
teardown and restore, persistence across a full reboot, and LAN access
returning the service's health JSON.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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>
soundtouch-web was a transitional alias of soundtouch-player. Stop
building and publishing it everywhere, and refresh the release notes
while at it:
- release.yml: remove the soundtouch-web binary, its individual and
combined checksums, and its release assets (EXPECTED_COUNT 35 -> 28);
drop the ghcr.io/...-web Docker image steps. Also slim the
workflow_dispatch release notes to an accurate AfterTouch header plus
GitHub's auto-generated changelog, with the bare tag as the title.
- Dockerfile: drop the soundtouch-web image stage.
- Makefile: remove WEB_NAME and the build-web target (and its use in
build/install).
- Delete scripts/raspberry-pi/install-web.sh (it fetched a release asset
that is no longer published) and point the docs at install-player.sh.
- Correct README, CLAUDE.md, and main.go wording that claimed the alias
was still published.
The runtime notice for a binary still run under the soundtouch-web name
is kept, so anyone who renamed the binary is nudged to soundtouch-player.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The web player is intrinsically LAN-resident: it reaches speakers directly
and only delegates cloud-only features (e.g. TTS) to a possibly-remote
AfterTouch service via --service-url. That is exactly what a cloud-hosted
soundtouch-service cannot do, so the standalone player binary stays useful
and is not being deprecated. Rename it to state its purpose, with a
transition window so existing downloads keep working.
- cmd/soundtouch-web -> cmd/soundtouch-player; CLI name is now
soundtouch-player. When the binary is invoked under its old name it prints
a one-line rename notice (filepath.Base(os.Args[0])).
- Build/release both names from the same source: Makefile (build-player +
build-web alias, dev-player* targets), Dockerfile (soundtouch-player image
+ transitional soundtouch-web image), release.yml and ci.yml (player +
web artifacts, checksums, Docker images; release notes announce the
rename). The soundtouch-web binary, image, and install script remain a
transitional alias to be dropped in a future release (which will break
stale fetch scripts and nudge users to the release notes).
- scripts/raspberry-pi/install-player.sh is canonical; install-web.sh keeps
working but warns.
- Sweep docs, code comments, user-facing strings, and assets
(soundtouch-web-ui.png, soundtouch-web-tunein.png, soundtouch-web-roadmap.md)
to soundtouch-player; README documents the rename and why the player
remains separate from the embedded /app.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The links used /guides/ and /reference/ directly, missing the
/docs/ sub-path that Hugo places all content under. They also
had a .html suffix which Hugo's clean URL mode does not produce.
Fix: /Bose-SoundTouch/guides/FOO.html → /Bose-SoundTouch/docs/guides/FOO/
/Bose-SoundTouch/reference/FOO.html → /Bose-SoundTouch/docs/reference/FOO/
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Extend image ignorePattern in markdown-link-check.json to cover all
/images/*.png (covers ui-settings, ui-devices, ui-sync, ui-migration,
speaker-ap-wifi-setup that live under docs/static/images/ but are
referenced as absolute /images/ paths in Markdown)
- Fix appendix cross-section links: add ../ prefix to guides/, reference/,
and analysis/ paths in PRESET-QUICKSTART, SOUNDTOUCH-SERVICE-ANNOUNCEMENT,
CONTENT-SELECTION-IMPLEMENTATION, DEVICE-LOGGING, NAVIGATION-GUIDE,
PARITY-SOUNDCORK, and CLAUDE.md
- Convert ../examples/* relative links in appendix to GitHub URLs (the
examples/ dir is at repo root, not under docs/content/)
- Fix CLAUDE.md in appendix: archive/PLAN.md → ../../../archive/PLAN.md;
remove dead PDF link
- Fix TROUBLESHOOTING.md: ../DEVICE-LOGGING.md → ../appendix/DEVICE-LOGGING.md
- Fix CAPTURE-DEVICE-PAIRING.md: ../DEVICE-SETUP.md → ../appendix/DEVICE-SETUP.md
- Fix RASPBERRY-PI.md: remove accidental ../ prefix from GitHub URL
- Fix CONTRIBUTING.md: update docs/reference/ and docs/PROJECT-PATTERNS.md
to their new paths under docs/content/docs/
- Fix README.md: update deployment overview link to new path
- Fix BASS-CONTROLS.md and SOURCE-SELECTION.md: convert ../../pkg/models/
relative links to GitHub URLs
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Bose shut down SoundTouch cloud services on 2026-05-06. Update the three
main user-facing docs to reflect that the shutdown has happened:
- README.md: rename section, rewrite opening paragraph, reframe the two
getting-started scenarios as 'already migrated' vs 'starting fresh'.
- SURVIVAL-GUIDE.md: past-tense title and opening; remove duplicate
Scenario B heading (copy-paste leftover from earlier edit); remove the
table of redirect methods and TLS note that belonged to the deleted
pre-shutdown Scenario B stub.
- MIGRATION-GUIDE.md: remove the 'cloud is still running' note from the
Sync step; fix the post-migration backup blurb to reference
soundtouch-backup rather than a non-existent Step 4 tar.gz.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Problem: the existing docs gave no clear path for non-technical users.
- GETTING-STARTED.md is a Go library developer guide
- RASPBERRY-PI.md stops after the service is running (no migration or preset steps)
- DEVICE-LOCAL-INSTALL.md is an architectural analysis that confused installation intent
- No single page helped a user choose between external-host vs on-device
Changes:
- docs/DEVICE-LOCAL-INSTALL.md → docs/architecture/DEVICE-LOCAL-INSTALL.md
Move the planning/architecture doc out of the user-visible guides root;
add a redirect banner pointing to the user guides
- docs/guides/DEPLOYMENT-OVERVIEW.md (new)
Navigation landing page: comparison table (external host vs on-device),
links to user-friendly walkthrough + technical reference for each scenario
- docs/guides/EXTERNAL-HOST-WALKTHROUGH.md (new)
Step-by-step for Raspberry Pi / any always-on host: install, discover
speaker, run migration wizard, Health QuickFix, verify pairing, set
presets via UI or CLI — the post-install steps that RASPBERRY-PI.md
did not cover
- docs/guides/RASPBERRY-PI.md: cross-link to full walkthrough and overview
- README.md: replace the one-liner "see On-Device Installer" with a
pointer to the Deployment Overview so both paths are equally visible
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Adds new favicon-braille.svg logo file for AfterTouch branding
- Updates README.md to reference the new braille-style logo
- Establishes visual identity for the project
Two user-facing additions modelled on the streborn project's README:
- **Disclaimer section in README.** Stronger Bose-trademark clause,
explicit "not affiliated, endorsed, sponsored, or connected"
statement, and the EU 2009/24/EC Art. 6 interoperability clause
with a stable EUR-Lex hyperlink. Adds a Stockholm-specific
sentence: users supply the Stockholm web-app sources themselves,
no Bose code is redistributed in this repo.
- **Ways to Contribute / Support the project in README and
CONTRIBUTING.** Itemises the contribution categories users
actually have (code, docs, bug reports, donations) and adds the
GitHub Sponsors badge for gesellix. Sponsorship is explicitly
optional and licensing-neutral.
The thin "Not affiliated" line at the top of the README now points at
the full Disclaimer section rather than carrying the whole statement.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace the placeholder MIGRATION-GUIDE.md (which had a "planned to be"
header, a nonexistent install.sh reference, and 9 broken screenshot links)
with a complete, image-free step-by-step walkthrough covering all 6 steps:
install, configure URL, enable SSH via USB stick, discover/sync, migrate
(XML or DNS/DHCP), and verify.
Add the Migration Guide to the README docs section and link to it from
the Survival Guide.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Rewrite README.md to be concise and tool-focused (no code snippets),
clearly presenting all five tools and their use cases. Expand the
soundtouch-service section to cover both user scenarios and redirect
method trade-offs.
Rewrite SURVIVAL-GUIDE.md around the same two scenarios with step-by-step
instructions. Remove deprecated hosts-file method from all user-facing
docs; update MIGRATION-SAFETY.md, HTTPS-SETUP.md, and SOUNDTOUCH-SERVICE.md
to reflect only the two supported methods (XML redirect and DNS/DHCP).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Implements the ability to mirror local requests to the official Bose
Cloud in the background, allowing for real-time comparison and parity
analysis between the emulated service and the original backend.
Core Changes:
- Implement `MirrorMiddleware` for asynchronous and synchronous mirroring.
- Add `Parity Logger` to detect discrepancies in status, headers, and body.
- Implement storage for parity mismatches in `data/parity_mismatches/`.
- Add `Internal Paths` configuration to exclude management traffic from logs.
Web UI & API:
- Add "Parity & Mirroring" tab to the Web UI for discrepancy analysis.
- Integrated "Internal Paths" configuration in Settings.
- Add "mirror" category filter to the Interactions UI.
- Implement endpoints for listing and clearing parity mismatches.
Infrastructure & Tools:
- Extend `setup.Manager` with `HTTPGet` override for reliable testing.
- Add CLI flags `--mirror-enabled`, `--mirror-endpoints`, and `--internal-paths`.
- Update `datastore.Settings` to persist mirroring and internal path configurations.
Tests:
- Add `pkg/service/handlers/mirror_test.go` for middleware verification.
- Update `TestProxySettingsAPI` and `TestRecordMiddleware` for new settings.
- Refactor `TestMigrationAndCA` to use mocked network calls (30x speedup).
This implementation follows the reference from soundcork pull request #158. It adds RADIO_BROWSER to the known providers and includes the service configuration in bmx_services.json. Documentation has also been added to explain how to use the RadioBrowser feature. Credits to @gmuth (https://github.com/gmuth) for the original idea and implementation in soundcork. Reference: https://github.com/deborahgu/soundcork/pull/158
## SoundTouch Service Documentation
### Enhanced README.md
- Added detailed SoundTouch service feature overview and capabilities
- Comprehensive service installation, configuration, and usage guide
- Device migration examples and service endpoint documentation
- Web UI feature description and management interface guide
### Updated docs/SOUNDTOUCH-SERVICE.md
- Complete service architecture overview (BMX, Marge, proxy services)
- Step-by-step device migration guide with troubleshooting
- Full API reference with endpoint documentation and examples
- Web interface feature guide and usage instructions
- Data management, backup strategies, and maintenance procedures
- Advanced usage examples and integration patterns
- Security considerations and performance tuning guide
### New docs/SOUNDTOUCH-SERVICE-ANNOUNCEMENT.md
- Feature announcement and implementation overview
- Detailed comparison with community implementations
- Use cases, future roadmap, and contribution guidelines
## Community Credits & Attribution
### SoundCork Recognition
- Acknowledged as primary architectural inspiration and foundation
- Credited for pioneering service interception and emulation approach
- Recognized for BMX/Marge endpoint discovery and migration strategies
- Noted as providing Python implementation reference
### ÜberBöse API Recognition
- Credited for advanced API endpoint insights and research
- Acknowledged for contributing to implementation completeness
- Recognized for extended protocol documentation
### SoundTouch Plus Recognition
- Credited for comprehensive API documentation via wiki
- Acknowledged for real-world usage patterns and endpoint discovery
- Recognized for enabling preset management feature development
This documentation update ensures proper attribution to the excellent community
projects that inspired our Go implementation while providing comprehensive guides
for users to leverage the new service functionality, particularly valuable given
Bose's cloud service discontinuation in May 2026.
- Move SPEAKER_ENDPOINT.md from project root to docs/ directory
- Update README.md documentation link to reflect new path
- Maintain consistency with other documentation organization
- Update API-COVERAGE-ANALYSIS.md:
- Add /speaker and /playNotification to official API table
- Update endpoint count from 18/19 to 20/21 (95% coverage)
- Add notification system to conclusion summary
- Update API-Endpoints-Overview.md:
- Add comprehensive speaker endpoints documentation
- Include TTS and URL playback examples with XML
- Document ST-10 Series compatibility and features
- Update UNIMPLEMENTED-ENDPOINTS.md:
- Mark speaker notification system as ✅ IMPLEMENTED
- Update priority counts (14→12 critical, 15→13 high priority)
- Replace implementation notes with CLI and Go client examples
- Update STATUS.md:
- Add Phase 6: Notification System completion
- Update endpoint count from 26→28 total endpoints
- Add speaker notifications to production ready features
- Document recent major updates with speaker implementation
- Update README.md:
- Add 🔔 Smart Notifications feature to features list
- Add speaker CLI examples and Go library usage examples
- Add Speaker Notifications to API coverage table
- Include SPEAKER_ENDPOINT.md in documentation links
- Update CLI-REFERENCE.md:
- Add comprehensive speaker command section
- Include TTS examples with multi-language support
- Document URL content playback and beep notifications
- Add supported languages list and compatibility notes
- Update FEATURE_HISTORY.md:
- Add Phase 8: Speaker Notification System (February 2025)
- Document TTS, URL playback, and beep functionality
- Update endpoint statistics (27→29 total, 100% coverage)
- Add speaker notification test coverage and CLI commands
All documentation now reflects the complete speaker endpoint implementation
with comprehensive examples, usage patterns, and technical details.
- Update Go version requirement from 1.25.5 to 1.25.6 in all docs (security fix)
- Add golangci-lint tooling information to CONTRIBUTING.md
- Document code quality improvements in STATUS.md including:
- Security vulnerability resolution (GO-2026-4340)
- Cyclomatic complexity reduction for 5 functions
- Comprehensive error handling improvements
- Complete style and formatting compliance
- Add code quality metrics section showing production readiness
- Update development workflow to include modern linting tools
Ensures documentation accurately reflects current security and quality status.
- Add missing CLI commands for navigation and station management functionality
- Implement browse commands (content, menu, container, tunein, pandora, stored-music)
- Implement station commands (search, add, remove) for all sources (TuneIn, Pandora, Spotify)
- Create comprehensive examples for preset management and navigation/station demo
- Update all documentation to properly credit SoundTouch Plus Wiki as endpoint source
- Correct attribution from 'reverse engineering' to community-documented endpoints
- Add Related Projects section acknowledging SoundTouch Plus and SoundCork
- Update API coverage documentation to reflect 100% functional implementation
- Resolve GitHub issue #14 with complete preset management and direct content playback
Resolves: #14
Implements the complete /navigate, /searchStation, /addStation, and /removeStation
API endpoints with full client support, models, tests, and documentation.
This resolves GitHub issue #14 by enabling direct radio station and custom
stream playback without requiring preset storage first.
## New Features
### Content Navigation
- Browse content sources (TuneIn, Pandora, Spotify, stored music)
- Navigate directory structures in music libraries
- Paginated browsing with configurable page sizes
- Menu-based navigation for services like Pandora
### Station Search & Discovery
- Search across music services for stations, artists, songs
- Service-specific search methods for TuneIn, Pandora, Spotify
- Smart result categorization (songs vs artists vs stations)
- Rich metadata including artwork and descriptions
### Station Management
- Add stations to collections with immediate playback
- Remove stations from user collections
- Token-based operations for discovered content
- WebSocket event generation for real-time updates
## Implementation Details
### New Client Methods
- Navigate(), NavigateWithMenu(), NavigateContainer()
- SearchStation(), SearchTuneInStations(), SearchPandoraStations(), SearchSpotifyContent()
- AddStation(), RemoveStation()
- GetTuneInStations(), GetPandoraStations(), GetStoredMusicLibrary()
### New Models (pkg/models/navigation.go)
- NavigateRequest/Response with helper methods
- SearchStationRequest/Response with result filtering
- AddStationRequest, RemoveStationRequest, StationResponse
- Rich helper methods for type detection and display formatting
### Enhanced HTTP Client
- Added postWithResponse() method for POST requests with XML response parsing
- Proper error handling with API error response parsing
- XML marshaling/unmarshaling for all new request/response types
## Testing
### Comprehensive Test Suite
- Unit tests for all client methods (navigation_test.go)
- XML validation tests (navigation_xml_test.go)
- Integration tests for real devices (navigation_integration_test.go)
- Example workflows (navigation_examples_test.go)
- Complete model tests (navigation_test.go)
- Edge case and error handling tests
### Test Coverage
- ~50 new test cases across different categories
- 100% coverage of new navigation methods
- XML protocol compliance verification
- Performance benchmarking capabilities
- Integration testing ready for real devices
## Documentation
### User-Focused Guide (docs/NAVIGATION-GUIDE.md)
- Complete usage examples from basic to advanced
- Real-world workflows (discover → search → add → play)
- Error handling patterns and best practices
- Service-specific guidance (TuneIn vs Pandora vs Spotify)
- Performance optimization tips
### Technical Reference (docs/API-NAVIGATION-REFERENCE.md)
- Complete API method documentation
- Model specifications with helper methods
- HTTP endpoint mapping with XML examples
- Error codes and troubleshooting guide
- XML schema definitions
### Updated README.md
- Added navigation to API coverage
- Updated documentation links
- Enhanced feature list
## API Endpoints Implemented
- POST /navigate - Browse content sources
- POST /searchStation - Search for stations and content
- POST /addStation - Add station and immediately play
- POST /removeStation - Remove station from collection
## Breaking Changes
None - all additions are backwards compatible.
## Usage Examples
This implementation enables the complete workflow requested in issue #14:
direct radio station and custom stream playback without preset dependencies.
Major Features:
• Implement complete /requestToken API endpoint for bearer token generation
• Fix clock time parsing and display with comprehensive time information
• Add comprehensive API documentation for 103 discovered endpoints
/requestToken Implementation:
• Add BearerToken model with full XML marshaling support
• Add RequestToken() client method with proper error handling
• Add 'soundtouch-cli token request' CLI command with security features
• Token validation, formatting, and secure display (truncated for security)
• Comprehensive unit tests and integration tests
• Support for Authorization header formatting and raw token extraction
Clock Time Fixes:
• Fix ClockTime model to match actual device XML response structure
• Add LocalTime component for nested time details
• Support for utcTime, timeFormat, brightness, clockError attributes
• Enhanced CLI display with comprehensive time information
• Fixed month conversion (device uses 0-11, Go uses 1-12)
Documentation Enhancements:
• Add comprehensive /supportedURLs endpoint analysis (103 endpoints discovered)
• Create detailed unimplemented endpoints documentation with examples
• Update API coverage from 34% implemented to full endpoint catalog
• Add SoundTouch End of Life notice with May 6, 2026 details
• Enhanced endpoint descriptions with real device response examples
Security:
• All tests use generic token examples (no real tokens exposed)
• Integration tests validate token properties without exposing values
• Secure token display with truncation in CLI and string representations
• Environment variable based testing for real devices
Testing:
• 15+ new test functions with comprehensive coverage
• Real device validation on 192.168.178.28 and 192.168.178.35
• Mock server tests and XML marshaling validation
• Integration tests with SOUNDTOUCH_TEST_HOST environment variable
CLI Enhancements:
• Enhanced clock time display with local time details and device settings
• New token management commands with usage instructions
• Improved error handling and user-friendly output formatting
Correct the disclaimer to state that the project is based on official
Bose SoundTouch Web API documentation provided by Bose Corporation,
not reverse-engineering. The implementation follows the official API
specification that Bose made available.
Maintains accurate statement that the project is independent and not
affiliated with Bose Corporation.
- Update CONTRIBUTING.md to require Go 1.25.5 or later
- Update README.md prerequisites
- Update GETTING-STARTED.md requirements
- Update Dockerfile examples to use golang:1.25-alpine
- Update issue templates to reflect supported Go versions
- Ensure consistency across all documentation files
All CI workflows already use go-version-file: go.mod so they
automatically pick up the correct version from go.mod.
- Add CONTRIBUTING.md with detailed contributor guidelines
- Create GitHub issue templates (bug reports, feature requests, device compatibility)
- Add pull request template with comprehensive checklist
- Create FEATURE_HISTORY.md documenting development evolution
- Streamline README.md to focus on overview and usage
- Improve documentation organization and clarity
The project now has proper contribution guidelines following GitHub best practices,
making it easier for new contributors to get started and maintain consistent
quality standards.
- Fix package declaration in doc.go (main -> soundtouch)
- Update all documentation to reflect 100% API endpoint completion
- Clarify trackInfo as implemented but device-dependent
- Properly exclude POST /presets as officially N/A by Bose
- Update PLAN.md phases 1-6 to show COMPLETE status
- Update STATUS.md statistics to show 26/26 endpoints (100%)
- Update README.md to show accurate completion status
- Align all documentation for consistent project status
The library now correctly shows complete implementation of all
available and functional SoundTouch API endpoints.
