Skip to main content

deepmind_midi/wire/
decoder.rs

1//! Turning a byte stream into whole MIDI messages.
2
3use core::fmt;
4
5use crate::error::{Error, Result};
6
7use super::{Channel, ChannelMessage, Realtime, SYSEX_END, SYSEX_START, SystemCommon};
8
9/// Buffer size the default [`Decoder`] uses.
10///
11/// The longest documented frame is the bank program names dump response: seven
12/// header bytes, a version and a bank byte, 2344 packed bytes and `F7`.
13pub const MAX_SYSEX_LEN: usize = 2354;
14
15/// One whole message pulled out of a byte stream.
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
17#[non_exhaustive]
18pub enum Event<'a> {
19    /// A channel voice message and the channel it arrived on.
20    Channel {
21        /// Channel from the status byte's low nibble.
22        channel: Channel,
23        /// The message itself.
24        message: ChannelMessage,
25    },
26    /// A complete `SysEx` frame, `F0` through `F7` inclusive.
27    ///
28    /// The slice borrows the decoder's buffer and lives until the next byte is
29    /// fed in. Anything a host keeps has to be copied out, or parsed on the spot
30    /// with [`crate::sysex::Frame::parse`].
31    SysEx(&'a [u8]),
32    /// A system common message.
33    Common(SystemCommon),
34    /// A system real-time message.
35    Realtime(Realtime),
36}
37
38/// Reassembles MIDI messages from bytes arriving in any chunking.
39///
40/// The decoder handles the three things that make a MIDI stream awkward:
41///
42/// - **Running status.** A status byte stays in force until another one arrives,
43///   so a stream of note-ons may carry one status byte and nothing but data
44///   afterwards. System common messages clear it; real-time messages do not.
45/// - **Real-time interleaving.** `F8` through `FF` may appear between any two
46///   bytes, including between the `F0` and `F7` of a `SysEx` frame. They are
47///   reported where they arrive and disturb nothing.
48/// - **Chunking.** A USB packet or a serial read boundary can fall anywhere.
49///   Feeding one byte at a time and feeding a whole dump at once produce the
50///   same events.
51///
52/// `N` is the `SysEx` buffer size and defaults to [`MAX_SYSEX_LEN`]. A frame
53/// longer than the buffer is dropped, with [`Error::SysExTooLong`] reported once.
54///
55/// ```
56/// use deepmind_midi::wire::{Decoder, Event};
57///
58/// // A firmware-sized buffer is wasted on a host that only sends NRPN edits.
59/// let mut decoder: Decoder<64> = Decoder::new();
60/// let mut frames = 0;
61/// decoder.feed(&[0xF0, 0x00, 0x20, 0x32, 0x20, 0x00, 0x03, 0xF7], |event| {
62///     if matches!(event, Ok(Event::SysEx(_))) {
63///         frames += 1;
64///     }
65/// });
66/// assert_eq!(frames, 1);
67/// ```
68#[derive(Clone)]
69pub struct Decoder<const N: usize = MAX_SYSEX_LEN> {
70    /// `SysEx` frame under construction, starting at its `F0`.
71    frame: [u8; N],
72    /// Bytes of `frame` in use.
73    len: usize,
74    /// Set between `F0` and the `F7` that closes it.
75    in_sysex: bool,
76    /// Status byte in force, channel or system common. `SysEx` clears it.
77    status: Option<u8>,
78    /// Data bytes collected for `status` so far.
79    data: [u8; 2],
80    /// Number of `data` bytes in use.
81    have: usize,
82}
83
84impl<const N: usize> fmt::Debug for Decoder<N> {
85    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86        f.debug_struct("Decoder")
87            .field("capacity", &N)
88            .field("in_sysex", &self.in_sysex)
89            .field("buffered", &self.len)
90            .field("status", &self.status)
91            .finish_non_exhaustive()
92    }
93}
94
95impl<const N: usize> Default for Decoder<N> {
96    fn default() -> Self {
97        Self::new()
98    }
99}
100
101impl<const N: usize> Decoder<N> {
102    /// Builds a decoder with an empty buffer.
103    #[must_use]
104    pub const fn new() -> Self {
105        Self {
106            frame: [0; N],
107            len: 0,
108            in_sysex: false,
109            status: None,
110            data: [0; 2],
111            have: 0,
112        }
113    }
114
115    /// Returns the `SysEx` buffer size in bytes.
116    #[must_use]
117    pub const fn capacity(&self) -> usize {
118        N
119    }
120
121    /// Returns `true` while a `SysEx` frame is still being reassembled.
122    #[must_use]
123    pub const fn in_sysex(&self) -> bool {
124        self.in_sysex
125    }
126
127    /// Forgets any partial message and the running status.
128    ///
129    /// Worth calling when a port is reopened, since the first bytes after a
130    /// reconnect may be the middle of something.
131    pub fn reset(&mut self) {
132        self.len = 0;
133        self.in_sysex = false;
134        self.status = None;
135        self.have = 0;
136    }
137
138    /// Feeds bytes in, calling `on_event` once per message or rejection.
139    ///
140    /// Chunking is irrelevant: a message split across two calls is reported when
141    /// its last byte arrives.
142    pub fn feed<F>(&mut self, bytes: &[u8], mut on_event: F)
143    where
144        F: FnMut(Result<Event<'_>>),
145    {
146        let mut rest = bytes;
147        while let Some((&byte, tail)) = rest.split_first() {
148            if self.in_sysex {
149                // The inside of a frame is a run of data bytes, which is where
150                // the bulk of a dump is spent, so it goes in as one run. The
151                // status byte that ends the run goes through `step` like any
152                // other.
153                let run = rest
154                    .iter()
155                    .position(|byte| *byte >= 0x80)
156                    .unwrap_or(rest.len());
157                let (data, after) = rest.split_at(run);
158                self.push_sysex_run(data, &mut on_event);
159                rest = after;
160                if let Some((&status, after)) = rest.split_first() {
161                    self.step(status, &mut on_event);
162                    rest = after;
163                }
164            } else {
165                self.step(byte, &mut on_event);
166                rest = tail;
167            }
168        }
169    }
170
171    /// Handles one byte.
172    fn step<F>(&mut self, byte: u8, on_event: &mut F)
173    where
174        F: FnMut(Result<Event<'_>>),
175    {
176        if byte >= 0xF8 {
177            // Real-time. Interrupts anything, disturbs nothing.
178            if let Some(message) = Realtime::from_status(byte) {
179                on_event(Ok(Event::Realtime(message)));
180            }
181        } else if byte >= 0x80 {
182            self.status_byte(byte, on_event);
183        } else {
184            self.data_byte(byte, on_event);
185        }
186    }
187
188    /// Handles a status byte, `0x80..=0xF7`.
189    fn status_byte<F>(&mut self, byte: u8, on_event: &mut F)
190    where
191        F: FnMut(Result<Event<'_>>),
192    {
193        if self.in_sysex {
194            if byte == SYSEX_END {
195                self.finish_sysex(on_event);
196                return;
197            }
198            // Any other status byte ends the frame early. The frame is lost; the
199            // status byte that ended it is not, and is handled below.
200            self.in_sysex = false;
201            self.len = 0;
202            on_event(Err(Error::SysExInterrupted));
203        }
204
205        // An F7 with no F0 in front of it reports nothing, and still falls
206        // through: it is a system common byte, and clears the running status
207        // like the others.
208        self.have = 0;
209        match byte {
210            SYSEX_START => {
211                self.status = None;
212                self.in_sysex = true;
213                self.len = 0;
214                self.push_sysex(SYSEX_START, on_event);
215            }
216            // A channel status byte stays in force. F1, F2 and F3 are system
217            // common messages that take data bytes, so they are held the same
218            // way, and cleared again once their last data byte arrives.
219            0x80..=0xEF | 0xF1..=0xF3 => self.status = Some(byte),
220            // F6 is a system common message that is complete as it stands.
221            0xF6 => {
222                self.status = None;
223                on_event(Ok(Event::Common(SystemCommon::TuneRequest)));
224            }
225            // F4 and F5 are undefined, and still clear the running status.
226            _ => self.status = None,
227        }
228    }
229
230    /// Handles a data byte, `0x00..=0x7F`.
231    fn data_byte<F>(&mut self, byte: u8, on_event: &mut F)
232    where
233        F: FnMut(Result<Event<'_>>),
234    {
235        if self.in_sysex {
236            self.push_sysex(byte, on_event);
237            return;
238        }
239        let Some(status) = self.status else {
240            // A data byte with no status in front of it, which is what the
241            // middle of a message looks like after a reconnect.
242            return;
243        };
244        if let Some(slot) = self.data.get_mut(self.have) {
245            *slot = byte;
246            self.have += 1;
247        }
248        if self.have < Self::data_len_for(status) {
249            return;
250        }
251        self.have = 0;
252        let (first, second) = (self.data.first().copied(), self.data.get(1).copied());
253        let (first, second) = (first.unwrap_or_default(), second.unwrap_or_default());
254        if let Some(message) = ChannelMessage::from_bytes(status, first, second) {
255            if let Ok(channel) = Channel::new(status & 0x0F) {
256                on_event(Ok(Event::Channel { channel, message }));
257            }
258            return;
259        }
260        // System common carries no running status: the next data byte belongs to
261        // nothing until another status byte arrives.
262        self.status = None;
263        let common = match status {
264            0xF1 => SystemCommon::TimeCodeQuarterFrame(first),
265            0xF2 => SystemCommon::SongPosition(u16::from(second) << 7 | u16::from(first)),
266            _ => SystemCommon::SongSelect(first),
267        };
268        on_event(Ok(Event::Common(common)));
269    }
270
271    /// Returns how many data bytes the message under `status` carries.
272    const fn data_len_for(status: u8) -> usize {
273        match ChannelMessage::data_len_for(status) {
274            Some(len) => len,
275            // F2 is the only two-byte system common message.
276            None if status == 0xF2 => 2,
277            None => 1,
278        }
279    }
280
281    /// Appends one byte to the frame under construction.
282    fn push_sysex<F>(&mut self, byte: u8, on_event: &mut F)
283    where
284        F: FnMut(Result<Event<'_>>),
285    {
286        if let Some(slot) = self.frame.get_mut(self.len) {
287            *slot = byte;
288            self.len += 1;
289            return;
290        }
291        // Out of room. Drop the frame and every byte up to its F7, which then
292        // reads as a stray end and is ignored.
293        self.in_sysex = false;
294        self.len = 0;
295        on_event(Err(Error::SysExTooLong(N)));
296    }
297
298    /// Appends a run of data bytes to the frame under construction.
299    fn push_sysex_run<F>(&mut self, data: &[u8], on_event: &mut F)
300    where
301        F: FnMut(Result<Event<'_>>),
302    {
303        if data.is_empty() {
304            return;
305        }
306        let end = self.len.saturating_add(data.len());
307        if let Some(slots) = self.frame.get_mut(self.len..end) {
308            slots.copy_from_slice(data);
309            self.len = end;
310            return;
311        }
312        // Out of room, the same as one byte too many in `push_sysex`.
313        self.in_sysex = false;
314        self.len = 0;
315        on_event(Err(Error::SysExTooLong(N)));
316    }
317
318    /// Closes the frame under construction and reports it.
319    fn finish_sysex<F>(&mut self, on_event: &mut F)
320    where
321        F: FnMut(Result<Event<'_>>),
322    {
323        self.push_sysex(SYSEX_END, on_event);
324        if !self.in_sysex {
325            // The F7 did not fit; push_sysex has already reported the overflow.
326            return;
327        }
328        if let Some(frame) = self.frame.get(..self.len) {
329            on_event(Ok(Event::SysEx(frame)));
330        }
331        self.in_sysex = false;
332        self.len = 0;
333    }
334}
335
336#[cfg(all(test, feature = "alloc"))]
337mod tests {
338    use alloc::vec::Vec;
339
340    use super::*;
341
342    /// Collects owned events, since the borrowed frames do not outlive the feed.
343    #[derive(Debug, PartialEq, Eq)]
344    enum Owned {
345        Channel(Channel, ChannelMessage),
346        SysEx(Vec<u8>),
347        Common(SystemCommon),
348        Realtime(Realtime),
349        Rejected(Error),
350    }
351
352    fn collect<const N: usize>(decoder: &mut Decoder<N>, bytes: &[u8]) -> Vec<Owned> {
353        let mut out = Vec::new();
354        decoder.feed(bytes, |event| {
355            out.push(match event {
356                Ok(Event::Channel { channel, message }) => Owned::Channel(channel, message),
357                Ok(Event::SysEx(frame)) => Owned::SysEx(frame.to_vec()),
358                Ok(Event::Common(message)) => Owned::Common(message),
359                Ok(Event::Realtime(message)) => Owned::Realtime(message),
360                Err(error) => Owned::Rejected(error),
361            });
362        });
363        out
364    }
365
366    fn decode(bytes: &[u8]) -> Vec<Owned> {
367        collect(&mut Decoder::<MAX_SYSEX_LEN>::new(), bytes)
368    }
369
370    #[test]
371    fn running_status_applies_to_every_following_data_pair() {
372        let events = decode(&[0x90, 0x3C, 0x40, 0x3E, 0x40, 0x80, 0x3C, 0x00]);
373        assert_eq!(
374            events,
375            [
376                Owned::Channel(
377                    Channel::ONE,
378                    ChannelMessage::NoteOn {
379                        key: 0x3C,
380                        velocity: 0x40
381                    }
382                ),
383                Owned::Channel(
384                    Channel::ONE,
385                    ChannelMessage::NoteOn {
386                        key: 0x3E,
387                        velocity: 0x40
388                    }
389                ),
390                Owned::Channel(
391                    Channel::ONE,
392                    ChannelMessage::NoteOff {
393                        key: 0x3C,
394                        velocity: 0x00
395                    }
396                ),
397            ]
398        );
399    }
400
401    #[test]
402    fn chunking_does_not_change_what_comes_out() {
403        let stream = [
404            0xB0, 0x63, 0x01, 0x62, 0x0E, 0x06, 0x00, 0x26, 0x40, 0xF0, 0x00, 0x20, 0x32, 0x20,
405            0x00, 0x03, 0xF7, 0xE1, 0x00, 0x40,
406        ];
407        let whole = decode(&stream);
408        for chunk in 1..=stream.len() {
409            let mut decoder = Decoder::<MAX_SYSEX_LEN>::new();
410            let mut split = Vec::new();
411            for piece in stream.chunks(chunk) {
412                split.extend(collect(&mut decoder, piece));
413            }
414            assert_eq!(split, whole, "chunked {chunk} bytes at a time");
415        }
416    }
417
418    #[test]
419    fn real_time_bytes_interleave_anywhere_without_disturbing_anything() {
420        let events = decode(&[
421            0x90, 0xF8, 0x3C, 0xF8, 0x40, 0xF0, 0xFE, 0x7F, 0xF7, 0x3E, 0x40,
422        ]);
423        assert_eq!(
424            events,
425            [
426                Owned::Realtime(Realtime::Clock),
427                Owned::Realtime(Realtime::Clock),
428                Owned::Channel(
429                    Channel::ONE,
430                    ChannelMessage::NoteOn {
431                        key: 0x3C,
432                        velocity: 0x40
433                    }
434                ),
435                Owned::Realtime(Realtime::ActiveSensing),
436                Owned::SysEx(alloc::vec![0xF0, 0x7F, 0xF7]),
437                // SysEx cleared the running status, so the trailing pair is lost.
438            ]
439        );
440    }
441
442    #[test]
443    fn a_status_byte_inside_a_frame_ends_it_and_is_still_acted_on() {
444        let events = decode(&[0xF0, 0x00, 0x20, 0x90, 0x3C, 0x40]);
445        assert_eq!(
446            events,
447            [
448                Owned::Rejected(Error::SysExInterrupted),
449                Owned::Channel(
450                    Channel::ONE,
451                    ChannelMessage::NoteOn {
452                        key: 0x3C,
453                        velocity: 0x40
454                    }
455                ),
456            ]
457        );
458    }
459
460    #[test]
461    fn a_frame_larger_than_the_buffer_is_dropped_once_and_the_stream_recovers() {
462        let mut decoder: Decoder<8> = Decoder::new();
463        let mut stream = alloc::vec![0xF0];
464        stream.extend(core::iter::repeat_n(0x00, 32));
465        stream.push(0xF7);
466        stream.extend([0x90, 0x3C, 0x40]);
467        let events = collect(&mut decoder, &stream);
468        assert_eq!(
469            events,
470            [
471                Owned::Rejected(Error::SysExTooLong(8)),
472                Owned::Channel(
473                    Channel::ONE,
474                    ChannelMessage::NoteOn {
475                        key: 0x3C,
476                        velocity: 0x40
477                    }
478                ),
479            ]
480        );
481        assert!(!decoder.in_sysex());
482    }
483
484    #[test]
485    fn a_frame_that_exactly_fills_the_buffer_still_comes_out() {
486        let mut decoder: Decoder<8> = Decoder::new();
487        let frame = [0xF0, 0x00, 0x20, 0x32, 0x20, 0x00, 0x03, 0xF7];
488        assert_eq!(
489            collect(&mut decoder, &frame),
490            [Owned::SysEx(frame.to_vec())]
491        );
492    }
493
494    #[test]
495    fn system_common_messages_clear_the_running_status() {
496        let events = decode(&[0x90, 0x3C, 0x40, 0xF2, 0x00, 0x02, 0x3E, 0x40]);
497        assert_eq!(
498            events,
499            [
500                Owned::Channel(
501                    Channel::ONE,
502                    ChannelMessage::NoteOn {
503                        key: 0x3C,
504                        velocity: 0x40
505                    }
506                ),
507                Owned::Common(SystemCommon::SongPosition(256)),
508                // The trailing pair has no status in front of it.
509            ]
510        );
511        assert_eq!(
512            decode(&[0xF1, 0x11, 0xF3, 0x04, 0xF6]),
513            [
514                Owned::Common(SystemCommon::TimeCodeQuarterFrame(0x11)),
515                Owned::Common(SystemCommon::SongSelect(0x04)),
516                Owned::Common(SystemCommon::TuneRequest),
517            ]
518        );
519    }
520
521    #[test]
522    fn data_bytes_with_no_status_and_stray_ends_are_ignored() {
523        assert_eq!(decode(&[0x40, 0x40, 0xF7, 0x40]), []);
524    }
525
526    /// A stray F7 is a system common byte like F4 and F5, so a data pair split
527    /// by one is not put back together.
528    #[test]
529    fn a_stray_end_clears_the_running_status() {
530        assert_eq!(decode(&[0x90, 0x3C, 0xF7, 0x40, 0x3E, 0x40]), []);
531        assert_eq!(
532            decode(&[0x90, 0xF7, 0x90, 0x3C, 0x40]),
533            [Owned::Channel(
534                Channel::ONE,
535                ChannelMessage::NoteOn {
536                    key: 0x3C,
537                    velocity: 0x40
538                }
539            )]
540        );
541    }
542
543    #[test]
544    fn a_second_f0_restarts_the_frame_and_reports_the_first() {
545        let events = decode(&[0xF0, 0x01, 0xF0, 0x02, 0xF7]);
546        assert_eq!(
547            events,
548            [
549                Owned::Rejected(Error::SysExInterrupted),
550                Owned::SysEx(alloc::vec![0xF0, 0x02, 0xF7]),
551            ]
552        );
553    }
554
555    #[test]
556    fn reset_forgets_a_partial_frame_and_the_running_status() {
557        let mut decoder = Decoder::<MAX_SYSEX_LEN>::new();
558        assert_eq!(collect(&mut decoder, &[0x90, 0x3C, 0xF0, 0x01]), []);
559        assert!(decoder.in_sysex());
560        decoder.reset();
561        assert!(!decoder.in_sysex());
562        assert_eq!(collect(&mut decoder, &[0x02, 0xF7]), []);
563    }
564}