Skip to main content

qualia_audio/midi/instrument/
dls.rs

1//! Downloadable Sounds (`.dls`) header/instrument enumeration — RIFF `DLS ` walk down to each
2//! instrument's `insh` locale and `INFO/INAM` name. Clean-room from the public DLS-1/2 spec.
3//!
4//! Qualia ships NO content. This reads a USER-supplied `.dls` far enough to enumerate its
5//! instruments (name, bank, program). It does NOT decode the `wvpl` wave-pool audio.
6//!
7//! RIFF layout walked:
8//! ```text
9//! RIFF <size> 'DLS '
10//!   'colh' <size> cInstruments:u32       (advisory count)
11//!   LIST <size> 'lins'
12//!     LIST <size> 'ins '
13//!       'insh' <size> cRegions:u32, ulBank:u32, ulInstrument:u32
14//!       LIST <size> 'INFO'  'INAM' <size> <name>
15//!     ...
16//! ```
17//! `ulBank` packs bank MSB (bits 8..14) and LSB (bits 0..6) plus a drum flag (bit 31);
18//! `ulInstrument` is the program number. Parsing is a COLD path (`Vec`/`String` allowed).
19
20use crate::types::AudioError;
21
22/// Cap on instruments returned (bounded, DoS-safe).
23pub const MAX_INSTRUMENTS: usize = 4096;
24
25/// One DLS instrument descriptor (no wave audio).
26#[derive(Debug, Clone, PartialEq, Eq)]
27pub struct DlsInstrument {
28    /// Instrument name (`INFO/INAM`), or empty if absent.
29    pub name: String,
30    /// Combined 14-bit MIDI bank (MSB<<7 | LSB) from `ulBank`.
31    pub bank: u16,
32    /// MIDI program from `ulInstrument`.
33    pub program: u8,
34    /// True when the drum bit (0x8000_0000) is set in `ulBank`.
35    pub is_drum: bool,
36}
37
38/// Enumerated instruments of a DLS collection.
39#[derive(Debug, Clone, Default, PartialEq, Eq)]
40pub struct DlsCollection {
41    /// Instruments in file order.
42    pub instruments: Vec<DlsInstrument>,
43}
44
45impl DlsCollection {
46    /// Number of instruments.
47    #[inline]
48    pub fn len(&self) -> usize {
49        self.instruments.len()
50    }
51    /// True when there are no instruments.
52    #[inline]
53    pub fn is_empty(&self) -> bool {
54        self.instruments.is_empty()
55    }
56}
57
58#[inline]
59fn read_u32_le(b: &[u8], off: usize) -> Result<u32, AudioError> {
60    b.get(off..off + 4)
61        .map(|s| u32::from_le_bytes([s[0], s[1], s[2], s[3]]))
62        .ok_or(AudioError::MalformedAudio)
63}
64
65#[inline]
66fn tag(b: &[u8], off: usize) -> Result<&[u8], AudioError> {
67    b.get(off..off + 4).ok_or(AudioError::MalformedAudio)
68}
69
70/// Enumerate the instruments of a `.dls` byte buffer.
71///
72/// Errors: [`AudioError::UnsupportedFormat`] if not a RIFF `DLS ` collection;
73/// [`AudioError::MalformedAudio`] if a chunk header is truncated.
74pub fn read_dls_instruments(bytes: &[u8]) -> Result<DlsCollection, AudioError> {
75    if tag(bytes, 0)? != b"RIFF" {
76        return Err(AudioError::UnsupportedFormat);
77    }
78    let riff_size = read_u32_le(bytes, 4)? as usize;
79    if tag(bytes, 8)? != b"DLS " {
80        return Err(AudioError::UnsupportedFormat);
81    }
82    let body_end = (8 + riff_size).min(bytes.len());
83
84    // Find LIST 'lins'.
85    let mut pos = 12usize;
86    while pos + 8 <= body_end {
87        let ck_id = tag(bytes, pos)?;
88        let ck_size = read_u32_le(bytes, pos + 4)? as usize;
89        let data_start = pos + 8;
90        let data_end = (data_start + ck_size).min(bytes.len());
91        if ck_id == b"LIST" && data_start + 4 <= data_end && tag(bytes, data_start)? == b"lins" {
92            return parse_lins(bytes, data_start + 4, data_end);
93        }
94        pos = data_start + ck_size + (ck_size & 1);
95    }
96    Ok(DlsCollection::default())
97}
98
99/// Walk the `lins` list of `ins ` instrument LISTs.
100fn parse_lins(bytes: &[u8], start: usize, end: usize) -> Result<DlsCollection, AudioError> {
101    let mut instruments = Vec::new();
102    let mut pos = start;
103    while pos + 8 <= end {
104        let ck_id = tag(bytes, pos)?;
105        let ck_size = read_u32_le(bytes, pos + 4)? as usize;
106        let data_start = pos + 8;
107        let data_end = (data_start + ck_size).min(bytes.len());
108        if ck_id == b"LIST" && data_start + 4 <= data_end && tag(bytes, data_start)? == b"ins " {
109            if instruments.len() < MAX_INSTRUMENTS {
110                if let Some(instr) = parse_ins(bytes, data_start + 4, data_end)? {
111                    instruments.push(instr);
112                }
113            }
114        }
115        pos = data_start + ck_size + (ck_size & 1);
116    }
117    Ok(DlsCollection { instruments })
118}
119
120/// Parse one `ins ` LIST: `insh` locale + optional `INFO/INAM` name.
121fn parse_ins(bytes: &[u8], start: usize, end: usize) -> Result<Option<DlsInstrument>, AudioError> {
122    let mut bank_raw = 0u32;
123    let mut program = 0u8;
124    let mut is_drum = false;
125    let mut name = String::new();
126    let mut found_insh = false;
127
128    let mut pos = start;
129    while pos + 8 <= end {
130        let ck_id = tag(bytes, pos)?;
131        let ck_size = read_u32_le(bytes, pos + 4)? as usize;
132        let data_start = pos + 8;
133        let data_end = (data_start + ck_size).min(bytes.len());
134        if ck_id == b"insh" {
135            // insh: cRegions u32, ulBank u32, ulInstrument u32.
136            let ul_bank = read_u32_le(bytes, data_start + 4)?;
137            let ul_instr = read_u32_le(bytes, data_start + 8)?;
138            bank_raw = ul_bank;
139            is_drum = (ul_bank & 0x8000_0000) != 0;
140            program = (ul_instr & 0x7F) as u8;
141            found_insh = true;
142        } else if ck_id == b"LIST"
143            && data_start + 4 <= data_end
144            && tag(bytes, data_start)? == b"INFO"
145        {
146            name = parse_info_name(bytes, data_start + 4, data_end);
147        }
148        pos = data_start + ck_size + (ck_size & 1);
149    }
150
151    if !found_insh {
152        return Ok(None);
153    }
154    let bank_msb = (bank_raw >> 8) & 0x7F;
155    let bank_lsb = bank_raw & 0x7F;
156    Ok(Some(DlsInstrument {
157        name,
158        bank: ((bank_msb << 7) | bank_lsb) as u16,
159        program,
160        is_drum,
161    }))
162}
163
164/// Extract the `INAM` name from an INFO list body.
165fn parse_info_name(bytes: &[u8], start: usize, end: usize) -> String {
166    let mut pos = start;
167    while pos + 8 <= end {
168        let Ok(ck_id) = tag(bytes, pos) else {
169            break;
170        };
171        let Ok(ck_size) = read_u32_le(bytes, pos + 4) else {
172            break;
173        };
174        let ck_size = ck_size as usize;
175        let data_start = pos + 8;
176        let data_end = (data_start + ck_size).min(bytes.len());
177        if ck_id == b"INAM" {
178            if let Some(raw) = bytes.get(data_start..data_end) {
179                let stop = raw.iter().position(|&c| c == 0).unwrap_or(raw.len());
180                return String::from_utf8_lossy(&raw[..stop]).trim().to_string();
181            }
182        }
183        pos = data_start + ck_size + (ck_size & 1);
184    }
185    String::new()
186}
187
188#[cfg(test)]
189mod tests {
190    use super::*;
191
192    fn chunk(id: &[u8; 4], body: &[u8]) -> Vec<u8> {
193        let mut v = Vec::new();
194        v.extend_from_slice(id);
195        v.extend_from_slice(&(body.len() as u32).to_le_bytes());
196        v.extend_from_slice(body);
197        if body.len() & 1 == 1 {
198            v.push(0); // word-align pad
199        }
200        v
201    }
202
203    fn list(form: &[u8; 4], body: &[u8]) -> Vec<u8> {
204        let mut inner = Vec::new();
205        inner.extend_from_slice(form);
206        inner.extend_from_slice(body);
207        chunk(b"LIST", &inner)
208    }
209
210    fn build_tiny_dls(name: &str, bank: u16, program: u8) -> Vec<u8> {
211        // insh: cRegions, ulBank, ulInstrument.
212        let bank_msb = (bank >> 7) & 0x7F;
213        let bank_lsb = bank & 0x7F;
214        let ul_bank = ((bank_msb as u32) << 8) | (bank_lsb as u32);
215        let mut insh_body = Vec::new();
216        insh_body.extend_from_slice(&1u32.to_le_bytes()); // cRegions
217        insh_body.extend_from_slice(&ul_bank.to_le_bytes());
218        insh_body.extend_from_slice(&(program as u32).to_le_bytes());
219        let insh = chunk(b"insh", &insh_body);
220
221        // INFO / INAM.
222        let mut inam_body = name.as_bytes().to_vec();
223        inam_body.push(0);
224        let inam = chunk(b"INAM", &inam_body);
225        let info = list(b"INFO", &inam);
226
227        // ins ' LIST { insh, INFO }.
228        let mut ins_body = Vec::new();
229        ins_body.extend_from_slice(&insh);
230        ins_body.extend_from_slice(&info);
231        let ins = list(b"ins ", &ins_body);
232
233        // lins LIST { ins }.
234        let lins = list(b"lins", &ins);
235
236        // colh advisory.
237        let colh = chunk(b"colh", &1u32.to_le_bytes());
238
239        // RIFF 'DLS '.
240        let mut body = Vec::new();
241        body.extend_from_slice(b"DLS ");
242        body.extend_from_slice(&colh);
243        body.extend_from_slice(&lins);
244        chunk(b"RIFF", &body)
245    }
246
247    #[test]
248    fn enumerates_instrument() {
249        let dls = build_tiny_dls("Warm Pad", 0, 89);
250        let coll = read_dls_instruments(&dls).expect("parse");
251        assert_eq!(coll.len(), 1);
252        assert_eq!(coll.instruments[0].name, "Warm Pad");
253        assert_eq!(coll.instruments[0].program, 89);
254        assert_eq!(coll.instruments[0].bank, 0);
255        assert!(!coll.instruments[0].is_drum);
256    }
257
258    #[test]
259    fn rejects_non_dls() {
260        assert_eq!(
261            read_dls_instruments(b"RIFF\x00\x00\x00\x00WAVE"),
262            Err(AudioError::UnsupportedFormat)
263        );
264    }
265}