qualia_audio/models/audio_tokens/
fsq.rs1use crate::types::AudioError;
14
15pub fn fsq_quantize(
30 input: &[f32],
31 levels: &[u16],
32 lo: f32,
33 hi: f32,
34 out_tokens: &mut [u16],
35) -> Result<usize, AudioError> {
36 let dim = levels.len();
37 if dim == 0 || hi <= lo || levels.contains(&0) {
38 return Err(AudioError::InvalidParameter);
39 }
40 if input.len() < dim || out_tokens.len() < dim {
41 return Err(AudioError::OutputBufferTooSmall);
42 }
43 for d in 0..dim {
44 let l = levels[d];
45 if l == 1 {
46 out_tokens[d] = 0;
47 continue;
48 }
49 let step = (hi - lo) / ((l - 1) as f32);
50 let raw = ((input[d] - lo) / step).round();
52 let idx = if raw < 0.0 {
53 0.0
54 } else if raw > (l - 1) as f32 {
55 (l - 1) as f32
56 } else {
57 raw
58 };
59 out_tokens[d] = idx as u16;
60 }
61 Ok(dim)
62}
63
64pub fn fsq_dequantize(
74 tokens: &[u16],
75 levels: &[u16],
76 lo: f32,
77 hi: f32,
78 out: &mut [f32],
79) -> Result<(), AudioError> {
80 let dim = levels.len();
81 if dim == 0 || hi <= lo || levels.contains(&0) {
82 return Err(AudioError::InvalidParameter);
83 }
84 if tokens.len() < dim || out.len() < dim {
85 return Err(AudioError::OutputBufferTooSmall);
86 }
87 for d in 0..dim {
88 let l = levels[d];
89 if l == 1 {
90 out[d] = lo;
91 continue;
92 }
93 let step = (hi - lo) / ((l - 1) as f32);
94 let idx = tokens[d].min(l - 1);
95 out[d] = lo + (idx as f32) * step;
96 }
97 Ok(())
98}
99
100#[cfg(test)]
101mod tests {
102 use super::*;
103
104 #[test]
105 fn on_grid_values_round_trip_exactly() {
106 let levels = [5u16, 5, 5];
108 let input = [-1.0f32, 0.0, 0.5]; let mut tokens = [0u16; 3];
110 fsq_quantize(&input, &levels, -1.0, 1.0, &mut tokens).expect("quant");
111 assert_eq!(tokens, [0, 2, 3]); let mut recon = [0.0f32; 3];
114 fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut recon).expect("dequant");
115 assert_eq!(recon, input, "on-grid values must reconstruct bit-exactly");
116 }
117
118 #[test]
119 fn off_grid_snaps_to_nearest_level() {
120 let levels = [5u16];
122 let mut tokens = [0u16; 1];
123
124 fsq_quantize(&[0.24f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
125 assert_eq!(tokens[0], 2); let mut r = [0.0f32; 1];
127 fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut r).expect("d");
128 assert!((r[0] - 0.0).abs() < 1e-6, "0.24 -> {}", r[0]);
129
130 fsq_quantize(&[0.26f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
131 assert_eq!(tokens[0], 3); fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut r).expect("d");
133 assert!((r[0] - 0.5).abs() < 1e-6, "0.26 -> {}", r[0]);
134 }
135
136 #[test]
137 fn out_of_range_input_clamps_to_end_levels() {
138 let levels = [4u16];
139 let mut tokens = [0u16; 1];
140 fsq_quantize(&[10.0f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
141 assert_eq!(tokens[0], 3); fsq_quantize(&[-10.0f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
143 assert_eq!(tokens[0], 0); }
145
146 #[test]
147 fn per_dim_level_counts() {
148 let levels = [8u16, 2];
150 let input = [1.0f32, -1.0]; let mut tokens = [0u16; 2];
152 fsq_quantize(&input, &levels, -1.0, 1.0, &mut tokens).expect("q");
153 assert_eq!(tokens, [7, 0]);
154 let mut recon = [0.0f32; 2];
155 fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut recon).expect("d");
156 assert_eq!(recon, input);
157 }
158
159 #[test]
160 fn single_level_dim_collapses_to_lo() {
161 let levels = [1u16];
162 let mut tokens = [99u16; 1];
163 fsq_quantize(&[0.7f32], &levels, -1.0, 1.0, &mut tokens).expect("q");
164 assert_eq!(tokens[0], 0);
165 let mut r = [0.0f32; 1];
166 fsq_dequantize(&tokens, &levels, -1.0, 1.0, &mut r).expect("d");
167 assert_eq!(r[0], -1.0);
168 }
169
170 #[test]
171 fn rejects_bad_params() {
172 let levels = [5u16];
173 let mut tokens = [0u16; 1];
174 assert_eq!(
175 fsq_quantize(&[0.0], &[], 0.0, 1.0, &mut tokens),
176 Err(AudioError::InvalidParameter)
177 );
178 assert_eq!(
179 fsq_quantize(&[0.0], &levels, 1.0, 1.0, &mut tokens),
180 Err(AudioError::InvalidParameter)
181 );
182 assert_eq!(
183 fsq_quantize(&[0.0], &[0u16], -1.0, 1.0, &mut tokens),
184 Err(AudioError::InvalidParameter)
185 );
186 let mut empty: [u16; 0] = [];
187 assert_eq!(
188 fsq_quantize(&[0.0], &levels, -1.0, 1.0, &mut empty),
189 Err(AudioError::OutputBufferTooSmall)
190 );
191 }
192}