Crate sonos_sdk 

Sonos SDK - Sync-First API for Sonos Control

Provides a clean, property-centric API for controlling Sonos devices. All operations are synchronous - no async/await required.

Quick Start

use sonos_sdk::prelude::*;

fn main() -> Result<(), SdkError> {
    let sonos = SonosSystem::new()?;

    // Direct SOAP calls — no event infrastructure created
    let kitchen = sonos.speaker("Kitchen").unwrap();
    kitchen.play()?;
    let vol = kitchen.volume.fetch()?;

    // Fluent navigation
    let group = kitchen.group().unwrap();
    println!("Kitchen is in group {}", group.id);

    // ONLY NOW does the event manager lazily initialize
    let _vol = kitchen.volume.watch()?;
    for event in sonos.iter() {
        // The new value arrives with the event — no cache re-read needed
        match &event.change {
            PropertyChange::Volume(v) => println!("volume -> {}%", v.value()),
            other => println!("{} changed on {}", other.key(), event.speaker_id),
        }
    }

    Ok(())
}

Key Features

• Sync-First API: All methods are synchronous - no async/await required
• Cheap constructor: SonosSystem::new() does discovery only — event infrastructure is lazy
• DOM-like API: Access properties directly on speaker objects
• Three access patterns: get() for cached, fetch() for fresh, watch() for reactive
• Fluent navigation: speaker.group(), group.speaker("name")
• Type safety: All properties are strongly typed
• Resource efficiency: Shared state management and HTTP connections

Available Properties

Currently implemented:

• volume - Speaker volume (0-100)
• playback_state - Current playback state (Playing/Paused/Stopped/Transitioning)
• mute - Mute state
• bass, treble, loudness - EQ settings
• position - Current track position
• current_track - Track metadata

Architecture

sonos-sdk (Sync-First DOM-like API)
    ↓
sonos-state (State Management) ←→ sonos-event-manager (Event Subscriptions)
    ↓                                    ↓
sonos-api (UPnP Operations)         sonos-stream (Event Processing)

Re-exports

pub use property::PropertyHandle;

pub use property::SpeakerContext;

pub use property::WatchHandle;

pub use property::WatchMode;

pub use property::GroupContext;

pub use property::GroupFetchable;

pub use property::GroupMuteHandle;

pub use property::GroupPropertyHandle;

pub use property::GroupVolumeChangeableHandle;

pub use property::GroupVolumeHandle;

Modules

prelude

Convenience re-exports for common types.

property

Property handles for DOM-like property access

Structs

AddURIToQueueResponse

BecomeCoordinatorOfStandaloneGroupResponse

ChangeEvent

A change event emitted when a watched property changes.

ChangeIterator

Blocking iterator over property change events

CreateSavedQueueResponse

CurrentTrack

Information about the currently playing track

GetCrossfadeModeResponse

GetCurrentTransportActionsResponse

GetDeviceCapabilitiesResponse

GetMediaInfoResponse

GetRemainingSleepTimerDurationResponse

GetRunningAlarmPropertiesResponse

GetTransportSettingsResponse

Group

Group handle with access to coordinator and members

GroupChangeResult

Result of a multi-speaker group operation (e.g., dissolve(), create_group())

GroupId

Unique identifier for a zone group

GroupMute

Group master mute state

GroupVolume

Group master volume level (0-100)

GroupVolumeChangeable

Whether the group volume can be changed

RemoveTrackRangeFromQueueResponse

SaveQueueResponse

SetRelativeGroupVolumeResponse

SetRelativeVolumeResponse

SonosSystem

Main system entry point - provides DOM-like API

Speaker

Speaker handle with property access

SpeakerId

Unique identifier for a Sonos speaker

Volume

Master volume level (0-100)

WriteStamp

When a value was observed, and by what.

Enums

ChangeSource

Where a property value came from.

PlayMode

Play mode for the set_play_mode() method

PlaybackState

Current playback state

PropertyChange

A single property change

SdkError

SeekTarget

Seek target for the seek() method

WriteOutcome

Result of attempting to write a property.

Traits

Property

The property trait, re-exported so downstream crates can write code that is generic over properties.

SonosProperty

The property trait, re-exported so downstream crates can write code that is generic over properties.