Update v0.103.0 -> v0.104.0 across installer scripts, walkthrough docs,
and example go.mod files, and refresh the devices/migration/settings/sync
UI screenshots.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Add package comment (revive: package-comments)
- Use index-based range loop for stations slice to avoid 160-byte copy
per iteration (gocritic: rangeValCopy)
- Rename unused client parameters to _ in three stub functions (revive:
unused-parameter)
- Remove custom min() helper; Go 1.21+ provides a built-in min (revive:
redefines-builtin-id)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Files in cmd/ examples/ scripts/ referenced docs/guides/ and docs/reference/
which moved to docs/content/docs/guides/ and docs/content/docs/reference/.
A few links to loose files at the docs/ root were updated to their new
location under docs/content/docs/appendix/.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Completes the docs-tier RFC-5737 rollout by sweeping the remaining
192.168.1.x references that lived outside .md / .txt / test files:
- .env.example — active PREFERRED_DEVICES default + examples
- .github/ISSUE_TEMPLATE/*.yml + workflows — issue template + CI examples
- cmd/websocket-demo/main.go, doc.go — top-level docs
- examples/*/main.go (7 files) — example program comments
- pkg/client/client.go — godoc examples
- pkg/models/doc.go — package godoc
- pkg/service/{amazon,spotify,zeroconf}/zeroconf.go — godoc comments
- pkg/service/handlers/web/index.html — placeholder text in the UI
- scripts/prepare-release.sh — example invocations
- scripts/spotify/spotify-prime-speaker.sh — usage comment
- tests/integration/http-client/http-client.env.json — fixture IPs
Same mapping as the docs commit (136d24a): 192.168.1.X → 192.0.2.X
preserving the last octet.
One semantic carve-out: the three zeroconf `zcBaseURL` godoc comments
in pkg/service/{amazon,spotify,zeroconf}/zeroconf.go switched to
192.168.10.10 instead of the doc range, because validateZcBaseURL
only accepts RFC-1918 / loopback / link-local. The comment must show
a value the validator actually accepts — see the matching test fix
in 92f66a2 for the same reason.
go build ./... clean. go test ./... clean except the pre-existing
TestDocsConsistency (untracked DEVICE-LOCAL-INSTALL.md, unrelated).
golangci-lint run ./... — 0 issues after a gofmt fix on
examples/zone-slave-operations/main.go.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 4 of the docs portion of the rfc-5737-cleanup. Replaces all
192.168.1.x example IPs in tracked .md / .txt files with the
equivalent last-octet under 192.0.2.x.
192.168.1.x is RFC-1918 private space and routes on real networks,
which leaves readers guessing whether a documented IP is a placeholder
or a documented LAN. 192.0.2.0/24 is reserved by RFC 5737 exclusively
for documentation — readers know on sight that they're examples.
58 files touched, 551 line pairs. Includes .github issue/PR templates,
all docs/ references, example READMEs, and one script doc. No code
changes, no test changes; test files still carry the 192.168.1.x
placeholder pending Phase 2 in _/RFC-5737-cleanup/assessment.md.
Also fixed a small fallout in docs/analysis/ANONYMIZATION-SUMMARY.md
where the explanatory sentence "a reader can't tell whether
192.168.1.10 is a placeholder or a documented LAN address" had
itself been swept by the regex (inverting the point); restored the
literal example and noted the sweep progress inline.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The maintainer's two test-speaker MACs (A81B6A536A98 / A81B6A849D99,
plus colon-separated forms) appeared throughout documentation, runbooks,
and example READMEs. Public repo — same hygiene argument as the LAN-IP
sweep in 787c4fa.
Mapping:
A81B6A536A98 → AABBCCDDEEFF
A81B6A849D99 → AABBCCDDEE01
A8:1B:6A:53:6A:98 → AA:BB:CC:DD:EE:FF
A8:1B:6A:84:9D:99 → AA:BB:CC:DD:EE:01
The placeholders use the IANA-reserved AA:BB:CC:DD:EE:FF address that's
clearly synthetic, matching the convention the earlier anonymisation
pass had already adopted. 13 .md files touched; no tests, no code.
ANONYMIZATION-SUMMARY.md left for a dedicated rewrite commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The ST10's /presets response after a factory reset emits self-closing
<preset/> entries with no ContentItem child. cmd/soundtouch-cli's
getPresets() handled the missing ContentItem in GetDisplayName() but
then dereferenced preset.ContentItem.Source on the next line, panicking
with "invalid memory address or nil pointer dereference" the moment the
loop reached the first empty entry.
A second placeholder shape was observed on healthy devices that were
never reset: <preset id="0"><ContentItem source="INVALID_SOURCE"
isPresetable="true"/></preset>. ContentItem is non-nil here, so the
previous "ContentItem != nil" guard at other call sites still let
these placeholders through into listings and into the AfterTouch
datastore.
Fix shape:
pkg/models/presets.go - extend Preset.IsEmpty() to recognise both
shapes (ContentItem == nil, OR Source == "" / "INVALID_SOURCE").
HasPresets, GetEmptyPresetSlots and GetUsedPresetSlots become honest
about which slots actually carry playable content.
cmd/soundtouch-cli/cmd_info.go (the crash site) - filter the slice
via IsEmpty before the print loop, and switch the still-printed
fields to the existing nil-safe Get* helpers.
pkg/service/setup/setup.go - upgrade syncPresets's "ContentItem ==
nil" continue-guard to IsEmpty so Shape B placeholders don't get
persisted in the AfterTouch datastore and then surface as junk
rows in the admin web UI.
cmd/soundtouch-cli/cmd_events.go, cmd/websocket-demo/main.go - same
nil-guard upgrade. These already nil-checked so were crash-safe;
the change is for consistency and to stop printing
"Preset 0: (INVALID_SOURCE)" demo lines.
examples/preset-management/main.go - had the same latent crash as
cmd_info.go; same fix shape.
Regression tests in pkg/models/presets_test.go cover both shapes using
the exact XML observed in the wild: the reporter's three <preset/>
placeholders plus the three INVALID_SOURCE entries from a live device.
The reporter XML test walks every preset through the same accessor
path the CLI used and asserts no panic.
The soundtouch-web Go code does not deref preset.ContentItem.X
anywhere - presets flow through as JSON - so no separate crash trap
exists there. The web frontend will pick up the cleaner data once
syncPresets stops persisting placeholders.
Closes#308
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Update Go version to 1.26.1 in go.mod and examples to address:
- GO-2026-4602 (os: FileInfo escape)
- GO-2026-4601 (net/url: IPv6 host literal parsing)
- GO-2026-4600 (crypto/x509: panic in name constraint checking)
- GO-2026-4599 (crypto/x509: incorrect email constraint enforcement)
- Upgrade golang.org/x/* and other dependencies to latest stable versions.
- Synchronize go.sum via go mod tidy.
Co-authored-by: Junie <junie@jetbrains.com>
- Update `getRecordingPath` to use a timestamp format that includes the date (`20060102-150405.000`).
- Update `parseInteractionFile` and `getFullTimestamp` to handle both the new filename format and the legacy format for backward compatibility.
- Improved parsing logic to reliably extract date, time, and HTTP method from interaction filenames.
- Updated Go version from 1.25.6 to 1.25.7 in main go.mod
- Updated Go version in example modules (navigation-station-demo, preset-management)
- Fixes TLS vulnerability: Unexpected session resumption in crypto/tls
- Addresses security issue affecting WebSocket, HTTP handlers, and proxy operations
Reference: https://pkg.go.dev/vuln/GO-2026-4337
- Fix content type display tests to expect lowercase 'track' instead of 'Track'
- Content types should display raw API values for technical accuracy
- Fix icon test to expect correct emoji for unknown content types
- Update documentation links in README files:
- Point source selection links to docs/SOURCE-SELECTION.md
- Point navigation links to docs/NAVIGATION-GUIDE.md
- Point zone management links to docs/zone-management.md
- Update service management link to SERVICE-AVAILABILITY-IMPLEMENTATION.md
All tests now pass and documentation links are verified to exist.
✨ New Features:
- Add SelectContentItem() method for direct ContentItem selection
- Add SelectLocalInternetRadio() with full streamUrl format support
- Add SelectLocalMusic() for SoundTouch App Media Server content
- Add SelectStoredMusic() for UPnP/DLNA media server content
📻 streamUrl Format Support:
- Full implementation of wiki specification for LOCAL_INTERNET_RADIO
- Support for proxy URLs: http://contentapi.gmuth.de/station.php?name=Station&streamUrl=ActualStream
- Direct stream URL support for simple internet radio
- Complete ContentItem structure with metadata and artwork
🖥️ CLI Commands:
- Add 'source internet-radio' command with streamUrl support
- Add 'source local-music' command for local media server content
- Add 'source stored-music' command for UPnP/DLNA content
- Add 'source content' command for advanced generic selection
- All commands include comprehensive flag support and validation
🧪 Testing:
- Add 17+ comprehensive unit tests covering all scenarios
- Test streamUrl format validation and parsing
- Test error handling and parameter validation
- Test default value assignment and ContentItem construction
- All tests passing with full coverage
📚 Documentation:
- Update CLI-REFERENCE.md with new command examples
- Add complete content-selection example with working code
- Add implementation summary document
- Include API documentation for all new methods
- Add usage examples for both API and CLI
🔗 References:
Implements features from SoundTouch WebServices API Wiki:
- https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API#select-local_internet_radio---streamurl-format
- https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API#select-local_music🎯 Benefits:
- Complete API coverage for advanced content selection
- Backward compatible with existing code
- Flexible design with both convenience and power-user methods
- Production-ready with comprehensive testing and documentation
Co-authored-by: SoundTouch WebServices API Wiki <https://github.com/thlucas1/homeassistantcomponent_soundtouchplus>
🔥 NEW ENDPOINTS IMPLEMENTED:
📊 /introspect endpoint:
- Get detailed music service state and capabilities data
- Support for SPOTIFY, PANDORA, TUNEIN, AMAZON, DEEZER services
- Service state tracking (Active, Inactive, InactiveUnselected)
- Playback capabilities (skip, seek, resume, data collection)
- Authentication token status and user account information
- Subscription type and content history metadata
📚 /recents endpoint:
- Retrieve recently played content history
- Support for all music sources (Spotify, Local, TuneIn, Pandora, etc.)
- Rich filtering by source type and content type
- Content classification (tracks, stations, playlists, albums)
- Presetable item identification and artwork metadata
- Timestamp tracking with UTC time support
⚡ CLIENT API:
- client.Introspect(source, sourceAccount) method
- client.IntrospectSpotify(sourceAccount) convenience method
- client.GetRecents() method with comprehensive filtering
- Complete error handling and validation
- Rich helper methods for content analysis
🖥️ CLI COMMANDS:
- soundtouch-cli source introspect --source <SERVICE>
- soundtouch-cli source introspect-spotify
- soundtouch-cli source introspect-all (bulk introspect)
- soundtouch-cli recents list [--detailed] [--limit N]
- soundtouch-cli recents filter --source <SRC> --type <TYPE>
- soundtouch-cli recents latest (most recent item)
- soundtouch-cli recents stats (detailed analytics)
📦 MODELS & FEATURES:
- IntrospectRequest/Response with service-specific handling
- RecentsResponse with RecentsResponseItem for individual items
- Rich filtering: GetSpotifyItems(), GetTracks(), GetPresetableItems()
- Content type detection: IsTrack(), IsStation(), IsPlaylist()
- Source classification: IsStreamingContent(), IsLocalContent()
- Full XML marshalling/unmarshalling with proper attribute handling
🧪 COMPREHENSIVE TESTING:
- Unit tests for models with XML parsing validation
- Integration tests for real device communication
- CLI command tests with mock server responses
- Error condition testing and edge case handling
- Performance tests and timeout validation
📖 DOCUMENTATION & EXAMPLES:
- Updated API endpoints overview marking endpoints as implemented
- Comprehensive CLI reference with usage examples
- Removed endpoints from unimplemented list
- Updated wiki implementation plan status
- Complete example applications with README guides
- Real-world usage patterns and best practices
✨ KEY FEATURES:
- Service health monitoring and diagnostics
- Recently played content discovery and analysis
- Preset candidate identification
- Content statistics and usage analytics
- Time-based filtering and relative timestamps
- Rich emoji-based CLI output formatting
- Cross-service compatibility and error handling
This implements two critical missing endpoints from the SoundTouch API,
providing essential functionality for music service management and
recently played content analysis with full programmatic and CLI access.
Applied automatic fixes using golangci-lint --fix which resolved:
- All remaining wsl_v5 whitespace issues (28 issues)
- All whitespace formatting issues (1 issue)
- Improved code formatting consistency across the entire codebase
All tests passing and functionality preserved.
- Add missing whitespace above range loops, if statements, and assignments
- Fix whitespace in models package (navigation, serviceavailability, supportedurls)
- Improve whitespace in test files and examples
- Fix whitespace in client package methods
- Maintain code functionality while improving readability
Reduced wsl_v5 issues from 29 to 27.
- Remove unnecessary trailing/leading whitespace
- Add missing whitespace above return statements, if statements, and loops
- Fix whitespace around variable declarations and assignments
- Improve code readability by following Go whitespace conventions
- Maintain functionality while improving code style consistency
Addresses majority of wsl_v5 and whitespace linting rules.
- Updated go.mod files to require Go 1.25.6
- Fixes vulnerability in crypto/tls package related to handshake message processing
- All example modules also updated to maintain consistency
- Verified with govulncheck: no vulnerabilities found
✨ New Features:
- Implement missing /supportedURLs endpoint with full XML parsing
- Add comprehensive endpoint-to-feature mapping system (15+ features, 9 categories)
- Create device capability analysis with personalized recommendations
- Add intelligent device classification (Premium, Standard, Basic, Essential, Limited)
🔧 CLI Enhancements:
- Add 'supported-urls' command with --features and --verbose flags
- Add 'analyze' command for comprehensive device capability analysis
- Add 'station list' command for saved station management
- Add 'source availability' and 'source compare' commands
- Enhanced service availability checking across all commands
📚 Models & API:
- New SupportedURLsResponse model with rich helper methods
- Enhanced ServiceAvailability model with validation utilities
- New EndpointFeature mapping system with CLI command references
- Feature completeness scoring and partial implementation detection
🧪 Testing:
- 35+ new test cases covering all functionality
- Comprehensive feature mapping validation tests
- Service availability integration tests with real device scenarios
- Mock server tests for error handling and edge cases
📖 Documentation:
- New FEATURE-MAPPING-GUIDE.md with comprehensive usage examples
- Updated API documentation with correct implementation status
- CLI command reference organized by feature category
- Device troubleshooting guide with capability checking
🎯 Key Capabilities:
- Device feature coverage scoring (0-100%)
- Essential vs optional feature classification
- Personalized CLI command recommendations
- Missing capability detection with usage impact analysis
- Smart device type classification based on supported endpoints
This resolves the documentation inconsistency where /supportedURLs was marked as
implemented but was actually missing from the client. The new implementation goes
far beyond basic endpoint listing to provide intelligent device capability analysis
and personalized usage recommendations.
- 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
Move example files to separate packages to avoid main redeclaration. Fix cyclomatic complexity and variable shadowing. Address errcheck and wsl linting issues. Update tests to handle capabilities and fix panics. Apply consistent formatting with gofmt.
Completes the implementation of all official Bose SoundTouch Web API v1.0
endpoints, achieving 100% official API coverage.
## New Features
### DSP Audio Controls (/audiodspcontrols)
- GetAudioDSPControls() - Get current DSP settings and supported audio modes
- SetAudioDSPControls() - Set audio mode and video sync delay
- SetAudioMode() - Set audio mode only (NORMAL, DIALOG, MUSIC, MOVIE, etc.)
- SetVideoSyncAudioDelay() - Set video sync delay only
### Advanced Tone Controls (/audioproducttonecontrols)
- GetAudioProductToneControls() - Get advanced bass/treble settings with ranges
- SetAudioProductToneControls() - Set both bass and treble
- SetAdvancedBass() - Set advanced bass level only
- SetAdvancedTreble() - Set advanced treble level only
### Speaker Level Controls (/audioproductlevelcontrols)
- GetAudioProductLevelControls() - Get front-center and rear-surround levels
- SetAudioProductLevelControls() - Set both speaker levels
- SetFrontCenterSpeakerLevel() - Set front-center speaker level only
- SetRearSurroundSpeakersLevel() - Set rear-surround speakers level only
## Implementation Details
### Models & Validation
- Complete XML marshaling/unmarshaling with proper struct separation
- Comprehensive input validation with device capability checking
- Support for device-specific ranges and step values
- Proper error handling and constraint validation
### CLI Integration
- Full CLI command tree: audio -> {dsp,tone,level} -> {get,set,specific}
- Rich help text with device-specific guidance
- Flexible parameter handling (individual or combined operations)
- Professional usage examples and CLI command demonstrations
### Testing Coverage
- 748+ lines of comprehensive model tests
- 786+ lines of client integration tests
- XML marshaling/unmarshaling validation
- Error handling and edge case coverage
- Network error simulation and validation testing
## Device Compatibility
### Consumer Devices (SoundTouch 10, 20, 30)
- ✅ Basic controls (bass, volume, balance)
- ❌ Advanced audio controls (professional feature)
### Professional/High-end Devices
- ✅ All basic controls
- ✅ DSP audio modes and video sync
- ✅ Advanced bass/treble controls
- ✅ Speaker level controls (surround systems)
## Documentation & Examples
### Updated Coverage Documentation
- README.md: Updated to 100% complete (19/19 endpoints)
- API-Endpoints-Overview.md: Complete coverage analysis
- API-COVERAGE-ANALYSIS.md: Achievement of full API implementation
### Comprehensive Examples
- advanced-audio-controls.go: Complete usage demonstration
- CLI command examples and device compatibility guide
- Error handling and validation examples
## Final API Status
- ✅ **19/19 Official Endpoints Implemented** (100%)
- ✅ **18/19 Functional on Real Devices** (95%)
- ❌ **1 Endpoint Non-functional** (/trackInfo times out on hardware)
- 🔍 **5 Extended Features** (beyond official API v1.0)
This completes the most comprehensive Bose SoundTouch API implementation
available, covering all documented endpoints plus extended functionality.
Implements the remaining zone slave management endpoints from the official
Bose SoundTouch Web API v1.0 specification, bringing API coverage to 89%.
## New Features
### Client Methods
- AddZoneSlave(masterID, slaveID, slaveIP) - Add individual device to zone
- AddZoneSlaveByDeviceID(masterID, slaveID) - Add device by ID only
- RemoveZoneSlave(masterID, slaveID, slaveIP) - Remove individual device
- RemoveZoneSlaveByDeviceID(masterID, slaveID) - Remove device by ID only
### Models
- ZoneSlaveRequest - Request structure for slave operations
- ZoneSlaveEntry - Individual slave entry with IP address support
- Complete XML marshaling/unmarshaling with proper omitempty handling
- Comprehensive validation and error handling
### CLI Commands
- zone add-slave --master ID --slave ID [--slave-ip IP]
- zone remove-slave --master ID --slave ID [--slave-ip IP]
## Implementation Details
- Follows official API specification exactly (POST /addZoneSlave, /removeZoneSlave)
- Supports both device ID + IP and device ID only operations
- Comprehensive input validation (IP addresses, device ID conflicts)
- Proper XML formatting with omitempty for optional IP addresses
- Extensive test coverage (580+ lines of tests)
- Integration with existing high-level zone management API
## Testing
- 200+ new test cases covering all functionality
- Complete model validation and XML marshaling tests
- HTTP client integration tests with mock servers
- Error handling and edge case coverage
- Network error simulation tests
## Documentation Updates
- Updated API coverage from 84% to 89% (17/19 endpoints)
- Comprehensive API coverage analysis document
- Updated README.md with new endpoint status
- Added practical usage examples
- CLI help documentation
## Compatibility
- Maintains full backward compatibility
- Complements existing high-level zone API
- Users can choose between low-level official API or enhanced high-level API
- No breaking changes to existing functionality
This implementation provides both the exact official API endpoints and
enhanced high-level zone management, giving users maximum flexibility
for zone operations while maintaining full API compliance.
