sonos_sdk/lib.rs
1//! # Sonos SDK - Sync-First API for Sonos Control
2//!
3//! Provides a clean, property-centric API for controlling Sonos devices.
4//! All operations are **synchronous** - no async/await required.
5//!
6//! ## Quick Start
7//!
8//! ```rust,ignore
9//! use sonos_sdk::prelude::*;
10//!
11//! fn main() -> Result<(), SdkError> {
12//! let sonos = SonosSystem::new()?;
13//!
14//! // Direct SOAP calls — no event infrastructure created
15//! let kitchen = sonos.speaker("Kitchen").unwrap();
16//! kitchen.play()?;
17//! let vol = kitchen.volume.fetch()?;
18//!
19//! // Fluent navigation
20//! let group = kitchen.group().unwrap();
21//! println!("Kitchen is in group {}", group.id);
22//!
23//! // ONLY NOW does the event manager lazily initialize
24//! let _vol = kitchen.volume.watch()?;
25//! for event in sonos.iter() {
26//! println!("Changed: {} on {}", event.property_key, event.speaker_id);
27//! }
28//!
29//! Ok(())
30//! }
31//! ```
32//!
33//! ## Key Features
34//!
35//! - **Sync-First API**: All methods are synchronous - no async/await required
36//! - **Cheap constructor**: `SonosSystem::new()` does discovery only — event infrastructure is lazy
37//! - **DOM-like API**: Access properties directly on speaker objects
38//! - **Three access patterns**: `get()` for cached, `fetch()` for fresh, `watch()` for reactive
39//! - **Fluent navigation**: `speaker.group()`, `group.speaker("name")`
40//! - **Type safety**: All properties are strongly typed
41//! - **Resource efficiency**: Shared state management and HTTP connections
42//!
43//! ## Available Properties
44//!
45//! Currently implemented:
46//! - `volume` - Speaker volume (0-100)
47//! - `playback_state` - Current playback state (Playing/Paused/Stopped/Transitioning)
48//! - `mute` - Mute state
49//! - `bass`, `treble`, `loudness` - EQ settings
50//! - `position` - Current track position
51//! - `current_track` - Track metadata
52//!
53//! ## Architecture
54//!
55//! ```text
56//! sonos-sdk (Sync-First DOM-like API)
57//! ↓
58//! sonos-state (State Management) ←→ sonos-event-manager (Event Subscriptions)
59//! ↓ ↓
60//! sonos-api (UPnP Operations) sonos-stream (Event Processing)
61//! ```
62
63// Main exports
64pub use error::SdkError;
65pub use group::{Group, GroupChangeResult};
66pub use speaker::{PlayMode, SeekTarget, Speaker};
67pub use system::SonosSystem;
68
69// Re-export the generic PropertyHandle, SpeakerContext, and watch types
70pub use property::{PropertyHandle, SpeakerContext, WatchHandle, WatchMode};
71
72// Re-export group property handle types
73pub use property::{
74 GroupContext, GroupFetchable, GroupMuteHandle, GroupPropertyHandle,
75 GroupVolumeChangeableHandle, GroupVolumeHandle,
76};
77
78// Re-export response types for action methods
79pub use sonos_api::services::av_transport::{
80 AddURIToQueueResponse, BecomeCoordinatorOfStandaloneGroupResponse, CreateSavedQueueResponse,
81 GetCrossfadeModeResponse, GetCurrentTransportActionsResponse, GetDeviceCapabilitiesResponse,
82 GetMediaInfoResponse, GetRemainingSleepTimerDurationResponse,
83 GetRunningAlarmPropertiesResponse, GetTransportSettingsResponse,
84 RemoveTrackRangeFromQueueResponse, SaveQueueResponse,
85};
86pub use sonos_api::services::group_rendering_control::SetRelativeGroupVolumeResponse;
87pub use sonos_api::services::rendering_control::SetRelativeVolumeResponse;
88
89// sonos_discovery is internal — consumers use SonosSystem::new()
90// Re-exported under test-support for integration tests that need Device
91#[cfg(feature = "test-support")]
92pub use sonos_discovery;
93
94// Re-export commonly used types from sonos-state
95pub use sonos_state::{
96 ChangeEvent, ChangeIterator, GroupId, GroupMute, GroupVolume, GroupVolumeChangeable,
97 PlaybackState, SpeakerId, Volume,
98};
99
100// Public modules
101pub mod prelude;
102
103// Internal modules
104mod cache;
105mod error;
106mod group;
107pub mod property;
108mod speaker;
109mod system;