github/Bose-SoundTouch
1
0
Fork 0
mirror of https://github.com/gesellix/Bose-SoundTouch.git synced 2026-08-19 17:16:16 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
ea2b6502b2f32b37943f1185cb843f67bda3bd4b
Bose-SoundTouch/docs/API-Endpoints-Overview.md
T
Tobias Gesellchen ea2b6502b2 docs: sync all documentation with current implementation status 
Documentation Updates:
• Update README.md to reflect implemented key controls and volume management
• Add implementation status indicators to API-Endpoints-Overview.md
• Update PLAN.md roadmap to show completed phases
• Create STATUS.md with comprehensive project status summary

Key Changes:
• Mark key controls and volume management as implemented (not planned)
• Add CLI examples for media controls and volume management
• Update API overview with ✅/🔄 status indicators
• Document press+release key pattern implementation
• Add real device validation notes
• Update Go library usage examples

Current Status:
✅ 6/6 Informational endpoints complete
✅ 2/3 Core control endpoints complete (key + volume)
✅ Host:port parsing enhancement
✅ Production-ready CLI with safety features
✅ Comprehensive testing with real devices

Next Priority:
🔄 Source selection, bass control, preset management
2026-01-09 00:00:54 +01:00

6.9 KiB
Raw Blame History

Bose SoundTouch Web API - Endpoints Overview

This document provides a comprehensive overview of the available API endpoints of the Bose SoundTouch Web API based on the official specification.

Implementation Status Legend

  • ✅ Implemented - Fully implemented with tests and real device validation
  • 🔄 Planned - Not yet implemented, planned for future development
  • 📝 Documented - API documented but not implemented

API Basics

  • Protocol: HTTP REST-like
  • Data Format: XML Request/Response
  • Standard Port: 8090
  • Base URL: http://<device-ip>:8090/
  • Authentication: No complex authentication required
  • Real-time Updates: WebSocket connection available

Device Information

GET /info ✅ Implemented

Retrieves basic device information.

Response XML Structure:

<info deviceID="..." type="..." name="..." ...>
  <name>Device Name</name>
  <type>Device Type</type>
  <margeAccountUUID>UUID</margeAccountUUID>
  <components>...</components>
</info>

Playback Control

GET /now_playing ✅ Implemented

Retrieves information about the currently playing music.

Response XML Structure:

<nowPlaying deviceID="..." source="...">
  <ContentItem source="..." type="..." location="..." sourceAccount="...">
    <itemName>Track Name</itemName>
    <containerArt>Album Art URL</containerArt>
  </ContentItem>
  <track>Track Name</track>
  <artist>Artist Name</artist>
  <album>Album Name</album>
  <stationName>Station Name</stationName>
  <art artImageStatus="...">Art URL</art>
  <playStatus>PLAY_STATE</playStatus>
  <shuffleSetting>...</shuffleSetting>
  <repeatSetting>...</repeatSetting>
</nowPlaying>

POST /key ✅ Implemented

Sends key commands to the device.

Important: Proper key simulation requires sending both press and release states:

Request XML (Press + Release):

<key state="press" sender="Gabbo">KEY_NAME</key>
<key state="release" sender="Gabbo">KEY_NAME</key>

Available Keys:

  • PLAY
  • PAUSE
  • STOP
  • PREV_TRACK
  • NEXT_TRACK
  • THUMBS_UP
  • THUMBS_DOWN
  • BOOKMARK
  • POWER
  • MUTE
  • VOLUME_UP
  • VOLUME_DOWN
  • PRESET_1 to PRESET_6
  • AUX_INPUT
  • SHUFFLE_OFF
  • SHUFFLE_ON
  • REPEAT_OFF
  • REPEAT_ONE
  • REPEAT_ALL

Volume Control

GET /volume ✅ Implemented

Retrieves the current volume.

Response XML:

<volume deviceID="...">
  <targetvolume>50</targetvolume>
  <actualvolume>50</actualvolume>
  <muteenabled>false</muteenabled>
</volume>

POST /volume ✅ Implemented

Sets the volume.

Request XML:

<volume>50</volume>

Bass Settings

GET /bass 🔄 Planned

Retrieves the current bass settings.

Response XML:

<bass deviceID="...">
  <targetbass>0</targetbass>
  <actualbass>0</actualbass>
</bass>

POST /bass 🔄 Planned

Sets the bass settings (-9 to +9).

Request XML:

<bass>0</bass>

Source Management

GET /sources ✅ Implemented

Retrieves the available audio sources.

Response XML:

<sources deviceID="...">
  <sourceItem source="SPOTIFY" sourceAccount="..." status="READY" multiroomallowed="true">
    <itemName>Spotify</itemName>
  </sourceItem>
  <sourceItem source="BLUETOOTH" status="READY" multiroomallowed="false">
    <itemName>Bluetooth</itemName>
  </sourceItem>
  <!-- Additional sources -->
</sources>

Typical Sources:

  • SPOTIFY
  • AMAZON
  • PANDORA
  • IHEARTRADIO
  • TUNEIN
  • BLUETOOTH
  • AUX
  • STORED_MUSIC

POST /select 🔄 Planned

Selects an audio source.

Request XML:

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

Preset Management

GET /presets ✅ Implemented

Retrieves the configured presets.

Response XML:

<presets deviceID="...">
  <preset id="1" createdOn="..." updatedOn="...">
    <ContentItem source="..." sourceAccount="..." location="...">
      <itemName>Preset Name</itemName>
      <containerArt>Art URL</containerArt>
    </ContentItem>
  </preset>
  <!-- Additional presets -->
</presets>

POST /presets 🔄 Planned

Creates or updates a preset.

Request XML:

<preset id="1">
  <ContentItem source="..." sourceAccount="..." location="...">
    <itemName>Preset Name</itemName>
  </ContentItem>
</preset>

Advanced Features

GET /getZone 🔄 Planned

Retrieves multiroom zone information.

POST /setZone 🔄 Planned

Configures multiroom zones.

GET /balance 🔄 Planned

Retrieves balance settings (stereo devices).

POST /balance 🔄 Planned

Sets balance settings.

GET /clockTime 🔄 Planned

Retrieves the device time.

POST /clockTime 🔄 Planned

Sets the device time.

GET /clockDisplay 🔄 Planned

Retrieves clock display settings.

POST /clockDisplay 🔄 Planned

Configures the clock display.

WebSocket Connection

WebSocket / 🔄 Planned

Establishes a persistent connection for live updates.

Event Types:

  • nowPlayingUpdated
  • volumeUpdated
  • connectionStateUpdated
  • presetUpdated

Network and System

GET /networkInfo 🔄 Planned

Retrieves network information.

GET /capabilities ✅ Implemented

Retrieves device capabilities.

GET /name ✅ Implemented

Retrieves the device name.

POST /reboot 🔄 Planned

Restarts the device.

Error Handling

The API uses standard HTTP status codes:

  • 200 OK - Successful request
  • 400 Bad Request - Invalid request
  • 404 Not Found - Endpoint or resource not found
  • 500 Internal Server Error - Internal device error

Example Implementation

// Example for a GET request
func GetNowPlaying(deviceIP string) (*NowPlaying, error) {
    url := fmt.Sprintf("http://%s:8090/now_playing", deviceIP)
    resp, err := http.Get(url)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var nowPlaying NowPlaying
    err = xml.NewDecoder(resp.Body).Decode(&nowPlaying)
    return &nowPlaying, err
}

// Example for a POST request
func SendKey(deviceIP string, key string) error {
    url := fmt.Sprintf("http://%s:8090/key", deviceIP)
    xmlData := fmt.Sprintf(`<key state="press" sender="GoClient">%s</key>`, key)
    
    resp, err := http.Post(url, "application/xml", strings.NewReader(xmlData))
    if err != nil {
        return err
    }
    resp.Body.Close()
    return nil
}

Notes

  1. XML Namespace: Most responses use no explicit XML namespace
  2. Encoding: UTF-8 is used for all XML documents
  3. Timeouts: Recommended timeout for HTTP requests: 10 seconds
  4. Rate Limiting: No explicit limits documented, but moderate usage recommended
  5. Device Discovery: Devices can be found via UPnP on the local network

Reference

Based on the official Bose SoundTouch Web API documentation: https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf

Reference in New Issue View Git Blame Copy Permalink