Skip to content
Introduction
Technical Reference
Source Selection Guide

Source Selection Guide

Source Selection Guide

Overview

The Bose SoundTouch Go client provides comprehensive source selection functionality through the POST /select endpoint. This feature allows you to switch between different audio sources like Spotify, Bluetooth, AUX input, and various streaming services.

Implementation Status

✅ Complete - All source selection functionality implemented and tested

  • Generic source selection with SelectSource()
  • Convenience methods for popular sources
  • CLI flags for easy source switching
  • Real device validation with SoundTouch hardware
  • Comprehensive error handling

API Endpoint

POST /select

Purpose: Select an audio source for playback

Request Format:

<ContentItem source="SPOTIFY" sourceAccount="user_account">
  <itemName>Spotify</itemName>
</ContentItem>

Response: HTTP 200 OK (no body) on success

Supported Sources:

  • SPOTIFY - Spotify streaming service
  • BLUETOOTH - Bluetooth audio input
  • AUX - Auxiliary input (3.5mm jack)
  • TUNEIN - TuneIn internet radio
  • PANDORA - Pandora streaming service
  • AMAZON - Amazon Music
  • IHEARTRADIO - iHeartRadio streaming
  • STORED_MUSIC - Local/network stored music
  • AIRPLAY - Apple AirPlay (device dependent)
  • RADIO_BROWSER - RadioBrowser internet radio directory

Client Library Usage

Basic Source Selection 

import "github.com/gesellix/bose-soundtouch/pkg/client"

// Create client
config := client.ClientConfig{
    Host: "192.0.2.100",
    Port: 8090,
}
c := client.NewClient(config)

// Select a source
err := c.SelectSource("SPOTIFY", "your_spotify_account")
if err != nil {
    fmt.Printf("Failed to select source: %v\n", err)
}

Convenience Methods

For popular sources, use the convenience methods:

// Select Spotify
err := c.SelectSpotify("your_account")

// Select Bluetooth
err := c.SelectBluetooth()

// Select AUX input
err := c.SelectAux()

// Select TuneIn
err := c.SelectTuneIn("tunein_account")

// Select Pandora
err := c.SelectPandora("pandora_account")

Source Selection from Available Sources

First get available sources, then select from them:

// Get available sources
sources, err := c.GetSources()
if err != nil {
    return fmt.Errorf("failed to get sources: %w", err)
}

// Find and select a ready Spotify source
spotifySources := sources.GetReadySpotifySources()
if len(spotifySources) > 0 {
    err := c.SelectSourceFromItem(&spotifySources[0])
    if err != nil {
        return fmt.Errorf("failed to select Spotify: %w", err)
    }
}

// Or use helper methods
if sources.HasBluetooth() {
    err := c.SelectBluetooth()
    if err != nil {
        return fmt.Errorf("failed to select Bluetooth: %w", err)
    }
}

Error Handling 

err := c.SelectSource("INVALID_SOURCE", "")
if err != nil {
    // Check for API errors
    if apiErr, ok := err.(*models.APIError); ok {
        fmt.Printf("API Error: %s (code: %d)\n", apiErr.Message, apiErr.Code)
    } else {
        fmt.Printf("General error: %v\n", err)
    }
}

CLI Usage

Basic Commands 

# Select source using generic method
soundtouch-cli -host 192.0.2.100 -select-source SPOTIFY -source-account "your_account"

# Select source with convenience flags
soundtouch-cli -host 192.0.2.100 -spotify -source-account "your_account"
soundtouch-cli -host 192.0.2.100 -bluetooth
soundtouch-cli -host 192.0.2.100 -aux

Real Examples 

# Check available sources first
soundtouch-cli -host 192.0.2.100 -sources

# Select Spotify with account
soundtouch-cli -host 192.0.2.100 -spotify -source-account "your_account"

# Select TuneIn
soundtouch-cli -host 192.0.2.100 -select-source TUNEIN

# Select AUX input
soundtouch-cli -host 192.0.2.100 -aux

CLI Flags

FlagDescriptionExample
-select-source <source>Select audio source-select-source SPOTIFY
-source-account <account>Account for streaming services-source-account "user123"
-spotifySelect Spotify source-spotify -source-account "user"
-bluetoothSelect Bluetooth source-bluetooth
-auxSelect AUX input-aux

Source Account Information

When Source Accounts are Required

  • Spotify: Required for multi-account setups
  • Pandora: Required for account-based access
  • TuneIn: Optional, may improve personalization
  • Amazon Music: Required for account access
  • Bluetooth/AUX: Not required (leave empty)

Finding Source Accounts

Use the sources endpoint to discover available accounts:

soundtouch-cli -host 192.0.2.100 -sources

This shows account names for each source:

Ready Sources:
  • user+spotify@example.com (user) [Remote, Multiroom, Streaming]

In this example:

  • Full account: user+spotify@example.com
  • Short account: user (often works better)

Integration Examples

Smart Source Selection 

func selectBestAvailableSource(client *client.Client) error {
    sources, err := client.GetSources()
    if err != nil {
        return err
    }

    // Prefer Spotify if available
    if sources.HasSpotify() {
        spotifySources := sources.GetReadySpotifySources()
        return client.SelectSourceFromItem(&spotifySources[0])
    }

    // Fall back to TuneIn
    if sources.HasSource("TUNEIN") {
        tuneInSources := sources.GetSourcesByType("TUNEIN")
        for _, src := range tuneInSources {
            if src.Status.IsReady() {
                return client.SelectSourceFromItem(&src)
            }
        }
    }

    // Last resort: AUX if available
    if sources.HasAux() {
        return client.SelectAux()
    }

    return fmt.Errorf("no suitable sources available")
}

Source-Specific Configuration 

type SourceConfig struct {
    PreferredSources []string
    Accounts         map[string]string
}

func selectWithConfig(client *client.Client, config SourceConfig) error {
    sources, err := client.GetSources()
    if err != nil {
        return err
    }

    for _, preferred := range config.PreferredSources {
        if sources.HasSource(preferred) {
            account := config.Accounts[preferred]
            return client.SelectSource(preferred, account)
        }
    }

    return fmt.Errorf("none of the preferred sources are available")
}

Error Codes and Troubleshooting

Common Error Codes

CodeNameDescriptionSolution
1005UNKNOWN_SOURCE_ERRORInvalid or unavailable sourceCheck available sources first
1006SOURCE_UNAVAILABLESource temporarily unavailableTry again later
1007ACCOUNT_ERRORInvalid account for sourceCheck account name format

Troubleshooting Tips

  1. Check Source Availability

    soundtouch-cli -host <ip> -sources

  2. Verify Account Names

    • Use short account names when possible
    • Check for special characters in account names
    • Some sources don’t require accounts

  3. Source-Specific Issues

    • Spotify: Ensure account is logged in via Spotify app
    • Bluetooth: Check device pairing status
    • AUX: Verify physical connection

  4. Network Issues

    • Ensure device is on same network
    • Check firewall settings
    • Verify port 8090 is accessible

Testing

Unit Tests

Run all source selection tests:

go test ./pkg/client -v -run ".*SelectSource.*"

Integration Tests

Test with real hardware:

SOUNDTOUCH_TEST_HOST=192.0.2.100 go test ./pkg/client -v -run ".*Integration.*"

Manual Testing 

# Test discovery and source selection
soundtouch-cli -discover
soundtouch-cli -host <discovered-ip> -sources
soundtouch-cli -host <discovered-ip> -spotify -source-account "account"
soundtouch-cli -host <discovered-ip> -nowplaying  # Verify selection

Performance

Benchmarks

Source selection typically completes in:

  • Local Network: 100-300ms
  • Wi-Fi: 200-500ms
  • Error Cases: 50-100ms (validation)

Optimization Tips

  1. Cache Source Information: Get sources once, reuse for selections
  2. Validate Before Selecting: Check source availability first
  3. Use Convenience Methods: Slightly faster than generic selection
  4. Handle Errors Gracefully: Implement fallback source selection

API Compliance

XML Format Requirements

The implementation follows the official SoundTouch API:

  • Uses ContentItem XML structure
  • Sets appropriate source and sourceAccount attributes
  • Includes human-readable itemName for better UX
  • Handles all documented source types

Known Limitations

  1. Source Dependencies: Some sources require external app authentication
  2. Account Format Variations: Different devices may expect different account formats
  3. Source Availability: Dynamic based on network and service status

Related Documentation

Implementation Date: 2026-01-09
Status: ✅ Complete and tested
Real Device Validation: SoundTouch 10, SoundTouch 20

Last updated on
SoundTouch Speaker Endpoint DocumentationSpotify Account Addition Technical Reference