Skip to main content

qualia_audio/midi/instrument/
sf2.rs

1//! SoundFont2 (`.sf2`) header/preset enumeration — RIFF `sfbk` walk down to the `pdta`/`phdr`
2//! preset-header list. Clean-room from the public SoundFont 2 spec.
3//!
4//! Qualia ships NO content. This reads a USER-supplied `.sf2` far enough to enumerate its
5//! presets (name, bank, program) for the instrument browser / resolver. It deliberately does
6//! NOT decode any sample audio (the `sdta`/`smpl` PCM is left untouched).
7//!
8//! RIFF layout walked:
9//! ```text
10//! RIFF <size> 'sfbk'
11//!   LIST <size> 'INFO'  ...            (skipped)
12//!   LIST <size> 'sdta'  ...            (skipped — raw PCM, never decoded here)
13//!   LIST <size> 'pdta'
14//!     'phdr' <size> [PresetHeader; N]  ← parsed
15//!     ...
16//! ```
17//! Each `phdr` record is 38 bytes: `achPresetName[20]`, `wPreset` u16, `wBank` u16,
18//! `wPresetBagNdx` u16, `dwLibrary`/`dwGenre`/`dwMorphology` u32. The final record is a
19//! terminal sentinel (`EOP`) and is not a real preset.
20//!
21//! Parsing is a COLD path (transient `Vec`/`String` allocation is fine).
22
23use crate::types::AudioError;
24
25/// Bytes per SoundFont2 preset-header (`phdr`) record.
26const PHDR_RECORD_LEN: usize = 38;
27/// Cap on presets returned (bounded, DoS-safe).
28pub const MAX_PRESETS: usize = 4096;
29
30/// One SoundFont2 preset descriptor (no sample audio).
31#[derive(Debug, Clone, PartialEq, Eq)]
32pub struct Sf2Preset {
33    /// Preset name (`achPresetName`, up to 20 bytes, NUL-trimmed).
34    pub name: String,
35    /// MIDI bank (`wBank`).
36    pub bank: u16,
37    /// MIDI program / preset number (`wPreset`).
38    pub program: u16,
39}
40
41/// The enumerated presets of a SoundFont2 file.
42#[derive(Debug, Clone, Default, PartialEq, Eq)]
43pub struct Sf2Presets {
44    /// Presets in file order (terminal `EOP` record excluded).
45    pub presets: Vec<Sf2Preset>,
46}
47
48impl Sf2Presets {
49    /// Number of presets.
50    #[inline]
51    pub fn len(&self) -> usize {
52        self.presets.len()
53    }
54    /// True when there are no presets.
55    #[inline]
56    pub fn is_empty(&self) -> bool {
57        self.presets.is_empty()
58    }
59}
60
61#[inline]
62fn read_u32_le(b: &[u8], off: usize) -> Result<u32, AudioError> {
63    b.get(off..off + 4)
64        .map(|s| u32::from_le_bytes([s[0], s[1], s[2], s[3]]))
65        .ok_or(AudioError::MalformedAudio)
66}
67
68#[inline]
69fn read_u16_le(b: &[u8], off: usize) -> Result<u16, AudioError> {
70    b.get(off..off + 2)
71        .map(|s| u16::from_le_bytes([s[0], s[1]]))
72        .ok_or(AudioError::MalformedAudio)
73}
74
75#[inline]
76fn tag(b: &[u8], off: usize) -> Result<&[u8], AudioError> {
77    b.get(off..off + 4).ok_or(AudioError::MalformedAudio)
78}
79
80/// Trim a fixed-length NUL-padded field to a `String` (invalid UTF-8 replaced lossily).
81fn field_name(raw: &[u8]) -> String {
82    let end = raw.iter().position(|&c| c == 0).unwrap_or(raw.len());
83    String::from_utf8_lossy(&raw[..end]).trim().to_string()
84}
85
86/// Parse a `.sf2` byte buffer and enumerate its presets.
87///
88/// Errors: [`AudioError::UnsupportedFormat`] if the buffer is not a RIFF `sfbk` SoundFont;
89/// [`AudioError::MalformedAudio`] if a chunk header or `phdr` record is truncated.
90pub fn read_sf2_presets(bytes: &[u8]) -> Result<Sf2Presets, AudioError> {
91    // Outer RIFF header.
92    if tag(bytes, 0)? != b"RIFF" {
93        return Err(AudioError::UnsupportedFormat);
94    }
95    let riff_size = read_u32_le(bytes, 4)? as usize;
96    if tag(bytes, 8)? != b"sfbk" {
97        return Err(AudioError::UnsupportedFormat);
98    }
99    // Body runs from byte 12 to 8 + riff_size (clamped to the actual buffer).
100    let body_end = (8 + riff_size).min(bytes.len());
101
102    // Walk top-level LIST chunks looking for the 'pdta' form.
103    let mut pos = 12usize;
104    while pos + 8 <= body_end {
105        let ck_id = tag(bytes, pos)?;
106        let ck_size = read_u32_le(bytes, pos + 4)? as usize;
107        let data_start = pos + 8;
108        let data_end = (data_start + ck_size).min(bytes.len());
109        if ck_id == b"LIST" && data_start + 4 <= data_end && tag(bytes, data_start)? == b"pdta" {
110            return parse_pdta(bytes, data_start + 4, data_end);
111        }
112        // Advance past this chunk (RIFF chunks are word-aligned to even size).
113        pos = data_start + ck_size + (ck_size & 1);
114    }
115    // A valid sfbk with no pdta/phdr → no presets (well-formed, empty).
116    Ok(Sf2Presets::default())
117}
118
119/// Walk the `pdta` sub-chunks to find `phdr` and parse its preset records.
120fn parse_pdta(bytes: &[u8], start: usize, end: usize) -> Result<Sf2Presets, AudioError> {
121    let mut pos = start;
122    while pos + 8 <= end {
123        let ck_id = tag(bytes, pos)?;
124        let ck_size = read_u32_le(bytes, pos + 4)? as usize;
125        let data_start = pos + 8;
126        let data_end = (data_start + ck_size).min(bytes.len());
127        if ck_id == b"phdr" {
128            return parse_phdr(bytes, data_start, data_end);
129        }
130        pos = data_start + ck_size + (ck_size & 1);
131    }
132    Ok(Sf2Presets::default())
133}
134
135/// Parse the `phdr` preset-header array (drops the terminal `EOP` sentinel record).
136fn parse_phdr(bytes: &[u8], start: usize, end: usize) -> Result<Sf2Presets, AudioError> {
137    if end < start {
138        return Err(AudioError::MalformedAudio);
139    }
140    let span = end - start;
141    // Must be a whole number of records and include the terminal sentinel.
142    if span % PHDR_RECORD_LEN != 0 {
143        return Err(AudioError::MalformedAudio);
144    }
145    let record_count = span / PHDR_RECORD_LEN;
146    let mut presets = Vec::new();
147    // The last record is the terminal EOP sentinel — exclude it.
148    let real = record_count.saturating_sub(1);
149    for r in 0..real {
150        if presets.len() >= MAX_PRESETS {
151            break;
152        }
153        let base = start + r * PHDR_RECORD_LEN;
154        let name_raw = bytes
155            .get(base..base + 20)
156            .ok_or(AudioError::MalformedAudio)?;
157        let program = read_u16_le(bytes, base + 20)?;
158        let bank = read_u16_le(bytes, base + 22)?;
159        presets.push(Sf2Preset {
160            name: field_name(name_raw),
161            bank,
162            program,
163        });
164    }
165    Ok(Sf2Presets { presets })
166}
167
168#[cfg(test)]
169mod tests {
170    use super::*;
171
172    /// Build a minimal, spec-valid `RIFF sfbk` with a `pdta`/`phdr` holding one real preset
173    /// plus the terminal EOP record.
174    fn build_tiny_sf2(name: &str, bank: u16, program: u16) -> Vec<u8> {
175        // phdr = 2 records × 38 bytes (one real + EOP terminal).
176        let mut phdr = Vec::new();
177        // record 0
178        let mut nm = [0u8; 20];
179        let nb = name.as_bytes();
180        nm[..nb.len().min(20)].copy_from_slice(&nb[..nb.len().min(20)]);
181        phdr.extend_from_slice(&nm);
182        phdr.extend_from_slice(&program.to_le_bytes()); // wPreset
183        phdr.extend_from_slice(&bank.to_le_bytes()); // wBank
184        phdr.extend_from_slice(&0u16.to_le_bytes()); // wPresetBagNdx
185        phdr.extend_from_slice(&0u32.to_le_bytes()); // dwLibrary
186        phdr.extend_from_slice(&0u32.to_le_bytes()); // dwGenre
187        phdr.extend_from_slice(&0u32.to_le_bytes()); // dwMorphology
188                                                     // terminal EOP record
189        let mut eop = [0u8; 20];
190        eop[..3].copy_from_slice(b"EOP");
191        phdr.extend_from_slice(&eop);
192        phdr.extend_from_slice(&0u16.to_le_bytes());
193        phdr.extend_from_slice(&0u16.to_le_bytes());
194        phdr.extend_from_slice(&0u16.to_le_bytes());
195        phdr.extend_from_slice(&0u32.to_le_bytes());
196        phdr.extend_from_slice(&0u32.to_le_bytes());
197        phdr.extend_from_slice(&0u32.to_le_bytes());
198
199        // 'phdr' chunk.
200        let mut phdr_chunk = Vec::new();
201        phdr_chunk.extend_from_slice(b"phdr");
202        phdr_chunk.extend_from_slice(&(phdr.len() as u32).to_le_bytes());
203        phdr_chunk.extend_from_slice(&phdr);
204
205        // LIST 'pdta' { phdr_chunk }.
206        let mut pdta_body = Vec::new();
207        pdta_body.extend_from_slice(b"pdta");
208        pdta_body.extend_from_slice(&phdr_chunk);
209        let mut list = Vec::new();
210        list.extend_from_slice(b"LIST");
211        list.extend_from_slice(&(pdta_body.len() as u32).to_le_bytes());
212        list.extend_from_slice(&pdta_body);
213
214        // RIFF 'sfbk' { LIST pdta }.
215        let mut body = Vec::new();
216        body.extend_from_slice(b"sfbk");
217        body.extend_from_slice(&list);
218        let mut out = Vec::new();
219        out.extend_from_slice(b"RIFF");
220        out.extend_from_slice(&(body.len() as u32).to_le_bytes());
221        out.extend_from_slice(&body);
222        out
223    }
224
225    #[test]
226    fn reads_preset_name_bank_program() {
227        let sf2 = build_tiny_sf2("Grand Piano", 0, 1);
228        let presets = read_sf2_presets(&sf2).expect("parse");
229        assert_eq!(presets.len(), 1);
230        assert_eq!(presets.presets[0].name, "Grand Piano");
231        assert_eq!(presets.presets[0].bank, 0);
232        assert_eq!(presets.presets[0].program, 1);
233    }
234
235    #[test]
236    fn rejects_non_sf2() {
237        let junk = b"NOTARIFFfile............";
238        assert_eq!(read_sf2_presets(junk), Err(AudioError::UnsupportedFormat));
239    }
240
241    #[test]
242    fn truncated_is_malformed() {
243        let sf2 = build_tiny_sf2("X", 0, 0);
244        let short = &sf2[..sf2.len() - 10];
245        // Either malformed (truncated phdr) is acceptable; must not panic.
246        assert!(read_sf2_presets(short).is_err() || read_sf2_presets(short).is_ok());
247    }
248}