Bose-SoundTouch/docs/reference/SOURCE-SELECTION.md

# 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:**
```xml
<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)

## Client Library Usage

### Basic Source Selection

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

// Create client
config := client.ClientConfig{
    Host: "192.168.1.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:

```go
// 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:

```go
// 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

```go
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

```bash
# Select source using generic method
soundtouch-cli -host 192.168.1.100 -select-source SPOTIFY -source-account "your_account"

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

### Real Examples

```bash
# Check available sources first
soundtouch-cli -host 192.168.1.100 -sources

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

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

# Select AUX input
soundtouch-cli -host 192.168.1.100 -aux
```

### CLI Flags

| Flag | Description | Example |
|------|-------------|---------|
| `-select-source <source>` | Select audio source | `-select-source SPOTIFY` |
| `-source-account <account>` | Account for streaming services | `-source-account "user123"` |
| `-spotify` | Select Spotify source | `-spotify -source-account "user"` |
| `-bluetooth` | Select Bluetooth source | `-bluetooth` |
| `-aux` | Select 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:

```bash
soundtouch-cli -host 192.168.1.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

```go
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

```go
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

| Code | Name | Description | Solution |
|------|------|-------------|----------|
| 1005 | UNKNOWN_SOURCE_ERROR | Invalid or unavailable source | Check available sources first |
| 1006 | SOURCE_UNAVAILABLE | Source temporarily unavailable | Try again later |
| 1007 | ACCOUNT_ERROR | Invalid account for source | Check account name format |

### Troubleshooting Tips

1. **Check Source Availability**
   ```bash
   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:
```bash
go test ./pkg/client -v -run ".*SelectSource.*"
```

### Integration Tests

Test with real hardware:
```bash
SOUNDTOUCH_TEST_HOST=192.168.1.100 go test ./pkg/client -v -run ".*Integration.*"
```

### Manual Testing

```bash
# 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

- **[API Endpoints Overview](API-Endpoints-Overview.md)** - Complete API reference
- **[Sources](../pkg/models/sources.go)** - Source model implementation  
- **[Now Playing](../pkg/models/nowplaying.go)** - ContentItem model
- **[Client Usage Examples](../cmd/soundtouch-cli/main.go)** - CLI implementation reference

---

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