mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-19 00:56:16 +00:00
Tobias Gesellchen
2a9f219d40
- Add root package documentation with quick start guide and feature overview - Enhance client package with detailed usage examples and API coverage - Add comprehensive discovery package documentation with protocol explanations - Create models package documentation explaining all data structures - Add extensive example functions for all major use cases: * Basic device control and playback * Volume, bass, and balance management * Source selection and preset handling * Multiroom zone management * Real-time WebSocket event monitoring * Device discovery with UPnP and mDNS * Error handling and context cancellation - Include code examples for pkg.go.dev's example rendering - Document API endpoints, data structures, and best practices - Add hardware compatibility and implementation notes
156 lines
4.3 KiB
Go
156 lines
4.3 KiB
Go
// Package bose-soundtouch provides a comprehensive Go library and CLI tool for controlling Bose SoundTouch devices.
|
|
//
|
|
// This library implements the complete Bose SoundTouch Web API, enabling programmatic control
|
|
// of SoundTouch speakers including playback control, volume management, source selection,
|
|
// multiroom zone management, and real-time event monitoring via WebSocket connections.
|
|
//
|
|
// # Quick Start
|
|
//
|
|
// Install the library:
|
|
//
|
|
// go get github.com/gesellix/bose-soundtouch
|
|
//
|
|
// Basic usage example:
|
|
//
|
|
// package main
|
|
//
|
|
// import (
|
|
// "fmt"
|
|
// "log"
|
|
//
|
|
// "github.com/gesellix/bose-soundtouch/pkg/client"
|
|
// )
|
|
//
|
|
// func main() {
|
|
// // Create a client for your SoundTouch device
|
|
// config := &client.Config{
|
|
// Host: "192.168.1.100",
|
|
// Port: 8090,
|
|
// }
|
|
// client := client.NewClient(config)
|
|
//
|
|
// // Get device information
|
|
// info, err := client.GetInfo()
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
// fmt.Printf("Device: %s\n", info.Name)
|
|
//
|
|
// // Control playback
|
|
// err = client.Play()
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
//
|
|
// // Set volume
|
|
// err = client.SetVolume(50)
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
// }
|
|
//
|
|
// # Device Discovery
|
|
//
|
|
// Automatically discover SoundTouch devices on your network:
|
|
//
|
|
// import "github.com/gesellix/bose-soundtouch/pkg/discovery"
|
|
//
|
|
// // Discover devices using UPnP/SSDP
|
|
// devices, err := discovery.DiscoverDevices(ctx, 5*time.Second)
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
//
|
|
// for _, device := range devices {
|
|
// fmt.Printf("Found device: %s at %s\n", device.Name, device.Host)
|
|
// }
|
|
//
|
|
// # Real-time Events
|
|
//
|
|
// Monitor device state changes in real-time using WebSocket connections:
|
|
//
|
|
// // Subscribe to device events
|
|
// events, err := client.SubscribeToEvents(ctx)
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
//
|
|
// for event := range events {
|
|
// switch e := event.(type) {
|
|
// case *models.NowPlayingUpdated:
|
|
// fmt.Printf("Now playing: %s by %s\n", e.Track, e.Artist)
|
|
// case *models.VolumeUpdated:
|
|
// fmt.Printf("Volume changed to: %d\n", e.ActualVolume)
|
|
// }
|
|
// }
|
|
//
|
|
// # Multiroom Zone Management
|
|
//
|
|
// Create and manage multiroom zones:
|
|
//
|
|
// // Create a zone with multiple speakers
|
|
// zone := &models.Zone{
|
|
// Master: "192.168.1.100",
|
|
// Members: []models.ZoneMember{
|
|
// {IPAddress: "192.168.1.101"},
|
|
// {IPAddress: "192.168.1.102"},
|
|
// },
|
|
// }
|
|
// err = client.SetZone(zone)
|
|
//
|
|
// # CLI Tool
|
|
//
|
|
// The package includes a comprehensive CLI tool for device control:
|
|
//
|
|
// # Install the CLI
|
|
// go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-cli@latest
|
|
//
|
|
// # Discover devices
|
|
// soundtouch-cli discover devices
|
|
//
|
|
// # Control a device
|
|
// soundtouch-cli --host 192.168.1.100 play start
|
|
// soundtouch-cli --host 192.168.1.100 volume set --level 50
|
|
// soundtouch-cli --host 192.168.1.100 source select --source SPOTIFY
|
|
//
|
|
// # Supported Features
|
|
//
|
|
// - ✅ Device Information & Capabilities
|
|
// - ✅ Playback Control (Play/Pause/Stop/Next/Previous)
|
|
// - ✅ Volume, Bass, and Balance Control
|
|
// - ✅ Source Selection (Spotify, Bluetooth, AUX, etc.)
|
|
// - ✅ Preset Management
|
|
// - ✅ Clock/Time Management
|
|
// - ✅ Network Information
|
|
// - ✅ Real-time WebSocket Events
|
|
// - ✅ Multiroom Zone Management
|
|
// - ✅ Device Discovery (UPnP/SSDP and mDNS)
|
|
// - ✅ Cross-platform Support (Windows, macOS, Linux)
|
|
//
|
|
// # Package Structure
|
|
//
|
|
// - client: HTTP client for SoundTouch Web API
|
|
// - discovery: Device discovery using UPnP/SSDP and mDNS
|
|
// - models: Data structures for API requests/responses
|
|
// - config: Configuration management
|
|
// - cmd/soundtouch-cli: Command-line interface tool
|
|
//
|
|
// # Hardware Compatibility
|
|
//
|
|
// This library has been tested with real Bose SoundTouch hardware and supports
|
|
// all SoundTouch-compatible devices including:
|
|
// - SoundTouch 10, 20, 30 series
|
|
// - SoundTouch Portable
|
|
// - Wave SoundTouch music system
|
|
// - And other SoundTouch-enabled Bose speakers
|
|
//
|
|
// # Implementation Notes
|
|
//
|
|
// This implementation is based on the official Bose SoundTouch Web API documentation
|
|
// and provides 90% coverage of all available endpoints. It is an independent project
|
|
// and is not affiliated with or endorsed by Bose Corporation.
|
|
//
|
|
// For detailed API documentation, examples, and advanced usage patterns, visit:
|
|
// https://pkg.go.dev/github.com/gesellix/bose-soundtouch
|
|
package main
|