Bose-SoundTouch/examples/content-selection/README.md

Content Selection Example

This example demonstrates the advanced content selection features of the Bose SoundTouch Go client, including support for LOCAL_INTERNET_RADIO with streamUrl format, LOCAL_MUSIC, and STORED_MUSIC content.

Features Demonstrated

1. LOCAL_INTERNET_RADIO with streamUrl Format

• Uses proxy server format: http://contentapi.gmuth.de/station.php?name=StationName&streamUrl=ActualStreamURL
• Supports complex radio station metadata
• Artwork and station information

2. LOCAL_INTERNET_RADIO Direct Streams

• Direct HTTP/HTTPS stream URLs
• Simple internet radio playback
• MP3 and other audio format support

3. LOCAL_MUSIC Content

• SoundTouch App Media Server content
• Albums, tracks, artists, playlists
• Requires local SoundTouch Media Server running

4. STORED_MUSIC Content

• UPnP/DLNA media server content
• NAS libraries and Windows Media Player sharing
• Network-attached storage music libraries

5. Generic ContentItem Selection

• Direct ContentItem object creation
• Maximum flexibility for any content type
• All SoundTouch sources supported

Prerequisites

• SoundTouch device on your network
• Device IP address
• Go 1.21+ installed

Optional (for specific examples):

• LOCAL_MUSIC: SoundTouch App Media Server running on a computer
• STORED_MUSIC: UPnP/DLNA media server (Windows Media Player, NAS, etc.)

Usage

# Build and run
go run main.go <device_ip>

# Example
go run main.go 192.168.1.100

Example Output

🎵 SoundTouch Content Selection Example
📱 Device: 192.168.1.100:8090

📻 Step 1: Demonstrating LOCAL_INTERNET_RADIO with streamUrl format...
  📡 Using streamUrl format with proxy server...
      Station: Antenne Chillout
      Proxy URL: http://contentapi.gmuth.de/station.php?name=Antenne%20Chillout&streamUrl=https://stream.antenne.de/chillout/stream/aacp
  ✅ Successfully selected internet radio with streamUrl format

  🎵 Now Playing:
      Title: Antenne Chillout
      Source: LOCAL_INTERNET_RADIO
      Status: Playing
      Location: http://contentapi.gmuth.de/station.php?name=Antenne%20Chillout&streamUrl=https://stream.antenne.de/chillout/stream/aacp

📻 Step 2: Demonstrating LOCAL_INTERNET_RADIO with direct stream...
  📡 Using direct stream URL...
      Stream: Test Audio Stream
      URL: https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_1MB_MP3.mp3
  ✅ Successfully selected direct internet radio stream

💿 Step 3: Demonstrating LOCAL_MUSIC selection...
  ⚠️  LOCAL_MUSIC demo failed (this requires SoundTouch App Media Server): failed to select local music: HTTP 404 Not Found

💾 Step 4: Demonstrating STORED_MUSIC selection...
  ⚠️  STORED_MUSIC demo failed (this requires UPnP/DLNA media server): failed to select stored music: HTTP 404 Not Found

🎯 Step 5: Demonstrating generic ContentItem selection...
  🎯 Using generic ContentItem selection...
      Content: K-LOVE Radio
      Source: TUNEIN
      Location: /v1/playbook/station/s33828
  ✅ Successfully selected content using ContentItem

✅ Content selection demo completed!

API Methods Demonstrated

SelectLocalInternetRadio

err := client.SelectLocalInternetRadio(location, sourceAccount, itemName, containerArt)

SelectLocalMusic

err := client.SelectLocalMusic(location, sourceAccount, itemName, containerArt)

SelectStoredMusic

err := client.SelectStoredMusic(location, sourceAccount, itemName, containerArt)

SelectContentItem (Advanced)

contentItem := &models.ContentItem{
    Source:        "LOCAL_INTERNET_RADIO",
    Type:          "stationurl",
    Location:      "http://contentapi.gmuth.de/station.php?name=MyStation&streamUrl=https://stream.example.com/radio",
    SourceAccount: "",
    IsPresetable:  true,
    ItemName:      "My Radio Station",
    ContainerArt:  "https://example.com/art.png",
}
err := client.SelectContentItem(contentItem)

CLI Usage Examples

These API methods are also available via the CLI:

# Internet radio with streamUrl format
soundtouch-cli --host 192.168.1.100 source internet-radio \
  --location "http://contentapi.gmuth.de/station.php?name=MyStation&streamUrl=https://stream.example.com/radio" \
  --name "My Station" \
  --artwork "https://example.com/art.png"

# Local music content
soundtouch-cli --host 192.168.1.100 source local-music \
  --location "album:983" \
  --account "3f205110-4a57-4e91-810a-123456789012" \
  --name "Welcome to the New"

# Stored music content
soundtouch-cli --host 192.168.1.100 source stored-music \
  --location "6_a2874b5d_4f83d999" \
  --account "d09708a1-5953-44bc-a413-123456789012/0" \
  --name "Christmas Album"

# Generic content selection (advanced)
soundtouch-cli --host 192.168.1.100 source content \
  --source LOCAL_INTERNET_RADIO \
  --location "https://stream.example.com/radio" \
  --name "My Stream" \
  --type stationurl \
  --presetable

Implementation Notes

streamUrl Format

The streamUrl format uses a proxy server that accepts the actual stream URL as a parameter. This allows for:

• Complex metadata handling
• Stream URL obfuscation
• Cross-origin request handling
• Additional processing capabilities

ContentItem Structure

All content selection methods create a ContentItem with appropriate defaults:

• Type is automatically set based on source
• IsPresetable defaults to true
• ItemName gets a sensible default if not provided

Error Handling

The example gracefully handles missing services:

• LOCAL_MUSIC requires SoundTouch App Media Server
• STORED_MUSIC requires UPnP/DLNA media server
• Some internet streams may be geo-restricted

Related Documentation

• SoundTouch WebServices API Wiki
• CLI Reference
• Navigation Guide