mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-18 16:46:17 +00:00
feat: Add comprehensive navigation and station management functionality
Implements the complete /navigate, /searchStation, /addStation, and /removeStation API endpoints with full client support, models, tests, and documentation. This resolves GitHub issue #14 by enabling direct radio station and custom stream playback without requiring preset storage first. ## New Features ### Content Navigation - Browse content sources (TuneIn, Pandora, Spotify, stored music) - Navigate directory structures in music libraries - Paginated browsing with configurable page sizes - Menu-based navigation for services like Pandora ### Station Search & Discovery - Search across music services for stations, artists, songs - Service-specific search methods for TuneIn, Pandora, Spotify - Smart result categorization (songs vs artists vs stations) - Rich metadata including artwork and descriptions ### Station Management - Add stations to collections with immediate playback - Remove stations from user collections - Token-based operations for discovered content - WebSocket event generation for real-time updates ## Implementation Details ### New Client Methods - Navigate(), NavigateWithMenu(), NavigateContainer() - SearchStation(), SearchTuneInStations(), SearchPandoraStations(), SearchSpotifyContent() - AddStation(), RemoveStation() - GetTuneInStations(), GetPandoraStations(), GetStoredMusicLibrary() ### New Models (pkg/models/navigation.go) - NavigateRequest/Response with helper methods - SearchStationRequest/Response with result filtering - AddStationRequest, RemoveStationRequest, StationResponse - Rich helper methods for type detection and display formatting ### Enhanced HTTP Client - Added postWithResponse() method for POST requests with XML response parsing - Proper error handling with API error response parsing - XML marshaling/unmarshaling for all new request/response types ## Testing ### Comprehensive Test Suite - Unit tests for all client methods (navigation_test.go) - XML validation tests (navigation_xml_test.go) - Integration tests for real devices (navigation_integration_test.go) - Example workflows (navigation_examples_test.go) - Complete model tests (navigation_test.go) - Edge case and error handling tests ### Test Coverage - ~50 new test cases across different categories - 100% coverage of new navigation methods - XML protocol compliance verification - Performance benchmarking capabilities - Integration testing ready for real devices ## Documentation ### User-Focused Guide (docs/NAVIGATION-GUIDE.md) - Complete usage examples from basic to advanced - Real-world workflows (discover → search → add → play) - Error handling patterns and best practices - Service-specific guidance (TuneIn vs Pandora vs Spotify) - Performance optimization tips ### Technical Reference (docs/API-NAVIGATION-REFERENCE.md) - Complete API method documentation - Model specifications with helper methods - HTTP endpoint mapping with XML examples - Error codes and troubleshooting guide - XML schema definitions ### Updated README.md - Added navigation to API coverage - Updated documentation links - Enhanced feature list ## API Endpoints Implemented - POST /navigate - Browse content sources - POST /searchStation - Search for stations and content - POST /addStation - Add station and immediately play - POST /removeStation - Remove station from collection ## Breaking Changes None - all additions are backwards compatible. ## Usage Examples This implementation enables the complete workflow requested in issue #14: direct radio station and custom stream playback without preset dependencies.
This commit is contained in:
Tobias Gesellchen
@@ -0,0 +1,809 @@
|
||||
# Navigation API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a complete API reference for the Bose SoundTouch navigation and station management functionality. For usage examples and workflows, see [NAVIGATION-GUIDE.md](NAVIGATION-GUIDE.md).
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Client Methods](#client-methods)
|
||||
- [Models](#models)
|
||||
- [HTTP Endpoints](#http-endpoints)
|
||||
- [XML Schemas](#xml-schemas)
|
||||
- [Error Codes](#error-codes)
|
||||
|
||||
## Client Methods
|
||||
|
||||
### Navigation Methods
|
||||
|
||||
#### `Navigate(source, sourceAccount string, startItem, numItems int) (*models.NavigateResponse, error)`
|
||||
|
||||
Browse content within a source.
|
||||
|
||||
**Parameters:**
|
||||
- `source` (string, required): Content source identifier
|
||||
- Valid values: `"TUNEIN"`, `"PANDORA"`, `"SPOTIFY"`, `"STORED_MUSIC"`, `"BLUETOOTH"`, `"AUX"`
|
||||
- `sourceAccount` (string, optional): Account identifier for authenticated sources
|
||||
- `startItem` (int, required): Starting position (1-based index)
|
||||
- `numItems` (int, required): Number of items to retrieve
|
||||
|
||||
**Returns:**
|
||||
- `*models.NavigateResponse`: Navigation results with items and metadata
|
||||
- `error`: Error if request fails
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
response, err := client.Navigate("TUNEIN", "", 1, 25)
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
- `source` cannot be empty
|
||||
- `startItem` must be >= 1
|
||||
- `numItems` must be >= 1
|
||||
|
||||
---
|
||||
|
||||
#### `NavigateWithMenu(source, sourceAccount, menu, sort string, startItem, numItems int) (*models.NavigateResponse, error)`
|
||||
|
||||
Browse content with specific menu and sorting options (primarily for Pandora).
|
||||
|
||||
**Parameters:**
|
||||
- `source` (string, required): Content source identifier
|
||||
- `sourceAccount` (string, optional): Account identifier
|
||||
- `menu` (string, optional): Menu context (e.g., `"radioStations"`)
|
||||
- `sort` (string, optional): Sort order (e.g., `"dateCreated"`)
|
||||
- `startItem` (int, required): Starting position (1-based)
|
||||
- `numItems` (int, required): Number of items to retrieve
|
||||
|
||||
**Returns:**
|
||||
- `*models.NavigateResponse`: Navigation results
|
||||
- `error`: Error if request fails
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
response, err := client.NavigateWithMenu("PANDORA", "user123", "radioStations", "dateCreated", 1, 100)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `NavigateContainer(source, sourceAccount string, startItem, numItems int, containerItem *models.ContentItem) (*models.NavigateResponse, error)`
|
||||
|
||||
Browse into a specific container/directory.
|
||||
|
||||
**Parameters:**
|
||||
- `source` (string, required): Content source identifier
|
||||
- `sourceAccount` (string, optional): Account identifier
|
||||
- `startItem` (int, required): Starting position (1-based)
|
||||
- `numItems` (int, required): Number of items to retrieve
|
||||
- `containerItem` (*models.ContentItem, required): Container to browse into
|
||||
|
||||
**Returns:**
|
||||
- `*models.NavigateResponse`: Container contents
|
||||
- `error`: Error if request fails
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
response, err := client.NavigateContainer("STORED_MUSIC", "device/0", 1, 100, albumContentItem)
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
- `containerItem` cannot be nil
|
||||
- Container must have valid `Location` field
|
||||
|
||||
---
|
||||
|
||||
### Convenience Navigation Methods
|
||||
|
||||
#### `GetTuneInStations(sourceAccount string) (*models.NavigateResponse, error)`
|
||||
|
||||
Browse TuneIn radio stations.
|
||||
|
||||
**Parameters:**
|
||||
- `sourceAccount` (string, optional): TuneIn account (usually empty)
|
||||
|
||||
**Returns:**
|
||||
- `*models.NavigateResponse`: TuneIn stations and content
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
stations, err := client.GetTuneInStations("")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `GetPandoraStations(sourceAccount string) (*models.NavigateResponse, error)`
|
||||
|
||||
Browse Pandora radio stations with proper sorting.
|
||||
|
||||
**Parameters:**
|
||||
- `sourceAccount` (string, required): Pandora user account identifier
|
||||
|
||||
**Returns:**
|
||||
- `*models.NavigateResponse`: Pandora stations sorted by creation date
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
stations, err := client.GetPandoraStations("user123")
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
- `sourceAccount` cannot be empty
|
||||
|
||||
---
|
||||
|
||||
#### `GetStoredMusicLibrary(sourceAccount string) (*models.NavigateResponse, error)`
|
||||
|
||||
Browse stored/local music library.
|
||||
|
||||
**Parameters:**
|
||||
- `sourceAccount` (string, required): Device account identifier (format: `deviceID/index`)
|
||||
|
||||
**Returns:**
|
||||
- `*models.NavigateResponse`: Music library root contents
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
library, err := client.GetStoredMusicLibrary("A81B6A536A98/0")
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
- `sourceAccount` cannot be empty
|
||||
|
||||
---
|
||||
|
||||
### Search Methods
|
||||
|
||||
#### `SearchStation(source, sourceAccount, searchTerm string) (*models.SearchStationResponse, error)`
|
||||
|
||||
Search for stations and content within a music service.
|
||||
|
||||
**Parameters:**
|
||||
- `source` (string, required): Service to search
|
||||
- `sourceAccount` (string, optional): Account identifier
|
||||
- `searchTerm` (string, required): Search query
|
||||
|
||||
**Returns:**
|
||||
- `*models.SearchStationResponse`: Search results categorized by type
|
||||
- `error`: Error if request fails
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
results, err := client.SearchStation("PANDORA", "user123", "jazz")
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
- `source` cannot be empty
|
||||
- `searchTerm` cannot be empty
|
||||
|
||||
---
|
||||
|
||||
#### `SearchTuneInStations(searchTerm string) (*models.SearchStationResponse, error)`
|
||||
|
||||
Search TuneIn radio stations.
|
||||
|
||||
**Parameters:**
|
||||
- `searchTerm` (string, required): Search query
|
||||
|
||||
**Returns:**
|
||||
- `*models.SearchStationResponse`: TuneIn search results
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
results, err := client.SearchTuneInStations("classical music")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `SearchPandoraStations(sourceAccount, searchTerm string) (*models.SearchStationResponse, error)`
|
||||
|
||||
Search Pandora for artists and stations.
|
||||
|
||||
**Parameters:**
|
||||
- `sourceAccount` (string, required): Pandora account identifier
|
||||
- `searchTerm` (string, required): Artist or genre to search for
|
||||
|
||||
**Returns:**
|
||||
- `*models.SearchStationResponse`: Pandora search results with songs, artists, stations
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
results, err := client.SearchPandoraStations("user123", "Taylor Swift")
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
- `sourceAccount` cannot be empty
|
||||
|
||||
---
|
||||
|
||||
#### `SearchSpotifyContent(sourceAccount, searchTerm string) (*models.SearchStationResponse, error)`
|
||||
|
||||
Search Spotify for tracks, albums, and playlists.
|
||||
|
||||
**Parameters:**
|
||||
- `sourceAccount` (string, required): Spotify account identifier
|
||||
- `searchTerm` (string, required): Content to search for
|
||||
|
||||
**Returns:**
|
||||
- `*models.SearchStationResponse`: Spotify search results
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
results, err := client.SearchSpotifyContent("user@example.com", "Queen")
|
||||
```
|
||||
|
||||
**Validation:**
|
||||
- `sourceAccount` cannot be empty
|
||||
|
||||
---
|
||||
|
||||
### Station Management Methods
|
||||
|
||||
#### `AddStation(source, sourceAccount, token, name string) error`
|
||||
|
||||
Add a station to music service collection and immediately start playing it.
|
||||
|
||||
**Parameters:**
|
||||
- `source` (string, required): Music service identifier
|
||||
- `sourceAccount` (string, optional): Account identifier
|
||||
- `token` (string, required): Station token from search results
|
||||
- `name` (string, required): Display name for the station
|
||||
|
||||
**Returns:**
|
||||
- `error`: Error if operation fails
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
err := client.AddStation("PANDORA", "user123", "R4328162", "Classic Rock Radio")
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Station is immediately selected and starts playing
|
||||
- Station is added to user's collection permanently
|
||||
- Generates `presetsUpdated` WebSocket event if station is stored as preset
|
||||
|
||||
**Validation:**
|
||||
- `source` cannot be empty
|
||||
- `token` cannot be empty
|
||||
- `name` cannot be empty
|
||||
|
||||
---
|
||||
|
||||
#### `RemoveStation(contentItem *models.ContentItem) error`
|
||||
|
||||
Remove a station from music service collection.
|
||||
|
||||
**Parameters:**
|
||||
- `contentItem` (*models.ContentItem, required): Station content item with source and location
|
||||
|
||||
**Returns:**
|
||||
- `error`: Error if operation fails
|
||||
|
||||
**Example:**
|
||||
```go
|
||||
err := client.RemoveStation(stationContentItem)
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Station is removed from user's collection
|
||||
- If station is currently playing, playback stops
|
||||
- Generates `nowPlayingUpdated` WebSocket event if playing station was removed
|
||||
|
||||
**Validation:**
|
||||
- `contentItem` cannot be nil
|
||||
- `contentItem.Source` cannot be empty
|
||||
- `contentItem.Location` cannot be empty
|
||||
|
||||
---
|
||||
|
||||
## Models
|
||||
|
||||
### NavigateRequest
|
||||
|
||||
Request structure for `/navigate` endpoint.
|
||||
|
||||
```go
|
||||
type NavigateRequest struct {
|
||||
Source string `xml:"source,attr"`
|
||||
SourceAccount string `xml:"sourceAccount,attr,omitempty"`
|
||||
Menu string `xml:"menu,attr,omitempty"`
|
||||
Sort string `xml:"sort,attr,omitempty"`
|
||||
StartItem int `xml:"startItem"`
|
||||
NumItems int `xml:"numItems"`
|
||||
Item *NavigateItem `xml:"item,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
**Constructors:**
|
||||
- `NewNavigateRequest(source, sourceAccount string, startItem, numItems int)`
|
||||
- `NewNavigateRequestWithMenu(source, sourceAccount, menu, sort string, startItem, numItems int)`
|
||||
- `NewNavigateRequestWithItem(source, sourceAccount string, startItem, numItems int, item *ContentItem)`
|
||||
|
||||
---
|
||||
|
||||
### NavigateResponse
|
||||
|
||||
Response structure from navigation operations.
|
||||
|
||||
```go
|
||||
type NavigateResponse struct {
|
||||
Source string `xml:"source,attr"`
|
||||
SourceAccount string `xml:"sourceAccount,attr,omitempty"`
|
||||
TotalItems int `xml:"totalItems"`
|
||||
Items []NavigateItem `xml:"items>item"`
|
||||
}
|
||||
```
|
||||
|
||||
**Helper Methods:**
|
||||
- `GetPlayableItems() []NavigateItem` - Filter items with `Playable="1"`
|
||||
- `GetDirectories() []NavigateItem` - Filter directory items (`type="dir"`)
|
||||
- `GetTracks() []NavigateItem` - Filter track items (`type="track"`)
|
||||
- `GetStations() []NavigateItem` - Filter station items (`type="stationurl"`)
|
||||
- `IsEmpty() bool` - Check if response has no items
|
||||
|
||||
---
|
||||
|
||||
### NavigateItem
|
||||
|
||||
Individual item within navigation response.
|
||||
|
||||
```go
|
||||
type NavigateItem struct {
|
||||
Playable int `xml:"Playable,attr,omitempty"`
|
||||
Name string `xml:"name"`
|
||||
Type string `xml:"type"`
|
||||
ContentItem *ContentItem `xml:"ContentItem,omitempty"`
|
||||
MediaItemContainer *MediaItemContainer `xml:"mediaItemContainer,omitempty"`
|
||||
ArtistName string `xml:"artistName,omitempty"`
|
||||
AlbumName string `xml:"albumName,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
**Helper Methods:**
|
||||
- `GetDisplayName() string` - Get formatted display name
|
||||
- `IsPlayable() bool` - Check if `Playable="1"`
|
||||
- `IsDirectory() bool` - Check if `type="dir"`
|
||||
- `IsTrack() bool` - Check if `type="track"`
|
||||
- `IsStation() bool` - Check if `type="stationurl"`
|
||||
- `GetContentItem() *ContentItem` - Get associated content item
|
||||
- `GetArtwork() string` - Get artwork URL from content item
|
||||
|
||||
**Common Type Values:**
|
||||
- `"dir"` - Directory/container
|
||||
- `"track"` - Music track
|
||||
- `"stationurl"` - Radio station
|
||||
- `"playlist"` - Playlist
|
||||
- `"album"` - Album
|
||||
|
||||
---
|
||||
|
||||
### SearchStationRequest
|
||||
|
||||
Request structure for station search.
|
||||
|
||||
```go
|
||||
type SearchStationRequest struct {
|
||||
Source string `xml:"source,attr"`
|
||||
SourceAccount string `xml:"sourceAccount,attr,omitempty"`
|
||||
SearchTerm string `xml:",chardata"`
|
||||
}
|
||||
```
|
||||
|
||||
**Constructor:**
|
||||
- `NewSearchStationRequest(source, sourceAccount, searchTerm string)`
|
||||
|
||||
---
|
||||
|
||||
### SearchStationResponse
|
||||
|
||||
Response structure from search operations.
|
||||
|
||||
```go
|
||||
type SearchStationResponse struct {
|
||||
DeviceID string `xml:"deviceID,attr"`
|
||||
Source string `xml:"source,attr"`
|
||||
SourceAccount string `xml:"sourceAccount,attr,omitempty"`
|
||||
Songs []SearchResult `xml:"songs>searchResult"`
|
||||
Artists []SearchResult `xml:"artists>searchResult"`
|
||||
Stations []SearchResult `xml:"stations>searchResult"`
|
||||
}
|
||||
```
|
||||
|
||||
**Helper Methods:**
|
||||
- `GetSongs() []SearchResult` - Get song results
|
||||
- `GetArtists() []SearchResult` - Get artist results
|
||||
- `GetStations() []SearchResult` - Get station results
|
||||
- `GetAllResults() []SearchResult` - Get all results combined
|
||||
- `GetResultCount() int` - Count total results
|
||||
- `HasResults() bool` - Check if any results found
|
||||
- `IsEmpty() bool` - Check if no results
|
||||
|
||||
---
|
||||
|
||||
### SearchResult
|
||||
|
||||
Individual search result item.
|
||||
|
||||
```go
|
||||
type SearchResult struct {
|
||||
Source string `xml:"source,attr"`
|
||||
SourceAccount string `xml:"sourceAccount,attr,omitempty"`
|
||||
Token string `xml:"token,attr"`
|
||||
Name string `xml:"name"`
|
||||
Artist string `xml:"artist,omitempty"`
|
||||
Album string `xml:"album,omitempty"`
|
||||
Logo string `xml:"logo,omitempty"`
|
||||
Description string `xml:"description,omitempty"`
|
||||
}
|
||||
```
|
||||
|
||||
**Helper Methods:**
|
||||
- `IsSong() bool` - Check if result is a song (has `Artist` field)
|
||||
- `IsArtist() bool` - Check if result is an artist (no `Artist` or `Description`)
|
||||
- `IsStation() bool` - Check if result is a station (has `Description`)
|
||||
- `GetDisplayName() string` - Get formatted name
|
||||
- `GetFullTitle() string` - Get name with artist for songs
|
||||
- `GetArtworkURL() string` - Get logo/artwork URL
|
||||
|
||||
**Token Usage:**
|
||||
The `Token` field is used with `AddStation()` to add the result to your collection.
|
||||
|
||||
---
|
||||
|
||||
### AddStationRequest
|
||||
|
||||
Request structure for adding stations.
|
||||
|
||||
```go
|
||||
type AddStationRequest struct {
|
||||
Source string `xml:"source,attr"`
|
||||
SourceAccount string `xml:"sourceAccount,attr,omitempty"`
|
||||
Token string `xml:"token,attr"`
|
||||
Name string `xml:"name"`
|
||||
}
|
||||
```
|
||||
|
||||
**Constructor:**
|
||||
- `NewAddStationRequest(source, sourceAccount, token, name string)`
|
||||
|
||||
---
|
||||
|
||||
### StationResponse
|
||||
|
||||
Response structure from station management operations.
|
||||
|
||||
```go
|
||||
type StationResponse struct {
|
||||
Status string `xml:",chardata"`
|
||||
}
|
||||
```
|
||||
|
||||
**Common Values:**
|
||||
- `"/addStation"` - Station added successfully
|
||||
- `"/removeStation"` - Station removed successfully
|
||||
|
||||
---
|
||||
|
||||
## HTTP Endpoints
|
||||
|
||||
### POST /navigate
|
||||
|
||||
Browse content within a source.
|
||||
|
||||
**Request Body:**
|
||||
```xml
|
||||
<navigate source="TUNEIN" sourceAccount="">
|
||||
<startItem>1</startItem>
|
||||
<numItems>25</numItems>
|
||||
</navigate>
|
||||
```
|
||||
|
||||
**Response Body:**
|
||||
```xml
|
||||
<navigateResponse source="TUNEIN">
|
||||
<totalItems>5</totalItems>
|
||||
<items>
|
||||
<item Playable="1">
|
||||
<name>Station Name</name>
|
||||
<type>stationurl</type>
|
||||
<ContentItem source="TUNEIN" location="/v1/playback/station/s12345" isPresetable="true">
|
||||
<itemName>Station Name</itemName>
|
||||
</ContentItem>
|
||||
</item>
|
||||
</items>
|
||||
</navigateResponse>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /searchStation
|
||||
|
||||
Search for stations and content.
|
||||
|
||||
**Request Body:**
|
||||
```xml
|
||||
<search source="PANDORA" sourceAccount="user123">Taylor Swift</search>
|
||||
```
|
||||
|
||||
**Response Body:**
|
||||
```xml
|
||||
<results deviceID="A81B6A536A98" source="PANDORA" sourceAccount="user123">
|
||||
<songs>
|
||||
<searchResult source="PANDORA" sourceAccount="user123" token="S123">
|
||||
<name>Love Story</name>
|
||||
<artist>Taylor Swift</artist>
|
||||
<logo>http://example.com/artwork.jpg</logo>
|
||||
</searchResult>
|
||||
</songs>
|
||||
<artists>
|
||||
<searchResult source="PANDORA" sourceAccount="user123" token="R456">
|
||||
<name>Taylor Swift</name>
|
||||
<logo>http://example.com/artist.jpg</logo>
|
||||
</searchResult>
|
||||
</artists>
|
||||
</results>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /addStation
|
||||
|
||||
Add a station to collection and start playing.
|
||||
|
||||
**Request Body:**
|
||||
```xml
|
||||
<addStation source="PANDORA" sourceAccount="user123" token="R456">
|
||||
<name>Taylor Swift Radio</name>
|
||||
</addStation>
|
||||
```
|
||||
|
||||
**Response Body:**
|
||||
```xml
|
||||
<status>/addStation</status>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /removeStation
|
||||
|
||||
Remove a station from collection.
|
||||
|
||||
**Request Body:**
|
||||
```xml
|
||||
<ContentItem source="PANDORA" location="126740707481236361" sourceAccount="user123" isPresetable="true">
|
||||
<itemName>Taylor Swift Radio</itemName>
|
||||
</ContentItem>
|
||||
```
|
||||
|
||||
**Response Body:**
|
||||
```xml
|
||||
<status>/removeStation</status>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## XML Schemas
|
||||
|
||||
### Navigate Request Schema
|
||||
|
||||
```xml
|
||||
<xs:element name="navigate">
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:element name="startItem" type="xs:int"/>
|
||||
<xs:element name="numItems" type="xs:int"/>
|
||||
<xs:element name="item" minOccurs="0">
|
||||
<xs:complexType>
|
||||
<xs:sequence>
|
||||
<xs:element name="name" type="xs:string"/>
|
||||
<xs:element name="type" type="xs:string"/>
|
||||
<xs:element name="ContentItem" type="ContentItemType"/>
|
||||
</xs:sequence>
|
||||
<xs:attribute name="Playable" type="xs:int"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
</xs:sequence>
|
||||
<xs:attribute name="source" type="xs:string" use="required"/>
|
||||
<xs:attribute name="sourceAccount" type="xs:string"/>
|
||||
<xs:attribute name="menu" type="xs:string"/>
|
||||
<xs:attribute name="sort" type="xs:string"/>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
```
|
||||
|
||||
### Search Request Schema
|
||||
|
||||
```xml
|
||||
<xs:element name="search">
|
||||
<xs:complexType>
|
||||
<xs:simpleContent>
|
||||
<xs:extension base="xs:string">
|
||||
<xs:attribute name="source" type="xs:string" use="required"/>
|
||||
<xs:attribute name="sourceAccount" type="xs:string"/>
|
||||
</xs:extension>
|
||||
</xs:simpleContent>
|
||||
</xs:complexType>
|
||||
</xs:element>
|
||||
```
|
||||
|
||||
### ContentItem Type Schema
|
||||
|
||||
```xml
|
||||
<xs:complexType name="ContentItemType">
|
||||
<xs:sequence>
|
||||
<xs:element name="itemName" type="xs:string" minOccurs="0"/>
|
||||
<xs:element name="containerArt" type="xs:string" minOccurs="0"/>
|
||||
</xs:sequence>
|
||||
<xs:attribute name="source" type="xs:string" use="required"/>
|
||||
<xs:attribute name="type" type="xs:string"/>
|
||||
<xs:attribute name="location" type="xs:string"/>
|
||||
<xs:attribute name="sourceAccount" type="xs:string"/>
|
||||
<xs:attribute name="isPresetable" type="xs:boolean"/>
|
||||
</xs:complexType>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Codes
|
||||
|
||||
### HTTP Status Codes
|
||||
|
||||
| Status | Meaning | Description |
|
||||
|--------|---------|-------------|
|
||||
| 200 | OK | Request successful |
|
||||
| 400 | Bad Request | Invalid parameters or XML |
|
||||
| 404 | Not Found | Endpoint or content not found |
|
||||
| 500 | Internal Server Error | Device error |
|
||||
|
||||
### Common Error Responses
|
||||
|
||||
**Invalid Source:**
|
||||
```xml
|
||||
<error>
|
||||
<code>INVALID_SOURCE</code>
|
||||
<message>Source 'INVALID' is not available</message>
|
||||
</error>
|
||||
```
|
||||
|
||||
**Authentication Required:**
|
||||
```xml
|
||||
<error>
|
||||
<code>AUTH_REQUIRED</code>
|
||||
<message>Source account required for this service</message>
|
||||
</error>
|
||||
```
|
||||
|
||||
**Service Unavailable:**
|
||||
```xml
|
||||
<error>
|
||||
<code>SERVICE_UNAVAILABLE</code>
|
||||
<message>PANDORA service is not configured</message>
|
||||
</error>
|
||||
```
|
||||
|
||||
### Client-Side Validation Errors
|
||||
|
||||
The Go client performs validation before sending requests:
|
||||
|
||||
| Error Message | Cause | Solution |
|
||||
|---------------|-------|----------|
|
||||
| `"source cannot be empty"` | Empty source parameter | Provide valid source |
|
||||
| `"search term cannot be empty"` | Empty search query | Provide search term |
|
||||
| `"startItem must be >= 1"` | Invalid start position | Use 1-based indexing |
|
||||
| `"numItems must be >= 1"` | Invalid page size | Use positive number |
|
||||
| `"content item cannot be nil"` | Nil ContentItem | Provide valid ContentItem |
|
||||
| `"container item cannot be nil"` | Nil container for NavigateContainer | Provide valid container |
|
||||
| `"Pandora source account cannot be empty"` | Missing Pandora account | Configure Pandora account |
|
||||
| `"token cannot be empty"` | Missing station token | Use token from search results |
|
||||
| `"station name cannot be empty"` | Missing station name | Provide station name |
|
||||
|
||||
---
|
||||
|
||||
## WebSocket Events
|
||||
|
||||
Navigation and station operations generate WebSocket events:
|
||||
|
||||
### presetsUpdated
|
||||
|
||||
Generated when stations are added/removed that affect presets.
|
||||
|
||||
```xml
|
||||
<presetsUpdated deviceID="A81B6A536A98">
|
||||
<presets>
|
||||
<!-- Updated preset list -->
|
||||
</presets>
|
||||
</presetsUpdated>
|
||||
```
|
||||
|
||||
### nowPlayingUpdated
|
||||
|
||||
Generated when station operations affect current playback.
|
||||
|
||||
```xml
|
||||
<nowPlayingUpdated deviceID="A81B6A536A98">
|
||||
<nowPlaying source="PANDORA">
|
||||
<ContentItem source="PANDORA" location="R456" sourceAccount="user123" isPresetable="true">
|
||||
<itemName>Taylor Swift Radio</itemName>
|
||||
</ContentItem>
|
||||
<track>Love Story</track>
|
||||
<artist>Taylor Swift</artist>
|
||||
<playStatus>PLAY_STATE</playStatus>
|
||||
</nowPlaying>
|
||||
</nowPlayingUpdated>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Parameter Validation
|
||||
|
||||
Always validate parameters before API calls:
|
||||
|
||||
```go
|
||||
func validateNavigateParams(source string, startItem, numItems int) error {
|
||||
if source == "" {
|
||||
return fmt.Errorf("source cannot be empty")
|
||||
}
|
||||
if startItem < 1 {
|
||||
return fmt.Errorf("startItem must be >= 1")
|
||||
}
|
||||
if numItems < 1 {
|
||||
return fmt.Errorf("numItems must be >= 1")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
Handle both network and API errors:
|
||||
|
||||
```go
|
||||
response, err := client.Navigate("TUNEIN", "", 1, 25)
|
||||
if err != nil {
|
||||
// Check if it's a known API error
|
||||
if strings.Contains(err.Error(), "not available") {
|
||||
log.Printf("TuneIn not configured on device")
|
||||
return
|
||||
}
|
||||
return fmt.Errorf("navigation failed: %w", err)
|
||||
}
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
Use appropriate page sizes for different contexts:
|
||||
|
||||
```go
|
||||
// Small pages for interactive browsing
|
||||
response, err := client.Navigate("TUNEIN", "", 1, 25)
|
||||
|
||||
// Larger pages for bulk processing
|
||||
response, err := client.Navigate("STORED_MUSIC", "device/0", 1, 100)
|
||||
```
|
||||
|
||||
### Resource Management
|
||||
|
||||
Cache frequently accessed data:
|
||||
|
||||
```go
|
||||
type CachedClient struct {
|
||||
client *client.Client
|
||||
sources *models.Sources
|
||||
sourcesTime time.Time
|
||||
}
|
||||
|
||||
func (c *CachedClient) GetSources() (*models.Sources, error) {
|
||||
if c.sources == nil || time.Since(c.sourcesTime) > 5*time.Minute {
|
||||
var err error
|
||||
c.sources, err = c.client.GetSources()
|
||||
c.sourcesTime = time.Now()
|
||||
return c.sources, err
|
||||
}
|
||||
return c.sources, nil
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*For complete usage examples and workflows, see [NAVIGATION-GUIDE.md](NAVIGATION-GUIDE.md).*
|
||||
@@ -0,0 +1,898 @@
|
||||
# Navigation and Station Management Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The Bose SoundTouch Go client provides comprehensive navigation and station management functionality that allows you to:
|
||||
|
||||
- **Browse content sources** (TuneIn, Pandora, Spotify, stored music)
|
||||
- **Search for stations and content** across music services
|
||||
- **Add stations and immediately play them**
|
||||
- **Remove stations from collections**
|
||||
- **Navigate directory structures** in music libraries
|
||||
|
||||
This guide provides complete examples and best practices for using these features.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Quick Start](#quick-start)
|
||||
- [Content Navigation](#content-navigation)
|
||||
- [Station Search](#station-search)
|
||||
- [Station Management](#station-management)
|
||||
- [Complete Workflows](#complete-workflows)
|
||||
- [Error Handling](#error-handling)
|
||||
- [Best Practices](#best-practices)
|
||||
- [API Reference](#api-reference)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Basic Setup
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"log"
|
||||
|
||||
"github.com/gesellix/bose-soundtouch/pkg/client"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// Create client
|
||||
config := &client.Config{
|
||||
Host: "192.168.1.100",
|
||||
Port: 8090,
|
||||
}
|
||||
soundtouch := client.NewClient(config)
|
||||
|
||||
// Your navigation code here...
|
||||
}
|
||||
```
|
||||
|
||||
### Simple Navigation Example
|
||||
|
||||
```go
|
||||
// Browse TuneIn content
|
||||
response, err := soundtouch.Navigate("TUNEIN", "", 1, 25)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d items\n", response.TotalItems)
|
||||
for _, item := range response.Items {
|
||||
fmt.Printf("- %s (%s)\n", item.GetDisplayName(), item.Type)
|
||||
}
|
||||
```
|
||||
|
||||
## Content Navigation
|
||||
|
||||
### Browse Different Sources
|
||||
|
||||
```go
|
||||
// Browse TuneIn radio stations
|
||||
tuneInStations, err := soundtouch.GetTuneInStations("")
|
||||
if err != nil {
|
||||
log.Printf("TuneIn not available: %v", err)
|
||||
} else {
|
||||
fmt.Printf("TuneIn has %d items\n", tuneInStations.TotalItems)
|
||||
}
|
||||
|
||||
// Browse Pandora stations (requires account)
|
||||
pandoraStations, err := soundtouch.GetPandoraStations("your_pandora_account")
|
||||
if err != nil {
|
||||
log.Printf("Pandora not available: %v", err)
|
||||
} else {
|
||||
stations := pandoraStations.GetStations()
|
||||
fmt.Printf("Found %d Pandora stations\n", len(stations))
|
||||
}
|
||||
|
||||
// Browse stored music library
|
||||
musicLibrary, err := soundtouch.GetStoredMusicLibrary("device_account/0")
|
||||
if err != nil {
|
||||
log.Printf("Stored music not available: %v", err)
|
||||
} else {
|
||||
directories := musicLibrary.GetDirectories()
|
||||
tracks := musicLibrary.GetTracks()
|
||||
fmt.Printf("Music library: %d dirs, %d tracks\n", len(directories), len(tracks))
|
||||
}
|
||||
```
|
||||
|
||||
### Navigate Into Directories
|
||||
|
||||
```go
|
||||
// First, get the root level
|
||||
musicLibrary, err := soundtouch.GetStoredMusicLibrary("device_account/0")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Find a directory to browse into
|
||||
directories := musicLibrary.GetDirectories()
|
||||
if len(directories) == 0 {
|
||||
fmt.Println("No directories found")
|
||||
return
|
||||
}
|
||||
|
||||
// Navigate into the first directory
|
||||
directory := directories[0]
|
||||
fmt.Printf("Browsing into: %s\n", directory.GetDisplayName())
|
||||
|
||||
contents, err := soundtouch.NavigateContainer(
|
||||
"STORED_MUSIC",
|
||||
"device_account/0",
|
||||
1, 100, // Get up to 100 items starting from position 1
|
||||
directory.ContentItem,
|
||||
)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Show what's inside
|
||||
tracks := contents.GetTracks()
|
||||
subdirs := contents.GetDirectories()
|
||||
fmt.Printf("Found %d tracks and %d subdirectories\n", len(tracks), len(subdirs))
|
||||
|
||||
// List first few tracks
|
||||
for i, track := range tracks[:min(5, len(tracks))] {
|
||||
fmt.Printf("%d. %s", i+1, track.GetDisplayName())
|
||||
if track.ArtistName != "" {
|
||||
fmt.Printf(" - %s", track.ArtistName)
|
||||
}
|
||||
if track.AlbumName != "" {
|
||||
fmt.Printf(" [%s]", track.AlbumName)
|
||||
}
|
||||
fmt.Println()
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Navigation with Pagination
|
||||
|
||||
```go
|
||||
// Browse large collections with pagination
|
||||
const pageSize = 50
|
||||
startItem := 1
|
||||
|
||||
for {
|
||||
response, err := soundtouch.Navigate("STORED_MUSIC", "device/0", startItem, pageSize)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
if len(response.Items) == 0 {
|
||||
break // No more items
|
||||
}
|
||||
|
||||
fmt.Printf("Page starting at %d: %d items\n", startItem, len(response.Items))
|
||||
|
||||
// Process this page
|
||||
for _, item := range response.Items {
|
||||
fmt.Printf(" %s (%s)\n", item.GetDisplayName(), item.Type)
|
||||
}
|
||||
|
||||
// Move to next page
|
||||
startItem += pageSize
|
||||
|
||||
// Stop if we've seen all items
|
||||
if startItem > response.TotalItems {
|
||||
break
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Station Search
|
||||
|
||||
### Basic Search
|
||||
|
||||
```go
|
||||
// Search TuneIn for jazz stations
|
||||
results, err := soundtouch.SearchTuneInStations("jazz")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Found %d total results for 'jazz'\n", results.GetResultCount())
|
||||
|
||||
// Show different types of results
|
||||
songs := results.GetSongs()
|
||||
artists := results.GetArtists()
|
||||
stations := results.GetStations()
|
||||
|
||||
fmt.Printf("Songs: %d, Artists: %d, Stations: %d\n",
|
||||
len(songs), len(artists), len(stations))
|
||||
```
|
||||
|
||||
### Service-Specific Search
|
||||
|
||||
```go
|
||||
// Search Pandora (requires account)
|
||||
pandoraResults, err := soundtouch.SearchPandoraStations("your_account", "Taylor Swift")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Show artists found
|
||||
artists := pandoraResults.GetArtists()
|
||||
for _, artist := range artists {
|
||||
fmt.Printf("Artist: %s (Token: %s)\n", artist.Name, artist.Token)
|
||||
if artist.Logo != "" {
|
||||
fmt.Printf(" Artwork: %s\n", artist.GetArtworkURL())
|
||||
}
|
||||
}
|
||||
|
||||
// Search Spotify content
|
||||
spotifyResults, err := soundtouch.SearchSpotifyContent("your_spotify_account", "Queen")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
songs := spotifyResults.GetSongs()
|
||||
for _, song := range songs[:min(5, len(songs))] {
|
||||
fmt.Printf("Song: %s\n", song.GetFullTitle())
|
||||
}
|
||||
```
|
||||
|
||||
### Search Result Analysis
|
||||
|
||||
```go
|
||||
results, err := soundtouch.SearchPandoraStations("account", "classic rock")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Analyze all results
|
||||
for _, result := range results.GetAllResults() {
|
||||
fmt.Printf("Name: %s, Token: %s\n", result.GetDisplayName(), result.Token)
|
||||
|
||||
// Determine result type
|
||||
switch {
|
||||
case result.IsSong():
|
||||
fmt.Printf(" Type: Song by %s\n", result.Artist)
|
||||
case result.IsArtist():
|
||||
fmt.Printf(" Type: Artist\n")
|
||||
case result.IsStation():
|
||||
fmt.Printf(" Type: Station")
|
||||
if result.Description != "" {
|
||||
fmt.Printf(" - %s", result.Description)
|
||||
}
|
||||
fmt.Println()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Station Management
|
||||
|
||||
### Adding Stations (Immediate Playback)
|
||||
|
||||
```go
|
||||
// Search for content first
|
||||
results, err := soundtouch.SearchPandoraStations("your_account", "Led Zeppelin")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Find an artist to create a station from
|
||||
artists := results.GetArtists()
|
||||
if len(artists) == 0 {
|
||||
fmt.Println("No artists found")
|
||||
return
|
||||
}
|
||||
|
||||
artist := artists[0]
|
||||
stationName := artist.Name + " Radio"
|
||||
|
||||
// Add station - this immediately starts playing it!
|
||||
err = soundtouch.AddStation("PANDORA", "your_account", artist.Token, stationName)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
fmt.Printf("✓ Added and now playing: %s\n", stationName)
|
||||
|
||||
// The station is now:
|
||||
// 1. Added to your Pandora collection
|
||||
// 2. Currently playing on the device
|
||||
```
|
||||
|
||||
### Removing Stations
|
||||
|
||||
```go
|
||||
// First, get existing stations
|
||||
stations, err := soundtouch.GetPandoraStations("your_account")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Show current stations
|
||||
fmt.Printf("Current stations (%d):\n", len(stations.Items))
|
||||
for i, station := range stations.Items {
|
||||
fmt.Printf("%d. %s\n", i+1, station.GetDisplayName())
|
||||
}
|
||||
|
||||
// Remove a specific station (example: remove the first one)
|
||||
if len(stations.Items) > 0 {
|
||||
stationToRemove := stations.Items[0]
|
||||
|
||||
if stationToRemove.ContentItem != nil {
|
||||
fmt.Printf("Removing: %s\n", stationToRemove.GetDisplayName())
|
||||
|
||||
err := soundtouch.RemoveStation(stationToRemove.ContentItem)
|
||||
if err != nil {
|
||||
log.Printf("Failed to remove station: %v", err)
|
||||
} else {
|
||||
fmt.Println("✓ Station removed successfully")
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Station Collection Management
|
||||
|
||||
```go
|
||||
// Get current collection
|
||||
currentStations, err := soundtouch.GetPandoraStations("your_account")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
fmt.Printf("Current collection has %d stations\n", len(currentStations.Items))
|
||||
|
||||
// Search for new content
|
||||
searchResults, err := soundtouch.SearchPandoraStations("your_account", "indie rock")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Add top 3 artist stations
|
||||
artists := searchResults.GetArtists()
|
||||
for i, artist := range artists[:min(3, len(artists))] {
|
||||
stationName := fmt.Sprintf("%s Radio", artist.Name)
|
||||
|
||||
fmt.Printf("Adding station %d: %s\n", i+1, stationName)
|
||||
|
||||
err := soundtouch.AddStation("PANDORA", "your_account", artist.Token, stationName)
|
||||
if err != nil {
|
||||
log.Printf("Failed to add %s: %v", stationName, err)
|
||||
continue
|
||||
}
|
||||
|
||||
fmt.Printf("✓ Added: %s\n", stationName)
|
||||
|
||||
// Note: Each AddStation immediately starts playing that station
|
||||
// You might want to pause between additions in a real app
|
||||
}
|
||||
|
||||
fmt.Println("Station collection updated!")
|
||||
```
|
||||
|
||||
## Complete Workflows
|
||||
|
||||
### Discover and Play Workflow
|
||||
|
||||
```go
|
||||
func discoverAndPlayWorkflow(soundtouch *client.Client) {
|
||||
fmt.Println("=== Discover and Play Workflow ===")
|
||||
|
||||
// Step 1: Search for content
|
||||
searchTerm := "electronic music"
|
||||
fmt.Printf("🔍 Searching for '%s'...\n", searchTerm)
|
||||
|
||||
results, err := soundtouch.SearchTuneInStations(searchTerm)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
if results.IsEmpty() {
|
||||
fmt.Println("❌ No results found")
|
||||
return
|
||||
}
|
||||
|
||||
// Step 2: Show options
|
||||
stations := results.GetStations()
|
||||
fmt.Printf("📻 Found %d stations:\n", len(stations))
|
||||
|
||||
for i, station := range stations[:min(5, len(stations))] {
|
||||
fmt.Printf("%d. %s", i+1, station.GetDisplayName())
|
||||
if station.Description != "" {
|
||||
fmt.Printf(" - %s", station.Description)
|
||||
}
|
||||
fmt.Println()
|
||||
}
|
||||
|
||||
// Step 3: Select and play (example: select first one)
|
||||
if len(stations) > 0 {
|
||||
selectedStation := stations[0]
|
||||
fmt.Printf("🎵 Playing: %s\n", selectedStation.GetDisplayName())
|
||||
|
||||
// For services that support it, add the station to play it
|
||||
if selectedStation.Token != "" {
|
||||
err := soundtouch.AddStation("TUNEIN", "", selectedStation.Token, selectedStation.Name)
|
||||
if err != nil {
|
||||
log.Printf("Could not add station: %v", err)
|
||||
} else {
|
||||
fmt.Println("✓ Station added and playing!")
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Library Organization Workflow
|
||||
|
||||
```go
|
||||
func organizeLibraryWorkflow(soundtouch *client.Client, deviceAccount string) {
|
||||
fmt.Println("=== Library Organization Workflow ===")
|
||||
|
||||
// Step 1: Explore library structure
|
||||
fmt.Println("📂 Exploring music library...")
|
||||
|
||||
library, err := soundtouch.GetStoredMusicLibrary(deviceAccount)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
directories := library.GetDirectories()
|
||||
tracks := library.GetTracks()
|
||||
|
||||
fmt.Printf("📊 Library overview: %d directories, %d tracks\n",
|
||||
len(directories), len(tracks))
|
||||
|
||||
// Step 2: Navigate into each directory
|
||||
for _, dir := range directories[:min(3, len(directories))] {
|
||||
fmt.Printf("\n📁 Exploring: %s\n", dir.GetDisplayName())
|
||||
|
||||
contents, err := soundtouch.NavigateContainer(
|
||||
"STORED_MUSIC", deviceAccount, 1, 20, dir.ContentItem)
|
||||
if err != nil {
|
||||
log.Printf("❌ Failed to explore %s: %v", dir.GetDisplayName(), err)
|
||||
continue
|
||||
}
|
||||
|
||||
subTracks := contents.GetTracks()
|
||||
subDirs := contents.GetDirectories()
|
||||
|
||||
fmt.Printf(" Contains: %d tracks, %d subdirectories\n",
|
||||
len(subTracks), len(subDirs))
|
||||
|
||||
// Show some tracks
|
||||
for i, track := range subTracks[:min(3, len(subTracks))] {
|
||||
fmt.Printf(" %d. %s", i+1, track.GetDisplayName())
|
||||
if track.ArtistName != "" {
|
||||
fmt.Printf(" - %s", track.ArtistName)
|
||||
}
|
||||
fmt.Println()
|
||||
}
|
||||
}
|
||||
|
||||
fmt.Println("\n✓ Library exploration complete!")
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Service Content Discovery
|
||||
|
||||
```go
|
||||
func multiServiceDiscovery(soundtouch *client.Client, accounts map[string]string) {
|
||||
searchTerm := "jazz"
|
||||
fmt.Printf("🔍 Searching '%s' across all services...\n", searchTerm)
|
||||
|
||||
// Search TuneIn (no account needed)
|
||||
fmt.Println("\n📻 TuneIn Results:")
|
||||
tuneInResults, err := soundtouch.SearchTuneInStations(searchTerm)
|
||||
if err != nil {
|
||||
fmt.Printf("❌ TuneIn search failed: %v\n", err)
|
||||
} else {
|
||||
stations := tuneInResults.GetStations()
|
||||
fmt.Printf("✓ Found %d TuneIn stations\n", len(stations))
|
||||
for i, station := range stations[:min(3, len(stations))] {
|
||||
fmt.Printf(" %d. %s\n", i+1, station.GetDisplayName())
|
||||
}
|
||||
}
|
||||
|
||||
// Search Pandora (if account available)
|
||||
if pandoraAccount, ok := accounts["PANDORA"]; ok {
|
||||
fmt.Println("\n🎵 Pandora Results:")
|
||||
pandoraResults, err := soundtouch.SearchPandoraStations(pandoraAccount, searchTerm)
|
||||
if err != nil {
|
||||
fmt.Printf("❌ Pandora search failed: %v\n", err)
|
||||
} else {
|
||||
artists := pandoraResults.GetArtists()
|
||||
stations := pandoraResults.GetStations()
|
||||
fmt.Printf("✓ Found %d artists, %d stations\n", len(artists), len(stations))
|
||||
|
||||
for i, artist := range artists[:min(2, len(artists))] {
|
||||
fmt.Printf(" Artist: %s\n", artist.GetDisplayName())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Search Spotify (if account available)
|
||||
if spotifyAccount, ok := accounts["SPOTIFY"]; ok {
|
||||
fmt.Println("\n🎼 Spotify Results:")
|
||||
spotifyResults, err := soundtouch.SearchSpotifyContent(spotifyAccount, searchTerm)
|
||||
if err != nil {
|
||||
fmt.Printf("❌ Spotify search failed: %v\n", err)
|
||||
} else {
|
||||
songs := spotifyResults.GetSongs()
|
||||
fmt.Printf("✓ Found %d songs\n", len(songs))
|
||||
|
||||
for i, song := range songs[:min(2, len(songs))] {
|
||||
fmt.Printf(" Song: %s\n", song.GetFullTitle())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fmt.Println("\n✓ Multi-service discovery complete!")
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Graceful Error Handling
|
||||
|
||||
```go
|
||||
func robustNavigation(soundtouch *client.Client) error {
|
||||
// Try multiple sources gracefully
|
||||
sources := []string{"TUNEIN", "SPOTIFY", "STORED_MUSIC"}
|
||||
|
||||
for _, source := range sources {
|
||||
fmt.Printf("Trying %s...\n", source)
|
||||
|
||||
response, err := soundtouch.Navigate(source, "", 1, 10)
|
||||
if err != nil {
|
||||
fmt.Printf("❌ %s failed: %v\n", source, err)
|
||||
continue
|
||||
}
|
||||
|
||||
if response.IsEmpty() {
|
||||
fmt.Printf("⚠️ %s has no content\n", source)
|
||||
continue
|
||||
}
|
||||
|
||||
fmt.Printf("✓ %s available with %d items\n", source, response.TotalItems)
|
||||
return nil
|
||||
}
|
||||
|
||||
return fmt.Errorf("no sources available")
|
||||
}
|
||||
```
|
||||
|
||||
### Retry Logic
|
||||
|
||||
```go
|
||||
func searchWithRetry(soundtouch *client.Client, maxRetries int) (*models.SearchStationResponse, error) {
|
||||
var lastErr error
|
||||
|
||||
for attempt := 1; attempt <= maxRetries; attempt++ {
|
||||
fmt.Printf("Search attempt %d/%d...\n", attempt, maxRetries)
|
||||
|
||||
results, err := soundtouch.SearchTuneInStations("classical")
|
||||
if err == nil {
|
||||
return results, nil
|
||||
}
|
||||
|
||||
lastErr = err
|
||||
fmt.Printf("❌ Attempt %d failed: %v\n", attempt, err)
|
||||
|
||||
if attempt < maxRetries {
|
||||
time.Sleep(time.Duration(attempt) * time.Second)
|
||||
}
|
||||
}
|
||||
|
||||
return nil, fmt.Errorf("search failed after %d attempts: %w", maxRetries, lastErr)
|
||||
}
|
||||
```
|
||||
|
||||
### Validation and Safety
|
||||
|
||||
```go
|
||||
func safeStationManagement(soundtouch *client.Client, pandoraAccount string) {
|
||||
// Always validate inputs
|
||||
if pandoraAccount == "" {
|
||||
log.Fatal("Pandora account required")
|
||||
}
|
||||
|
||||
// Search safely
|
||||
results, err := soundtouch.SearchPandoraStations(pandoraAccount, "blues")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
if results.IsEmpty() {
|
||||
fmt.Println("No results found")
|
||||
return
|
||||
}
|
||||
|
||||
// Check what we have before adding stations
|
||||
artists := results.GetArtists()
|
||||
if len(artists) == 0 {
|
||||
fmt.Println("No artists found to create stations from")
|
||||
return
|
||||
}
|
||||
|
||||
// Get current stations to avoid duplicates
|
||||
currentStations, err := soundtouch.GetPandoraStations(pandoraAccount)
|
||||
if err != nil {
|
||||
log.Printf("Warning: Could not get current stations: %v", err)
|
||||
}
|
||||
|
||||
// Create a map of existing station names
|
||||
existingStations := make(map[string]bool)
|
||||
for _, station := range currentStations.Items {
|
||||
existingStations[station.GetDisplayName()] = true
|
||||
}
|
||||
|
||||
// Add stations only if they don't exist
|
||||
for _, artist := range artists[:min(2, len(artists))] {
|
||||
stationName := artist.Name + " Radio"
|
||||
|
||||
if existingStations[stationName] {
|
||||
fmt.Printf("⚠️ Station already exists: %s\n", stationName)
|
||||
continue
|
||||
}
|
||||
|
||||
fmt.Printf("Adding new station: %s\n", stationName)
|
||||
err := soundtouch.AddStation("PANDORA", pandoraAccount, artist.Token, stationName)
|
||||
if err != nil {
|
||||
log.Printf("❌ Failed to add %s: %v", stationName, err)
|
||||
} else {
|
||||
fmt.Printf("✓ Added: %s\n", stationName)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Check Source Availability
|
||||
|
||||
```go
|
||||
// Always check what sources are available first
|
||||
sources, err := soundtouch.GetSources()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// Check if TuneIn is ready
|
||||
for _, source := range sources.SourceItem {
|
||||
if source.Source == "TUNEIN" && source.Status.IsReady() {
|
||||
// TuneIn is available
|
||||
break
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Use Pagination for Large Collections
|
||||
|
||||
```go
|
||||
// For large libraries, use pagination
|
||||
const batchSize = 50
|
||||
|
||||
func processLargeLibrary(soundtouch *client.Client, sourceAccount string) {
|
||||
startItem := 1
|
||||
|
||||
for {
|
||||
batch, err := soundtouch.Navigate("STORED_MUSIC", sourceAccount, startItem, batchSize)
|
||||
if err != nil {
|
||||
log.Printf("Error at position %d: %v", startItem, err)
|
||||
break
|
||||
}
|
||||
|
||||
if len(batch.Items) == 0 {
|
||||
break // No more items
|
||||
}
|
||||
|
||||
// Process this batch
|
||||
processBatch(batch.Items)
|
||||
|
||||
startItem += batchSize
|
||||
|
||||
// Prevent infinite loops
|
||||
if startItem > batch.TotalItems {
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Handle Service-Specific Behavior
|
||||
|
||||
```go
|
||||
func handleServiceDifferences(soundtouch *client.Client) {
|
||||
// TuneIn: Usually no account needed
|
||||
tuneInStations, err := soundtouch.SearchTuneInStations("news")
|
||||
if err == nil {
|
||||
fmt.Printf("TuneIn: %d stations\n", len(tuneInStations.GetStations()))
|
||||
}
|
||||
|
||||
// Pandora: Requires user account
|
||||
pandoraResults, err := soundtouch.SearchPandoraStations("user_account", "rock")
|
||||
if err == nil {
|
||||
// Pandora returns artists you can create stations from
|
||||
artists := pandoraResults.GetArtists()
|
||||
fmt.Printf("Pandora: %d artists\n", len(artists))
|
||||
}
|
||||
|
||||
// Spotify: Requires user account, returns tracks/playlists
|
||||
spotifyResults, err := soundtouch.SearchSpotifyContent("spotify_user", "pop")
|
||||
if err == nil {
|
||||
songs := spotifyResults.GetSongs()
|
||||
fmt.Printf("Spotify: %d songs\n", len(songs))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Implement User-Friendly Interfaces
|
||||
|
||||
```go
|
||||
func userFriendlySearch(soundtouch *client.Client, searchTerm string) {
|
||||
fmt.Printf("🔍 Searching for '%s'...\n", searchTerm)
|
||||
|
||||
results, err := soundtouch.SearchTuneInStations(searchTerm)
|
||||
if err != nil {
|
||||
fmt.Printf("❌ Search failed: %v\n", err)
|
||||
return
|
||||
}
|
||||
|
||||
if results.IsEmpty() {
|
||||
fmt.Printf("😞 No results found for '%s'\n", searchTerm)
|
||||
fmt.Println("💡 Try different search terms like:")
|
||||
fmt.Println(" - Genre names: jazz, rock, classical")
|
||||
fmt.Println(" - Artist names: Beatles, Mozart")
|
||||
fmt.Println(" - Station types: news, talk, music")
|
||||
return
|
||||
}
|
||||
|
||||
stations := results.GetStations()
|
||||
fmt.Printf("🎵 Found %d stations:\n", len(stations))
|
||||
|
||||
for i, station := range stations {
|
||||
fmt.Printf("%d. 📻 %s", i+1, station.GetDisplayName())
|
||||
if station.Description != "" {
|
||||
fmt.Printf("\n %s", station.Description)
|
||||
}
|
||||
if station.GetArtworkURL() != "" {
|
||||
fmt.Printf("\n 🎨 %s", station.GetArtworkURL())
|
||||
}
|
||||
fmt.Println()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Performance Considerations
|
||||
|
||||
```go
|
||||
func efficientBrowsing(soundtouch *client.Client) {
|
||||
// Use reasonable page sizes
|
||||
const optimalPageSize = 25 // Good balance of network efficiency and memory usage
|
||||
|
||||
// Cache frequently accessed data
|
||||
var cachedSources *models.Sources
|
||||
|
||||
getSources := func() (*models.Sources, error) {
|
||||
if cachedSources == nil {
|
||||
var err error
|
||||
cachedSources, err = soundtouch.GetSources()
|
||||
return cachedSources, err
|
||||
}
|
||||
return cachedSources, nil
|
||||
}
|
||||
|
||||
// Use the cached sources
|
||||
sources, err := getSources()
|
||||
if err != nil {
|
||||
return
|
||||
}
|
||||
|
||||
// Process efficiently
|
||||
for _, source := range sources.SourceItem {
|
||||
if source.Status.IsReady() {
|
||||
// Only browse ready sources
|
||||
procesReadySource(soundtouch, source.Source, source.SourceAccount)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### Navigation Methods
|
||||
|
||||
| Method | Description | Parameters | Returns |
|
||||
|--------|-------------|------------|---------|
|
||||
| `Navigate()` | Browse content source | source, account, start, count | NavigateResponse |
|
||||
| `NavigateWithMenu()` | Browse with menu/sort | source, account, menu, sort, start, count | NavigateResponse |
|
||||
| `NavigateContainer()` | Browse into directory | source, account, start, count, container | NavigateResponse |
|
||||
| `GetTuneInStations()` | Convenience for TuneIn | account | NavigateResponse |
|
||||
| `GetPandoraStations()` | Convenience for Pandora | account | NavigateResponse |
|
||||
| `GetStoredMusicLibrary()` | Convenience for stored music | account | NavigateResponse |
|
||||
|
||||
### Search Methods
|
||||
|
||||
| Method | Description | Parameters | Returns |
|
||||
|--------|-------------|------------|---------|
|
||||
| `SearchStation()` | Generic station search | source, account, term | SearchStationResponse |
|
||||
| `SearchTuneInStations()` | Search TuneIn | term | SearchStationResponse |
|
||||
| `SearchPandoraStations()` | Search Pandora | account, term | SearchStationResponse |
|
||||
| `SearchSpotifyContent()` | Search Spotify | account, term | SearchStationResponse |
|
||||
|
||||
### Station Management Methods
|
||||
|
||||
| Method | Description | Parameters | Returns |
|
||||
|--------|-------------|------------|---------|
|
||||
| `AddStation()` | Add station (plays immediately) | source, account, token, name | error |
|
||||
| `RemoveStation()` | Remove station from collection | contentItem | error |
|
||||
|
||||
### Response Helper Methods
|
||||
|
||||
#### NavigateResponse Methods
|
||||
|
||||
- `GetPlayableItems()` - Filter playable items
|
||||
- `GetDirectories()` - Filter directories
|
||||
- `GetTracks()` - Filter music tracks
|
||||
- `GetStations()` - Filter radio stations
|
||||
- `IsEmpty()` - Check if response has no items
|
||||
|
||||
#### SearchStationResponse Methods
|
||||
|
||||
- `GetSongs()` - Filter song results
|
||||
- `GetArtists()` - Filter artist results
|
||||
- `GetStations()` - Filter station results
|
||||
- `GetAllResults()` - Get all results combined
|
||||
- `GetResultCount()` - Count total results
|
||||
- `HasResults()` - Check if any results found
|
||||
- `IsEmpty()` - Check if no results
|
||||
|
||||
#### SearchResult Methods
|
||||
|
||||
- `IsSong()` - Check if result is a song
|
||||
- `IsArtist()` - Check if result is an artist
|
||||
- `IsStation()` - Check if result is a station
|
||||
- `GetDisplayName()` - Get formatted name
|
||||
- `GetFullTitle()` - Get name with artist (for songs)
|
||||
- `GetArtworkURL()` - Get artwork/logo URL
|
||||
|
||||
### Common Source Types
|
||||
|
||||
| Source | Description | Account Required | Search Support |
|
||||
|--------|-------------|------------------|----------------|
|
||||
| `TUNEIN` | Internet radio stations | No | Yes |
|
||||
| `PANDORA` | Pandora music service | Yes | Yes |
|
||||
| `SPOTIFY` | Spotify music service | Yes | Yes |
|
||||
| `STORED_MUSIC` | Local/network music | Device account | No |
|
||||
| `BLUETOOTH` | Bluetooth audio input | No | No |
|
||||
| `AUX` | Auxiliary input | No | No |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"Source not available"**
|
||||
- Check if the service is configured on your SoundTouch device
|
||||
- Verify account credentials are set up properly
|
||||
- Use `GetSources()` to see what's actually available
|
||||
|
||||
**"No results found"**
|
||||
- Try broader search terms
|
||||
- Check if the service is working (try via SoundTouch app)
|
||||
- Verify account has access to content
|
||||
|
||||
**"AddStation failed"**
|
||||
- Ensure the token is valid (from search results)
|
||||
- Check that the service supports adding stations
|
||||
- Verify account permissions
|
||||
|
||||
**Navigation timeouts**
|
||||
- Large libraries may take time to browse
|
||||
- Use smaller page sizes for better performance
|
||||
- Implement timeout handling in your code
|
||||
|
||||
### Getting Help
|
||||
|
||||
For additional help:
|
||||
- Check the SoundTouch device logs
|
||||
- Test functionality via the official SoundTouch app
|
||||
- Review network connectivity between client and device
|
||||
- Examine the raw XML responses for debugging
|
||||
|
||||
---
|
||||
|
||||
*This guide covers the complete navigation and station management functionality. For preset management, see [PRESET-MANAGEMENT.md](PRESET-MANAGEMENT.md).*
|
||||
Reference in New Issue
Block a user