Bose-SoundTouch/docs/archive/WIKI-IMPLEMENTATION-PLAN.md

SoundTouch API Wiki Implementation Plan

Date: January 2026
Source: SoundTouch Plus Wiki
Target: Complete implementation of 64 additional endpoints from wiki documentation

Project Overview

Scope

Implement 64 additional API endpoints documented in the SoundTouch Plus Wiki to achieve comprehensive SoundTouch ecosystem coverage.

Current Status

• ✅ Implemented: 23 endpoints (core functionality)
• 🎯 Target: 87 endpoints (comprehensive functionality)
• 📈 Expansion: 3.8x increase in API coverage

---

Implementation Phases

Phase 1: Essential User Features (4 weeks)

Priority: CRITICAL
Endpoints: 20
User Impact: HIGH

1.1 Preset Management (Week 1)

Essential for user experience - save and manage favorite stations/playlists.

Endpoints to Implement:

// pkg/api/presets.go (new file)
func (c *Client) StorePreset(id int, content ContentItem) error
func (c *Client) RemovePreset(id int) error  
func (c *Client) SelectPreset(id int) error

XML Structures:

<!-- Store Preset Request -->
<preset id="3" createdOn="1701220500" updatedOn="1701220500">
  <ContentItem source="TUNEIN" type="stationurl" location="/v1/playback/station/s309605" sourceAccount="" isPresetable="true">
    <itemName>K-LOVE 90s</itemName>
    <containerArt>http://cdn-profiles.tunein.com/s309605/images/logog.png</containerArt>
  </ContentItem>
</preset>

<!-- Remove Preset Request -->
<preset id="4"></preset>

WebSocket Events:

• presetsUpdated - Triggered on store/remove operations

1.2 Music Service Management (Week 1-2)

Critical for streaming service integration - Spotify, Pandora, NAS libraries.

Endpoints to Implement:

// pkg/api/music_services.go (new file)
func (c *Client) SetMusicServiceAccount(source, user, password, displayName string) error
func (c *Client) RemoveMusicServiceAccount(source, user string) error
func (c *Client) ListMediaServers() (*MediaServerList, error)
func (c *Client) GetServiceAvailability() (*ServiceAvailability, error)

Service Types:

type MusicService string

const (
    ServicePandora     MusicService = "PANDORA"
    ServiceSpotify     MusicService = "SPOTIFY" 
    ServiceStoredMusic MusicService = "STORED_MUSIC"
    ServiceLocalMusic  MusicService = "LOCAL_MUSIC"
)

type MediaServer struct {
    ID           string `xml:"id,attr"`
    MAC          string `xml:"mac,attr"`
    IP           string `xml:"ip,attr"`
    Manufacturer string `xml:"manufacturer,attr"`
    ModelName    string `xml:"model_name,attr"`
    FriendlyName string `xml:"friendly_name,attr"`
    Location     string `xml:"location,attr"`
}

XML Examples:

<!-- Pandora Account Setup -->
<credentials source="PANDORA" displayName="Pandora Music Service">
  <user>YourPandoraUserId</user>
  <pass>YourPandoraPassword$1pd</pass>
</credentials>

<!-- NAS Library Setup -->
<credentials source="STORED_MUSIC" displayName="My NAS Media Library:">
  <user>d09708a1-5953-44bc-a413-123456789012/0</user>
  <pass />
</credentials>

1.3 Content Discovery (Week 2-3)

Essential for browsing music libraries and searching content.

Endpoints to Implement:

// pkg/api/content.go (new file)
func (c *Client) Navigate(source, sourceAccount string, options NavigateOptions) (*NavigateResponse, error)
func (c *Client) Search(source, sourceAccount, searchTerm string, options SearchOptions) (*SearchResponse, error)
func (c *Client) GetRecents() (*RecentsResponse, error) // ✅ IMPLEMENTED
func (c *Client) Introspect(source, sourceAccount string) (*IntrospectResponse, error) // ✅ IMPLEMENTED

Data Structures:

type NavigateOptions struct {
    StartItem int            `xml:"startItem"`
    NumItems  int            `xml:"numItems"`
    Item      *ContentItem   `xml:"item,omitempty"`
    Sort      string         `xml:"sort,attr,omitempty"`
    Menu      string         `xml:"menu,attr,omitempty"`
}

type NavigateResponse struct {
    Source       string        `xml:"source,attr"`
    SourceAccount string       `xml:"sourceAccount,attr"`
    TotalItems   int           `xml:"totalItems"`
    Items        []ContentItem `xml:"items>item"`
}

type SearchOptions struct {
    StartItem int    `xml:"startItem"`
    NumItems  int    `xml:"numItems"`
    Filter    string `xml:"searchTerm,attr,omitempty"`  // "track", "artist", "album"
}

1.4 Station Management (Week 3)

Pandora and other music service station management.

Endpoints to Implement:

// pkg/api/stations.go (new file)
func (c *Client) SearchStations(source, sourceAccount, searchTerm string) (*StationSearchResponse, error)
func (c *Client) AddStation(source, sourceAccount, token, name string) error
func (c *Client) RemoveStation(content ContentItem) error

1.5 Enhanced Playback Control (Week 4)

Advanced playback and rating controls.

Endpoints to Implement:

// pkg/api/playback.go (extend existing)
func (c *Client) SendPlayControl(action PlayControlAction) error
func (c *Client) RateCurrentTrack(rating RatingValue) error

Enums:

type PlayControlAction string
const (
    PlayControlPause     PlayControlAction = "PAUSE_CONTROL"
    PlayControlPlay      PlayControlAction = "PLAY_CONTROL" 
    PlayControlPlayPause PlayControlAction = "PLAY_PAUSE_CONTROL"
    PlayControlStop      PlayControlAction = "STOP_CONTROL"
)

type RatingValue string
const (
    RatingUp   RatingValue = "UP"
    RatingDown RatingValue = "DOWN"
)

1.6 Power Management (Week 4)

Essential for smart home integration.

Endpoints to Implement:

// pkg/api/power.go (new file)
func (c *Client) Standby() error
func (c *Client) GetPowerState() (*PowerState, error)
func (c *Client) SetLowPowerStandby() error

---

Phase 2: Smart Home Integration (3 weeks)

Priority: HIGH
Endpoints: 15
User Impact: MEDIUM-HIGH

2.1 Notification System (Week 1)

Text-to-speech and URL playback for smart home notifications.

Endpoints to Implement:

// pkg/api/notifications.go (new file)
func (c *Client) PlayTTSMessage(message string, options TTSOptions) error
func (c *Client) PlayURL(url string, options PlayOptions) error
func (c *Client) PlayNotificationBeep() error

Data Structures:

type TTSOptions struct {
    VolumeLevel int    `xml:"volume,omitempty"`
    Language    string `xml:"tl,omitempty"`     // "EN", "DE", etc.
    AppKey      string `xml:"app_key"`
    Service     string `xml:"service"`
    Message     string `xml:"message"`
    Reason      string `xml:"reason"`
}

type PlayOptions struct {
    VolumeLevel int    `xml:"volume,omitempty"`
    AppKey      string `xml:"app_key"`
    Service     string `xml:"service"`
    Message     string `xml:"message"`
    Reason      string `xml:"reason"`
}

XML Examples:

<!-- TTS Message -->
<play_info>
  <url>http://translate.google.com/translate_tts?ie=UTF-8&amp;tl=EN&amp;client=tw-ob&amp;q=There%20is%20activity%20at%20the%20front%20door.</url>
  <app_key>YourAppKey</app_key>
  <service>TTS Notification</service>
  <message>Google TTS</message>
  <reason>There is activity at the front door.</reason>
  <volume>70</volume>
</play_info>

2.2 Network Management (Week 2)

WiFi configuration and network information.

Endpoints to Implement:

// pkg/api/network.go (extend existing)
func (c *Client) PerformWiFiSurvey() (*WiFiSurveyResponse, error)
func (c *Client) AddWiFiProfile(ssid, password string, securityType SecurityType) error
func (c *Client) GetActiveWiFiProfile() (*WiFiProfile, error)
func (c *Client) GetNetworkStats() (*NetworkStats, error)

Security Types:

type SecurityType string
const (
    SecurityNone       SecurityType = "none"
    SecurityWEP        SecurityType = "wep"
    SecurityWPATKIP    SecurityType = "wpatkip"
    SecurityWPAAES     SecurityType = "wpaaes"
    SecurityWPA2TKIP   SecurityType = "wpa2tkip" 
    SecurityWPA2AES    SecurityType = "wpa2aes"
    SecurityWPAOrWPA2  SecurityType = "wpa_or_wpa2"  // Recommended
)

2.3 Bluetooth Management (Week 2)

Bluetooth pairing and connection management.

Endpoints to Implement:

// pkg/api/bluetooth.go (new file)
func (c *Client) EnterBluetoothPairing() error
func (c *Client) ClearBluetoothPairings() error
func (c *Client) GetBluetoothInfo() (*BluetoothInfo, error)

2.4 Language and System Configuration (Week 3)

Device language and system settings.

Endpoints to Implement:

// pkg/api/system.go (new file)
func (c *Client) GetLanguage() (LanguageCode, error)
func (c *Client) SetLanguage(lang LanguageCode) error
func (c *Client) GetConfigurationStatus() (*ConfigurationStatus, error)
func (c *Client) GetSystemTimeout() (*SystemTimeout, error)

Language Codes:

type LanguageCode int
const (
    LangDanish              LanguageCode = 1
    LangGerman              LanguageCode = 2
    LangEnglish             LanguageCode = 3
    LangSpanish             LanguageCode = 4
    LangFrench              LanguageCode = 5
    LangItalian             LanguageCode = 6
    LangDutch               LanguageCode = 7
    LangSwedish             LanguageCode = 8
    LangJapanese            LanguageCode = 9
    LangSimplifiedChinese   LanguageCode = 10
    LangTraditionalChinese  LanguageCode = 11
    LangKorean              LanguageCode = 12
)

---

Phase 3: Advanced Features (4 weeks)

Priority: MEDIUM
Endpoints: 19
User Impact: MEDIUM

3.1 Stereo Pair Management (Week 1)

ST-10 specific left/right speaker pairing.

Endpoints to Implement:

// pkg/api/groups.go (new file)
func (c *Client) GetStereoPairStatus() (*StereoPair, error)
func (c *Client) CreateStereoPair(leftDeviceID, rightDeviceID string, name string) (*StereoPair, error)
func (c *Client) RemoveStereoPair() error
func (c *Client) UpdateStereoPairName(groupID, newName string) (*StereoPair, error)

Data Structures:

type StereoPair struct {
    ID              string      `xml:"id,attr"`
    Name            string      `xml:"name"`
    MasterDeviceID  string      `xml:"masterDeviceId"`
    Roles           []GroupRole `xml:"roles>groupRole"`
    SenderIPAddress string      `xml:"senderIPAddress"`
    Status          string      `xml:"status"`
}

type GroupRole struct {
    DeviceID  string `xml:"deviceId"`
    Role      string `xml:"role"`      // "LEFT", "RIGHT"
    IPAddress string `xml:"ipAddress"`
}

3.2 Software Update Management (Week 2)

Firmware update checking and management.

Endpoints to Implement:

// pkg/api/updates.go (new file)
func (c *Client) CheckSoftwareUpdate() (*UpdateInfo, error)
func (c *Client) GetUpdateStatus() (*UpdateStatus, error)
func (c *Client) StartSoftwareUpdate() error
func (c *Client) AbortSoftwareUpdate() error

3.3 Advanced Audio Features (Week 3)

Advanced DSP and speaker configuration.

Endpoints to Implement:

// pkg/api/audio_advanced.go (new file)
func (c *Client) GetDSPMonoStereo() (*DSPMonoStereoConfig, error)
func (c *Client) SetDSPMonoStereo(enabled bool) error
func (c *Client) GetAudioSpeakerAttributes() (*SpeakerAttributes, error)
func (c *Client) GetRebroadcastLatencyMode() (*LatencyMode, error)

3.4 Source Selection Shortcuts (Week 4)

Quick source switching utilities.

Endpoints to Implement:

// pkg/api/sources.go (extend existing)
func (c *Client) SelectLastSource() error
func (c *Client) SelectLastSoundTouchSource() error
func (c *Client) SelectLastWiFiSource() error
func (c *Client) SelectLocalSource() error

---

Phase 4: Professional Features (2 weeks)

Priority: LOW
Endpoints: 10
User Impact: LOW

4.1 HDMI and Product Controls

ST-300 specific HDMI and product controls.

Endpoints to Implement:

// pkg/api/product.go (new file)
func (c *Client) GetProductCECHDMIControl() (*CECHDMIControl, error)
func (c *Client) SetProductCECHDMIControl(config CECHDMIControl) error
func (c *Client) GetProductHDMIAssignmentControls() (*HDMIAssignmentControls, error)
func (c *Client) SetProductHDMIAssignmentControls(config HDMIAssignmentControls) error

4.2 System Administration

Advanced system configuration and diagnostics.

Endpoints to Implement:

// pkg/api/admin.go (new file)
func (c *Client) GetCriticalErrors() (*CriticalErrors, error)
func (c *Client) PerformFactoryDefault() error
func (c *Client) GetBCOReset() (*BCOResetStatus, error)
func (c *Client) SetBCOReset(enabled bool) error

---

Implementation Guidelines

File Structure

pkg/
├── api/
│   ├── presets.go          (Phase 1.1)
│   ├── music_services.go   (Phase 1.2)
│   ├── content.go          (Phase 1.3)
│   ├── stations.go         (Phase 1.4)
│   ├── playback.go         (Phase 1.5 - extend existing)
│   ├── power.go            (Phase 1.6)
│   ├── notifications.go    (Phase 2.1)
│   ├── network.go          (Phase 2.2 - extend existing)
│   ├── bluetooth.go        (Phase 2.3)
│   ├── system.go           (Phase 2.4)
│   ├── groups.go           (Phase 3.1)
│   ├── updates.go          (Phase 3.2)
│   ├── audio_advanced.go   (Phase 3.3)
│   ├── sources.go          (Phase 3.4 - extend existing)
│   ├── product.go          (Phase 4.1)
│   └── admin.go            (Phase 4.2)
├── types/
│   ├── presets.go
│   ├── music_services.go
│   ├── content.go
│   ├── notifications.go
│   ├── network.go
│   ├── bluetooth.go
│   ├── system.go
│   ├── groups.go
│   ├── updates.go
│   └── product.go
└── websocket/
    └── events.go           (extend with new event types)

Error Handling Strategy

Device Capability Checking

// Always check capabilities before calling advanced features
func (c *Client) callAdvancedEndpoint() error {
    capabilities, err := c.GetCapabilities()
    if err != nil {
        return fmt.Errorf("failed to get capabilities: %w", err)
    }
    
    if !capabilities.SupportsFeature("targetFeature") {
        return ErrFeatureNotSupported
    }
    
    // Proceed with endpoint call
}

Timeout Handling

// Some endpoints timeout on unsupported devices
func (c *Client) callWithTimeout(endpoint string) error {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    
    // Make request with context
    if err := c.makeRequest(ctx, endpoint); err != nil {
        if errors.Is(err, context.DeadlineExceeded) {
            return ErrEndpointNotSupported
        }
        return err
    }
    return nil
}

Testing Strategy

Unit Tests

• XML marshaling/unmarshaling for all new types
• Error handling scenarios
• Input validation

Integration Tests

• Real device testing for each endpoint
• Device compatibility matrix validation
• WebSocket event verification

Device Matrix Testing

var deviceTests = []struct {
    model     string
    endpoints []string
    supported bool
}{
    {"ST-10", []string{"/playNotification", "/getGroup"}, true},
    {"ST-300", []string{"/audiodspcontrols", "/productcechdmicontrol"}, true},
    {"ST-10", []string{"/audiodspcontrols"}, false},
}

WebSocket Event Integration

Extend Existing Event System

// pkg/websocket/events.go (extend existing)
type WebSocketEvent struct {
    // Existing events...
    VolumeUpdated      *VolumeUpdate      `xml:"volumeUpdated"`
    NowPlayingUpdated  *NowPlayingUpdate  `xml:"nowPlayingUpdated"`
    
    // New events from wiki
    PresetsUpdated     *PresetsUpdate     `xml:"presetsUpdated"`
    GroupUpdated       *GroupUpdate       `xml:"groupUpdated"`
    AudioDSPUpdated    *AudioDSPUpdate    `xml:"audiodspcontrols"`
    ToneControlsUpdated *ToneUpdate       `xml:"audioproducttonecontrols"`
    LevelControlsUpdated *LevelUpdate     `xml:"audioproductlevelcontrols"`
}

Documentation Integration

Wiki Examples in Go Docs

// StorePreset saves a preset to the device (maximum 6 presets).
//
// Example from SoundTouch Plus Wiki:
//   preset := PresetData{
//       ID: 3,
//       ContentItem: ContentItem{
//           Source:      "TUNEIN",
//           Type:        "stationurl", 
//           Location:    "/v1/playback/station/s309605",
//           IsPresetable: true,
//           ItemName:    "K-LOVE 90s",
//           ContainerArt: "http://cdn-profiles.tunein.com/s309605/images/logog.png",
//       },
//   }
//   err := client.StorePreset(preset.ID, preset.ContentItem)
//
// This generates a presetsUpdated WebSocket event.
func (c *Client) StorePreset(id int, content ContentItem) error

---

Success Metrics

Phase 1 Completion Criteria

• All 20 endpoints implemented with full XML support
• Comprehensive unit test coverage (>90%)
• Real device testing on ST-10 and ST-300
• Documentation with wiki examples
• WebSocket event integration

Phase 2 Completion Criteria

• Smart home integration examples
• Network management automation
• Notification system with TTS
• Bluetooth management
• Language configuration

Phase 3 Completion Criteria

• Stereo pair management
• Software update automation
• Advanced audio features
• Source switching utilities

Phase 4 Completion Criteria

• Professional HDMI controls
• System administration features
• Complete device capability matrix
• Production deployment guide

Overall Success Metrics

• ✅ 87+ total endpoints implemented
• ✅ Complete SoundTouch ecosystem coverage
• ✅ Production-ready error handling
• ✅ Comprehensive documentation
• ✅ Real-world testing validation
• ✅ Community collaboration with SoundTouch Plus project

---

Risk Mitigation

Technical Risks

1. Device Compatibility: Test each endpoint on multiple device models
2. Timeout Issues: Implement capability checking before endpoint calls
3. XML Complexity: Thorough marshaling/unmarshaling tests
4. WebSocket Events: Validate event generation for all POST operations

Schedule Risks

1. Resource Availability: Prioritize high-impact endpoints first
2. Device Access: Arrange access to multiple SoundTouch models
3. Complexity Underestimation: Buffer time in each phase
4. Integration Issues: Continuous integration testing

Quality Risks

1. Incomplete Testing: Mandate real device validation
2. Poor Documentation: Use wiki examples in all documentation
3. Breaking Changes: Maintain backward compatibility
4. Performance: Benchmark all new endpoints

---

Conclusion

This implementation plan leverages the comprehensive SoundTouch Plus Wiki to transform our library from basic device control to complete ecosystem management. The phased approach prioritizes user-facing features while ensuring quality and maintainability.

Key Benefits:

• 🎯 3.8x API Coverage Expansion: From 23 to 87+ endpoints
• 🏠 Complete Smart Home Integration: Power, notifications, network management
• 🎵 Full Music Service Support: Spotify, Pandora, NAS libraries
• ✅ Production-Ready Implementation: Real-world tested examples
• 📚 Comprehensive Documentation: Wiki integration and examples

Timeline: 13 weeks total for complete implementation Resources: 1-2 developers with access to multiple SoundTouch devices Outcome: Industry-leading SoundTouch API library with complete ecosystem support

This plan transforms our library into the definitive Go implementation for SoundTouch integration, suitable for everything from basic home automation to professional audio installations.