createGroup used to POST only to the LEFT (master) speaker and rely on
the master to propagate the group to the slave via marge. That round-
trip is the source of the "context deadline exceeded" failures reported
in #252 — the master blocks waiting for marge while the CLI times out
client-side. SoundCork's working ST10 implementation addresses each
speaker directly, which avoids the inter-device coordination entirely.
Changes:
* Build the group request with senderIPAddress = master IP (the fhem
wiki documents this field; SoundCork sets it; we previously omitted
it).
* propagateAddGroup() POSTs the same payload to both speakers
concurrently via a sync.WaitGroup and returns per-side outcomes.
* postAddGroup() flags a non-GROUP_OK response Status as an error so
the caller doesn't have to re-parse the body.
* On partial failure (one side succeeded), surface a remove command
the user can run to clean up.
Tests cover the happy path (both succeed, payload shape correct), the
right-side-fails path, the non-GROUP_OK response, and an empty-status
response (some firmware omits Status entirely on a successful echo).
Refs #252. Optimistic fix — still pending feedback from BirdyBA's
two-curl test on real ST10s before we're confident.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
term.ReadPassword takes an int, but syscall.Stdin is syscall.Handle
(uintptr) on Windows. The explicit cast keeps the call building on
Windows while a //nolint:unconvert silences the false positive on Unix
where syscall.Stdin is already int.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brings the five remaining gocyclo > 20 warnings to zero by extracting
cohesive sub-functions; same observable behaviour, smaller surface to
read at each call site. Bonus: the new helpers are individually testable.
- pkg/models/clockdisplay.go: split ClockDisplay.UnmarshalXML attr
handling into applyClockDisplayOuterAttrs (legacy flat shape) and
applyClockConfigAttrs (current nested shape).
- pkg/service/setup/ssh_probe_apply.go: split applyProbeToSummary into
applyProbeCurrentConfig / applyProbeResolvConf /
applyProbeRemoteServices / applyProbeCACert — one helper per
MigrationSummary axis the probe populates.
- pkg/service/setup/init_plan.go: split ExecuteInitPlan into
applyInitPlanDefaults, runURLRewrite, resolveAccountID, and
verifyPairing. Cleans up several shadowed err variables in the
process.
- cmd/soundtouch-cli/cmd_setup.go: split renderInspectReport into
renderInspectIdentityAndPairing / renderInspectNetwork /
renderInspectSources / renderInspectPresets / renderInspectRuntimeURLs,
and buildPlanSteps into resetSteps + migrationSteps helpers.
golangci-lint run ./pkg/service/setup/... ./pkg/models/...
./cmd/soundtouch-cli/... now reports zero findings. Tests green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Rename SetupStateMachine → setup.StateMachine, SetupSessionConfig →
setup.SessionConfig, SetupSession → setup.Session, and
DialSetupSession → setup.DialSession. The Setup* prefix only stutters
in package context (`setup.SetupSession`); the renamed forms read
cleaner at every call site (revive: exported).
- Iterate r.Network.Interfaces.Interfaces by index in cmd_setup.go
rather than by value — each NetworkInterface is 168 bytes and the
per-iteration copy was unnecessary (gocritic: rangeValCopy).
Test fixtures (fakeSetupSession → fakeSession, TestSetupSession_* →
TestSession_*) renamed by the same substring replacement to keep
naming consistent inside the package.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fixes the lint hits that pointed at real bugs or dead code; leaves the
remaining style-only suggestions (rangeValCopy micro-copies, gocyclo
informational, intentional name choices like SetupStateMachine) alone.
- pkg/models/clockdisplay.go: restore <clockDisplay> XMLName tag on both
ClockDisplay and ClockDisplayRequest. The earlier `xml:"-"` clashed
with ClockDisplayUpdatedEvent.ClockDisplay's `xml:"clockDisplay"` tag
(SA5008). Custom MarshalXML/UnmarshalXML still own the wire format.
- pkg/service/setup/setup.go: drop the now-unused checkRemoteServices
helper (replaced by applyProbeToSummary) and rename the unused
deviceIP parameter of populatePlannedNetworkConfig to _.
- pkg/service/setup/setup_session.go: collapse sendStep's (string, error)
return to plain error — every caller already discarded the string.
- pkg/service/setup/init_plan.go: rename shadowed err variables to
rwErr / genErr / invalidErr / nilErr / stepErr.
- cmd/soundtouch-cli/cmd_setup.go: drop redundant int(syscall.Stdin)
conversion (already int) and rename a shadowed err to pairErr.
go build ./..., go vet ./..., and tests for the touched packages all
green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add `soundtouch-cli setup` subcommand group covering the full reset →
re-provision → pair lifecycle as a scriptable alternative to the web UI:
inspect, verify, plan, factory-reset, wait-ap, wifi-push, wait-online,
ssh-check, install-ca, migrate, reboot, pair (bare | full state machine)
Supporting library code lives in pkg/service/setup: factory_reset.go,
wifi_provision.go, inspect.go, init_plan.go, setup_session.go.
Confirmed against ST10 firmware 27.0.6 that bare setMargeAccount over
WebSocket — no SETUP_START/SETUP_ENTER/SETUP_LEAVE bracket — is
sufficient to pair a factory-reset speaker; the firmware materializes
SystemConfigurationDB.xml and Sources.xml itself and the pairing
survives reboot. Result and field-by-field SystemConfigurationDB
comparison documented in docs/analysis/SETUP-WEBSOCKET-EXPERIMENT.md.
Captures the device's pre-reset DELETE-to-marge plus its LAN peer
notification flow in docs/analysis/FACTORY-RESET-PROTOCOL.md.
Perf: batch GetMigrationSummary's SSH probes into one Run() call via
ssh_probe.go / ssh_probe_apply.go — was ~8 sequential dials at
500-1000 ms each on FW 27 crypto, now one round-trip. Same data shape,
same MigrationSummary fields populated.
Fixes /clockTime and /clockDisplay wire formats — firmware 27 rejects
the legacy flat XML ("Error parsing request"). ClockTimeRequest now
uses utcTime attribute; ClockDisplayRequest emits the nested
<clockConfig> envelope with timezoneInfo/timeFormat/brightnessLevel.
Removes cmd/example-init-speaker (superseded by setup pair).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Implements the speaker-side group API surface (path 1 of the two
approaches gmuth outlined in issue #252): clients form, rename, and
dissolve stereo pairs directly on the device, and the resulting
GroupService.xml persists on disk in the same shape the device emits
over /getGroup.
What landed:
- pkg/models/group.go: Status field + IsEmpty() helper, matching the
GET /getGroup response shape (id-attr, masterDeviceId, roles,
senderIPAddress).
- pkg/client/client.go: GetGroup, AddGroup, UpdateGroup, RemoveGroup.
The endpoint name is /getGroup (not /group, despite some wiki docs)
— confirmed against a real ST-10's /supportedURLs. RemoveGroup uses
GET per the wire spec.
- cmd/soundtouch-cli/cmd_group.go + main.go: new `group` subcommand
with status / create --left --right [--name] / rename / remove,
mirroring gmuth's group.sh recipe.
WebSocket notifications:
- pkg/models/websocket.go: EventTypeGroupUpdated +
GroupUpdatedEvent + dispatch helpers. The device fans this out to
both LEFT and RIGHT speakers on every group mutation, including
empty-group teardowns; the parse test covers both shapes.
- pkg/client/websocket.go: OnGroupUpdated registration and dispatch.
- cmd/soundtouch-cli/cmd_events.go: `group` filter +
handleGroupEvent formatter.
WebSocket observability (came up while validating the above against
a real device):
- New RawMessageHandler type + OnRawMessage hook that fires for every
incoming frame before parsing, with the parse error alongside.
- New --debug flag on `events subscribe` with modes all / unknown /
errors. Raw output goes to stderr so it composes cleanly with
shell redirects.
The pkg/client refactor in this commit also adopts speaker.HTTPPort
(introduced in the previous refactor) — the unexported
defaultSoundTouchPort and three hard-coded 8090 literals are gone.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- 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.
Add WebSocket event monitoring functionality to soundtouch-cli:
• New 'events subscribe' command for real-time device monitoring
• Support for all 8 event types: nowPlaying, volume, connection, preset, zone, bass, sdkInfo, userActivity
• Event filtering with --filter flag (comma-separated list)
• Duration limits with --duration flag
• Reconnection control with --no-reconnect flag
• Verbose logging with --verbose flag
• Comprehensive test coverage with 349+ test cases
• Full documentation updates in CLI-REFERENCE.md and websocket-events.md
Usage examples:
- soundtouch-cli --host 192.168.1.100 events subscribe
- soundtouch-cli --host 192.168.1.100 events subscribe --filter volume,nowPlaying
- soundtouch-cli --host 192.168.1.100 events subscribe --duration 5m --verbose
Resolves README discrepancy - the documented command now works as expected.
All golangci-lint issues resolved, maintains code quality standards.
- Add PlayInfo model for TTS and URL content playback requests
- Add SpeakerResponse model for endpoint responses
- Implement client methods: PlayTTS, PlayURL, PlayCustom, PlayNotificationBeep
- Add comprehensive CLI commands for speaker functionality:
- speaker tts: Text-to-Speech with Google TTS and language support
- speaker url: Audio content playback from HTTP/HTTPS URLs
- speaker beep: Simple notification beep sound
- speaker help: Detailed functionality documentation
- Support for volume control (0-100 or current volume)
- Multi-language TTS support (EN, DE, ES, FR, IT, NL, PT, RU, ZH, JA, etc.)
- Custom metadata support for NowPlaying display
- Comprehensive validation and error handling
- Full test suite with XML marshaling/unmarshaling tests
- Complete documentation with API reference and usage examples
- Compatible with ST-10 (Series III) and other supported SoundTouch devices
The /speaker endpoint enables notification and audio content playback,
automatically managing volume restoration and content interruption.
Perfect for home automation, alerts, and custom audio notifications.
- Add container art URL display in verbose mode
- Show shuffle and repeat settings
- Display track ID for streaming services
- Include art image status and URL details
- Add capabilities section showing available controls (skip, favorite, seek)
- Organize verbose output in logical sections for better readability
- All additional details match those available via direct curl API calls
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.
- Remove unused parsePaginationParams function from cmd_navigation.go
- Remove unused validateSource function from cmd_navigation.go
- Clean up dead code and related comments
Addresses 'unused' linting issues and improves code maintainability.
- 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.
- Fix error string capitalization to follow Go guidelines (ST1005)
- Fix unchecked error returns in test files (errcheck)
- Replace nil-nil return with proper error for non-TuneIn URLs (nilnil)
- Add missing comments for exported service type constants (revive)
- Rename unused parameters to underscore in test handlers (revive)
- Add t.Helper() calls to test helper functions (thelper)
- Update test expectations to match lowercase error messages
This addresses all critical linting issues while maintaining functionality.
✨ 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
- Add StorePreset, StoreCurrentAsPreset, and RemovePreset methods to client
- Create comprehensive preset management CLI with subcommands:
* preset store-current --slot N (store currently playing content)
* preset store --slot N --source X --location Y (store specific content)
* preset remove --slot N (remove preset)
* preset select --slot N (select/play preset)
* preset list (list all presets)
- Fix WebSocket event handling for preset updates:
* Correct event type from 'presetUpdated' to 'presetsUpdated'
* Update event structure to handle complete preset list
* Improve WebSocket demo display for preset events
- Add comprehensive test coverage for all new client methods
- Fix mock server URL mismatch in tests (/now_playing vs /nowPlaying)
- Add proper input validation and error handling
- Support all content sources: SPOTIFY, TUNEIN, LOCAL_INTERNET_RADIO, etc.
Successfully tested with real SoundTouch device:
- Storing Spotify content as presets ✅
- Removing presets ✅
- Real-time WebSocket events ✅
- CLI usability and error handling ✅Resolves#14 - Complete /storePreset implementation
- Add automatic display of ContentItem location (URI/ID) for all sources with location data
- Add --verbose flag to 'play now' command for detailed content information
- Show location details by default for any source (SPOTIFY, TUNEIN, PANDORA, STORED_MUSIC, etc.)
- Add comprehensive test coverage for content details display logic
- Add preset-store.md documentation for future /storePreset implementation
- Update documentation to reflect universal location support
This enables users to easily capture location URIs needed for the planned /storePreset feature:
- Spotify: spotify:track:123456789
- TUNEIN: /v1/playback/station/s33828
- Internet Radio: https://stream.example.com/radio
- NAS Music: 6_a2874b5d_4f83d999
- Pandora: 126740707481236361
Resolves#14 preparation work
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
- Add recursive sortCommands function to sort commands and subcommands alphabetically
- Add sortFlags function to sort flags alphabetically by name
- Add getFlagName helper to extract flag names from different flag types
- Sort both top-level commands and all nested subcommands recursively
- Sort command-specific flags while preserving auto-generated help flags
- Improve CLI usability by making commands and options easier to find
Commands and subcommands are now displayed in alphabetical order in help output.
All user-defined flags are sorted alphabetically within each command.
- Use package-level variables instead of mixed return/ignore pattern
- Call updateBuildInfo() once at startup instead of multiple function calls
- Cleaner, more consistent design with single responsibility
- Eliminates confusing 'version, _, _' usage pattern
Thanks for the excellent code review feedback!
Remove unnecessary truncation of Git commit hash from vcs.revision.
The full hash provides better traceability and eliminates arbitrary
magic numbers in the code.
Simpler, cleaner, and more robust approach.
- Use debug.ReadBuildInfo() for version information (Go 1.18+ best practice)
- Extract version from module info and VCS settings (vcs.revision, vcs.time)
- Remove complex ldflags setup from Makefile and GitHub workflows
- Simplify build process while maintaining all version information
- Cleaner approach recommended by Go community
Thanks to Gopher Slack feedback for this improvement!
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.
- Specify that '/now_playing' endpoint is the API alternative
- Clarify that CLI 'now' command (playback status) is the CLI alternative
- Distinguish between the two 'now' CLI commands (playback vs clock)
- Update warning messages to be more specific about alternatives
Based on real device testing, the /trackInfo endpoint returns
'AllegroWebserver timeout' errors despite being documented in the
official Bose SoundTouch Web API v1.0 specification.
## Changes
- Updated API coverage from 89% to 84% (16/19 functional endpoints)
- Marked /trackInfo as ❌ Non-functional in all documentation
- Added warning comments to GetTrackInfo() method
- Updated CLI command with warning message
- Recommend using /now_playing instead for track information
## Real Device Evidence
- Device: SoundTouch at 192.168.178.28:8090
- Error: 'AllegroWebserver timeout: /trackInfo'
- Status: Endpoint documented but not working on hardware
This reflects the reality that some officially documented endpoints
may not function properly on actual devices, emphasizing the importance
of real hardware testing in API implementation.
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.
Major improvements to device discovery system:
🔧 **SSDP Discovery Fixed**:
- Fixed networking issue where SSDP used connected UDP socket instead of UDP listener
- SSDP now properly receives unicast responses from multicast requests
- UPnP discovery now works reliably and finds all MediaRenderer devices
✨ **Enhanced DiscoveredDevice Model**:
- Added consistent URL fields (APIBaseURL, InfoURL) for all discovery methods
- Added protocol-specific fields (UPnPLocation, UPnPUSN, MDNSHostname, etc.)
- Added DiscoveryMethod tracking to show how devices were found
- Added device merging support for same device found via multiple protocols
🚀 **Unified Discovery Improvements**:
- Fixed device merging logic to properly combine protocol-specific data
- Discovery methods now correctly show combinations like 'Configuration+SSDP/UPnP+mDNS/Bonjour'
- Removed duplicate configuration device loading in individual services
- All three discovery methods (SSDP, mDNS, Configuration) work together seamlessly
🛠 **Updated Tools & Examples**:
- Updated soundtouch-cli to display new consistent field structure
- Enhanced all example programs with better device information display
- Added new unified discovery example demonstrating all three methods
- Fixed context timeout issues in example programs
📋 **Comprehensive Testing**:
- All tests updated and passing
- Real-world validation with actual Bose SoundTouch devices
- Confirmed discovery methods properly merge device data
Every discovered device now has consistent http://host:port/info URLs regardless
of discovery method, while preserving valuable protocol-specific metadata.
- Force IPv4-only mDNS queries with DisableIPv6=true to avoid routing issues
- Add automatic IPv4 interface selection for better compatibility
- Filter mDNS results to only include SoundTouch devices
- Clean up device names by unescaping mDNS characters
- Fix timeout flag handling to respect DISCOVERY_TIMEOUT from .env file
- Only override discovery timeout when --timeout flag is explicitly provided
- Add file operations safety guidelines to docs/CLAUDE.md
- Remove duplicate timeout flags from discover command, use global flags
Fixes IPv6 'no route to host' errors that prevented mDNS discovery.
Now discovers same devices as native dns-sd and dig tools.
- Replace hardcoded version with build-time injected variables
- Add version, commit, and date variables to main.go with default values
- Update Makefile ldflags to use consistent variable names
- Add detailed 'version' subcommand showing build info, Go version, and platform
- Maintain compatibility with existing release workflow
- Support both --version flag (simple) and version subcommand (detailed)
- Reference original API documentation source from Bose Corporation
- Link to official Bose SoundTouch End-of-Life page
- Clarify this is an independent implementation
- Add disclaimer about non-affiliation with Bose Corporation
- Provide both online and local documentation references
- Move --host, --port, and --timeout from individual commands to global app level
- Enables cleaner syntax: 'soundtouch-cli --host 192.168.1.10 volume get'
- Consistent with Docker, kubectl, and other CLI tools that use global connection flags
- Environment variables (SOUNDTOUCH_HOST, SOUNDTOUCH_PORT) work seamlessly
- Remove repetitive CommonFlags from all individual commands
- Maintains backward compatibility - all functionality works exactly the same
- Discovery commands ignore host flag when not needed
BREAKING: CLI syntax improved from 'volume --host IP get' to '--host IP volume get'
Tobias GesellchenandClaude Opus 4.7
