Skip to main content

qualia_audio/midi/smf/
meta_event.rs

1//! SMF meta-event model with parse/serialize.
2//!
3//! Meta-events live inside MTrk chunks, framed as `0xFF <type> <vlq len> <data>`.
4//! This module owns the *payload* codec: [`parse_meta`] decodes a `(type, data)`
5//! pair into a [`MetaEvent`], and [`serialize_meta`] writes the full
6//! `0xFF type len data` framing back out. The named variants (tempo,
7//! time-signature, track-name, end-of-track, key-signature, sequence number)
8//! are decoded structurally; every other meta type is preserved byte-exact via
9//! [`MetaEvent::Unknown`], so round-trips are lossless.
10//!
11//! Lane AU-MIDI-FILE.
12
13use super::vlq::write_vlq;
14use crate::types::AudioError;
15
16/// Meta-event type bytes (the `<type>` after `0xFF`).
17pub const META_SEQUENCE_NUMBER: u8 = 0x00;
18pub const META_TRACK_NAME: u8 = 0x03;
19pub const META_END_OF_TRACK: u8 = 0x2F;
20pub const META_TEMPO: u8 = 0x51;
21pub const META_TIME_SIGNATURE: u8 = 0x58;
22pub const META_KEY_SIGNATURE: u8 = 0x59;
23
24/// A parsed SMF meta-event payload.
25///
26/// `Unknown` carries any meta type this module does not decode structurally
27/// (text, marker, SMPTE offset, sequencer-specific, …) so serialization is
28/// byte-identical to the source.
29#[derive(Debug, Clone, PartialEq, Eq)]
30pub enum MetaEvent {
31    /// `0x00` — optional 16-bit sequence number.
32    SequenceNumber(u16),
33    /// `0x03` — track name (raw bytes; SMF text is not guaranteed UTF-8).
34    TrackName(Vec<u8>),
35    /// `0x2F` — end of track (zero-length).
36    EndOfTrack,
37    /// `0x51` — tempo in microseconds per quarter note (24-bit range).
38    Tempo(u32),
39    /// `0x58` — time signature.
40    TimeSignature {
41        /// Numerator, as written.
42        numerator: u8,
43        /// Denominator as a negative power of two (`2` ⇒ 1/4). This is the raw
44        /// SMF field, i.e. denominator = 2^value.
45        denominator_pow2: u8,
46        /// MIDI clocks per metronome click.
47        clocks_per_click: u8,
48        /// Number of notated 32nd-notes per MIDI quarter-note (usually 8).
49        thirty_seconds_per_quarter: u8,
50    },
51    /// `0x59` — key signature.
52    KeySignature {
53        /// Sharps (positive) / flats (negative), -7..=7.
54        sharps: i8,
55        /// `true` for minor, `false` for major.
56        minor: bool,
57    },
58    /// Any other meta type, preserved verbatim.
59    Unknown { meta_type: u8, data: Vec<u8> },
60}
61
62/// Decode a meta-event from its type byte and payload `data` (the bytes after
63/// the VLQ length, exactly `len` of them).
64///
65/// Structurally-decoded types validate their fixed length and error with
66/// [`AudioError::MalformedAudio`] on a mismatch; unrecognised types are kept in
67/// [`MetaEvent::Unknown`].
68pub fn parse_meta(meta_type: u8, data: &[u8]) -> Result<MetaEvent, AudioError> {
69    match meta_type {
70        META_SEQUENCE_NUMBER => {
71            // Spec allows length 0 (implicit) or 2.
72            match data.len() {
73                0 => Ok(MetaEvent::SequenceNumber(0)),
74                2 => Ok(MetaEvent::SequenceNumber(
75                    (u16::from(data[0]) << 8) | u16::from(data[1]),
76                )),
77                _ => Err(AudioError::MalformedAudio),
78            }
79        }
80        META_TRACK_NAME => Ok(MetaEvent::TrackName(data.to_vec())),
81        META_END_OF_TRACK => {
82            if data.is_empty() {
83                Ok(MetaEvent::EndOfTrack)
84            } else {
85                Err(AudioError::MalformedAudio)
86            }
87        }
88        META_TEMPO => {
89            if data.len() != 3 {
90                return Err(AudioError::MalformedAudio);
91            }
92            let us = (u32::from(data[0]) << 16) | (u32::from(data[1]) << 8) | u32::from(data[2]);
93            Ok(MetaEvent::Tempo(us))
94        }
95        META_TIME_SIGNATURE => {
96            if data.len() != 4 {
97                return Err(AudioError::MalformedAudio);
98            }
99            Ok(MetaEvent::TimeSignature {
100                numerator: data[0],
101                denominator_pow2: data[1],
102                clocks_per_click: data[2],
103                thirty_seconds_per_quarter: data[3],
104            })
105        }
106        META_KEY_SIGNATURE => {
107            if data.len() != 2 {
108                return Err(AudioError::MalformedAudio);
109            }
110            Ok(MetaEvent::KeySignature {
111                sharps: data[0] as i8,
112                minor: data[1] != 0,
113            })
114        }
115        other => Ok(MetaEvent::Unknown {
116            meta_type: other,
117            data: data.to_vec(),
118        }),
119    }
120}
121
122/// Serialize a meta-event as `0xFF <type> <vlq len> <data>`, appended to `out`.
123///
124/// Returns the number of bytes written.
125pub fn serialize_meta(event: &MetaEvent, out: &mut Vec<u8>) -> Result<usize, AudioError> {
126    let start = out.len();
127    out.push(0xFF);
128    match event {
129        MetaEvent::SequenceNumber(n) => {
130            out.push(META_SEQUENCE_NUMBER);
131            write_vlq(2, out)?;
132            out.push((n >> 8) as u8);
133            out.push((n & 0xFF) as u8);
134        }
135        MetaEvent::TrackName(name) => {
136            out.push(META_TRACK_NAME);
137            write_len(name.len(), out)?;
138            out.extend_from_slice(name);
139        }
140        MetaEvent::EndOfTrack => {
141            out.push(META_END_OF_TRACK);
142            write_vlq(0, out)?;
143        }
144        MetaEvent::Tempo(us) => {
145            if *us > 0x00FF_FFFF {
146                return Err(AudioError::InvalidParameter);
147            }
148            out.push(META_TEMPO);
149            write_vlq(3, out)?;
150            out.push((us >> 16) as u8);
151            out.push((us >> 8) as u8);
152            out.push((us & 0xFF) as u8);
153        }
154        MetaEvent::TimeSignature {
155            numerator,
156            denominator_pow2,
157            clocks_per_click,
158            thirty_seconds_per_quarter,
159        } => {
160            out.push(META_TIME_SIGNATURE);
161            write_vlq(4, out)?;
162            out.push(*numerator);
163            out.push(*denominator_pow2);
164            out.push(*clocks_per_click);
165            out.push(*thirty_seconds_per_quarter);
166        }
167        MetaEvent::KeySignature { sharps, minor } => {
168            out.push(META_KEY_SIGNATURE);
169            write_vlq(2, out)?;
170            out.push(*sharps as u8);
171            out.push(if *minor { 1 } else { 0 });
172        }
173        MetaEvent::Unknown { meta_type, data } => {
174            out.push(*meta_type);
175            write_len(data.len(), out)?;
176            out.extend_from_slice(data);
177        }
178    }
179    Ok(out.len() - start)
180}
181
182/// Write a payload length as a VLQ, guarding the 28-bit VLQ ceiling.
183fn write_len(len: usize, out: &mut Vec<u8>) -> Result<(), AudioError> {
184    let len = u32::try_from(len).map_err(|_| AudioError::InvalidParameter)?;
185    write_vlq(len, out)?;
186    Ok(())
187}
188
189#[cfg(test)]
190mod tests {
191    use super::*;
192
193    /// Round-trip a meta-event through serialize → (strip 0xFF/type/len) → parse.
194    fn round_trip(event: &MetaEvent) {
195        let mut bytes = Vec::new();
196        serialize_meta(event, &mut bytes).unwrap();
197        assert_eq!(bytes[0], 0xFF);
198        let meta_type = bytes[1];
199        let (len, len_bytes) = super::super::vlq::read_vlq(&bytes[2..]).unwrap();
200        let data_start = 2 + len_bytes;
201        let data = &bytes[data_start..data_start + len as usize];
202        let parsed = parse_meta(meta_type, data).unwrap();
203        assert_eq!(&parsed, event);
204    }
205
206    #[test]
207    fn tempo_120bpm_bytes() {
208        // 120 BPM = 500000 µs/quarter = 0x07A120.
209        let mut out = Vec::new();
210        serialize_meta(&MetaEvent::Tempo(500_000), &mut out).unwrap();
211        assert_eq!(out, vec![0xFF, 0x51, 0x03, 0x07, 0xA1, 0x20]);
212        assert_eq!(
213            parse_meta(0x51, &[0x07, 0xA1, 0x20]).unwrap(),
214            MetaEvent::Tempo(500_000)
215        );
216    }
217
218    #[test]
219    fn end_of_track_bytes() {
220        let mut out = Vec::new();
221        serialize_meta(&MetaEvent::EndOfTrack, &mut out).unwrap();
222        assert_eq!(out, vec![0xFF, 0x2F, 0x00]);
223    }
224
225    #[test]
226    fn time_signature_4_4() {
227        // 4/4, 24 clocks/click, 8 32nds/quarter.
228        let ev = MetaEvent::TimeSignature {
229            numerator: 4,
230            denominator_pow2: 2,
231            clocks_per_click: 24,
232            thirty_seconds_per_quarter: 8,
233        };
234        let mut out = Vec::new();
235        serialize_meta(&ev, &mut out).unwrap();
236        assert_eq!(out, vec![0xFF, 0x58, 0x04, 0x04, 0x02, 0x18, 0x08]);
237        round_trip(&ev);
238    }
239
240    #[test]
241    fn key_signature_a_major_and_f_minor() {
242        // A major = 3 sharps, major.
243        let a_major = MetaEvent::KeySignature {
244            sharps: 3,
245            minor: false,
246        };
247        let mut out = Vec::new();
248        serialize_meta(&a_major, &mut out).unwrap();
249        assert_eq!(out, vec![0xFF, 0x59, 0x02, 0x03, 0x00]);
250        // F minor = 4 flats, minor.
251        let f_minor = MetaEvent::KeySignature {
252            sharps: -4,
253            minor: true,
254        };
255        let mut out2 = Vec::new();
256        serialize_meta(&f_minor, &mut out2).unwrap();
257        assert_eq!(out2, vec![0xFF, 0x59, 0x02, 0xFC, 0x01]);
258        assert_eq!(
259            parse_meta(0x59, &[0xFC, 0x01]).unwrap(),
260            MetaEvent::KeySignature {
261                sharps: -4,
262                minor: true
263            }
264        );
265    }
266
267    #[test]
268    fn track_name_round_trip() {
269        round_trip(&MetaEvent::TrackName(b"Lead".to_vec()));
270    }
271
272    #[test]
273    fn unknown_meta_preserved() {
274        // 0x01 (text) is not structurally decoded → Unknown, byte-exact.
275        let ev = MetaEvent::Unknown {
276            meta_type: 0x01,
277            data: b"hi".to_vec(),
278        };
279        let mut out = Vec::new();
280        serialize_meta(&ev, &mut out).unwrap();
281        assert_eq!(out, vec![0xFF, 0x01, 0x02, b'h', b'i']);
282        round_trip(&ev);
283    }
284
285    #[test]
286    fn bad_lengths_rejected() {
287        assert_eq!(
288            parse_meta(META_TEMPO, &[0x00, 0x00]),
289            Err(AudioError::MalformedAudio)
290        );
291        assert_eq!(
292            parse_meta(META_END_OF_TRACK, &[0x00]),
293            Err(AudioError::MalformedAudio)
294        );
295        assert_eq!(
296            parse_meta(META_KEY_SIGNATURE, &[0x00]),
297            Err(AudioError::MalformedAudio)
298        );
299        assert_eq!(
300            parse_meta(META_TIME_SIGNATURE, &[0x04, 0x02]),
301            Err(AudioError::MalformedAudio)
302        );
303    }
304}