use std::ops::RangeInclusive;
mod events;
pub use events::{Events, Iter};
pub const MAX_BLOCK_EVENTS: usize = 4096;
pub const MAX_BLOCK_SYSEX_BYTES: usize = 64 << 10;
pub const MAX_NOTE_ID: u32 = i32::MAX as u32;
pub(crate) fn validate_event_count(
automation: usize,
events: usize,
) -> Result<(), crate::InputError> {
if automation > MAX_BLOCK_EVENTS || events > MAX_BLOCK_EVENTS - automation {
return Err(crate::InputError::EventCapacity);
}
Ok(())
}
pub fn validate_event_budget(automation: usize, events: &Events) -> Result<(), crate::InputError> {
validate_event_count(automation, events.len())?;
if events.sysex_bytes() > MAX_BLOCK_SYSEX_BYTES {
return Err(crate::InputError::EventCapacity);
}
Ok(())
}
#[derive(Clone, Copy, Debug, PartialEq)]
#[non_exhaustive]
pub struct Event<'a> {
pub offset: usize,
pub port: usize,
pub data: EventData<'a>,
}
#[derive(Clone, Copy, Debug, PartialEq)]
#[non_exhaustive]
pub enum EventData<'a> {
Midi([u8; 3]),
SysEx(&'a [u8]),
NoteOn(Note),
NoteOff(Note),
Expression(NoteExpression),
}
#[derive(Clone, Copy, Debug, PartialEq)]
#[non_exhaustive]
pub struct Note {
pub id: Option<u32>,
pub channel: u8,
pub key: u8,
pub velocity: f64,
}
#[derive(Clone, Copy, Debug, PartialEq)]
#[non_exhaustive]
pub struct NoteExpression {
pub id: Option<u32>,
pub channel: u8,
pub key: u8,
pub kind: ExpressionKind,
pub value: f64,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum ExpressionKind {
Volume,
Pan,
Tuning,
Vibrato,
Expression,
Brightness,
Pressure,
}
impl ExpressionKind {
pub const ALL: [ExpressionKind; 7] = [
ExpressionKind::Volume,
ExpressionKind::Pan,
ExpressionKind::Tuning,
ExpressionKind::Vibrato,
ExpressionKind::Expression,
ExpressionKind::Brightness,
ExpressionKind::Pressure,
];
pub fn range(self) -> RangeInclusive<f64> {
match self {
ExpressionKind::Volume => 0.0..=4.0,
ExpressionKind::Tuning => -120.0..=120.0,
ExpressionKind::Pan
| ExpressionKind::Vibrato
| ExpressionKind::Expression
| ExpressionKind::Brightness
| ExpressionKind::Pressure => 0.0..=1.0,
}
}
}
impl Note {
#[must_use]
pub fn new(channel: u8, key: u8, velocity: f64) -> Note {
Note {
id: None,
channel,
key,
velocity,
}
}
#[must_use]
pub fn with_id(self, id: u32) -> Note {
Note {
id: Some(id),
..self
}
}
fn is_valid(&self) -> bool {
valid_address(self.id, self.channel, self.key)
&& self.velocity.is_finite()
&& (0.0..=1.0).contains(&self.velocity)
}
}
impl NoteExpression {
#[must_use]
pub fn new(channel: u8, key: u8, kind: ExpressionKind, value: f64) -> NoteExpression {
NoteExpression {
id: None,
channel,
key,
kind,
value,
}
}
#[must_use]
pub fn with_id(self, id: u32) -> NoteExpression {
NoteExpression {
id: Some(id),
..self
}
}
fn is_valid(&self) -> bool {
valid_address(self.id, self.channel, self.key)
&& self.value.is_finite()
&& self.kind.range().contains(&self.value)
}
}
fn valid_address(id: Option<u32>, channel: u8, key: u8) -> bool {
id.is_none_or(|id| id <= MAX_NOTE_ID) && channel < 16 && key < 0x80
}
fn two_bytes(status: u8) -> bool {
matches!(status & 0xF0, 0xC0 | 0xD0)
}
fn seven_bits(value: f64) -> u8 {
(value * 127.0).round().clamp(0.0, 127.0) as u8
}
impl EventData<'_> {
pub fn to_midi(&self) -> Option<[u8; 3]> {
Some(match self {
EventData::Midi([status, first, _]) if two_bytes(*status) => [*status, *first, 0],
EventData::Midi(bytes) => *bytes,
EventData::NoteOn(note) => [
0x90 | (note.channel & 0x0F),
note.key & 0x7F,
seven_bits(note.velocity).max(1),
],
EventData::NoteOff(note) => [
0x80 | (note.channel & 0x0F),
note.key & 0x7F,
seven_bits(note.velocity),
],
EventData::Expression(expression) if expression.kind == ExpressionKind::Pressure => [
0xA0 | (expression.channel & 0x0F),
expression.key & 0x7F,
seven_bits(expression.value),
],
EventData::Expression(_) | EventData::SysEx(_) => return None,
})
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum Message {
NoteOff {
channel: u8,
key: u8,
velocity: u8,
},
NoteOn {
channel: u8,
key: u8,
velocity: u8,
},
PolyPressure {
channel: u8,
key: u8,
pressure: u8,
},
ControlChange {
channel: u8,
controller: u8,
value: u8,
},
ProgramChange {
channel: u8,
program: u8,
},
ChannelPressure {
channel: u8,
pressure: u8,
},
PitchBend {
channel: u8,
value: u16,
},
}
impl<'a> Event<'a> {
#[must_use]
pub fn new(offset: usize, data: EventData<'a>) -> Event<'a> {
Event {
offset,
port: 0,
data,
}
}
#[must_use]
pub fn midi(offset: usize, data: [u8; 3]) -> Event<'a> {
Self::new(offset, EventData::Midi(data))
}
#[must_use]
pub fn note_on(offset: usize, channel: u8, key: u8, velocity: u8) -> Event<'a> {
Self::midi(
offset,
[0x90 | (channel & 0x0F), key & 0x7F, velocity & 0x7F],
)
}
#[must_use]
pub fn note_off(offset: usize, channel: u8, key: u8, velocity: u8) -> Event<'a> {
Self::midi(
offset,
[0x80 | (channel & 0x0F), key & 0x7F, velocity & 0x7F],
)
}
#[must_use]
pub fn control_change(offset: usize, channel: u8, controller: u8, value: u8) -> Event<'a> {
Self::midi(
offset,
[0xB0 | (channel & 0x0F), controller & 0x7F, value & 0x7F],
)
}
#[must_use]
pub fn sysex(offset: usize, bytes: &'a [u8]) -> Event<'a> {
Self::new(offset, EventData::SysEx(bytes))
}
#[must_use]
pub fn on_port(self, port: usize) -> Event<'a> {
Event { port, ..self }
}
#[must_use]
pub fn at(self, offset: usize) -> Event<'a> {
Event { offset, ..self }
}
pub fn message(&self) -> Option<Message> {
let EventData::Midi([status, first, second]) = self.data else {
return None;
};
if !(0x80..0xF0).contains(&status) || first > 0x7F || (second > 0x7F && !two_bytes(status))
{
return None;
}
let channel = status & 0x0F;
Some(match status & 0xF0 {
0x80 => Message::NoteOff {
channel,
key: first,
velocity: second,
},
0x90 if second == 0 => Message::NoteOff {
channel,
key: first,
velocity: 64,
},
0x90 => Message::NoteOn {
channel,
key: first,
velocity: second,
},
0xA0 => Message::PolyPressure {
channel,
key: first,
pressure: second,
},
0xB0 => Message::ControlChange {
channel,
controller: first,
value: second,
},
0xC0 => Message::ProgramChange {
channel,
program: first,
},
0xD0 => Message::ChannelPressure {
channel,
pressure: first,
},
_ => Message::PitchBend {
channel,
value: u16::from(first) | (u16::from(second) << 7),
},
})
}
pub fn is_valid(&self) -> bool {
match self.data {
EventData::Midi(_) => self.message().is_some(),
EventData::SysEx(bytes) => {
bytes.len() >= 2
&& bytes[0] == 0xF0
&& bytes[bytes.len() - 1] == 0xF7
&& bytes[1..bytes.len() - 1].iter().all(|&byte| byte < 0x80)
}
EventData::NoteOn(note) | EventData::NoteOff(note) => note.is_valid(),
EventData::Expression(expression) => expression.is_valid(),
}
}
}
pub fn events_fit(events: &Events, frames: usize) -> bool {
let mut previous = 0;
events.iter().all(|event| {
let ordered = event.offset >= previous;
previous = event.offset;
ordered && event.offset < frames && event.is_valid()
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn block_event_budget_counts_both_inputs_without_integer_overflow() {
assert_eq!(validate_event_count(0, 0), Ok(()));
assert_eq!(validate_event_count(MAX_BLOCK_EVENTS, 0), Ok(()));
assert_eq!(validate_event_count(1, MAX_BLOCK_EVENTS - 1), Ok(()));
for (automation, events) in [
(MAX_BLOCK_EVENTS, 1),
(0, MAX_BLOCK_EVENTS + 1),
(usize::MAX, usize::MAX),
(1, usize::MAX),
] {
assert_eq!(
validate_event_count(automation, events),
Err(crate::InputError::EventCapacity)
);
}
}
#[test]
fn channel_messages_decode() {
assert_eq!(
Event::note_on(0, 1, 60, 100).message(),
Some(Message::NoteOn {
channel: 1,
key: 60,
velocity: 100
})
);
assert!(matches!(
Event::note_on(0, 0, 60, 0).message(),
Some(Message::NoteOff { key: 60, .. })
));
assert_eq!(
Event::midi(0, [0xE3, 0x00, 0x40]).message(),
Some(Message::PitchBend {
channel: 3,
value: 8192
})
);
let clock = Event::midi(0, [0xF8, 0, 0]);
assert_eq!(clock.message(), None);
assert!(!clock.is_valid());
}
#[test]
fn system_exclusive_messages_are_complete_and_budgeted() {
let sysex = Event::sysex(0, &[0xF0, 0x7D, 0x01, 0xF7]).on_port(1);
assert!(sysex.is_valid());
assert_eq!(sysex.message(), None);
assert_eq!(sysex.data.to_midi(), None);
assert_eq!(sysex.port, 1);
for bytes in [vec![0xF0], vec![0xF0, 0x80, 0xF7], vec![0x7D, 0xF7]] {
assert!(!Event::sysex(0, &bytes).is_valid());
}
let mut large = vec![0; MAX_BLOCK_SYSEX_BYTES + 1];
large[0] = 0xF0;
large[MAX_BLOCK_SYSEX_BYTES] = 0xF7;
assert_eq!(
validate_event_budget(0, &Events::from_iter([Event::sysex(0, &large)])),
Err(crate::InputError::EventCapacity)
);
}
#[test]
fn notes_and_expressions_are_checked_against_their_ranges() {
let note = Note::new(15, 127, 1.0).with_id(MAX_NOTE_ID);
assert!(Event::new(0, EventData::NoteOn(note)).is_valid());
for invalid in [
Note::new(16, 60, 0.5),
Note::new(0, 128, 0.5),
Note::new(0, 60, 1.5),
Note::new(0, 60, f64::NAN),
Note::new(0, 60, 0.5).with_id(MAX_NOTE_ID + 1),
] {
assert!(!Event::new(0, EventData::NoteOff(invalid)).is_valid());
}
for (kind, min, max) in [
(ExpressionKind::Volume, 0.0, 4.0),
(ExpressionKind::Pan, 0.0, 1.0),
(ExpressionKind::Tuning, -120.0, 120.0),
(ExpressionKind::Vibrato, 0.0, 1.0),
(ExpressionKind::Expression, 0.0, 1.0),
(ExpressionKind::Brightness, 0.0, 1.0),
(ExpressionKind::Pressure, 0.0, 1.0),
] {
for (value, valid) in [
(min, true),
(max, true),
(min - 0.001, false),
(max + 0.001, false),
(f64::NAN, false),
(f64::NEG_INFINITY, false),
(f64::INFINITY, false),
] {
let expression = NoteExpression::new(0, 60, kind, value).with_id(3);
assert_eq!(
Event::new(0, EventData::Expression(expression)).is_valid(),
valid,
"{kind:?} {value}"
);
}
}
}
#[test]
fn notes_and_pressure_have_a_midi_form() {
let note = Note::new(2, 64, 0.0).with_id(9);
assert_eq!(EventData::NoteOn(note).to_midi(), Some([0x92, 64, 1]));
let note = Note::new(2, 64, 0.5);
assert_eq!(EventData::NoteOff(note).to_midi(), Some([0x82, 64, 64]));
let pressure = NoteExpression::new(1, 60, ExpressionKind::Pressure, 1.0);
assert_eq!(
EventData::Expression(pressure).to_midi(),
Some([0xA1, 60, 127])
);
let tuning = NoteExpression::new(1, 60, ExpressionKind::Tuning, 1.0);
assert_eq!(EventData::Expression(tuning).to_midi(), None);
}
#[test]
fn two_byte_messages_ignore_their_third_byte() {
for status in [0xC3, 0xD3] {
let event = Event::midi(0, [status, 5, 0x80]);
assert!(event.is_valid());
assert_eq!(event.data.to_midi(), Some([status, 5, 0]));
}
assert!(!Event::midi(0, [0xB3, 5, 0x80]).is_valid());
}
#[test]
fn events_must_be_ordered_and_inside_the_block() {
let on = Event::note_on(10, 0, 60, 100);
let off = Event::note_off(20, 0, 60, 0);
assert!(events_fit(&Events::from_iter([on, off]), 64));
assert!(!events_fit(&Events::from_iter([off, on]), 64));
assert!(!events_fit(&Events::from_iter([on, off]), 20));
}
}