Choose Sonos and Plex connections
Choose Sonos and Plex connections in Media connections for the selected home. A household manager chooses Sonos and Plex independently using the choices and unavailable reasons returned for that home. On a PLATFORM-hosted home, Sonos defaults to cloud and may switch to a reachable local connector; Plex may use a reachable local connector or stay disabled, and there is no Plex cloud option. These preferences change only media routing for this home. They do not change hosting mode, other connectors, devices, or credentials. Web and phone clients edit these settings, while TV uses the chosen route without infrastructure controls.
Who can change these settings
Section titled “Who can change these settings”Only a household manager can edit media connections for a home. Read and write access must use the authenticated API for the selected tenant and home.
Respect the server-returned permissions. Do not bypass home authorization, and do not call internal transport endpoints from public clients.
Read current runtime choices
Section titled “Read current runtime choices”Use:
GET /properties/:propertyId/connector-runtime?tenantId=...
The response includes:
| Field | Meaning |
|---|---|
propertyId | The home being configured |
version | The current settings version |
services | The configurable media services for this home |
Each item in services describes one service and includes:
| Field | Meaning |
|---|---|
selected | The saved preference |
effective | The route currently in effect |
source | Where the effective result comes from |
choices | The selectable options and whether each is available |
local | Local readiness for that service |
For Sonos, the available choices can include default, cloud, and local.
For Plex, there is no cloud option. Plex can use local when available or remain disabled.
Use the returned choices and their reasons exactly as given. Availability and returned reasons must govern disabled choices.
Choose Sonos or Plex
Section titled “Choose Sonos or Plex”Update one service at a time with:
PUT /properties/:propertyId/connector-runtime?tenantId=...
Send:
| Field | Meaning |
|---|---|
version | The version you last read |
service | The single service being changed |
selection | The new choice for that service |
Workflow
Section titled “Workflow”- Read the current runtime settings.
- Show the returned choices for Sonos or Plex.
- Let the household manager change one service.
- Send the update with the current
version. - Wait for confirmation after saving.
- If the server reports a stale version with HTTP 409, reload and try again.
If another editor changed the settings, reload before trying again.
What each choice means
Section titled “What each choice means”On a PLATFORM-hosted home:
- Sonos defaults to cloud.
- The home may select a reachable local connector instead.
- Local requires the correctly bound reachable home connector, not merely a reachable server.
A cloud-dependent connector requires the provider and network. Do not claim Sonos cloud is available when its cloud path is unavailable.
A local function can keep working during a cloud outage, but only when the returned choice indicates the local route is available for that home.
Plex has no cloud option.
The home can:
- use a reachable local connector, or
- leave Plex disabled.
On a PLATFORM-hosted home, if local Plex is not available, treat Plex as unavailable rather than inferring any cloud fallback.
Confirmed state vs pending state
Section titled “Confirmed state vs pending state”A successful save request is not enough to prove the route is active.
Follow pending versus confirmed results and the current reported state. Respect server-returned versions, availability, and operation results. Do not infer a supported action from brand, model, cached state, or a successful request acknowledgement.
effective is the applied runtime preference, but effective preference is not connectivity proof.
Conflicts and temporary blocks
Section titled “Conflicts and temporary blocks”Handle these cases explicitly:
- HTTP 409 stale version: another change won first. Reload and resubmit if needed.
- Sonos restoration in progress: audio restoration in progress can temporarily block a Sonos route change. Sonos restoration in progress also produces a conflict, so do not repeatedly force a route change.
If a save conflicts, refresh state before presenting another action.
Client behavior requirements
Section titled “Client behavior requirements”When building the UI or automation around this setting:
- Use the authenticated API and capability/settings descriptors for the selected tenant and home.
- Preserve settings fields the client does not edit.
- Update only one service per request.
- Respect server-returned permissions, availability, versions and pending versus confirmed results.
- Follow correlated operation results and current reported state.
- Keep actionable notification navigation scoped to the identified device and home.
Device-type settings are shared across brands exposing the required capabilities, so rely on descriptors and returned state rather than vendor-specific assumptions.
Surface behavior
Section titled “Surface behavior”Web and phone clients edit these preferences.
TV does not expose infrastructure controls for Sonos or Plex selection. TV uses the chosen route without infrastructure controls.
Access boundaries for credentials
Section titled “Access boundaries for credentials”If you are building or testing a connector around these flows:
- household permissions are narrower than staff
- DEV credentials act in the developer sandbox
- LIVE credentials only for their own installed connector
Those boundaries matter when deciding which homes and integrations a caller may inspect or modify.