Skip to main content

qualia_audio/midi/smf/
vlq.rs

1//! Variable-Length Quantity (VLQ) codec for Standard MIDI Files.
2//!
3//! SMF delta-times and several length fields are stored as VLQs: a big-endian
4//! base-128 number where each byte carries 7 payload bits and the high bit
5//! (`0x80`) signals "more bytes follow". The SMF spec caps a VLQ at 4 bytes,
6//! i.e. 28 payload bits (`0x0FFF_FFFF`). Cold path — `Vec`/slice use is fine.
7//!
8//! Lane AU-MIDI-FILE.
9
10use crate::types::AudioError;
11
12/// Largest value representable in a 4-byte SMF VLQ (28 bits).
13pub const VLQ_MAX: u32 = 0x0FFF_FFFF;
14
15/// Decode a VLQ from the front of `bytes`.
16///
17/// Returns `(value, bytes_consumed)`. Errors with [`AudioError::MalformedAudio`]
18/// if the input ends mid-number or the quantity exceeds the 4-byte / 28-bit
19/// SMF limit.
20pub fn read_vlq(bytes: &[u8]) -> Result<(u32, usize), AudioError> {
21    let mut value: u32 = 0;
22    let mut consumed: usize = 0;
23    loop {
24        // A VLQ is at most 4 bytes; a 5th continuation byte is malformed.
25        if consumed >= 4 {
26            return Err(AudioError::MalformedAudio);
27        }
28        let byte = *bytes.get(consumed).ok_or(AudioError::MalformedAudio)?;
29        consumed += 1;
30        value = (value << 7) | u32::from(byte & 0x7F);
31        if byte & 0x80 == 0 {
32            return Ok((value, consumed));
33        }
34    }
35}
36
37/// Encode `value` as a VLQ appended to `out`.
38///
39/// Returns the number of bytes written (1..=4). Errors with
40/// [`AudioError::InvalidParameter`] if `value` exceeds [`VLQ_MAX`].
41pub fn write_vlq(value: u32, out: &mut Vec<u8>) -> Result<usize, AudioError> {
42    if value > VLQ_MAX {
43        return Err(AudioError::InvalidParameter);
44    }
45    // Build the 7-bit groups most-significant first, setting the continuation
46    // bit on every group except the last.
47    let mut buffer = [0u8; 4];
48    let mut count = 1usize;
49    buffer[0] = (value & 0x7F) as u8;
50    let mut v = value >> 7;
51    while v != 0 {
52        // Prepend the next group with its continuation bit set.
53        buffer[count] = ((v & 0x7F) as u8) | 0x80;
54        count += 1;
55        v >>= 7;
56    }
57    // `buffer` holds groups least-significant first; emit reversed.
58    for i in (0..count).rev() {
59        out.push(buffer[i]);
60    }
61    Ok(count)
62}
63
64#[cfg(test)]
65mod tests {
66    use super::*;
67
68    #[test]
69    fn read_golden_values() {
70        assert_eq!(read_vlq(&[0x00]).unwrap(), (0, 1));
71        assert_eq!(read_vlq(&[0x7F]).unwrap(), (127, 1));
72        assert_eq!(read_vlq(&[0x81, 0x00]).unwrap(), (128, 2));
73        assert_eq!(read_vlq(&[0xFF, 0x7F]).unwrap(), (16383, 2));
74        // Spec canonical extremes.
75        assert_eq!(read_vlq(&[0x81, 0x80, 0x00]).unwrap(), (16384, 3));
76        assert_eq!(read_vlq(&[0xFF, 0xFF, 0xFF, 0x7F]).unwrap(), (VLQ_MAX, 4));
77    }
78
79    #[test]
80    fn write_golden_values() {
81        let cases: &[(u32, &[u8])] = &[
82            (0, &[0x00]),
83            (127, &[0x7F]),
84            (128, &[0x81, 0x00]),
85            (16383, &[0xFF, 0x7F]),
86            (16384, &[0x81, 0x80, 0x00]),
87            (VLQ_MAX, &[0xFF, 0xFF, 0xFF, 0x7F]),
88        ];
89        for (value, expected) in cases {
90            let mut out = Vec::new();
91            let n = write_vlq(*value, &mut out).unwrap();
92            assert_eq!(n, expected.len(), "byte count for {value}");
93            assert_eq!(out.as_slice(), *expected, "bytes for {value}");
94        }
95    }
96
97    #[test]
98    fn write_read_round_trip() {
99        for &value in &[0u32, 1, 127, 128, 16383, 16384, 2_097_151, VLQ_MAX] {
100            let mut out = Vec::new();
101            write_vlq(value, &mut out).unwrap();
102            let (decoded, consumed) = read_vlq(&out).unwrap();
103            assert_eq!(decoded, value);
104            assert_eq!(consumed, out.len());
105        }
106    }
107
108    #[test]
109    fn read_truncated_is_error() {
110        // Continuation bit set but no following byte.
111        assert_eq!(read_vlq(&[0x81]), Err(AudioError::MalformedAudio));
112        assert_eq!(read_vlq(&[]), Err(AudioError::MalformedAudio));
113    }
114
115    #[test]
116    fn read_overlong_is_error() {
117        // Five continuation bytes exceed the 4-byte cap.
118        assert_eq!(
119            read_vlq(&[0x80, 0x80, 0x80, 0x80, 0x00]),
120            Err(AudioError::MalformedAudio)
121        );
122    }
123
124    #[test]
125    fn write_rejects_oversize() {
126        let mut out = Vec::new();
127        assert_eq!(
128            write_vlq(VLQ_MAX + 1, &mut out),
129            Err(AudioError::InvalidParameter)
130        );
131        assert!(out.is_empty());
132    }
133}