clasp_client/
lib.rs

1//! # CLASP Client Library
2//!
3//! High-level async client for the CLASP (Creative Low-Latency Application Streaming Protocol).
4//!
5//! This crate provides a Rust client for connecting to CLASP routers, enabling real-time
6//! communication between creative applications such as lighting controllers, audio mixers,
7//! VJ software, and more.
8//!
9//! ## Features
10//!
11//! - **Async/await**: Built on Tokio for efficient async I/O
12//! - **Builder pattern**: Flexible client configuration
13//! - **Subscriptions**: Pattern-based subscriptions with callbacks
14//! - **Parameters**: Get/set persistent values with caching
15//! - **Events**: Fire-and-forget event emission
16//! - **Streams**: High-rate data streaming (QoS fire)
17//! - **Bundles**: Atomic multi-message operations
18//! - **Time sync**: Automatic clock synchronization with server
19//!
20//! ## Quick Start
21//!
22//! ```ignore
23//! use clasp_client::Clasp;
24//!
25//! #[tokio::main]
26//! async fn main() -> anyhow::Result<()> {
27//!     // Connect using builder pattern
28//!     let client = Clasp::builder("ws://localhost:7330")
29//!         .name("my-app")
30//!         .features(vec!["param", "event", "stream"])
31//!         .connect()
32//!         .await?;
33//!
34//!     println!("Connected! Session: {:?}", client.session_id());
35//!
36//!     // Subscribe to changes with wildcard patterns
37//!     client.subscribe("/lumen/scene/*/layer/*/opacity", |value, address| {
38//!         println!("{} = {:?}", address, value);
39//!     }).await?;
40//!
41//!     // Set a parameter value
42//!     client.set("/lumen/scene/0/layer/0/opacity", 0.75).await?;
43//!
44//!     // Emit an event (with map value)
45//!     client.emit("/cue/trigger", clasp_core::Value::Map(Default::default())).await?;
46//!
47//!     // Stream high-rate data
48//!     for i in 0..100 {
49//!         let value = (i as f64 / 100.0).sin();
50//!         client.stream("/sensor/value", value).await?;
51//!         tokio::time::sleep(std::time::Duration::from_millis(10)).await;
52//!     }
53//!
54//!     Ok(())
55//! }
56//! ```
57//!
58//! ## Address Patterns
59//!
60//! CLASP uses hierarchical addresses similar to OSC:
61//!
62//! - `/namespace/category/instance/property`
63//! - `/lumen/scene/0/layer/3/opacity`
64//! - `/midi/launchpad/cc/74`
65//!
66//! Wildcard patterns for subscriptions:
67//!
68//! - `*` - matches exactly one segment: `/path/*/value` matches `/path/foo/value`
69//! - `**` - matches any number of segments: `/path/**` matches `/path/a/b/c`
70//!
71//! ## Signal Types
72//!
73//! | Type | Use Case | Persistence | QoS |
74//! |------|----------|-------------|-----|
75//! | `set()` | Parameters with state | Persisted | Confirm |
76//! | `emit()` | One-shot events | Not persisted | Confirm |
77//! | `stream()` | High-rate sensor data | Not persisted | Fire |
78//!
79//! ## Error Handling
80//!
81//! All async methods return `Result<T, ClientError>`. Common errors:
82//!
83//! - `ClientError::NotConnected` - Operation requires active connection
84//! - `ClientError::SendFailed` - Message could not be sent
85//! - `ClientError::Timeout` - Operation timed out
86//!
87//! ## Crate Features
88//!
89//! - `p2p` - Enable peer-to-peer mesh networking support
90
91pub mod builder;
92pub mod client;
93pub mod error;
94#[cfg(feature = "p2p")]
95pub mod p2p;
96
97pub use builder::ClaspBuilder;
98pub use client::Clasp;
99pub use error::{ClientError, Result};
100#[cfg(feature = "p2p")]
101pub use p2p::{P2PEvent, P2PManager};
102
103/// Prelude for convenient imports
104pub mod prelude {
105    pub use crate::builder::ClaspBuilder;
106    pub use crate::client::Clasp;
107    pub use crate::error::{ClientError, Result};
108    #[cfg(feature = "p2p")]
109    pub use crate::p2p::{P2PEvent, P2PManager};
110    pub use clasp_core::{Message, SignalType, Value};
111}
clasp_client/lib.rs

clasp_client/
lib.rs
