github/Bose-SoundTouch
1
0
Fork 0
mirror of https://github.com/gesellix/Bose-SoundTouch.git synced 2026-08-18 08:36:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(api): reconcile stale endpoint-coverage docs against pkg/client (refs #451)

Browse Source 
The device-API coverage docs had drifted from the code. Verified each claim
against pkg/client and corrected:

- UNIMPLEMENTED-ENDPOINTS.md: re-marked endpoints now implemented but still
  listed as candidates — setMusicServiceAccount / removeMusicServiceAccount and
  the stereo-pair group set (getGroup/addGroup/removeGroup/updateGroup); added a
  reconciliation note and clarified this tracks the speaker :8090 API, not the
  service router.
- SUPPORTED-URLS.md: fixed the "Not Yet Implemented" lists (music services,
  presets, stations, navigate, speaker, requestToken/notification/playNotification
  are all implemented), the contradictory storePreset double-listing, the native
  group section, and the System Info over-claim (trackInfo non-functional,
  bluetoothInfo not implemented).
- API-COVERAGE.md: fixed the exec-summary count (18/19 -> 20/21) to match its own
  table and refreshed the date.

Also sanitised a real device ID (08DF1F0BA325 -> placeholder) found in
SUPPORTED-URLS.md, per the repo's no-real-MACs rule.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tobias Gesellchen
2026-06-06 19:11:24 +02:00
co-authored by Claude Opus 4.8
parent da081f6425
commit 02be18c19c
3 changed files with 83 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/docs/analysis/API-COVERAGE.md
+3 -3
View File
@@ -1,13 +1,13 @@
---
title: "Bose SoundTouch API Coverage Analysis"
---
**Last Updated:** February 2026
**Last Updated:** June 2026 (reconciled against `pkg/client`)
**API Version:** Official Bose SoundTouch Web API v1.0
**Implementation Status:** 100% Official Coverage + Extended Features
**Implementation Status:** Official coverage 20/21 + extended features
## Executive Summary
This Go implementation provides **complete coverage** of the Bose SoundTouch Web API with **100% of official endpoints implemented** (18/19) plus **5 additional extended features** not documented in the official API v1.0 but working with real hardware.
This Go implementation provides near-complete coverage of the Bose SoundTouch Web API with **20 of 21 official endpoints implemented** (the one exception, `/trackInfo`, is documented but non-functional on real hardware) 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**
docs/content/docs/analysis/SUPPORTED-URLS.md
+40 -27
View File
@@ -3,10 +3,23 @@ title: "SoundTouch supportedURLs Endpoint Analysis"
---
This document provides a comprehensive analysis of the `/supportedURLs` endpoint response from real Bose SoundTouch devices and compares it with our current implementation.
> **Reconciliation note (June 2026).** The categorised lists below had drifted
> from `pkg/client`. Verified against the code, these are **implemented** and have
> been re-marked (some were wrongly under "Not Yet Implemented", and a few were
> listed twice): the music-service set (`setMusicServiceAccount`,
> `setMusicServiceOAuthAccount`, `removeMusicServiceAccount`, `serviceAvailability`),
> presets (`storePreset`, `removePreset`), stations (`searchStation`, `addStation`,
> `removeStation`), `navigate`, the native stereo-pair group set (`getGroup`,
> `addGroup`, `removeGroup`, `updateGroup`), `speaker`, `playNotification`,
> `requestToken`, `notification`. Still **not** implemented (confirmed absent from
> `pkg/client`): `search`, `standby`, `powerManagement`, `lowPowerStandby`,
> `language`, `listMediaServers`, `bluetoothInfo`, `userPlayControl`, and the
> wireless / bluetooth-pairing / software-update / source-shortcut families.
## Discovery Summary
**Test Devices:**
- Device 1: `192.0.2.11:8090` (deviceID: `08DF1F0BA325`)
- Device 1: `192.0.2.11:8090` (deviceID: `AABBCCDDEE01`)
- Device 2: `192.0.2.10:8090` (deviceID: `AABBCCDDEEFF`)
**Key Findings:**
@@ -61,18 +74,18 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint
- `/audioproducttonecontrols` - Advanced tone controls (capability-dependent)
- `/audioproductlevelcontrols` - Speaker level controls (capability-dependent)
**System Info (3/3):**
- `/trackInfo` - Track information
- `/bluetoothInfo` - Bluetooth information
- `/recents` - Recently played content
**System Info (1/3):**
- `/recents` - Recently played content ✅
- `/trackInfo` - Track information ❌ non-functional on real devices (use `/now_playing`)
- `/bluetoothInfo` - Bluetooth information ❌ not implemented in `pkg/client`
### 🔶 Partially Implemented/Different Approach
### ✅ Stereo-Pair Group Management (native)
**Zone Management:**
- `/addGroup` ⚠️ - We use `/setZone` for group management
- `/removeGroup` ⚠️ - We use `/setZone` for group management
- `/getGroup` ⚠️ - We use `/getZone` for group information
- `/updateGroup` ⚠️ - We use `/setZone` for group updates
Implemented natively in `pkg/client` (in addition to the `/setZone` multiroom path):
- `/addGroup` ✅ - `AddGroup()`
- `/removeGroup` ✅ - `RemoveGroup()`
- `/getGroup` ✅ - `GetGroup()`
- `/updateGroup` ✅ - `UpdateGroup()`
### ❌ Not Yet Implemented (High Priority)
@@ -91,22 +104,22 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint
- `/selectLastSoundTouchSource` - Select last SoundTouch source
- `/selectLocalSource` - Select local source
**Music Services Integration:**
- `/setMusicServiceAccount` - Configure music service account
- `/setMusicServiceOAuthAccount` - OAuth account setup
- `/removeMusicServiceAccount` - Remove music service account
- `/serviceAvailability` - Check service availability
**Music Services Integration:** ✅ implemented (moved out of this list)
- ~~`/setMusicServiceAccount`~~ ✅ `SetMusicServiceAccount()`
- ~~`/setMusicServiceOAuthAccount`~~ ✅ `SetMusicServiceOAuthAccount()`
- ~~`/removeMusicServiceAccount`~~ ✅ `RemoveMusicServiceAccount()`
- ~~`/serviceAvailability`~~ ✅ `GetServiceAvailability()`
**Enhanced Presets:**
- `/storePreset` - Store new preset
- `/removePreset` - Remove existing preset
- ~~`/storePreset`~~ ✅ `StorePreset()` (also listed under Fully Implemented)
- ~~`/removePreset`~~ ✅ `RemovePreset()`
- `/bookmark` - Bookmark current content
- `/userRating` - User rating for content
**Station/Radio Management:**
- `/searchStation` - Search for stations
- `/addStation` - Add station to favorites
- `/removeStation` - Remove station from favorites
- ~~`/searchStation`~~ ✅ `SearchStation()`
- ~~`/addStation`~~ ✅ `AddStation()`
- ~~`/removeStation`~~ ✅ `RemoveStation()`
- `/genreStations` - Browse stations by genre
- `/stationInfo` - Station information
@@ -119,7 +132,7 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint
- `/systemtimeout` - System timeout settings
- `/powersaving` - Power saving configuration
- `/language` - Language settings
- `/speaker` - Speaker configuration
- ~~`/speaker`~~ ✅ `PlayTTS()` / `PlayURL()` (TTS & URL notifications; not "speaker configuration")
**Network & Connectivity:**
- `/performWirelessSiteSurvey` - WiFi site survey
@@ -133,7 +146,7 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint
**Content Discovery:**
- `/search` - Content search
- `/navigate` - Content navigation
- ~~`/navigate`~~ ✅ `Navigate()`
- `/listMediaServers` - List available media servers
### ❌ Not Yet Implemented (Low Priority)
@@ -156,9 +169,9 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint
**System Utilities:**
- `/userActivity` - User activity tracking
- `/requestToken` - Token management
- `/notification` - Notification management
- `/playNotification` - Play notification sound
- ~~`/requestToken`~~ ✅ `RequestToken()`
- ~~`/notification`~~ ✅ `NotifySourcesUpdated()`
- ~~`/playNotification`~~ ✅ `PlayNotification()`
- `/introspect` - System introspection
- `/test` - System test interface
@@ -229,7 +242,7 @@ This document provides a comprehensive analysis of the `/supportedURLs` endpoint
**Example Response Structure:**
```xml
<?xml version="1.0" encoding="UTF-8" ?>
<supportedURLs deviceID="08DF1F0BA325">
<supportedURLs deviceID="AABBCCDDEE01">
<URL location="/info" />
<URL location="/capabilities" />
<!-- ... 101 additional endpoints ... -->
docs/content/docs/appendix/UNIMPLEMENTED-ENDPOINTS.md
+40 -15
View File
@@ -3,13 +3,30 @@ title: "Unimplemented SoundTouch API Endpoints"
sidebar:
exclude: true
---
**Last Updated:** January 2026
**Last Updated:** June 2026 (reconciled against `pkg/client`)
**Source:** [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
**Current Implementation:** 35 endpoints (including preset & navigation management discovered via SoundTouch Plus Wiki)
**Current Implementation:** ~41 endpoints in `pkg/client` (see reconciliation note)
**Wiki Documentation:** 87 endpoints
**Implementation Gap:** 52 endpoints
**Implementation Gap:** ~46 endpoints
This document provides comprehensive information about SoundTouch API endpoints documented in the community wiki but not yet implemented in this Go library. All examples are based on real device responses and extensive community testing.
This document covers SoundTouch **device** WebServices API endpoints (the
speaker's local `:8090` API consumed by `pkg/client`) documented in the community
wiki but not yet implemented. It is **not** about the cloud-service router
(`cmd/soundtouch-service`); for that surface see the contract checklist
`tests/integration/http-client/COVERAGE.md`. Examples are based on real device
responses and community testing.
> **Reconciliation note (June 2026).** Verified against `pkg/client`. Since the
> last update these are **now implemented** and have been re-marked below:
> `setMusicServiceAccount` / `removeMusicServiceAccount` (`SetMusicServiceAccount`,
> `RemoveMusicServiceAccount`) and the full stereo-pair group set
> `getGroup` / `addGroup` / `removeGroup` / `updateGroup`
> (`GetGroup`, `AddGroup`, `RemoveGroup`, `UpdateGroup`). The priority-matrix
> counts further down are historical and have not all been recomputed; trust the
> per-endpoint ✅ markers over the section totals. Endpoints still listed as
> candidates (e.g. `/search`, `/standby`, `/powerManagement`, `/bluetoothInfo`,
> `/language`, `/listMediaServers`) were confirmed absent from `pkg/client`
> (some appear only in test fixtures).
---
@@ -69,12 +86,15 @@ Specialized hardware-specific features.
- CLI command: `preset select --slot <1-6>`
- Alternative: Direct key commands (`SendKey("PRESET_1")` etc.)
### Music Service Management
### ~~Music Service Management~~ ✅ **IMPLEMENTED**
Critical for streaming service integration.
#### POST /setMusicServiceAccount 🔥 **CRITICAL**
#### ~~POST /setMusicServiceAccount~~ ✅ **IMPLEMENTED**
Adds a music service account to the sources list.
**Status:** **COMPLETE** - `pkg/client` exposes `SetMusicServiceAccount(...)`
(and `SetMusicServiceOAuthAccount(...)` for OAuth sources like Spotify/Amazon).
**Request Examples:**
Pandora Service:
@@ -111,9 +131,11 @@ NAS Music Library:
- Note the `/0` suffix for STORED_MUSIC user names
- Spotify requires PREMIUM account for most operations
#### POST /removeMusicServiceAccount 🔥 **CRITICAL**
#### ~~POST /removeMusicServiceAccount~~ ✅ **IMPLEMENTED**
Removes an existing music service account.
**Status:** **COMPLETE** - `pkg/client` exposes `RemoveMusicServiceAccount(...)`.
**Request Examples:**
Remove Pandora:
@@ -630,9 +652,12 @@ Selects LOCAL source (only way to select LOCAL on some devices).
<status>/selectLocalSource</status>
```
### Group Management (ST-10 Stereo Pairs Only)
### ~~Group Management (ST-10 Stereo Pairs Only)~~ ✅ **IMPLEMENTED**
#### GET /getGroup 📊 **MEDIUM**
**Status:** **COMPLETE** - the full stereo-pair set is implemented in `pkg/client`:
`GetGroup()`, `AddGroup()`, `RemoveGroup()`, `UpdateGroup()`.
#### ~~GET /getGroup~~ ✅ **IMPLEMENTED**
Gets current stereo pair configuration.
**Response Example (paired):**
@@ -662,7 +687,7 @@ Gets current stereo pair configuration.
<group />
```
#### POST /addGroup 📊 **MEDIUM**
#### ~~POST /addGroup~~ ✅ **IMPLEMENTED**
Creates new stereo pair group.
**Request Example:**
@@ -688,7 +713,7 @@ Creates new stereo pair group.
**Response:** Same as GET /getGroup
**WebSocket Event:** `groupUpdated` sent to both devices
#### GET /removeGroup 📊 **MEDIUM**
#### ~~GET /removeGroup~~ ✅ **IMPLEMENTED**
Removes existing stereo pair group.
**Response:**
@@ -698,7 +723,7 @@ Removes existing stereo pair group.
**WebSocket Event:** `groupUpdated` sent to both devices
#### POST /updateGroup 📊 **MEDIUM**
#### ~~POST /updateGroup~~ ✅ **IMPLEMENTED**
Updates stereo pair group name.
**Request Example:**
@@ -982,8 +1007,8 @@ func TestDeviceCompatibility(t *testing.T) {
### Phase 1: Essential Features (4 weeks)
1. ✅ **Preset Management**: ~~`storePreset`, `removePreset`, `selectPreset`~~ (IMPLEMENTED)
2. **Music Services**: `setMusicServiceAccount`, `removeMusicServiceAccount`
3. ✅ **Content Discovery**: ~~`navigate`, `search`~~ (IMPLEMENTED), `recents`
2. ✅ **Music Services**: ~~`setMusicServiceAccount`, `removeMusicServiceAccount`~~ (IMPLEMENTED)
3. ✅ **Content Discovery**: ~~`navigate`~~ (IMPLEMENTED), `search`, `recents`
4. ✅ **Station Management**: ~~`searchStation`, `addStation`, `removeStation`~~ (IMPLEMENTED)
5. **Enhanced Controls**: `userPlayControl`, `userRating`
@@ -996,7 +1021,7 @@ func TestDeviceCompatibility(t *testing.T) {
### Phase 3: Advanced Features (3 weeks)
1. **Bluetooth**: `enterBluetoothPairing`, `clearBluetoothPaired`
2. **Software Updates**: `swUpdateCheck`, `swUpdateQuery`
3. **Stereo Pairs**: `getGroup`, `addGroup`, `removeGroup`, `updateGroup`
3. ✅ **Stereo Pairs**: ~~`getGroup`, `addGroup`, `removeGroup`, `updateGroup`~~ (IMPLEMENTED)
4. **Source Shortcuts**: `selectLastSource`, `selectLastSoundTouchSource`
### Phase 4: Specialized Features (2 weeks)