Skip to main content

qualia_core_db/audio/
tf_surface_edit.rs

1//! P7.6 — Audio edits as geometric surface operations on the time-frequency
2//! surface.
3//!
4//! Each edit is a geometric transformation of the TfSurface raster:
5//!
6//! - **Gain**: scale magnitude in a rectangular region (affine scale in z).
7//! - **Cut/paste**: copy a rectangular patch of the surface to another
8//!   location (translation in the time-frequency plane).
9//! - **Time-stretch**: resample the surface along the time axis (affine
10//!   scale in u).
11//! - **Pitch-shift**: resample along the frequency axis (affine scale in v).
12//! - **Crossfade**: blend two surfaces with a weight ramp (linear blend
13//!   of two height fields).
14//! - **Spectral gate**: zero out bins below a threshold (clipping plane
15//!   in z).
16//!
17//! All operations write to caller-supplied buffers. Deterministic.
18
19use super::tf_surface::TfSurface;
20
21// ───────────────────────────────────────────────────────────────────────────
22//  Errors
23// ───────────────────────────────────────────────────────────────────────────
24
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum SurfaceEditError {
27    BufferTooSmall { needed: usize, have: usize },
28    InvalidRegion,
29}
30
31impl core::fmt::Display for SurfaceEditError {
32    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
33        match self {
34            Self::BufferTooSmall { needed, have } => {
35                write!(
36                    f,
37                    "surface edit: buffer too small, need {needed}, have {have}"
38                )
39            }
40            Self::InvalidRegion => write!(f, "surface edit: invalid region"),
41        }
42    }
43}
44
45impl std::error::Error for SurfaceEditError {}
46
47// ───────────────────────────────────────────────────────────────────────────
48//  Region
49// ───────────────────────────────────────────────────────────────────────────
50
51/// A rectangular region in the time-frequency plane.
52#[derive(Debug, Clone, Copy, PartialEq, Eq)]
53pub struct Region {
54    /// First frame (inclusive).
55    pub frame_start: usize,
56    /// Last frame (exclusive).
57    pub frame_end: usize,
58    /// First frequency bin (inclusive).
59    pub bin_start: usize,
60    /// Last frequency bin (exclusive).
61    pub bin_end: usize,
62}
63
64impl Region {
65    /// Region covering frames `[frame_start, frame_end)` × bins
66    /// `[bin_start, bin_end)`.
67    #[inline]
68    pub fn new(frame_start: usize, frame_end: usize, bin_start: usize, bin_end: usize) -> Self {
69        Self {
70            frame_start,
71            frame_end,
72            bin_start,
73            bin_end,
74        }
75    }
76
77    /// Region covering the entire surface.
78    #[inline]
79    pub fn full(frame_count: usize, bin_count: usize) -> Self {
80        Self::new(0, frame_count, 0, bin_count)
81    }
82
83    /// Number of frames covered (`frame_end - frame_start`, saturating).
84    #[inline]
85    pub fn frame_span(&self) -> usize {
86        self.frame_end.saturating_sub(self.frame_start)
87    }
88
89    /// Number of bins covered (`bin_end - bin_start`, saturating).
90    #[inline]
91    pub fn bin_span(&self) -> usize {
92        self.bin_end.saturating_sub(self.bin_start)
93    }
94
95    /// True when both extents are non-empty.
96    #[inline]
97    pub fn is_valid(&self) -> bool {
98        self.frame_end > self.frame_start && self.bin_end > self.bin_start
99    }
100}
101
102// ───────────────────────────────────────────────────────────────────────────
103//  Edits
104// ───────────────────────────────────────────────────────────────────────────
105
106/// Apply a gain (scalar multiplication) to a region of the surface.
107/// `out` must be at least `frame_count * bin_count`.
108pub fn apply_gain(
109    surface: &TfSurface,
110    region: &Region,
111    gain: f32,
112    out: &mut [f32],
113) -> Result<usize, SurfaceEditError> {
114    let needed = surface.frame_count * surface.bin_count;
115    if out.len() < needed {
116        return Err(SurfaceEditError::BufferTooSmall {
117            needed,
118            have: out.len(),
119        });
120    }
121
122    // Copy the full surface, then apply gain to the region.
123    out[..needed].copy_from_slice(surface.raster);
124
125    let f_end = region.frame_end.min(surface.frame_count);
126    let b_end = region.bin_end.min(surface.bin_count);
127    for f in region.frame_start..f_end {
128        for b in region.bin_start..b_end {
129            out[f * surface.bin_count + b] *= gain;
130        }
131    }
132
133    Ok(needed)
134}
135
136/// Spectral gate: zero out all bins below `threshold` in the region.
137pub fn spectral_gate(
138    surface: &TfSurface,
139    region: &Region,
140    threshold: f32,
141    out: &mut [f32],
142) -> Result<usize, SurfaceEditError> {
143    let needed = surface.frame_count * surface.bin_count;
144    if out.len() < needed {
145        return Err(SurfaceEditError::BufferTooSmall {
146            needed,
147            have: out.len(),
148        });
149    }
150
151    out[..needed].copy_from_slice(surface.raster);
152
153    let f_end = region.frame_end.min(surface.frame_count);
154    let b_end = region.bin_end.min(surface.bin_count);
155    for f in region.frame_start..f_end {
156        for b in region.bin_start..b_end {
157            let idx = f * surface.bin_count + b;
158            if out[idx] < threshold {
159                out[idx] = 0.0;
160            }
161        }
162    }
163
164    Ok(needed)
165}
166
167/// Copy a rectangular patch from `src` to a destination offset in `out`.
168/// `out` must be at least `frame_count * bin_count`.
169pub fn copy_patch(
170    surface: &TfSurface,
171    src_region: &Region,
172    dst_frame: usize,
173    dst_bin: usize,
174    out: &mut [f32],
175) -> Result<usize, SurfaceEditError> {
176    let needed = surface.frame_count * surface.bin_count;
177    if out.len() < needed {
178        return Err(SurfaceEditError::BufferTooSmall {
179            needed,
180            have: out.len(),
181        });
182    }
183
184    out[..needed].copy_from_slice(surface.raster);
185
186    let f_span = src_region.frame_span();
187    let b_span = src_region.bin_span();
188
189    for df in 0..f_span {
190        let src_f = src_region.frame_start + df;
191        let dst_f = dst_frame + df;
192        if src_f >= surface.frame_count || dst_f >= surface.frame_count {
193            break;
194        }
195        for db in 0..b_span {
196            let src_b = src_region.bin_start + db;
197            let dst_b = dst_bin + db;
198            if src_b >= surface.bin_count || dst_b >= surface.bin_count {
199                break;
200            }
201            out[dst_f * surface.bin_count + dst_b] =
202                surface.raster[src_f * surface.bin_count + src_b];
203        }
204    }
205
206    Ok(needed)
207}
208
209/// Time-stretch by resampling along the time axis.
210/// `factor > 1.0` stretches, `factor < 1.0` compresses.
211/// `out` must be at least `new_frame_count * bin_count` where
212/// `new_frame_count = round(frame_count * factor)`.
213pub fn time_stretch(
214    surface: &TfSurface,
215    factor: f32,
216    out: &mut [f32],
217) -> Result<(usize, usize), SurfaceEditError> {
218    let new_frames = (surface.frame_count as f32 * factor).round() as usize;
219    let new_frames = new_frames.max(1);
220    let needed = new_frames * surface.bin_count;
221    if out.len() < needed {
222        return Err(SurfaceEditError::BufferTooSmall {
223            needed,
224            have: out.len(),
225        });
226    }
227
228    for f in 0..new_frames {
229        let src_f = f as f32 / factor;
230        for b in 0..surface.bin_count {
231            out[f * surface.bin_count + b] = surface.sample_bilinear(src_f, b as f32);
232        }
233    }
234
235    Ok((new_frames, surface.bin_count))
236}
237
238/// Pitch-shift by resampling along the frequency axis.
239/// `factor > 1.0` shifts up, `factor < 1.0` shifts down.
240/// `out` must be at least `frame_count * bin_count`.
241pub fn pitch_shift(
242    surface: &TfSurface,
243    factor: f32,
244    out: &mut [f32],
245) -> Result<usize, SurfaceEditError> {
246    let needed = surface.frame_count * surface.bin_count;
247    if out.len() < needed {
248        return Err(SurfaceEditError::BufferTooSmall {
249            needed,
250            have: out.len(),
251        });
252    }
253
254    for f in 0..surface.frame_count {
255        for b in 0..surface.bin_count {
256            let src_b = b as f32 / factor;
257            out[f * surface.bin_count + b] = surface.sample_bilinear(f as f32, src_b);
258        }
259    }
260
261    Ok(needed)
262}
263
264/// Crossfade: blend two surfaces with weight `t` (0 = surface_a, 1 = surface_b).
265/// Both surfaces must have the same dimensions.
266pub fn crossfade(
267    surface_a: &TfSurface,
268    surface_b: &TfSurface,
269    t: f32,
270    out: &mut [f32],
271) -> Result<usize, SurfaceEditError> {
272    if surface_a.frame_count != surface_b.frame_count || surface_a.bin_count != surface_b.bin_count
273    {
274        return Err(SurfaceEditError::InvalidRegion);
275    }
276
277    let needed = surface_a.frame_count * surface_a.bin_count;
278    if out.len() < needed {
279        return Err(SurfaceEditError::BufferTooSmall {
280            needed,
281            have: out.len(),
282        });
283    }
284
285    for i in 0..needed {
286        out[i] = surface_a.raster[i] * (1.0 - t) + surface_b.raster[i] * t;
287    }
288
289    Ok(needed)
290}
291
292/// Fade in: ramp gain from 0 to 1 over the first `fade_frames` frames.
293pub fn fade_in(
294    surface: &TfSurface,
295    fade_frames: usize,
296    out: &mut [f32],
297) -> Result<usize, SurfaceEditError> {
298    let needed = surface.frame_count * surface.bin_count;
299    if out.len() < needed {
300        return Err(SurfaceEditError::BufferTooSmall {
301            needed,
302            have: out.len(),
303        });
304    }
305
306    out[..needed].copy_from_slice(surface.raster);
307
308    let fade = fade_frames.min(surface.frame_count);
309    for f in 0..fade {
310        let gain = f as f32 / fade as f32;
311        for b in 0..surface.bin_count {
312            out[f * surface.bin_count + b] *= gain;
313        }
314    }
315
316    Ok(needed)
317}
318
319/// Fade out: ramp gain from 1 to 0 over the last `fade_frames` frames.
320pub fn fade_out(
321    surface: &TfSurface,
322    fade_frames: usize,
323    out: &mut [f32],
324) -> Result<usize, SurfaceEditError> {
325    let needed = surface.frame_count * surface.bin_count;
326    if out.len() < needed {
327        return Err(SurfaceEditError::BufferTooSmall {
328            needed,
329            have: out.len(),
330        });
331    }
332
333    out[..needed].copy_from_slice(surface.raster);
334
335    let fade = fade_frames.min(surface.frame_count);
336    let start = surface.frame_count - fade;
337    for f in 0..fade {
338        let gain = 1.0 - (f + 1) as f32 / fade as f32;
339        for b in 0..surface.bin_count {
340            out[(start + f) * surface.bin_count + b] *= gain;
341        }
342    }
343
344    Ok(needed)
345}
346
347// ───────────────────────────────────────────────────────────────────────────
348//  Tests
349// ───────────────────────────────────────────────────────────────────────────
350
351#[cfg(test)]
352mod tests {
353    use super::*;
354    use crate::audio::audio_spectral_sheet::SPECTRAL_PREVIEW_BINS;
355
356    fn make_surface() -> (Vec<f32>, usize, usize) {
357        let frames = 4;
358        let bins = SPECTRAL_PREVIEW_BINS;
359        let mut raster = vec![0.5f32; frames * bins];
360        // Set some distinct values for testing.
361        raster[1 * bins + 16] = 1.0;
362        raster[2 * bins + 32] = 0.8;
363        (raster, frames, bins)
364    }
365
366    #[test]
367    fn gain_scales_region() {
368        let (raster, frames, bins) = make_surface();
369        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
370        let region = Region::new(1, 3, 10, 20);
371        let mut out = vec![0.0f32; frames * bins];
372        apply_gain(&s, &region, 2.0, &mut out).unwrap();
373        // Inside region: doubled.
374        assert!(
375            (out[1 * bins + 16] - 2.0).abs() < 1e-6,
376            "peak should be doubled"
377        );
378        // Outside region: unchanged.
379        assert!(
380            (out[0 * bins + 0] - 0.5).abs() < 1e-6,
381            "outside should be unchanged"
382        );
383    }
384
385    #[test]
386    fn spectral_gate_zeros_below_threshold() {
387        let (raster, frames, bins) = make_surface();
388        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
389        let region = Region::full(frames, bins);
390        let mut out = vec![0.0f32; frames * bins];
391        spectral_gate(&s, &region, 0.6, &mut out).unwrap();
392        // Values below 0.6 should be zeroed.
393        assert_eq!(out[0 * bins + 0], 0.0, "0.5 should be gated");
394        // Values >= 0.6 should remain.
395        assert!((out[1 * bins + 16] - 1.0).abs() < 1e-6, "1.0 should remain");
396        assert!((out[2 * bins + 32] - 0.8).abs() < 1e-6, "0.8 should remain");
397    }
398
399    #[test]
400    fn copy_patch_translates_region() {
401        let (raster, frames, bins) = make_surface();
402        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
403        let src = Region::new(1, 2, 16, 17); // single cell at (1,16) = 1.0
404        let mut out = vec![0.0f32; frames * bins];
405        copy_patch(&s, &src, 3, 40, &mut out).unwrap();
406        // The value 1.0 should now appear at (3, 40).
407        assert!(
408            (out[3 * bins + 40] - 1.0).abs() < 1e-6,
409            "patch should be copied"
410        );
411    }
412
413    #[test]
414    fn time_stretch_doubles_frames() {
415        let (raster, frames, bins) = make_surface();
416        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
417        let mut out = vec![0.0f32; frames * 2 * bins];
418        let (new_frames, _) = time_stretch(&s, 2.0, &mut out).unwrap();
419        assert_eq!(new_frames, 8, "should double frame count");
420    }
421
422    #[test]
423    fn time_stretch_preserves_energy_pattern() {
424        let (raster, frames, bins) = make_surface();
425        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
426        let mut out = vec![0.0f32; frames * 2 * bins];
427        let (new_frames, _) = time_stretch(&s, 2.0, &mut out).unwrap();
428        // The peak at frame 1 should appear around frame 2 in the stretched version.
429        let peak_frame = (0..new_frames)
430            .map(|f| (f, out[f * bins + 16]))
431            .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap())
432            .unwrap()
433            .0;
434        assert!(
435            peak_frame >= 1 && peak_frame <= 3,
436            "peak should be near frame 2"
437        );
438    }
439
440    #[test]
441    fn pitch_shift_preserves_frame_count() {
442        let (raster, frames, bins) = make_surface();
443        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
444        let mut out = vec![0.0f32; frames * bins];
445        pitch_shift(&s, 2.0, &mut out).unwrap();
446        // Frame count unchanged.
447        // Check that the output has non-zero values.
448        assert!(
449            out.iter().any(|&v| v > 0.0),
450            "pitch shift should preserve energy"
451        );
452    }
453
454    #[test]
455    fn crossfade_blends_surfaces() {
456        let (raster_a, frames, bins) = make_surface();
457        let raster_b = vec![1.0f32; frames * bins];
458        let sa = TfSurface::new(&raster_a, frames, bins, 44100, 512);
459        let sb = TfSurface::new(&raster_b, frames, bins, 44100, 512);
460        let mut out = vec![0.0f32; frames * bins];
461        crossfade(&sa, &sb, 0.5, &mut out).unwrap();
462        // At t=0.5, value should be average.
463        let expected = (raster_a[0] + raster_b[0]) * 0.5;
464        assert!((out[0] - expected).abs() < 1e-6, "crossfade should blend");
465    }
466
467    #[test]
468    fn crossfade_at_t0_returns_a() {
469        let (raster_a, frames, bins) = make_surface();
470        let raster_b = vec![1.0f32; frames * bins];
471        let sa = TfSurface::new(&raster_a, frames, bins, 44100, 512);
472        let sb = TfSurface::new(&raster_b, frames, bins, 44100, 512);
473        let mut out = vec![0.0f32; frames * bins];
474        crossfade(&sa, &sb, 0.0, &mut out).unwrap();
475        for i in 0..frames * bins {
476            assert!(
477                (out[i] - raster_a[i]).abs() < 1e-6,
478                "t=0 should return surface A"
479            );
480        }
481    }
482
483    #[test]
484    fn crossfade_at_t1_returns_b() {
485        let (raster_a, frames, bins) = make_surface();
486        let raster_b = vec![1.0f32; frames * bins];
487        let sa = TfSurface::new(&raster_a, frames, bins, 44100, 512);
488        let sb = TfSurface::new(&raster_b, frames, bins, 44100, 512);
489        let mut out = vec![0.0f32; frames * bins];
490        crossfade(&sa, &sb, 1.0, &mut out).unwrap();
491        for i in 0..frames * bins {
492            assert!(
493                (out[i] - raster_b[i]).abs() < 1e-6,
494                "t=1 should return surface B"
495            );
496        }
497    }
498
499    #[test]
500    fn fade_in_ramps_from_zero() {
501        let (raster, frames, bins) = make_surface();
502        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
503        let mut out = vec![0.0f32; frames * bins];
504        fade_in(&s, 2, &mut out).unwrap();
505        // Frame 0 should be zeroed (gain = 0/2 = 0).
506        assert_eq!(out[0], 0.0, "frame 0 should be zeroed by fade-in");
507        // Frame 1 should be half (gain = 1/2 = 0.5).
508        assert!(
509            (out[1 * bins] - 0.25).abs() < 1e-6,
510            "frame 1 should be halved"
511        );
512        // Frame 2+ should be unchanged.
513        assert!(
514            (out[2 * bins] - 0.5).abs() < 1e-6,
515            "frame 2 should be unchanged"
516        );
517    }
518
519    #[test]
520    fn fade_out_ramps_to_zero() {
521        let (raster, frames, bins) = make_surface();
522        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
523        let mut out = vec![0.0f32; frames * bins];
524        fade_out(&s, 2, &mut out).unwrap();
525        // Last frame should be zeroed.
526        assert_eq!(out[(frames - 1) * bins], 0.0, "last frame should be zeroed");
527        // Second-to-last should be halved.
528        assert!(
529            (out[(frames - 2) * bins] - 0.25).abs() < 1e-6,
530            "second-to-last should be halved"
531        );
532    }
533
534    #[test]
535    fn all_edits_deterministic() {
536        let (raster, frames, bins) = make_surface();
537        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
538        let region = Region::new(0, 2, 0, 32);
539
540        let mut out1 = vec![0.0f32; frames * bins];
541        let mut out2 = vec![0.0f32; frames * bins];
542        apply_gain(&s, &region, 1.5, &mut out1).unwrap();
543        apply_gain(&s, &region, 1.5, &mut out2).unwrap();
544        assert_eq!(out1, out2, "gain must be deterministic");
545
546        let mut out3 = vec![0.0f32; frames * bins];
547        let mut out4 = vec![0.0f32; frames * bins];
548        spectral_gate(&s, &region, 0.3, &mut out3).unwrap();
549        spectral_gate(&s, &region, 0.3, &mut out4).unwrap();
550        assert_eq!(out3, out4, "gate must be deterministic");
551    }
552
553    #[test]
554    fn buffer_too_small_errors() {
555        let (raster, frames, bins) = make_surface();
556        let s = TfSurface::new(&raster, frames, bins, 44100, 512);
557        let mut out = vec![0.0f32; 10]; // too small
558        let region = Region::full(frames, bins);
559        let err = apply_gain(&s, &region, 2.0, &mut out).unwrap_err();
560        assert_eq!(
561            err,
562            SurfaceEditError::BufferTooSmall {
563                needed: frames * bins,
564                have: 10,
565            }
566        );
567    }
568}