deepmind_midi/lib.rs
1//! Sans-IO protocol library for Behringer `DeepMind` synthesizers.
2//!
3//! This crate models the `DeepMind` MIDI protocol and nothing else. It never opens a
4//! port, never spawns a thread and never blocks. The host application owns the
5//! transport, feeds inbound bytes in and sends outbound bytes out.
6//!
7//! ```text
8//! DeepMind <--MIDI--> host application <--bytes--> deepmind-midi
9//! ```
10//!
11//! # Layout
12//!
13//! | Module | Responsibility |
14//! |---------------|--------------------------------------------------------------------|
15//! | [`ids`] | Addressing primitives: device ID, model, bank, program number |
16//! | [`error`] | Crate-wide error type |
17//! | [`wire`] | MIDI bytes: running status, channel messages, `SysEx` reassembly |
18//! | [`sysex`] | `DeepMind` framing, the packed MS-bit codec, typed messages |
19//! | [`param`] | The 242 program parameters: names, ranges, value tables, NRPN |
20//! | [`effect`] | What an effect engine's twelve bytes are, per algorithm |
21//! | [`front`] | What the instrument's own front panel puts a control under |
22//! | [`generator`] | The shapes a set of parameters makes, for a host that draws them |
23//! | [`pixels`] | The one-bit grid of the marks, the source cells and the glyphs |
24//! | [`program`] | A program: the 242 bytes, typed accessors, names, value types |
25//! | [`syx`] | `.syx` files: the programs a preset pack carries, and building one |
26//! | [`device`] | The state machine: what the synthesizer holds, and what to send |
27//! | `transport` | The blocking adapter over a port and a clock (feature `transport`) |
28//! | `sim` | The other end of the conversation, for tests (feature `sim`) |
29//!
30//! Each layer depends only on those above it: [`wire`] does not know what a
31//! `DeepMind` is, and [`sysex`] does not know where its bytes came from.
32//!
33//! ```
34//! use deepmind_midi::ids::DeviceId;
35//! use deepmind_midi::sysex::{Frame, Message};
36//! use deepmind_midi::wire::{Decoder, Event};
37//!
38//! // Bytes off a port, in whatever chunks they arrived in.
39//! let mut decoder: Decoder = Decoder::new();
40//! decoder.feed(&[0xF0, 0x00, 0x20, 0x32, 0x20, 0x00, 0x03, 0xF7], |event| {
41//! if let Ok(Event::SysEx(bytes)) = event {
42//! let frame = Frame::parse(bytes).expect("a DeepMind frame");
43//! assert_eq!(frame.device, DeviceId::Unit(0));
44//! assert_eq!(frame.message, Message::EditBufferDumpRequest);
45//! }
46//! });
47//! ```
48//!
49//! See [`docs/architecture.md`] for the design and [`docs/midi-spec.md`] for the
50//! protocol itself.
51//!
52//! [`docs/architecture.md`]: https://github.com/MysteriousWolf/deepmind-midi/blob/main/docs/architecture.md
53//! [`docs/midi-spec.md`]: https://github.com/MysteriousWolf/deepmind-midi/blob/main/docs/midi-spec.md
54//!
55//! # Feature flags
56//!
57//! - `std` (default): implies `alloc`, and adds [`transport::StdClock`] when
58//! `transport` is on. The error types implement [`core::error::Error`] with
59//! or without it.
60//! - `alloc`: APIs that allocate, such as bank decoding and `.syx` handling.
61//! - `serde`: `Serialize`/`Deserialize` derives on the public data types.
62//! - `transport`: the blocking adapter, which is the one part of this crate that
63//! knows what IO is. Needs neither `std` nor an allocator.
64//! - `sim`: a synthesizer to talk to, for testing a host without one plugged in.
65//! - `descriptions`: what a parameter or an effect slot *does*, in a sentence.
66//! [`param::ParamId::description`] and [`effect::FxSlot::description`] answer
67//! `None` without it and a sentence with it, so a host writes one code path
68//! and an embedded build carries no prose.
69
70#![cfg_attr(not(feature = "std"), no_std)]
71#![cfg_attr(docsrs, feature(doc_cfg))]
72#![doc(
73 html_logo_url = "https://raw.githubusercontent.com/MysteriousWolf/deepmind-midi/main/docs/logo.svg"
74)]
75#![doc(
76 html_favicon_url = "https://raw.githubusercontent.com/MysteriousWolf/deepmind-midi/main/docs/logo.svg"
77)]
78
79#[cfg(feature = "alloc")]
80extern crate alloc;
81
82pub mod device;
83pub mod effect;
84pub mod error;
85pub mod front;
86pub mod generator;
87pub mod ids;
88mod math;
89mod nrpn;
90pub mod param;
91pub mod pixels;
92pub mod program;
93mod queue;
94#[cfg(feature = "sim")]
95#[cfg_attr(docsrs, doc(cfg(feature = "sim")))]
96pub mod sim;
97pub mod sysex;
98pub mod syx;
99#[cfg(test)]
100mod testing;
101#[cfg(feature = "transport")]
102#[cfg_attr(docsrs, doc(cfg(feature = "transport")))]
103pub mod transport;
104pub mod wire;
105
106pub use device::{Device, Known};
107pub use effect::{Algorithm, Engine};
108pub use error::{Error, Result};
109pub use ids::{Bank, DeviceId, Model, PatternNumber, ProgramNumber, ProtocolVersion, Slot};
110pub use param::{Group, NrpnEdit, ParamId};
111pub use program::{Program, ProgramName};
112pub use sysex::{Command, Frame, Message};
113#[cfg(feature = "transport")]
114pub use transport::Transport;
115pub use wire::{Channel, ChannelMessage, Decoder};