rill-patchbay 0.5.0-beta.5

The world where Automata live - control system for Rill
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# rill-patchbay

Automation and control system — LFOs, envelopes, sequencers, sensors, servos, and event mapping for the Rill audio graph.

## Architecture

Two-thread design. Automata run on the **control thread** (green threads
via tokio) and communicate with the audio thread through lock-free
`MpscQueue<ParameterCommand>`.

```
Control thread (tokio):
  Automaton ── mpsc<f64> ──→ PortCombiner ── MpscQueue ──→ Audio thread
  UI/MIDI    ── mpsc<UiCmd> → PortCombiner ── MpscQueue ──→ Audio thread
  Sequencer  ◀── crossbeam<Telemetry> ◀──────────────────── Audio thread
```

## Key components

- **Automata** — `LfoAutomaton`, `EnvelopeAutomaton`, `RandomWalkAutomaton`,
  `SequencerAutomaton`, `FunctionAutomaton`, `CellularAutomaton`
- **PortCombiner** — sits between automaton and audio thread. Resolves
  conflicts between automaton output and UI/MIDI/OSC input using
  `ControlStrategy` (Absolute / Modulation) and `ConflictStrategy`.
- **Sequencer** — `SnapshotSequencer` driven by clock ticks from the audio
  thread via crossbeam channel. `SequencerHandle` for start/stop/reset.
- **Servos** — apply automaton signals to graph node parameters via
  `ParameterMapping` (Linear, Exponential, Logarithmic, Inverted, Custom).
- **Sensors** — acoustic (pitch, envelope follower), physical (knobs,
  buttons), MIDI, CV.
- **Event mapping** — MIDI CC → parameter, OSC address → parameter,
  with transforms.
- **`Engine`** — centralised API for adding automata, servos, mappings,
  green threads, and port combiners (fka `PatchbayControl`).
- **`Manager`** — high-level coordinator with per-port cancellation
  domains.

## Usage

```rust
use rill_core_actor::ActorRef;
use rill_patchbay::prelude::*;

let (actor_ref, _mailbox) = ActorRef::new_pair();
let mut engine = Engine::new(actor_ref);

engine.add_lfo(
    "vibrato", 5.0, 0.5, 0.0, LfoWaveform::Sine,
    osc_node_id, "frequency", 400.0, 480.0,
);

engine.add_envelope(
    "amp", 0.01, 0.1, 0.7, 0.2,
    vca_node_id, "gain", 0.0, 1.0,
);

engine.update(1.0 / 60.0);
```

## Feature flags

| Feature | Description |
|---------|-------------|
| `serde` | Serialization support (JSON/CBOR) |
| `json` | `serde` + JSON serialization |
| `cbor` | `serde` + CBOR serialization |
| `serialization` | `json` + `cbor` |

## Dependencies

- `rill-core` — node traits, queues, types
- `crossbeam-channel`, `parking_lot`, `tokio` — green thread infrastructure

## Links

- Repository: <https://github.com/DigitalRats/rill>
- Documentation: <https://docs.rs/rill-patchbay>