Skip to main content

qualia_audio/midi/message/
pitch_bend.rs

1//! MIDI 1.0 Pitch Bend (`0xEn`) channel-voice message — 14-bit value.
2//!
3//! The 14-bit value is transmitted as two 7-bit bytes, LSB first:
4//! `[0xEn, lsb, msb]` where `value = (msb << 7) | lsb`. Center (no bend) is
5//! `8192` (`lsb = 0x00, msb = 0x40`).
6
7use crate::types::AudioError;
8
9/// Pitch Bend status nibble (`0xEn`).
10pub const STATUS_PITCH_BEND: u8 = 0xE0;
11/// 14-bit center value (no bend).
12pub const CENTER: u16 = 8192;
13/// Maximum 14-bit value.
14pub const MAX: u16 = 0x3FFF;
15
16/// A MIDI 1.0 Pitch Bend message. `value` is the raw 14-bit unsigned value
17/// (0..=16383); 8192 is center.
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
19pub struct PitchBend {
20    /// MIDI channel, 0..=15.
21    pub channel: u8,
22    /// 14-bit bend value, 0..=16383. 8192 = center.
23    pub value: u16,
24}
25
26impl PitchBend {
27    /// Construct from a raw 14-bit value (0..=16383).
28    pub fn new(channel: u8, value: u16) -> Result<Self, AudioError> {
29        if channel > 15 || value > MAX {
30            return Err(AudioError::InvalidParameter);
31        }
32        Ok(Self { channel, value })
33    }
34
35    /// Construct from a signed offset around center (-8192..=8191).
36    pub fn from_signed(channel: u8, signed: i16) -> Result<Self, AudioError> {
37        let v = signed as i32 + CENTER as i32;
38        if !(0..=MAX as i32).contains(&v) {
39            return Err(AudioError::InvalidParameter);
40        }
41        Self::new(channel, v as u16)
42    }
43
44    /// Value as a signed offset around center (-8192..=8191).
45    #[inline]
46    pub fn signed(self) -> i16 {
47        self.value as i16 - CENTER as i16
48    }
49
50    /// Serialize to `[0xEn, lsb, msb]` (LSB first).
51    #[inline]
52    pub fn to_bytes(self) -> [u8; 3] {
53        [
54            STATUS_PITCH_BEND | (self.channel & 0x0F),
55            (self.value & 0x7F) as u8,
56            ((self.value >> 7) & 0x7F) as u8,
57        ]
58    }
59
60    /// Parse from a slice whose first byte is a Pitch Bend status.
61    pub fn parse(bytes: &[u8]) -> Result<Self, AudioError> {
62        if bytes.len() < 3 {
63            return Err(AudioError::MalformedAudio);
64        }
65        if bytes[0] & 0xF0 != STATUS_PITCH_BEND {
66            return Err(AudioError::UnsupportedFormat);
67        }
68        if bytes[1] > 127 || bytes[2] > 127 {
69            return Err(AudioError::MalformedAudio);
70        }
71        let value = ((bytes[2] as u16) << 7) | (bytes[1] as u16);
72        Ok(Self {
73            channel: bytes[0] & 0x0F,
74            value,
75        })
76    }
77}
78
79#[cfg(test)]
80mod tests {
81    use super::*;
82
83    #[test]
84    fn golden_center() {
85        // Golden vector: 0xE0 0x00 0x40 -> 8192 (center).
86        let pb = PitchBend::parse(&[0xE0, 0x00, 0x40]).unwrap();
87        assert_eq!(pb.channel, 0);
88        assert_eq!(pb.value, 8192);
89        assert_eq!(pb.signed(), 0);
90    }
91
92    #[test]
93    fn roundtrip_and_extremes() {
94        let center = PitchBend::new(0, CENTER).unwrap();
95        assert_eq!(center.to_bytes(), [0xE0, 0x00, 0x40]);
96
97        let max = PitchBend::new(3, MAX).unwrap();
98        assert_eq!(max.to_bytes(), [0xE3, 0x7F, 0x7F]);
99        assert_eq!(PitchBend::parse(&max.to_bytes()).unwrap(), max);
100
101        let min = PitchBend::new(0, 0).unwrap();
102        assert_eq!(min.to_bytes(), [0xE0, 0x00, 0x00]);
103        assert_eq!(min.signed(), -8192);
104    }
105
106    #[test]
107    fn signed_roundtrip() {
108        let pb = PitchBend::from_signed(5, -2048).unwrap();
109        assert_eq!(pb.value, 8192 - 2048);
110        assert_eq!(pb.signed(), -2048);
111    }
112
113    #[test]
114    fn rejects_bad() {
115        assert_eq!(PitchBend::new(0, 16384), Err(AudioError::InvalidParameter));
116        assert_eq!(
117            PitchBend::parse(&[0x90, 0, 0x40]),
118            Err(AudioError::UnsupportedFormat)
119        );
120    }
121}