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//! | `gesture()` | Touch/pen/motion input | Phase only | Fire |
79//!
80//! ## Error Handling
81//!
82//! All async methods return `Result<T, ClientError>`. Common errors:
83//!
84//! - `ClientError::NotConnected` - Operation requires active connection
85//! - `ClientError::SendFailed` - Message could not be sent
86//! - `ClientError::Timeout` - Operation timed out
87//!
88//! ## Crate Features
89//!
90//! - `p2p` - Enable peer-to-peer mesh networking support
91
92pub mod builder;
93pub mod client;
94pub mod error;
95#[cfg(feature = "p2p")]
96pub mod p2p;
97
98pub use builder::ClaspBuilder;
99pub use client::Clasp;
100pub use error::{ClientError, Result};
101#[cfg(feature = "p2p")]
102pub use p2p::{P2PEvent, P2PManager, SendResult};
103
104// Re-export P2P routing mode for convenience
105#[cfg(feature = "p2p")]
106pub use clasp_core::RoutingMode;
107
108/// Prelude for convenient imports
109pub mod prelude {
110    pub use crate::builder::ClaspBuilder;
111    pub use crate::client::Clasp;
112    pub use crate::error::{ClientError, Result};
113    #[cfg(feature = "p2p")]
114    pub use crate::p2p::{P2PEvent, P2PManager, SendResult};
115    #[cfg(feature = "p2p")]
116    pub use clasp_core::RoutingMode;
117    pub use clasp_core::{
118        EasingType, GesturePhase, Message, SignalType, TimelineData, TimelineKeyframe, Value,
119    };
120}
121
122// Re-export types for convenience
123pub use clasp_core::{EasingType, GesturePhase, TimelineData, TimelineKeyframe};
clasp_client/lib.rs

clasp_client/
lib.rs
