version: "1.0.2" name: sonos-casting description: Sonos UPnP discovery, multi-room casting, coordinator transfer, custom checkbox UI, and protocol quirks. Use when working on Sonos casting, UPnP control, multi-room audio, or group management.

Sonos Integration

This guide covers Sonos speaker discovery, casting, and multi-room grouping in NullPlayer.

Quick Start

1. Open Sonos from either:

• Right-click anywhere in NullPlayer → Output Devices → Sonos
• Top menu bar → Output → Sonos

1. Check the rooms you want to cast to (checkboxes stay open for multi-select)
2. Click 🟢 Start Casting to begin playback
3. Click 🔴 Stop Casting from the Sonos menu to fully end the cast session

Discovery Methods

NullPlayer uses two methods to discover Sonos devices:

1. SSDP (Simple Service Discovery Protocol)

• UDP multicast to 239.255.255.250:1900
• Search target: urn:schemas-upnp-org:device:ZonePlayer:1
• Works on most networks but can be blocked by firewalls/routers

2. mDNS/Bonjour (Fallback)

• Service type: _sonos._tcp.local.
• Uses Apple's NWBrowser API
• More reliable on networks that block UDP multicast
• Added as fallback due to Sonos app changes in 2024-2025

Requirements

UPnP Must Be Enabled

Sonos added a UPnP toggle in their app settings. Discovery will fail if disabled.

To enable:

1. Open Sonos app (iOS/Android)
2. Go to Account → Privacy & Security → Connection Security
3. Ensure UPnP is ON (default)

If UPnP is disabled, SSDP discovery won't find devices and SOAP control won't work.

Connection Security (Firmware 85.0+, July 2025)

Sonos firmware 85.0-66270 added optional security settings:

NullPlayer detects 401/403 SOAP errors and shows a specific message directing users to the Connection Security settings.

Architecture

Zone vs Group vs Room

• Zone: Individual Sonos speaker hardware (e.g., a single Sonos One)
• Room: A named location that may contain one or more zones (e.g., "Living Room" with stereo pair)
• Group: Multiple rooms playing in sync (e.g., "Living Room + Kitchen")

When casting, NullPlayer targets the group coordinator - the speaker that controls playback for the group.

Discovery Flow

1. SSDP/mDNS finds Sonos devices on network
2. Fetch device description XML from each device (port 1400)
3. Extract room name, UDN (unique device name), and AVTransport URL
4. After 3 seconds, fetch group topology from any zone
5. Create cast devices based on groups (showing coordinator only)

Group Topology

Fetched via SOAP request to /ZoneGroupTopology/Control:

<u:GetZoneGroupState xmlns:u="urn:schemas-upnp-org:service:ZoneGroupTopology:1"/>

Response contains all groups and their member zones.

User Interface

Menu Structure

Sonos                          ▸
├── ☐ Dining Room                 (checkbox - selectable room)
├── ☐ Living Room                 (checkbox - selectable room)  
├── ☐ Kitchen                     (checkbox - selectable room)
├── ─────────────────
├── 🟢 Start Casting              (when NOT casting)
│   OR
├── 🔴 Stop Casting               (when casting)
└── Refresh

Checkbox Behavior

When NOT casting:

When casting:

Multi-Select Feature

The room checkboxes use SonosRoomCheckboxView which keeps the menu open when clicked, allowing you to select multiple rooms without the menu closing.

This behavior is intentionally the same in both:

• Context menu Sonos submenu
• Top menu bar Output > Sonos submenu

Casting Workflow

Starting a Cast

1. Load music - Play or load a track from Plex, Subsonic, local files, or internet radio
2. Open Sonos menu - Right-click → Output Devices → Sonos
3. Select rooms - Check one or more room checkboxes
4. Start casting - Click "🟢 Start Casting"

The app will:

• Cast to the first selected room
• Join additional rooms to that group
• Update checkboxes to show which rooms are receiving audio

Internet Radio Note: Radio streams are live and don't support seeking. When you cast a radio station, time resets to 0:00.

Managing Rooms While Casting

While casting is active:

• Check a room → Room joins the cast group and starts playing
• Uncheck a non-coordinator room → Room leaves the group and stops playing
• Uncheck the coordinator room (with other rooms still checked) → Playback transfers to the next remaining room, which becomes the new coordinator. Brief (~1-2s) playback interruption during transfer. Menu closes to refresh state.
• Uncheck the coordinator room (only room in group) → Casting stops entirely

Coordinator transfer implementation: CastManager.transferSonosCast() saves session state, stops the old coordinator, casts to the new coordinator, and re-joins other rooms. Uses UPnPManager.disconnectSession() to clear the session without sending Stop (old coordinator is already standalone after leaving). stopCasting() ungroups all member rooms before stopping the coordinator to prevent stale group topology on subsequent casts. Polling is also stopped at the top of stopCasting() before any ungrouping SOAP calls.

Stopping a Cast

There are two intentional stop paths:

• Player Stop button / end-of-playlist: sends Stop to Sonos but keeps upnpManager.activeSession, selected rooms, group membership, and LocalMediaServer registrations intact. The next compatible track reuses the same Sonos target without re-selecting rooms. This path is AudioEngine.stop() or castTrackDidFinish() → CastManager.softStopForActiveDevice() → stopPlayback().
• Sonos menu 🔴 Stop Casting: fully tears down the cast session via CastManager.stopCasting().

Click 🔴 Stop Casting to fully disconnect:

• Ungroup all member rooms (each becomes standalone)
• Stop playback on the coordinator
• Clear all room selections
• Return to local control (stopped; use the play button to resume)

Casting Protocol

AVTransport Control

• Control URL: http://{ip}:1400/MediaRenderer/AVTransport/Control
• Service type: urn:schemas-upnp-org:service:AVTransport:1

Key actions:

• SetAVTransportURI - Set media URL with DIDL-Lite metadata
• Play - Start playback
• Pause - Pause playback
• Stop - Stop playback
• Seek - Seek to position (REL_TIME format: HH:MM:SS)
• GetTransportInfo - Get transport state
• GetPositionInfo - Get current position and duration

Fire-and-Forget Commands

For Sonos audio casting, playback control commands use a fire-and-forget pattern:

Why fire-and-forget?

• Sonos SOAP requests can take 5-10 seconds
• Blocking makes the UI unresponsive
• Commands succeed even without waiting for acknowledgment

Error detection: Consecutive failures are tracked. After 3 failures, a user-facing error notification is posted.

Volume Control

Sonos uses GroupRenderingControl (not RenderingControl) so that volume/mute apply to the whole group, not just the coordinator zone. Non-Sonos DLNA devices still use RenderingControl.

This is handled in UPnPManager.setVolume(_:), getVolume(), and setMute(_:) by branching on session.device.type == .sonos.

Playback State Monitoring

NullPlayer polls Sonos every 5 seconds during casting:

• GetTransportInfo — Returns transport state (PLAYING, PAUSED_PLAYBACK, STOPPED, etc.)
• GetPositionInfo — Returns current position and duration

What polling detects:

• Sonos stopped externally (paused via Sonos app, speaker went to sleep)
• Track position drift (syncs local timer)
• Device unreachable (SOAP timeout) — tears down the session after 3 consecutive poll failures (~15s)

Polling lifecycle:

• Started (startSonosPolling) when Sonos casting begins
• Stopped (stopSonosPolling) at the top of stopCasting(), before ungrouping rooms
• Also runs post-wake check after Mac sleep

Position sync: Each PLAYING poll updates activeSession.position and sets activeSession.playbackStartDate = Date(). On PAUSED_PLAYBACK, playbackStartDate is set to nil so the timer freezes. CastManager.currentTime interpolates session.position + elapsed(since: playbackStartDate) — the same pattern used for Chromecast.

Seek clock sync: Sonos Seek is fire-and-forget, so an audio seek must optimistically re-anchor activeSession.position to the requested target and reset playbackStartDate when the session is playing. Do this for audio as well as video. Otherwise Sonos can reach EOF before the next 5-second poll while NullPlayer still evaluates completion from the pre-seek position.

Poll failure tracking and teardown: pollSonosState() counts consecutive pollSonosPlaybackState() failures (each returns nil). When the counter reaches 3 consecutive failures (~15s of poll timeouts), the cast session is torn down via _stopCastingCore(), returning audio playback to local. The counter is reset to 0 on every successful poll or when a new cast starts. Early post-stop race failures (detected by checking isAudioCastRoutingActive) are ignored so they don't trigger false teardowns.

Resilience and Recovery

CoreAudio route churn:

• Sonos grouping, coordinator transfer, room switching, Wi-Fi changes, Zoom routes, and AirPlay-style output changes can trigger local AVAudioEngineConfigurationChange notifications even while cast playback is remote.
• Local AudioEngine graph rebuilds must be deferred while CastManager.activeSession exists or AudioEngine.isAnyCastingActive is true.
• See skills/audio-system/audio-pipelines.md — Cast Route-Change Safety.

Network change detection:

• LocalMediaServer monitors network changes via NWPathMonitor and refreshes its own bound IP when Wi-Fi changes.
• UPnPManager also monitors network changes. When the active local IP changes, or the network returns after being unavailable, it stops SSDP/mDNS discovery, clears cached Sonos/DLNA device URLs and Sonos topology, then starts discovery on the current interface.
• Active Sonos casts are ended only when the local IP actually changes. A pure reconnect refreshes discovery without tearing down a working speaker session.

Mac sleep/wake handling:

• CastManager observes sleep/wake notifications
• On wake: waits 2s for network, refreshes local/UPnP network state, then polls Sonos state if casting and updates UI

Server health checks:

• LocalMediaServer pings itself every 30 seconds
• Auto-restarts if the ping fails

Group topology refresh:

• During casting, group topology refreshed every 60 seconds
• Detects external group changes

Cast-failure auto-recovery (stale coordinator after reboot):

• Casts target the group coordinator via the control URL cached in sonosZones + lastFetchedGroups. Topology is only re-fetched on a local-IP change or every 60s while a cast is already active — never before initiating a new cast. A speaker reboot is not an IP change, so the cached coordinator can go stale and SetAVTransportURI/Play returns HTTP 500. Manually refreshing the device list used to be the only fix.
• Both AVTransport SOAP error sites now throw CastError.soapError(statusCode:detail:) instead of playbackFailed, so the status code is reliably available to callers (UPnPManager.sendSetAVTransportURI fails fast with no retry; sendSOAPAction still retries transient 5xx first).
• CastManager.cast(...) .sonos branch: on a recoverable failure (soapError ≥ 500, networkError, or a raw URL-loading error) it disconnect()s, calls the awaitable UPnPManager.refreshSonosGroupTopologyAwait(). The refresh validates the HTTP response, tries each cached zone until one returns a valid topology, and blocks until the device/coordinator list is rebuilt. It then maps the old zone UDN through fresh group membership to the current coordinator (falling back to room-name matching) and retries the cast once. If no zone returns valid topology, it preserves the cached topology and does not retry the stale endpoint.
• Recovery is Sonos-only and retries at most once; a genuinely fatal error (401/403 Connection Security, unsupported format) is not retried and surfaces its existing message.

Mid-cast unreachability teardown (speaker reboot/power loss):

• While a cast is active, pollSonosState() continuously queries GetTransportInfo and GetPositionInfo every 5 seconds. If the poll fails 3 consecutive times (indicating the speaker is unreachable, e.g., due to a reboot or power loss), the session is automatically torn down via _stopCastingCore(), cleanly returning audio playback to local and clearing the UI. The counter is reset to 0 on every successful poll or when a new cast begins. Early post-stop poll failures (detected by isAudioCastRoutingActive check) are ignored to avoid false positives during normal teardown races.
• This is distinct from the stale-coordinator auto-recovery above: stale-coordinator recovery fires during cast() before playback starts; mid-cast unreachability detection fires during active polling if the speaker becomes unreachable while casting.

Premature STOPPED after a near-end Plex FLAC seek:

• Reproduced deterministically on a Living Room Sonos Arc (S19, S2 firmware 96.0-79160, home-theater/bonded renderer) while a Dining Room renderer handled repeated tests correctly.
• NullPlayer sent a valid REL_TIME seek to a direct Plex FLAC URL. The Arc acknowledged the SOAP request in about 15 ms and reported PLAYING at the requested position, then changed to STOPPED at position 0 after only 3–4 seconds while still advertising 12–18 seconds of remaining duration. This points to receiver-specific FLAC time-to-byte/range seeking behavior, not a rejected SOAP command.
• The ordinary natural-finish classifier intentionally has a tight 6-second tolerance so an external stop near the end does not advance. The Arc's premature EOF falls outside that tolerance and would therefore be misclassified as an external stop, leaving playback paused.
• CastManager briefly records a Sonos seek made within the final 30 seconds (and no earlier than halfway through a short track). If the same session was playing, its local clock reached the target, and Sonos reports STOPPED within 12 seconds, classify that report as EOF and use the normal cast-track advance path. Clear the recent-seek state on a new cast/track, teardown, local Stop, and after the first STOPPED classification. Rooms that play through normally remain on the ordinary completion path.
• Regression status: this is not introduced by the #419 changes. Fire-and-forget Sonos seeking existed from the initial January 2026 casting implementation, and STOPPED polling paused playback from the February 2026 resilience work. #419 added the 6-second natural-finish classifier for #415; the Arc/Plex case is a pre-existing renderer edge case that exceeded that classifier's intended tolerance.

Group Management

Join a group - SetAVTransportURI with x-rincon:{coordinator_uid}:

<u:SetAVTransportURI xmlns:u="urn:schemas-upnp-org:service:AVTransport:1">
  <InstanceID>0</InstanceID>
  <CurrentURI>x-rincon:RINCON_xxxx</CurrentURI>
  <CurrentURIMetaData></CurrentURIMetaData>
</u:SetAVTransportURI>

Leave a group - BecomeCoordinatorOfStandaloneGroup:

<u:BecomeCoordinatorOfStandaloneGroup xmlns:u="urn:schemas-upnp-org:service:AVTransport:1">
  <InstanceID>0</InstanceID>
</u:BecomeCoordinatorOfStandaloneGroup>

Implementation Details

State Management

CastManager.swift maintains:

/// Rooms selected for Sonos casting (UDNs) - used before casting starts
var selectedSonosRooms: Set<String> = []

Custom Checkbox View

SonosRoomCheckboxView is an NSView subclass that:

• Renders a checkbox with the room name
• Handles clicks without closing the menu
• Updates selectedSonosRooms when not casting
• Joins/unjoins rooms when casting is active

@objc private func checkboxClicked(_ sender: NSButton) {
    if isCastingToSonos {
        // Toggle actual Sonos group membership
        if isNowChecked {
            joinSonosToGroup(...)
        } else {
            unjoinSonos(...)
        }
    } else {
        // Just update local selection state
        if isNowChecked {
            selectedSonosRooms.insert(roomUDN)
        } else {
            selectedSonosRooms.remove(roomUDN)
        }
    }
}

Device Matching

Challenge: sonosRooms returns room UDNs, but sonosDevices only contains group coordinators.

Solution in castToSonosRoom:

1. Try direct ID match (room is a coordinator)
2. Fall back to matching by room name
3. Use first available device as last resort

Local File Casting

Local files are supported via an embedded HTTP server (LocalMediaServer):

• Port: 8765
• Seeking: Supports HTTP Range requests
• Network binding: Binds to local network interface (en0/en1), not localhost
• HEAD requests: Handles HEAD requests (Sonos may send HEAD before GET)

Supported content:

• ✅ Plex streaming (with token in URL)
• ✅ Subsonic/Navidrome streaming (via proxy)
• ✅ Jellyfin streaming (via proxy)
• ✅ Emby streaming (via proxy)
• ✅ Local files (via embedded HTTP server)
• ✅ Internet radio (Shoutcast/Icecast streams)

Subsonic/Navidrome/Jellyfin/Emby Casting: Streams are proxied through LocalMediaServer because:

1. Sonos has issues with URLs containing query parameters
2. The media server may be localhost-bound, unreachable by Sonos

Artwork Display

NullPlayer sends artwork URLs via DIDL-Lite metadata:

See artwork-debugging-history.md for historical artwork troubleshooting attempts.

Sonos Protocol Quirks

Content-Type matching: The content type in DIDL-Lite protocolInfo must match the actual HTTP Content-Type header. Use track.contentType when a backend provides it; otherwise use CastManager.detectAudioContentType(for:) to detect from file extension. Extensionless server streams must not fall back to audio/mpeg when API metadata says the codec/container is FLAC, WAV, ALAC, etc.

Content-Length for MP3/OGG: Sonos closes the connection if Content-Length is missing for MP3 and OGG. Chunked transfer encoding only works for WAV/FLAC.

HEAD requests: Sonos sends HTTP HEAD before GET to check file size. LocalMediaServer handles both methods.

Radio streams: MP3 radio streams use x-rincon-mp3radio:// URI scheme for better Sonos buffering.

Error 701: "Transition Not Available" - occurs when the speaker is busy. NullPlayer waits for transport ready state before retrying.

Redirect limitation: Sonos doesn't follow HTTP 30x redirects with relative URLs - only absolute URLs work.

Supported formats: MP3 (320kbps), AAC/HE-AAC (320kbps), FLAC (24-bit, 48kHz), WAV (16-bit), OGG Vorbis (320kbps).

Not supported for Sonos casting: ALAC, AIFF/AIF, WavPack (wv), Monkey's Audio (ape).

Format Compatibility and Auto-Skip

Two-Tier Compatibility Check

CastManager.isSonosCompatible(_:allowUnknownSampleRate:) has two modes:

• Strict (default): nil sample rate on a lossless track → incompatible. Used as the _final_ verdict in castCurrentTrack and castNewTrack after the sample rate has been fetched.
• Permissive (allowUnknownSampleRate: true): nil sample rate → pass through. Used in _scan/positioning_ functions that advance the playlist index before casting begins.

Always-incompatible formats (regardless of sample rate): alac, aiff, aif, wv (WavPack), ape (Monkey's Audio). Lossless formats requiring the sample-rate check: flac, wav — rejected above 48 kHz.

Format classification uses the URL extension first, then normalized Track.contentType when the URL is extensionless. MIME types are normalized case-insensitively and parameters are ignored, so Audio/X-FLAC; charset=binary is treated as FLAC. This matters for Plex, Subsonic/Navidrome, Jellyfin, and Emby stream URLs that may not end in .flac or .wav.

Scan Functions Use Permissive Mode

Functions that advance the playlist index use allowUnknownSampleRate: true because they run _before_ the sample rate is known:

Cast Functions Are the Final Authority

castCurrentTrack and castNewTrack in CastManager.swift call resolveSonosSampleRate(for:) for lossless tracks with nil SR. Plex tracks fetch the actual rate from the server; local files are probed directly with AVAudioFile and asynchronously-loaded AVAsset format descriptions. The resolution decision must use the same URL-extension-or-content-type classification as isSonosCompatible; Plex stream URLs are often extensionless, so Track.contentType must identify FLAC/WAV for the fetch to happen. If a track fails there, advanceToFirstSonosCompatibleTrack() is called again to find the next candidate.

The final compatibility call remains strict for server tracks. A local file whose sample rate is still genuinely undetectable is attempted instead of being skipped, because Sonos can make the final decoder decision. Known local rates above 48 kHz remain incompatible even when local-file leniency is enabled.

For non-Plex backends, preserve both Track.contentType and sample rate from server metadata. If an extensionless FLAC/WAV track reaches strict mode without sample rate, it is rejected conservatively rather than sent to Sonos.

Design Principle

Scan functions only reject _definitively_ incompatible formats (ALAC, AIFF, WavPack, Monkey's Audio, known >48 kHz SR). They pass nil-SR lossless tracks through so the cast function can fetch and decide. Never use strict mode in a skip/scan loop — it causes Plex FLAC tracks with nil SR to be skipped silently without a fetch attempt.

Troubleshooting

Devices Not Found

1. Check UPnP is enabled in Sonos app settings
2. Ensure devices are on same network/VLAN
3. Check firewall allows UDP 1900 (SSDP) and mDNS (5353)
4. Click "Refresh" and wait 10 seconds

Devices Found But Won't Play

1. Verify AVTransport URL is accessible: curl http://{ip}:1400/xml/device_description.xml
2. Check Sonos isn't in "TV" mode (some soundbars)
3. Ensure media URL is accessible from Sonos (not localhost)

Authentication Errors (401/403)

If you see "Sonos rejected the command":

1. Open Sonos app → Settings → Account → Privacy & Security → Connection Security
2. Ensure UPnP is ON
3. Ensure Authentication is OFF
4. These settings were added in Sonos firmware 85.0 (July 2025)

Local Files Won't Cast

1. Check your Mac has a local network IP address (not just 127.0.0.1)
2. Ensure firewall allows incoming connections on port 8765
3. Verify Sonos speakers are on same network
4. Check Console.app for "LocalMediaServer" log messages

Seek Bar Stuck at 0 / Position Not Updating

• Root cause: activeSession.position and activeSession.playbackStartDate not set at cast start.
• At Sonos cast start, activeSession.position = startPosition and activeSession.playbackStartDate = Date() must both be set immediately (Sonos has no status updates to set them later).
• Each PLAYING poll must update both fields. Check CastManager: Sonos poll — state=PLAYING logs.
• Intermittent "stuck at zero" at cast start (instrumented via `[CLOCKDBG]` logs): a PLAYING poll can carry position=0 because pollSonosPlaybackState() swallows a failed getPositionInfo() (e.g. SOAP contention while the volume slider is moving at cast start) and fabricates (position: 0, duration: 0). The "PLAYING" poll handler then blindly applies activeSession.position = 0 and re-anchors playbackStartDate = Date(), so AudioEngine.currentTime's interpolation (session.position + (now - playbackStartDate)) reads ~0 and freezes until a later successful poll. To capture it, grep logs for the [CLOCKDBG] tag and look for the sequence: UPnPManager: [CLOCKDBG] getPositionInfo FAILED → CastManager: [CLOCKDBG] PLAYING poll carries position=0 duration=0, correlated with nearby [CLOCKDBG] volume submit/send lines. This is diagnostics only — the poll still overwrites the clock; the fix (skip the position sync when the poll's getPositionInfo failed) is a follow-up.

Near-End Plex Seek Stops Instead of Advancing

• Confirm that the Seek SOAP request was acknowledged and Sonos briefly reported PLAYING at or after the target. A later STOPPED at position 0 can be receiver-generated premature EOF even when Sonos still reports a longer track duration.
• Compare rooms separately. The same Plex FLAC and server can behave correctly on one Sonos renderer and fail deterministically on a soundbar/home-theater coordinator.
• Log the target, track metadata duration, Sonos-reported duration, room UDN/model, time from seek to STOPPED, and the last interpolated session position. Do not diagnose this only from the final Sonos position because Sonos resets it to 0 when stopped.
• Preserve the narrow correlation guards described under Premature STOPPED after a near-end Plex FLAC seek; globally widening the normal EOF tolerance would make genuine external stops near the end advance unexpectedly.

Player Stop Keeps Session Alive

• This is expected for Sonos when using the player Stop button: handleStopForActiveDevice() calls softStopForActiveDevice(), which stops Sonos playback but leaves the session active.
• Use the Sonos menu 🔴 Stop Casting action when a full disconnect is required.
• Chromecast and non-Sonos DLNA should still route through stopCasting() from softStopForActiveDevice().

Casting Stops Unexpectedly

1. Check if Sonos speaker went to sleep (idle timeout)
2. Check if someone paused via Sonos app (NullPlayer detects this)
3. Check if Mac went to sleep (NullPlayer recovers on wake)
4. Check Console.app for "Sonos reported STOPPED" or "consecutive command failures"

Network Requirements

Ports

• UDP 1900: SSDP discovery
• UDP 5353: mDNS discovery
• TCP 1400: Sonos HTTP/SOAP control
• TCP 8765: Local media server (for casting local files)
• Media port: Whatever port your media is served on (Plex default: 32400)

Multicast

SSDP requires multicast. Some routers/switches block this:

• Enable IGMP snooping
• Allow multicast on WLAN
• Don't isolate wireless clients

Key Source Files

References

• Sonos UPnP Services (unofficial)
• SoCo Python Library
• Sonos Developer Docs
• Sonos Connection Security