Skip to main content

qualia_audio/midi/message/
sysex.rs

1//! MIDI 1.0 System Exclusive (SysEx) framing over caller buffers.
2//!
3//! A SysEx message is `F0 <payload...> F7`, where every payload byte is a data
4//! byte (high bit clear, 0..=127). These helpers are zero-heap: [`frame_sysex`]
5//! writes into a caller buffer and returns the length; [`sysex_payload`] borrows
6//! the payload slice out of a complete frame without copying.
7
8use crate::types::AudioError;
9
10/// SysEx start byte.
11pub const SYSEX_START: u8 = 0xF0;
12/// SysEx end (EOX) byte.
13pub const SYSEX_END: u8 = 0xF7;
14
15/// Frame `payload` as `F0 <payload> F7` into `out`, returning the total number
16/// of bytes written (`payload.len() + 2`).
17///
18/// Errors:
19/// - [`AudioError::InvalidParameter`] if any payload byte has its high bit set
20///   (SysEx payloads carry only 7-bit data bytes).
21/// - [`AudioError::OutputBufferTooSmall`] if `out` cannot hold the frame.
22pub fn frame_sysex(payload: &[u8], out: &mut [u8]) -> Result<usize, AudioError> {
23    let total = payload.len() + 2;
24    if out.len() < total {
25        return Err(AudioError::OutputBufferTooSmall);
26    }
27    for &b in payload {
28        if b > 127 {
29            return Err(AudioError::InvalidParameter);
30        }
31    }
32    out[0] = SYSEX_START;
33    out[1..1 + payload.len()].copy_from_slice(payload);
34    out[1 + payload.len()] = SYSEX_END;
35    Ok(total)
36}
37
38/// Borrow the payload (bytes between `F0` and `F7`) from a complete SysEx frame.
39///
40/// Errors [`AudioError::MalformedAudio`] if `frame` does not start with `F0`,
41/// does not end with `F7`, is shorter than 2 bytes, or contains a status byte
42/// (high bit set) inside the payload.
43pub fn sysex_payload(frame: &[u8]) -> Result<&[u8], AudioError> {
44    if frame.len() < 2 || frame[0] != SYSEX_START || frame[frame.len() - 1] != SYSEX_END {
45        return Err(AudioError::MalformedAudio);
46    }
47    let payload = &frame[1..frame.len() - 1];
48    for &b in payload {
49        if b > 127 {
50            return Err(AudioError::MalformedAudio);
51        }
52    }
53    Ok(payload)
54}
55
56/// Universal SysEx: build a Non-Real-Time / Real-Time universal header frame.
57///
58/// `F0 <7E|7F> <device_id> <sub_id1> <sub_id2> <payload...> F7`. `real_time`
59/// selects `0x7F` (real-time) vs `0x7E` (non-real-time). Returns bytes written.
60pub fn frame_universal(
61    real_time: bool,
62    device_id: u8,
63    sub_id1: u8,
64    sub_id2: u8,
65    payload: &[u8],
66    out: &mut [u8],
67) -> Result<usize, AudioError> {
68    let total = payload.len() + 6;
69    if out.len() < total {
70        return Err(AudioError::OutputBufferTooSmall);
71    }
72    if device_id > 127 || sub_id1 > 127 || sub_id2 > 127 {
73        return Err(AudioError::InvalidParameter);
74    }
75    for &b in payload {
76        if b > 127 {
77            return Err(AudioError::InvalidParameter);
78        }
79    }
80    out[0] = SYSEX_START;
81    out[1] = if real_time { 0x7F } else { 0x7E };
82    out[2] = device_id;
83    out[3] = sub_id1;
84    out[4] = sub_id2;
85    out[5..5 + payload.len()].copy_from_slice(payload);
86    out[5 + payload.len()] = SYSEX_END;
87    Ok(total)
88}
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93
94    #[test]
95    fn frame_and_unframe() {
96        let payload = [0x43, 0x12, 0x00]; // e.g. Yamaha manufacturer + data
97        let mut buf = [0u8; 8];
98        let n = frame_sysex(&payload, &mut buf).unwrap();
99        assert_eq!(n, 5);
100        assert_eq!(&buf[..n], &[0xF0, 0x43, 0x12, 0x00, 0xF7]);
101        assert_eq!(sysex_payload(&buf[..n]).unwrap(), &payload);
102    }
103
104    #[test]
105    fn buffer_too_small() {
106        let mut buf = [0u8; 2];
107        assert_eq!(
108            frame_sysex(&[1, 2, 3], &mut buf),
109            Err(AudioError::OutputBufferTooSmall)
110        );
111    }
112
113    #[test]
114    fn rejects_status_in_payload() {
115        let mut buf = [0u8; 8];
116        assert_eq!(
117            frame_sysex(&[0x80], &mut buf),
118            Err(AudioError::InvalidParameter)
119        );
120        assert_eq!(
121            sysex_payload(&[0xF0, 0x80, 0xF7]),
122            Err(AudioError::MalformedAudio)
123        );
124        assert_eq!(
125            sysex_payload(&[0x00, 0xF7]),
126            Err(AudioError::MalformedAudio)
127        );
128    }
129
130    #[test]
131    fn universal_header() {
132        let mut buf = [0u8; 16];
133        // Non-real-time, device 0x7F (all), General MIDI (7E ... 09 01) style.
134        let n = frame_universal(false, 0x7F, 0x09, 0x01, &[], &mut buf).unwrap();
135        assert_eq!(&buf[..n], &[0xF0, 0x7E, 0x7F, 0x09, 0x01, 0xF7]);
136    }
137}