Skip to main content

qualia_audio/midi/tuning/
scala_kbm.rs

1//! Scala keyboard mapping (`.kbm`) parsing — clean-room from the open Scala format spec.
2//!
3//! A `.kbm` maps MIDI key numbers onto scale degrees and anchors the whole tuning to a
4//! reference key/frequency. Grammar (comment lines begin with `!`; each field is the first
5//! token of its own non-comment line):
6//!
7//! ```text
8//! <map size>        number of keyboard-map entries; the pattern repeats every this many keys
9//! <first MIDI>      first MIDI note to retune (0..127)
10//! <last MIDI>       last MIDI note to retune (0..127)
11//! <middle note>     the key that scale degree 0 (1/1) is mapped to
12//! <reference note>  the key whose frequency is given below
13//! <reference freq>  frequency (Hz) to tune the reference note to
14//! <octave degree>   scale degree treated as the formal octave (usually the scale size)
15//! <map 0>           `mapsize` lines follow, each a scale degree or `x` (key not mapped)
16//! ...
17//! ```
18//!
19//! Cold path; the produced [`KbmMapping`] is fixed-size and `Copy` so it can feed the
20//! allocation-free tuning-table build.
21
22use crate::types::AudioError;
23
24/// Upper bound on keyboard-map entries (a map cannot usefully exceed the 128 MIDI keys).
25pub const MAX_KBM_ENTRIES: usize = 128;
26
27/// Sentinel in [`KbmMapping::mapping`] for a key that is not mapped to any scale degree (`x`).
28pub const KBM_UNMAPPED: i16 = -1;
29
30/// A parsed Scala keyboard mapping. Fixed-size, `Copy`, heap-free.
31#[derive(Debug, Clone, Copy)]
32pub struct KbmMapping {
33    /// Number of valid entries in `mapping` (the map repeats every `map_size` keys).
34    pub map_size: usize,
35    /// First MIDI key to retune.
36    pub first_midi: u8,
37    /// Last MIDI key to retune.
38    pub last_midi: u8,
39    /// The MIDI key that carries scale degree 0 (`1/1`).
40    pub middle_note: u8,
41    /// The MIDI key whose absolute frequency is pinned by `reference_freq`.
42    pub reference_note: u8,
43    /// Absolute frequency (Hz) assigned to `reference_note`.
44    pub reference_freq: f64,
45    /// Scale degree that constitutes the formal octave/period (typically the scale size).
46    pub octave_degree: usize,
47    /// Per-key scale degree, or [`KBM_UNMAPPED`]. Only `[0, map_size)` is meaningful.
48    pub mapping: [i16; MAX_KBM_ENTRIES],
49}
50
51impl KbmMapping {
52    /// A linear (identity) mapping: `map_size` keys map to scale degrees `0,1,…,map_size-1`,
53    /// with `octave_degree == map_size`. This is the implicit default when no `.kbm` accompanies
54    /// a scale. The reference key/frequency and middle key are explicit parameters — nothing is
55    /// hardcoded; A4=440 is only the caller's choice, not a baked assumption.
56    pub fn linear(
57        map_size: usize,
58        middle_note: u8,
59        reference_note: u8,
60        reference_freq: f64,
61    ) -> KbmMapping {
62        let n = map_size.min(MAX_KBM_ENTRIES).max(1);
63        let mut mapping = [KBM_UNMAPPED; MAX_KBM_ENTRIES];
64        for (i, m) in mapping.iter_mut().enumerate().take(n) {
65            *m = i as i16;
66        }
67        KbmMapping {
68            map_size: n,
69            first_midi: 0,
70            last_midi: 127,
71            middle_note,
72            reference_note,
73            reference_freq,
74            octave_degree: n,
75            mapping,
76        }
77    }
78
79    /// The canonical 12-key linear map anchored at A4 (`reference_note = 69 → reference_freq Hz`)
80    /// with `middle_note = 60`. Pass the reference frequency explicitly (e.g. 440.0 or 432.0).
81    pub fn linear_12(reference_freq: f64) -> KbmMapping {
82        KbmMapping::linear(12, 60, 69, reference_freq)
83    }
84
85    /// Scale degree a MIDI key maps to under this keyboard map, or `None` if the key is
86    /// unmapped or outside `[first_midi, last_midi]`. Returns the ABSOLUTE scale degree,
87    /// i.e. `octave * octave_degree + degree_within_period` (may be negative for low keys).
88    #[inline]
89    pub fn absolute_degree(&self, note: u8) -> Option<i32> {
90        if note < self.first_midi || note > self.last_midi {
91            return None;
92        }
93        if self.map_size == 0 {
94            return None;
95        }
96        let p = note as i32 - self.middle_note as i32;
97        let size = self.map_size as i32;
98        // Proper floor division / modulo (Rust `/`,`%` truncate toward zero).
99        let mut octave = p / size;
100        let mut index = p % size;
101        if index < 0 {
102            index += size;
103            octave -= 1;
104        }
105        let degree = self.mapping[index as usize];
106        if degree == KBM_UNMAPPED {
107            return None;
108        }
109        Some(octave * self.octave_degree as i32 + degree as i32)
110    }
111}
112
113/// Parse Scala `.kbm` text into a fixed-size [`KbmMapping`].
114///
115/// # Errors
116/// [`AudioError::InvalidParameter`] if a required field line is missing/unparseable, the map size
117/// exceeds [`MAX_KBM_ENTRIES`], a MIDI field is out of `0..=127`, or fewer map entries are present
118/// than declared.
119pub fn parse_kbm(text: &str) -> Result<KbmMapping, AudioError> {
120    let mut data = text.lines().filter(|l| {
121        let t = l.trim_start();
122        !t.starts_with('!')
123    });
124
125    let map_size = next_usize(&mut data)?;
126    if map_size == 0 || map_size > MAX_KBM_ENTRIES {
127        return Err(AudioError::InvalidParameter);
128    }
129    let first_midi = next_u8(&mut data)?;
130    let last_midi = next_u8(&mut data)?;
131    let middle_note = next_u8(&mut data)?;
132    let reference_note = next_u8(&mut data)?;
133    let reference_freq = next_f64(&mut data)?;
134    let octave_degree = next_usize(&mut data)?;
135    if octave_degree == 0 || octave_degree > MAX_KBM_ENTRIES || last_midi < first_midi {
136        return Err(AudioError::InvalidParameter);
137    }
138    if !(reference_freq.is_finite() && reference_freq > 0.0) {
139        return Err(AudioError::InvalidParameter);
140    }
141
142    let mut mapping = [KBM_UNMAPPED; MAX_KBM_ENTRIES];
143    for slot in mapping.iter_mut().take(map_size) {
144        let line = data.next().ok_or(AudioError::InvalidParameter)?;
145        let tok = line
146            .split_whitespace()
147            .next()
148            .ok_or(AudioError::InvalidParameter)?;
149        // `x` (any case) marks an unmapped key; otherwise a scale-degree index.
150        if tok.eq_ignore_ascii_case("x") {
151            *slot = KBM_UNMAPPED;
152        } else {
153            let d: i16 = tok.parse().map_err(|_| AudioError::InvalidParameter)?;
154            if d < 0 {
155                return Err(AudioError::InvalidParameter);
156            }
157            *slot = d;
158        }
159    }
160
161    Ok(KbmMapping {
162        map_size,
163        first_midi,
164        last_midi,
165        middle_note,
166        reference_note,
167        reference_freq,
168        octave_degree,
169        mapping,
170    })
171}
172
173fn next_token<'a>(data: &mut impl Iterator<Item = &'a str>) -> Result<&'a str, AudioError> {
174    let line = data.next().ok_or(AudioError::InvalidParameter)?;
175    line.split_whitespace()
176        .next()
177        .ok_or(AudioError::InvalidParameter)
178}
179
180fn next_usize<'a>(data: &mut impl Iterator<Item = &'a str>) -> Result<usize, AudioError> {
181    next_token(data)?
182        .parse()
183        .map_err(|_| AudioError::InvalidParameter)
184}
185
186fn next_u8<'a>(data: &mut impl Iterator<Item = &'a str>) -> Result<u8, AudioError> {
187    let v: i32 = next_token(data)?
188        .parse()
189        .map_err(|_| AudioError::InvalidParameter)?;
190    if (0..=127).contains(&v) {
191        Ok(v as u8)
192    } else {
193        Err(AudioError::InvalidParameter)
194    }
195}
196
197fn next_f64<'a>(data: &mut impl Iterator<Item = &'a str>) -> Result<f64, AudioError> {
198    next_token(data)?
199        .parse()
200        .map_err(|_| AudioError::InvalidParameter)
201}
202
203#[cfg(test)]
204mod tests {
205    use super::*;
206
207    #[test]
208    fn tuning_kbm_linear_12_defaults() {
209        let k = KbmMapping::linear_12(440.0);
210        assert_eq!(k.map_size, 12);
211        assert_eq!(k.middle_note, 60);
212        assert_eq!(k.reference_note, 69);
213        assert_eq!(k.octave_degree, 12);
214        assert!((k.reference_freq - 440.0).abs() < 1e-12);
215        // Linear identity mapping.
216        assert_eq!(k.absolute_degree(60), Some(0));
217        assert_eq!(k.absolute_degree(69), Some(9));
218        assert_eq!(k.absolute_degree(72), Some(12)); // one octave up
219        assert_eq!(k.absolute_degree(48), Some(-12)); // one octave down (floor div)
220    }
221
222    #[test]
223    fn tuning_parse_kbm_full_map() {
224        let text = "\
225! example.kbm
226! size
227 12
228! first
229 0
230! last
231 127
232! middle
233 60
234! reference note
235 69
236! reference freq
237 440.0
238! octave degree
239 12
240! mapping
241 0
242 1
243 2
244 3
245 4
246 5
247 6
248 7
249 8
250 9
251 10
252 11
253";
254        let k = parse_kbm(text).expect("parse .kbm");
255        assert_eq!(k.map_size, 12);
256        assert_eq!(k.first_midi, 0);
257        assert_eq!(k.last_midi, 127);
258        assert_eq!(k.middle_note, 60);
259        assert_eq!(k.reference_note, 69);
260        assert!((k.reference_freq - 440.0).abs() < 1e-12);
261        assert_eq!(k.octave_degree, 12);
262        assert_eq!(k.absolute_degree(69), Some(9));
263    }
264
265    #[test]
266    fn tuning_parse_kbm_unmapped_key() {
267        let text = "\
2682
2690
270127
27160
27269
273440.0
2742
2750
276x
277";
278        let k = parse_kbm(text).expect("parse .kbm with unmapped");
279        assert_eq!(k.mapping[0], 0);
280        assert_eq!(k.mapping[1], KBM_UNMAPPED);
281        // Key that lands on the unmapped slot yields no degree.
282        assert_eq!(k.absolute_degree(61), None);
283        assert_eq!(k.absolute_degree(60), Some(0));
284    }
285
286    #[test]
287    fn tuning_parse_kbm_rejects_bad_fields() {
288        assert!(parse_kbm("0\n0\n127\n60\n69\n440\n12\n").is_err()); // zero size
289        assert!(parse_kbm("1\n0\n200\n60\n69\n440\n1\n0\n").is_err()); // midi > 127
290        assert!(parse_kbm("2\n0\n127\n60\n69\n440\n2\n0\n").is_err()); // short mapping
291    }
292}