1use core::fmt;
4
5use crate::error::{Error, Result};
6
7use super::{Channel, ChannelMessage, Realtime, SYSEX_END, SYSEX_START, SystemCommon};
8
9pub const MAX_SYSEX_LEN: usize = 2354;
14
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
17#[non_exhaustive]
18pub enum Event<'a> {
19 Channel {
21 channel: Channel,
23 message: ChannelMessage,
25 },
26 SysEx(&'a [u8]),
32 Common(SystemCommon),
34 Realtime(Realtime),
36}
37
38#[derive(Clone)]
69pub struct Decoder<const N: usize = MAX_SYSEX_LEN> {
70 frame: [u8; N],
72 len: usize,
74 in_sysex: bool,
76 status: Option<u8>,
78 data: [u8; 2],
80 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 #[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 #[must_use]
117 pub const fn capacity(&self) -> usize {
118 N
119 }
120
121 #[must_use]
123 pub const fn in_sysex(&self) -> bool {
124 self.in_sysex
125 }
126
127 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 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 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 fn step<F>(&mut self, byte: u8, on_event: &mut F)
173 where
174 F: FnMut(Result<Event<'_>>),
175 {
176 if byte >= 0xF8 {
177 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 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 self.in_sysex = false;
201 self.len = 0;
202 on_event(Err(Error::SysExInterrupted));
203 }
204
205 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 0x80..=0xEF | 0xF1..=0xF3 => self.status = Some(byte),
220 0xF6 => {
222 self.status = None;
223 on_event(Ok(Event::Common(SystemCommon::TuneRequest)));
224 }
225 _ => self.status = None,
227 }
228 }
229
230 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 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 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 const fn data_len_for(status: u8) -> usize {
273 match ChannelMessage::data_len_for(status) {
274 Some(len) => len,
275 None if status == 0xF2 => 2,
277 None => 1,
278 }
279 }
280
281 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 self.in_sysex = false;
294 self.len = 0;
295 on_event(Err(Error::SysExTooLong(N)));
296 }
297
298 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 self.in_sysex = false;
314 self.len = 0;
315 on_event(Err(Error::SysExTooLong(N)));
316 }
317
318 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 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 #[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 ]
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 ]
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 #[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}