Quick Start

Your first program

This example discovers your Sonos network, plays music on a speaker, and reads its volume:

use sonos_sdk::prelude::*;

fn main() -> Result<(), SdkError> {
    // Discovers all speakers on your network
    let sonos = SonosSystem::new()?;

    // Get a speaker by name
    let speaker = sonos.speaker("Kitchen").unwrap();

    // Control playback
    speaker.play()?;

    // Read properties directly from the device
    let volume = speaker.volume.fetch()?;
    println!("Kitchen is playing at {}%", volume);

    Ok(())
}

Three ways to read properties

Every property on a speaker supports three access patterns:

// 1. get() — instant, returns cached value (None if never fetched)
let cached = speaker.volume.get();

// 2. fetch() — makes a live SOAP call to the device
let live = speaker.volume.fetch()?;

// 3. watch() — subscribes to real-time events, returns current value
let volume = speaker.volume.watch()?;
println!("Volume right now: {:?}", volume.value());

// Re-watch each iteration to get the updated snapshot
for event in sonos.iter() {
    let volume = speaker.volume.watch()?;
    println!("Volume: {:?}", volume.value());
}

Method	Speed	Freshness	Use when
get()	Instant	May be stale	Displaying cached state in a UI
fetch()	~10ms	Always fresh	Need the current value right now
watch()	Real-time	Live stream	Reacting to changes as they happen

Navigate between speakers and groups

let sonos = SonosSystem::new()?;

// Speakers → Groups
let kitchen = sonos.speaker("Kitchen").unwrap();
let group = kitchen.group().unwrap();
println!("Kitchen is in: {}", group.name);

// Groups → Speakers
for speaker in group.speakers() {
    println!("  - {}", speaker.name());
}

Next steps

• Architecture — understand the layered design
• Properties — deep dive into get/fetch/watch
• Cookbook — common recipes