Struct SonosSystem 

pub struct SonosSystem { /* private fields */ }

Main system entry point - provides DOM-like API

SonosSystem is fully synchronous - no async/await required.

Example

use sonos_sdk::SonosSystem;

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

    // Get speaker by name
    let speaker = system.speaker("Living Room")
        .ok_or_else(|| sonos_sdk::SdkError::SpeakerNotFound("Living Room".to_string()))?;

    // Three methods on each property:
    let volume = speaker.volume.get();              // Get cached value
    let fresh_volume = speaker.volume.fetch()?;     // API call + update cache
    let current = speaker.volume.watch()?;          // Start watching for changes

    // Iterate over changes
    for event in system.iter() {
        println!("Property changed: {:?}", event);
    }

    Ok(())
}

Implementations

impl SonosSystem

pub fn new() -> Result<Self, SdkError>

Create a new SonosSystem with cache-first device discovery (sync)

Discovery strategy:

1. Try loading cached devices from disk (~/.cache/sonos/cache.json)
2. If cache is fresh (< 24h), use cached devices
3. If cache is stale, run SSDP; fall back to stale cache if SSDP finds nothing
4. If no cache exists, run SSDP discovery
5. If no devices found anywhere, return Err(SdkError::DiscoveryFailed)

pub fn speaker(&self, name: &str) -> Option<Speaker>

Get speaker by name (sync)

If the speaker isn’t in the current map, triggers an SSDP rediscovery (rate-limited to once per 30s) before returning None.

Example

let kitchen = sonos.speaker("Kitchen").unwrap();
kitchen.play()?;

pub fn get_speaker_by_name(&self, name: &str) -> Option<Speaker>

👎Deprecated since 0.2.0:

renamed to speaker()

Get speaker by name (sync)

pub fn speakers(&self) -> Vec<Speaker>

Get all speakers (sync)

pub fn speaker_by_id(&self, speaker_id: &SpeakerId) -> Option<Speaker>

Get speaker by ID (sync)

pub fn get_speaker_by_id(&self, speaker_id: &SpeakerId) -> Option<Speaker>

👎Deprecated since 0.2.0:

renamed to speaker_by_id()

Get speaker by ID (sync)

pub fn speaker_names(&self) -> Vec<String>

Get all speaker names (sync)

pub fn state_manager(&self) -> &Arc<StateManager>

Get the state manager for advanced usage

pub fn iter(&self) -> ChangeIterator

Get a blocking iterator over property change events

Only emits events for properties that have been watch()ed.

Example

// First, watch some properties
speaker.volume.watch()?;
speaker.playback_state.watch()?;

// Then iterate over changes (blocking)
for event in system.iter() {
    println!("Changed: {} on {}", event.property_key, event.speaker_id);
}

pub fn groups(&self) -> Vec<Group>

Get all current groups (sync)

Returns all groups in the system. Every speaker is always in a group, so a single speaker forms a group of one.

Example

for group in system.groups() {
    println!("Group: {} ({} members)", group.id, group.member_count());
    if let Some(coordinator) = group.coordinator() {
        println!("  Coordinator: {}", coordinator.name);
    }
}

pub fn group_by_id(&self, group_id: &GroupId) -> Option<Group>

Get a specific group by ID (sync)

Returns None if no group with that ID exists.

Example

if let Some(group) = system.group_by_id(&group_id) {
    println!("Found group with {} members", group.member_count());
}

pub fn get_group_by_id(&self, group_id: &GroupId) -> Option<Group>

👎Deprecated since 0.2.0:

renamed to group_by_id()

Get a specific group by ID (sync)

pub fn group_for_speaker(&self, speaker_id: &SpeakerId) -> Option<Group>

Get the group a speaker belongs to (sync)

Returns None if the speaker is not found or has no group. Since all speakers are always in a group, this typically only returns None if the speaker ID is invalid.

Example

if let Some(speaker) = system.speaker("Living Room") {
    if let Some(group) = system.group_for_speaker(&speaker.id) {
        println!("{} is in a group with {} speakers",
            speaker.name, group.member_count());
    }
}

pub fn get_group_for_speaker(&self, speaker_id: &SpeakerId) -> Option<Group>

👎Deprecated since 0.2.0:

use speaker.group() or group_for_speaker() instead

Get the group a speaker belongs to (sync)

pub fn group(&self, name: &str) -> Option<Group>

Get a group by its coordinator speaker name (sync)

Sonos groups don’t have independent names — they are identified by the coordinator speaker’s friendly name. This method matches groups by looking up the coordinator’s name in the state manager.

Returns None if no group’s coordinator matches the given name.

Example

if let Some(group) = system.group("Living Room") {
    println!("Found group with {} members", group.member_count());
}

pub fn get_group_by_name(&self, name: &str) -> Option<Group>

👎Deprecated since 0.2.0:

renamed to group()

Get a group by its coordinator speaker name (sync)

pub fn create_group( &self, coordinator: &Speaker, members: &[&Speaker], ) -> Result<GroupChangeResult, SdkError>

Create a new group with the specified coordinator and members

Adds each member speaker to the coordinator’s current group. Attempts every speaker even if some fail, returning per-speaker results. After calling this, re-fetch groups via groups() to see the updated topology.

Example

let living_room = system.speaker("Living Room").unwrap();
let kitchen = system.speaker("Kitchen").unwrap();
let bedroom = system.speaker("Bedroom").unwrap();

let result = system.create_group(&living_room, &[&kitchen, &bedroom])?;
if !result.is_success() {
    for (id, err) in &result.failed {
        eprintln!("Failed to add {}: {}", id, err);
    }
}