Undocumented Community Features & API Discoveries

This document captures advanced API endpoints and device behaviors discovered by the SoundTouch community through reverse engineering projects like SoundCork and ÜberBöse API. These features are not documented in the official Bose SoundTouch Web API v1.0 but are crucial for full device emulation and offline operation.

Cloud Emulation (Marge/BMX) Discoveries

While the local /8090 API is well-documented, the cloud-side service emulation reveals deeper device integration points.

1. Stereo Pairing & Cloud-Side Grouping

SoundCork has pioneered the emulation of “Marge” group endpoints, which differ from the local /getGroup API. These are primarily used for persistent configurations like Stereo Pairs (e.g., two ST-10s).

• GET /marge/streaming/account/{account}/device/{device}/group Returns <group/> if ungrouped, or full group configuration for stereo pairs.
• POST /marge/streaming/account/{account}/group Creates a new group (returns a 7-digit group ID). Used for initial pairing.
• DELETE /marge/streaming/account/{account}/group/{group} Dissolves a group configuration.

  2. Device Analytics & Event Reporting

  Devices report real-time telemetry to the cloud. Intercepting these provides a window into device usage without polling.

• Endpoint: POST /v1/scmudc/{deviceId}
• Function: Submits event data including play-state-changed, preset-pressed, power-pressed, source-state-changed, and art-changed (Metadata updates). This endpoint was first extensively documented in the ÜberBöse API specification.

  3. Power-On Lifecycle

  When a SoundTouch device boots or “powers on” (distinct from waking from standby), it contacts specific support endpoints.

• Endpoint: POST /streaming/support/power_on
• Behavior: Reports device serial number, IP address, and diagnostic data.
• Critical Finding: SoundTouch devices fetch TUNEIN and LOCAL_INTERNET_RADIO source availability from the cloud ONLY at boot time. If the cloud is unreachable during a hard reboot (power cycle), these sources will disappear from the device’s /sources list and become unavailable, even if the local API is working. This behavior was analyzed and reported by the ÜberBöse API project (Issue #3).

  4. OAuth & Service Tokens

  Integration with music services (Spotify, Pandora, etc.) involves specific token management endpoints.

• Endpoint: POST /oauth/device/{deviceId}/music/musicprovider/{providerId}/token/{tokenType}
• Usage: Used to refresh or validate session tokens for cloud-based music providers.

  Community-Driven Extensions

  The community is working on extending SoundTouch functionality beyond its original design.

  1. Radio-Browser.info Integration

  There is an active effort to add radio-browser.info as a native sourceprovider. This would allow devices to browse a massive directory of thousands of stations without relying on the TuneIn cloud service.

• Status: Research phase in SoundCork (Issue #150).
• Implementation: Requires adding a new source provider entry in the emulated /streaming/sourceproviders response.

  2. Stockholm Internal App Analysis

  Deep analysis of the Stockholm (device firmware) internal web application reveals a set of internal AJAX/XML calls used by the device’s own control interface.

• Internal Domains: Marge (XML-based) and Gabbo (App-send based).
• Reference: See SoundCork Issue #128 for a comprehensive list of internal JS controllers and their functions.

  3. ETag Case-Sensitivity Bug

  The SoundTouch device firmware has a case-sensitivity bug regarding HTTP ETag headers.

• Discovery: SoundCork Issue #129.
• Detail: The device expects the ETag header to be exactly title-cased. If a server returns etag (lowercase), the device fails to use it for If-None-Match requests, breaking efficient preset synchronization.
• Solution: Force title-casing of the header via a reverse proxy like Nginx or mitmproxy.

  References

• SoundCork GitHub Repo
• ÜberBöse API Spec
• SoundTouch Plus Wiki
• IsItBose Regex Research
• SoundTouch Hook Repo