From 0e6dffead0765132ccf36f00cedda6f760643593 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Sun, 11 Jan 2026 00:16:07 +0100 Subject: [PATCH] docs: Mark /trackInfo endpoint as non-functional on real devices MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- README.md | 4 ++-- cmd/soundtouch-cli/cmd_info.go | 2 ++ cmd/soundtouch-cli/main.go | 2 +- docs/API-COVERAGE-ANALYSIS.md | 31 ++++++++++++++++++++----------- docs/API-Endpoints-Overview.md | 11 +++++++---- pkg/client/client.go | 2 ++ 6 files changed, 34 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 54884da..568797e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A modern Go library and CLI tool for interacting with Bose SoundTouch devices vi ## Features -### ✅ Implemented (89% Complete - 17/19 official endpoints) +### ✅ Implemented (84% Complete - 16/19 functional endpoints) - **HTTP Client with XML Support**: Complete client for SoundTouch Web API - **Device Information**: Get detailed device info via `/info` endpoint - **Device Name**: Get device name via `/name` endpoint @@ -684,7 +684,7 @@ Bose-SoundTouch/ | `/setZone` | POST | ✅ **NEW** | **Zone creation and management** | | `/name` | POST | ✅ Complete | Set device name | | `/bassCapabilities` | GET | ✅ Complete | Bass capability detection | -| `/trackInfo` | GET | ✅ Complete | Track information (duplicate of /now_playing) | +| `/trackInfo` | GET | ❌ Not Working | **Documented but times out on real devices** | | `/addZoneSlave` | POST | ✅ Complete | **Individual slave addition to existing zone** | | `/removeZoneSlave` | POST | ✅ Complete | **Individual slave removal from existing zone** | | `/audiodspcontrols` | GET/POST | ❌ Missing | **DSP audio modes and video sync delay** | diff --git a/cmd/soundtouch-cli/cmd_info.go b/cmd/soundtouch-cli/cmd_info.go index 51ffb21..448d3e3 100644 --- a/cmd/soundtouch-cli/cmd_info.go +++ b/cmd/soundtouch-cli/cmd_info.go @@ -235,6 +235,8 @@ func getTrackInfo(c *cli.Context) error { clientConfig := GetClientConfig(c) PrintDeviceHeader("Getting track information", clientConfig.Host, clientConfig.Port) + fmt.Println("⚠️ WARNING: /trackInfo endpoint times out on real devices. Use 'now' command instead.") + client, err := CreateSoundTouchClient(clientConfig) if err != nil { PrintError(fmt.Sprintf("Failed to create client: %v", err)) diff --git a/cmd/soundtouch-cli/main.go b/cmd/soundtouch-cli/main.go index d6b1bc1..e3fc315 100644 --- a/cmd/soundtouch-cli/main.go +++ b/cmd/soundtouch-cli/main.go @@ -223,7 +223,7 @@ func main() { // Track info { Name: "track", - Usage: "Get track information", + Usage: "Get track information (WARNING: times out on real devices, use 'now' instead)", Action: getTrackInfo, Before: RequireHost, }, diff --git a/docs/API-COVERAGE-ANALYSIS.md b/docs/API-COVERAGE-ANALYSIS.md index 64c7476..60712df 100644 --- a/docs/API-COVERAGE-ANALYSIS.md +++ b/docs/API-COVERAGE-ANALYSIS.md @@ -2,24 +2,24 @@ **Last Updated:** January 2025 **API Version:** Official Bose SoundTouch Web API v1.0 -**Implementation Status:** 89% Official Coverage + Extended Features +**Implementation Status:** 84% Official Coverage + Extended Features ## Executive Summary -This Go implementation provides **comprehensive coverage** of the Bose SoundTouch Web API with **89% of official endpoints implemented** (17/19) plus **5 additional extended features** not documented in the official API v1.0 but working with real hardware. +This Go implementation provides **comprehensive coverage** of the Bose SoundTouch Web API with **84% of official endpoints implemented** (16/19) plus **5 additional extended features** not documented in the official API v1.0 but working with real hardware. ### Key Findings - ✅ **All essential user functionality implemented** - ✅ **Complete zone management implementation** - ✅ **Real-time WebSocket event system** - ✅ **Extended features beyond official specification** -- ❌ **2 missing advanced audio endpoints** (professional/audiophile features) +- ❌ **3 missing/non-functional endpoints** (1 broken + 2 professional/audiophile features) --- ## Official API v1.0 Endpoint Coverage -### Implemented Endpoints: 17/19 (89%) +### Implemented Endpoints: 16/19 (84%) | Endpoint | Method | Status | Implementation | Notes | |----------|--------|--------|----------------|--------| @@ -31,7 +31,7 @@ This Go implementation provides **comprehensive coverage** of the Bose SoundTouc | `/getZone` | GET | ✅ **Complete** | `GetZone()`, `GetZoneStatus()`, `GetZoneMembers()` | Multiroom zone information | | `/setZone` | POST | ✅ **Complete** | `SetZone()`, `CreateZone()`, `AddToZone()`, `RemoveFromZone()` | Zone configuration and management | | `/now_playing` | GET | ✅ **Complete** | `GetNowPlaying()` | Current playback status with full metadata | -| `/trackInfo` | GET | ✅ **Complete** | `GetTrackInfo()` | Track information (identical to /now_playing) | +| `/trackInfo` | GET | ❌ **Non-functional** | `GetTrackInfo()` | Documented but times out on real devices | | `/volume` | GET/POST | ✅ **Complete** | `GetVolume()`, `SetVolume()`, `SetVolumeSafe()` | Volume and mute control with safety features | | `/presets` | GET | ✅ **Complete** | `GetPresets()`, `GetNextAvailablePresetSlot()` | Preset configurations (read-only per API spec) | | `/info` | GET | ✅ **Complete** | `GetDeviceInfo()` | Device information and capabilities | @@ -40,10 +40,11 @@ This Go implementation provides **comprehensive coverage** of the Bose SoundTouc | `/addZoneSlave` | POST | ✅ **Complete** | `AddZoneSlave()`, `AddZoneSlaveByDeviceID()` | Individual device addition to zone | | `/removeZoneSlave` | POST | ✅ **Complete** | `RemoveZoneSlave()`, `RemoveZoneSlaveByDeviceID()` | Individual device removal from zone | -### Missing Official Endpoints: 2/19 (11%) +### Missing/Non-functional Endpoints: 3/19 (16%) | Endpoint | Method | Status | Reason | Impact | |----------|--------|--------|--------|---------| +| `/trackInfo` | GET | ❌ **Non-functional** | Times out on real devices (AllegroWebserver timeout) | **None** - Use `/now_playing` instead | | `/audiodspcontrols` | GET/POST | ❌ **Missing** | Advanced professional feature | **Low** - Niche audiophile feature | | `/audioproducttonecontrols` | GET/POST | ❌ **Missing** | Advanced bass/treble beyond `/bass` | **Low** - Basic bass control available | | `/audioproductlevelcontrols` | GET/POST | ❌ **Missing** | Front-center/rear-surround speaker levels | **Low** - Professional audio feature | @@ -131,14 +132,20 @@ All essential user functionality is fully implemented. ### Medium Impact: None ✅ All common use cases are covered. -### Low Impact: 2 Missing Features ❌ +### Low Impact: 3 Missing/Non-functional Features ❌ -#### 1. Advanced Audio DSP Controls +#### 1. Non-functional Endpoint +- **Official**: `/trackInfo` +- **Impact**: None - identical functionality available via `/now_playing` +- **Issue**: Times out on real devices despite being documented in API +- **Workaround**: Use `GetNowPlaying()` method instead + +#### 2. Advanced Audio DSP Controls - **Official**: `/audiodspcontrols` - **Impact**: Low - Professional feature for high-end devices only - **Alternative**: Basic controls available via other endpoints -#### 2. Advanced Tone and Level Controls +#### 3. Advanced Tone and Level Controls - **Official**: `/audioproducttonecontrols`, `/audioproductlevelcontrols` - **Impact**: Low - Audiophile features for professional installations - **Alternative**: Basic bass control via `/bass` endpoint @@ -203,12 +210,14 @@ Missing only niche professional features: ## Conclusion This implementation achieves **excellent API coverage** with: -- ✅ **89% official endpoint implementation** (17/19) +- ✅ **84% functional endpoint implementation** (16/19) - ✅ **100% essential functionality coverage** - ✅ **Superior implementations** for complex operations - ✅ **Extended features** beyond official specification - ✅ **Comprehensive testing and validation** -The missing 2 endpoints represent **professional/niche features** that don't impact the vast majority of users. The implementation actually **exceeds the official API** in many areas through enhanced safety features, complete zone management, and real-time event capabilities. +The missing/broken 3 endpoints represent **professional/niche features** or **broken implementations** that don't impact users. The implementation actually **exceeds the official API** in many areas through enhanced safety features, complete zone management, and real-time event capabilities. + +**Note**: The `/trackInfo` endpoint is documented in the official API but times out on real devices, making it non-functional despite implementation. **Overall Assessment: Excellent** ⭐⭐⭐⭐⭐ \ No newline at end of file diff --git a/docs/API-Endpoints-Overview.md b/docs/API-Endpoints-Overview.md index ab692cd..3b87966 100644 --- a/docs/API-Endpoints-Overview.md +++ b/docs/API-Endpoints-Overview.md @@ -283,10 +283,12 @@ Checks if bass customization is supported on the device. ``` -### GET /trackInfo ✅ **Implemented** +### GET /trackInfo ❌ **Not Working** Gets track information (duplicate of `/now_playing` per official API). -**Implementation**: Available via `GetTrackInfo()` method with identical response format to `/now_playing`. +**Status**: Documented in official API but times out on real devices (AllegroWebserver timeout). Use `/now_playing` instead. + +**Implementation**: Available via `GetTrackInfo()` method but not functional on hardware. ### Zone Slave Management ✅ **Implemented** Both official low-level endpoints and high-level zone management are available: @@ -330,9 +332,10 @@ These endpoints work with real hardware but are NOT in official API v1.0: ## Coverage Summary -### Official API Coverage: 89% +### Official API Coverage: 84% - **Total Official Endpoints**: 19 -- **Implemented**: 17 (89%) +- **Implemented**: 16 (84%) +- **Non-functional**: 1 (5%) - `/trackInfo` times out on real devices - **Missing Low-Impact**: 2 (11%) ### Feature Coverage: 100% diff --git a/pkg/client/client.go b/pkg/client/client.go index 181fbab..7a28f4a 100644 --- a/pkg/client/client.go +++ b/pkg/client/client.go @@ -1049,6 +1049,8 @@ func (c *Client) GetBassCapabilities() (*models.BassCapabilities, error) { } // GetTrackInfo retrieves track information (duplicate of GetNowPlaying per official API) +// WARNING: This endpoint times out on real devices despite being documented in the official API. +// Use GetNowPlaying() instead for reliable track information. func (c *Client) GetTrackInfo() (*models.NowPlaying, error) { var nowPlaying models.NowPlaying