Skip to main content

qualia_audio/midi/smf/
write.rs

1//! Standard MIDI File serializer: [`SmfFile`] → bytes.
2//!
3//! The inverse of [`super::read::read_smf`]. Channel messages are always written
4//! with an explicit status byte (no running-status compression), so output is
5//! deterministic; a file parsed from explicit-status bytes therefore round-trips
6//! byte-for-byte. Cold path.
7//!
8//! Lane AU-MIDI-FILE.
9
10use super::meta_event::serialize_meta;
11use super::read::{SmfFile, Track, TrackEvent};
12use super::vlq::write_vlq;
13use crate::types::AudioError;
14
15/// Serialize an [`SmfFile`] to a fresh byte buffer.
16///
17/// Errors with [`AudioError::InvalidParameter`] if a channel message carries the
18/// wrong number of data bytes, if `format` is not 0/1/2, or if a chunk/VLQ field
19/// overflows its encodable range.
20pub fn write_smf(file: &SmfFile) -> Result<Vec<u8>, AudioError> {
21    if file.format > 2 {
22        return Err(AudioError::InvalidParameter);
23    }
24    let ntracks = u16::try_from(file.tracks.len()).map_err(|_| AudioError::InvalidParameter)?;
25
26    let mut out = Vec::new();
27    // --- Header chunk ---
28    out.extend_from_slice(b"MThd");
29    out.extend_from_slice(&6u32.to_be_bytes());
30    out.extend_from_slice(&file.format.to_be_bytes());
31    out.extend_from_slice(&ntracks.to_be_bytes());
32    out.extend_from_slice(&file.division.to_raw().to_be_bytes());
33
34    // --- Track chunks ---
35    for track in &file.tracks {
36        write_track(track, &mut out)?;
37    }
38    Ok(out)
39}
40
41/// Serialize one track as a full `MTrk` chunk (id + length + body) into `out`.
42fn write_track(track: &Track, out: &mut Vec<u8>) -> Result<(), AudioError> {
43    // Encode the body first so we know its length.
44    let mut body = Vec::new();
45    for ev in &track.events {
46        write_vlq(ev.delta_ticks, &mut body)?;
47        write_event(&ev.event, &mut body)?;
48    }
49
50    let body_len = u32::try_from(body.len()).map_err(|_| AudioError::InvalidParameter)?;
51    out.extend_from_slice(b"MTrk");
52    out.extend_from_slice(&body_len.to_be_bytes());
53    out.extend_from_slice(&body);
54    Ok(())
55}
56
57/// Serialize a single event's bytes (without its preceding delta) into `out`.
58fn write_event(event: &TrackEvent, out: &mut Vec<u8>) -> Result<(), AudioError> {
59    match event {
60        TrackEvent::Midi { status, data } => {
61            let expected =
62                super::read::channel_data_len(*status).ok_or(AudioError::InvalidParameter)?;
63            if data.len() != expected {
64                return Err(AudioError::InvalidParameter);
65            }
66            out.push(*status);
67            out.extend_from_slice(data);
68        }
69        TrackEvent::Meta(meta) => {
70            serialize_meta(meta, out)?;
71        }
72        TrackEvent::SysEx { start, data } => {
73            out.push(*start);
74            let len = u32::try_from(data.len()).map_err(|_| AudioError::InvalidParameter)?;
75            write_vlq(len, out)?;
76            out.extend_from_slice(data);
77        }
78    }
79    Ok(())
80}
81
82#[cfg(test)]
83mod tests {
84    use super::super::meta_event::MetaEvent;
85    use super::super::read::{read_smf, Division, Event, SmfFile, Track, TrackEvent};
86    use super::*;
87
88    /// Build a minimal format-0 SMF: one track with tempo, note-on, delayed
89    /// note-off, and end-of-track.
90    fn minimal_smf() -> SmfFile {
91        let events = vec![
92            Event {
93                delta_ticks: 0,
94                event: TrackEvent::Meta(MetaEvent::Tempo(500_000)),
95            },
96            Event {
97                delta_ticks: 0,
98                event: TrackEvent::Midi {
99                    status: 0x90,
100                    data: vec![60, 100],
101                },
102            },
103            Event {
104                delta_ticks: 480,
105                event: TrackEvent::Midi {
106                    status: 0x80,
107                    data: vec![60, 0],
108                },
109            },
110            Event {
111                delta_ticks: 0,
112                event: TrackEvent::Meta(MetaEvent::EndOfTrack),
113            },
114        ];
115        SmfFile {
116            format: 0,
117            division: Division::Ppq(480),
118            tracks: vec![Track { events }],
119        }
120    }
121
122    #[test]
123    fn round_trip_structure_and_bytes() {
124        let original = minimal_smf();
125        let bytes = write_smf(&original).unwrap();
126
127        // Parse back and compare structure.
128        let parsed = read_smf(&bytes).unwrap();
129        assert_eq!(parsed, original);
130        assert_eq!(parsed.division, Division::Ppq(480));
131        assert_eq!(parsed.tracks[0].events[2].delta_ticks, 480);
132
133        // bytes → read → write → bytes is identical.
134        let bytes2 = write_smf(&parsed).unwrap();
135        assert_eq!(bytes, bytes2);
136    }
137
138    #[test]
139    fn exact_header_bytes() {
140        let bytes = write_smf(&minimal_smf()).unwrap();
141        // MThd, len 6, format 0, ntracks 1, division 480 (0x01E0).
142        assert_eq!(
143            &bytes[0..14],
144            &[b'M', b'T', b'h', b'd', 0, 0, 0, 6, 0, 0, 0, 1, 0x01, 0xE0]
145        );
146    }
147
148    #[test]
149    fn rejects_wrong_data_byte_count() {
150        let bad = SmfFile {
151            format: 0,
152            division: Division::Ppq(480),
153            tracks: vec![Track {
154                events: vec![Event {
155                    delta_ticks: 0,
156                    // Note-on needs 2 data bytes; give 1.
157                    event: TrackEvent::Midi {
158                        status: 0x90,
159                        data: vec![60],
160                    },
161                }],
162            }],
163        };
164        assert_eq!(write_smf(&bad), Err(AudioError::InvalidParameter));
165    }
166}