rill_patchbay/lib.rs
1//! # Rill Patchbay — Event routing and automation
2//!
3//! `rill-patchbay` is the evolution of `rill-automation` from version 0.2.0,
4//! merged with the mapping functionality from `rill-control`.
5//!
6//! ## Core components
7//!
8//! - **Automatons** — generative signal sources (LFO, envelopes, sequencers)
9//! - **Servos** (in the `control` module) — connect automatons to node parameters
10//! - **Mappings** — connect external events (MIDI/OSC) to parameters
11//! - **Sensors** — event sources from the external world
12//! - **Manager** — central coordinator for dual-thread architecture
13//!
14//! ## Architecture
15//!
16//! ```text
17//! ┌─────────────────────────────────────────────────────────────┐
18//! │ CONTROL THREAD │
19//! │ │
20//! │ ┌─────────────────────────────────────────────────────┐ │
21//! │ │ Manager │ │
22//! │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │
23//! │ │ │ Automatons │ │ Servos │ │ Mappings │ │ │
24//! │ │ └────────────┘ └────────────┘ └────────────┘ │ │
25//! │ │ │ │ │ │
26//! │ │ ▼ ▼ │ │
27//! │ │ ┌──────────────────────────┐ │ │
28//! │ │ │ RtQueue<ParameterCommand>│ │ │
29//! │ │ └──────────────────────────┘ │ │
30//! │ └─────────────────────────────────────────────────────┘ │
31//! │ │ │
32//! │ │ non-blocking queue │
33//! │ ▼ │
34//! │ ┌─────────────────────────────────────────────────────┐ │
35//! │ │ SIGNAL THREAD │ │
36//! │ │ (rill-graph / rill-io) │ │
37//! │ └─────────────────────────────────────────────────────┘ │
38//! └─────────────────────────────────────────────────────────────┘
39//! ```
40
41#![warn(missing_docs)]
42#![deny(unsafe_code)]
43#![allow(clippy::too_many_arguments)]
44
45// =============================================================================
46// External dependencies
47// =============================================================================
48
49// Re-exports from rill-core
50pub use rill_core::prelude::*;
51pub use rill_core::queues::RtQueue;
52
53// =============================================================================
54// Public modules
55// =============================================================================
56
57/// Automatons — generative control sources
58pub mod automaton;
59
60/// Control and event mapping
61pub mod engine;
62
63/// Sensors — event sources from the external world
64pub mod sensor;
65
66/// Utilities and helper functions
67pub mod utils;
68
69/// Named function registry for serialization
70pub mod function_registry;
71
72/// Automaton control strategies
73pub mod strategy;
74
75/// Rack module type definitions (always compiled)
76pub mod module_def;
77
78pub use module_def::ClockDef;
79
80/// Custom module factory — type registry for rack module construction
81pub mod module_factory;
82
83/// Servo constructor — creates servo actors from ModuleDef descriptors
84pub mod servo_constructor;
85
86/// Automaton wrapper in a green thread (tokio task)
87pub mod automaton_task;
88
89/// Serialization — documents, JSON, CBOR
90#[cfg(feature = "serde")]
91pub mod serialization;
92
93#[cfg(feature = "serde")]
94pub use serialization::PatchbayDef;
95
96/// MIDI hub — raw MIDI → ControlEvent bridge
97#[cfg(feature = "midi")]
98pub mod midi;
99/// MIDI clock tracker — 24ppqn → BPM derivation
100#[cfg(feature = "midi")]
101pub mod midi_clock;
102
103/// OSC sensor — OSC → ControlEvent bridge
104#[cfg(feature = "osc")]
105pub mod osc;
106
107/// Micro-control observer for RT safety monitoring
108pub mod observer;
109
110/// Runtime introspection for control-path components
111#[cfg(feature = "debug")]
112pub mod debug;
113
114#[cfg(feature = "midi")]
115pub use midi::serialize_to_midi;
116#[cfg(feature = "midi")]
117pub use midi::spawn_midi_sensor;
118#[cfg(feature = "midi")]
119pub use midi::MidiHub;
120#[cfg(feature = "midi")]
121pub use midi_clock::MidiClockGenerator;
122#[cfg(feature = "midi")]
123pub use midi_clock::{
124 spawn_midi_clock_output, FreeRunning, MidiClockStrategy, MidiClockTracker, ResetOnStart,
125 SongPosition,
126};
127#[cfg(feature = "osc")]
128pub use osc::spawn_osc_sensor;
129#[cfg(feature = "osc")]
130pub use osc::OscSensor;
131pub use sensor::Sensor;
132
133// =============================================================================
134// Re-exports for convenience
135// =============================================================================
136
137// Selective re-exports
138pub use automaton::sequencer::{PlayMode, SequencerAutomaton, Step};
139pub use automaton::{
140 EnvelopeAutomaton, EnvelopeStage, EnvelopeType, FunctionAutomaton, LfoAutomaton, LfoWaveform,
141 Range, StatefulFunctionAutomaton, SyncMode,
142};
143pub use automaton_task::spawn_automaton_task;
144pub use engine::{
145 midi_cc, midi_note, osc_address, Automaton, BoxedModule, ControlEvent, EventPattern, Mapping,
146 MidiNoteKind, Module, NoAction, OscSurface, OscSurfaceEntry, ParameterMapping, Servo, Target,
147 Transform,
148};
149
150pub use strategy::{ConflictStrategy, ControlStrategy};
151
152// =============================================================================
153// Prelude for convenient imports
154// =============================================================================
155
156/// Prelude for convenient import of core types
157pub mod prelude {
158 // Core types
159 pub use crate::automaton::*;
160 pub use crate::automaton_task::*;
161 pub use crate::engine::*;
162 pub use crate::strategy::*;
163 pub use crate::utils::*;
164
165 // Re-exports from rill-core
166 pub use rill_core::prelude::*;
167 pub use rill_core::queues::RtQueue;
168}
169
170// =============================================================================
171// Tests
172// =============================================================================
173
174#[cfg(test)]
175mod tests {
176 use super::*;
177
178 #[test]
179 fn test_basic_imports() {
180 // Just check that everything imports
181 let _ = automaton::LfoWaveform::Sine;
182 let _ = engine::Transform::Linear;
183 }
184}