Preserve finite Float32 headroom during audio encoding

ROADMAP.md

@@ -2,7 +2,7 @@
 
 **Stage: pre-alpha** · next: alpha, ~5% and ~110–180 h away (the alpha gate's three failing workflows)
 
-> **Last reviewed:** 2026-10-18 · **Last updated:** 2026-10-18 · **Change:** trivial (mono device playback fold-down) · **Target:** Avid Pro Tools Ultimate 2026.4.1
+> **Last reviewed:** 2026-10-19 · **Last updated:** 2026-10-19 · **Change:** trivial (Float32 file headroom) · **Target:** Avid Pro Tools Ultimate 2026.4.1
 
 SoundCraft is a clean-room, pure-Rust digital audio workstation that aims at full parity with
 Avid Pro Tools, and then beyond it: faster, open, scriptable and agent-controllable. This page is
@@ -122,6 +122,7 @@ mutated and truncated movies. Field reports from the first public week are track
 
 ## Progress log
 
+- **2026-10-19:** Float32 WAV and AIFF-C encoding preserve finite samples above full scale. Integer PCM still clips at full scale. Tests cover whole-file and streaming encoders, non-finite samples, and bounce output with normalization on and off. No readiness percentage change.
 - **2026-10-18:** Mono audio devices receive the average of the stereo channels before output clipping, retaining right-only audio. Surround mixes use the same average after their ITU stereo fold-down. Regression tests cover channel balance, polarity cancellation, clipping, centered mono tracks, each 5.1 channel and several callback sizes. No readiness percentage change.
 - **2026-10-16:** Master fader volume automation uses each render block's actual last sample, matching track faders. Breakpoints in the next block no longer pull the preceding block's level toward them, and ramps reach their last-sample value. Regression tests cover nonzero starts, one-sample callbacks and several block sizes. No readiness percentage change.
 - **2026-10-16:** Aux, folder and master latency calculations exclude inserts already taken out for producing NaN or infinity, matching audio tracks. Subsequent blocks no longer compensate for an insert that is bypassed after failure. Regression tests check impulse timing, healthy insert latency and reset/retry at 64- and 512-sample blocks. No readiness percentage change.
@@ -161,6 +162,7 @@ mutated and truncated movies. Field reports from the first public week are track
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-10-19 | trivial | Float32 file encoding preserves finite headroom (#791); readiness estimates unchanged |
 | 2026-10-18 | trivial | Mono device playback retains both stereo sides and surround fold-down channels; readiness estimates unchanged |
 | 2026-10-16 | trivial | Master volume automation block boundaries corrected; readiness estimates unchanged |
 | 2026-10-16 | trivial | Failed inserts no longer contribute aux, folder or master latency after containment; readiness estimates unchanged |

contributors/people.toml

@@ -55,3 +55,6 @@ sync_github_name = true
 real_name = "Marco Arnulfo"
 display_name = "Marco Arnulfo"
 sync_github_name = false
+
+[people.mattburlage]
+display_name = "Matt Smith-Burlage"

crates/audio-io/src/lib.rs

@@ -115,6 +115,7 @@ pub enum BitDepth {
     Int16,
     Int24,
     Int32,
+    /// Preserve finite samples, including values above full scale; map NaN to 0 and infinities to ±1.
     Float32,
 }
 

crates/audio-io/src/pcm.rs

@@ -193,8 +193,8 @@ pub(crate) fn write_interleaved(
             for (c, q) in quantizers.iter_mut().enumerate() {
                 let s = block.get(c).and_then(|ch| ch.get(f)).copied().unwrap_or(0.0);
                 match (is_float, big_endian) {
-                    (true, false) => scratch.extend_from_slice(&clamp_float(s).to_le_bytes()),
-                    (true, true) => scratch.extend_from_slice(&clamp_float(s).to_be_bytes()),
+                    (true, false) => scratch.extend_from_slice(&sanitize_float(s).to_le_bytes()),
+                    (true, true) => scratch.extend_from_slice(&sanitize_float(s).to_be_bytes()),
                     (false, false) => scratch.extend_from_slice(q.quantize(s).to_le_bytes().get(..size).unwrap_or_default()),
                     (false, true) => scratch.extend_from_slice(q.quantize(s).to_be_bytes().get(4 - size..).unwrap_or_default()),
                 }
@@ -206,9 +206,15 @@ pub(crate) fn write_interleaved(
     Ok(())
 }
 
-/// Clamp a float sample to [-1, 1], mapping NaN to 0.
-pub(crate) fn clamp_float(x: f32) -> f32 {
-    if x.is_nan() { 0.0 } else { x.clamp(-1.0, 1.0) }
+/// Preserve finite float samples, mapping NaN to 0 and infinities to their sign (±1).
+fn sanitize_float(x: f32) -> f32 {
+    if x.is_finite() {
+        x
+    } else if x.is_nan() {
+        0.0
+    } else {
+        x.signum()
+    }
 }
 
 /// Check that a buffer is encodable: at least one channel and a non-zero sample rate.

crates/audio-io/tests/float_headroom.rs

@@ -0,0 +1,101 @@
+use soundcraft_audio_io::{AudioBuffer, BitDepth, EncodeOptions, FileEncoder, FileFormat, SampleFormat, decode, encode};
+use std::io::Cursor;
+
+fn encoded(audio: &AudioBuffer, options: &EncodeOptions, streaming: bool) -> Vec<u8> {
+    if !streaming {
+        return encode(audio, options).unwrap();
+    }
+    let mut writer = FileEncoder::new(Cursor::new(Vec::new()), options, audio.num_channels(), audio.sample_rate, None).unwrap();
+    // Cross the writer's 4096-frame scratch boundary, then write a short final block.
+    for start in (0..audio.frames()).step_by(4097) {
+        let end = (start + 4097).min(audio.frames());
+        let block: Vec<Vec<f32>> = audio.channels.iter().map(|channel| channel[start..end].to_vec()).collect();
+        writer.write(&block, end - start).unwrap();
+    }
+    writer.finish().unwrap().into_inner()
+}
+
+fn assert_float_headroom(streaming: bool) {
+    let samples = [
+        -f32::MAX,
+        -2.0,
+        -1.25,
+        -1.0,
+        -0.5,
+        -f32::MIN_POSITIVE,
+        -f32::from_bits(1),
+        -0.0,
+        0.0,
+        f32::from_bits(1),
+        f32::MIN_POSITIVE,
+        0.5,
+        1.0,
+        1.25,
+        2.0,
+        f32::MAX,
+    ];
+    for format in [FileFormat::Wav, FileFormat::Aiff] {
+        for dither in [false, true] {
+            for channels in [1, 2] {
+                let audio = AudioBuffer {
+                    sample_rate: 48_000,
+                    channels: (0..channels).map(|c| samples.iter().copied().cycle().skip(c).take(4103).collect()).collect(),
+                };
+                let options = EncodeOptions { format, bit_depth: BitDepth::Float32, dither, bwf: None };
+                let bytes = encoded(&audio, &options, streaming);
+                let pcm: Vec<u8> =
+                    audio.interleaved().iter().flat_map(|v| if format == FileFormat::Wav { v.to_le_bytes() } else { v.to_be_bytes() }).collect();
+                assert!(bytes.ends_with(&pcm), "{format:?}, dither={dither}: stored sample bytes changed");
+                let (info, decoded) = decode(&bytes, None).unwrap();
+                assert_eq!(info.sample_format, SampleFormat::Float32);
+                assert_eq!((decoded.sample_rate, decoded.num_channels(), decoded.frames()), (48_000, channels, 4103));
+                for (channel, (actual, expected)) in decoded.channels.iter().zip(&audio.channels).enumerate() {
+                    for (frame, (actual, expected)) in actual.iter().zip(expected).enumerate() {
+                        assert_eq!(actual.to_bits(), expected.to_bits(), "{format:?}, dither={dither}, channel={channel}, frame={frame}");
+                    }
+                }
+            }
+        }
+    }
+}
+
+#[test]
+fn whole_file_float32_preserves_finite_headroom() {
+    assert_float_headroom(false);
+}
+
+#[test]
+fn streaming_float32_preserves_finite_headroom() {
+    assert_float_headroom(true);
+}
+
+#[test]
+fn float32_keeps_non_finite_sample_handling() {
+    let audio = AudioBuffer { sample_rate: 48_000, channels: vec![vec![f32::NAN, f32::NEG_INFINITY, f32::INFINITY]] };
+    let expected = [0.0_f32, -1.0, 1.0];
+    for format in [FileFormat::Wav, FileFormat::Aiff] {
+        for streaming in [false, true] {
+            let options = EncodeOptions { format, bit_depth: BitDepth::Float32, dither: false, bwf: None };
+            let bytes = encoded(&audio, &options, streaming);
+            // Inspect stored samples too: the decoder itself replaces non-finite values.
+            let pcm: Vec<u8> = expected.iter().flat_map(|v| if format == FileFormat::Wav { v.to_le_bytes() } else { v.to_be_bytes() }).collect();
+            assert!(bytes.ends_with(&pcm), "{format:?}, streaming={streaming}");
+            assert_eq!(decode(&bytes, None).unwrap().1.channels[0], expected);
+        }
+    }
+}
+
+#[test]
+fn integer_pcm_still_clips_at_full_scale() {
+    let audio = AudioBuffer { sample_rate: 48_000, channels: vec![vec![-2.0, -1.25, -1.0, -0.5, 0.0, 0.5, 1.0, 1.25, 2.0]] };
+    for (depth, max) in [(BitDepth::Int16, 32767.0 / 32768.0), (BitDepth::Int24, 8_388_607.0 / 8_388_608.0), (BitDepth::Int32, 1.0)] {
+        for format in [FileFormat::Wav, FileFormat::Aiff, FileFormat::Flac] {
+            for streaming in [false, true] {
+                let options = EncodeOptions { format, bit_depth: depth, dither: false, bwf: None };
+                let bytes = encoded(&audio, &options, streaming);
+                let (_, decoded) = decode(&bytes, None).unwrap();
+                assert_eq!(decoded.channels[0], [-1.0, -1.0, -1.0, -0.5, 0.0, 0.5, max, max, max], "{format:?} {depth:?}, streaming={streaming}");
+            }
+        }
+    }
+}

crates/audio-io/tests/roundtrip.rs

@@ -205,7 +205,7 @@ fn encode_rejects_bad_buffers_and_formats() {
     for f in [FileFormat::Mp3, FileFormat::Ogg, FileFormat::Aac, FileFormat::Alac, FileFormat::Caf, FileFormat::Other] {
         assert!(encode(&sine(48_000, 1, 10), &EncodeOptions { format: f, ..EncodeOptions::default() }).is_err());
     }
-    // Non-finite and out-of-range samples are clamped, not errors.
+    // Non-finite samples are sanitized; only integer output clips finite samples.
     let mut b = AudioBuffer::new(48_000, 1, 4);
     b.channels[0] = vec![f32::NAN, f32::INFINITY, -5.0, 0.5];
     for format in [FileFormat::Wav, FileFormat::Aiff, FileFormat::Flac] {
@@ -217,7 +217,7 @@ fn encode_rejects_bad_buffers_and_formats() {
             let (_, out) = decode(&bytes, None).unwrap();
             assert_eq!(out.channels[0][0], 0.0);
             assert!(out.channels[0][1] > 0.99 && out.channels[0][1] <= 1.0);
-            assert_eq!(out.channels[0][2], -1.0);
+            assert_eq!(out.channels[0][2], if depth == BitDepth::Float32 { -5.0 } else { -1.0 });
         }
     }
     // Ragged buffers encode the common length.

crates/engine/tests/bounce.rs

@@ -5,6 +5,58 @@ use soundcraft_engine::io::{Bounce, bounce_stems};
 use soundcraft_time::Range;
 use std::path::PathBuf;
 
+#[test]
+fn float_bounce_preserves_headroom_and_reports_the_written_levels() {
+    let mut e = soundcraft_engine::Engine::default();
+    let sr = e.session().sample_rate.hz();
+    let frames = sr as usize + 17;
+    let samples: Vec<f32> = (0..frames).map(|i| 1.5 * (std::f32::consts::TAU * 440.0 * i as f32 / sr as f32).sin()).collect();
+    let audio = soundcraft_audio_io::AudioBuffer { sample_rate: sr, channels: vec![samples.clone(), samples] };
+    let s = e.session_mut();
+    // A new track has no inserts, so no limiter can mask encoder clipping.
+    let track = s.add_track(soundcraft_model::TrackKind::Audio, soundcraft_model::ChannelFormat::Stereo, Some("Headroom"));
+    let source = soundcraft_engine::io::add_source(s, "headroom", audio, None, FileFormat::Wav);
+    let clip = soundcraft_model::Clip::audio(s.new_clip_id(), "headroom", source, 0, 0, frames as i64);
+    soundcraft_engine::edit::place_clip(s, track, clip);
+    let mix = soundcraft_mix::render_range(e.session(), Range::new(0, frames as i64), 1024);
+    assert!(soundcraft_dsp::offline::peak(&mix) > 1.0);
+    let dir = scratch("bounce-float-headroom");
+    for extension in ["wav", "aiff"] {
+        for normalize in [false, true] {
+            let path = dir.join(format!("Mix.{extension}"));
+            let result = e
+                .execute(
+                    "file.bounce_mix",
+                    &serde_json::json!({
+                        "path": path, "bit_depth": "32f", "dither": false, "normalize": normalize,
+                        "start": 0, "end": frames,
+                    }),
+                )
+                .unwrap();
+            let bytes = std::fs::read(&path).unwrap();
+            let (_, file) = soundcraft_audio_io::decode(&bytes, None).unwrap();
+            let mut expected = mix.clone();
+            if normalize {
+                soundcraft_dsp::offline::normalize(&mut expected, -0.1, false);
+                assert!(file.peak() < 1.0);
+            } else {
+                assert!(file.peak() > 1.0, "{extension}: headroom was clipped");
+            }
+            assert_eq!(file.channels, expected, "{extension}, normalize={normalize}");
+            let mut meter = soundcraft_dsp::meter::LoudnessMeter::new(sr as f32, file.num_channels());
+            meter.process(&file.channels, file.frames());
+            for (key, value) in [
+                ("peak_db", soundcraft_dsp::offline::peak_db(&file.channels)),
+                ("lufs", meter.integrated_lufs()),
+                ("true_peak_db", meter.true_peak_db()),
+            ] {
+                assert_eq!(result[key].as_f64(), Some(f64::from(value)), "{extension}, normalize={normalize}, {key}");
+            }
+        }
+    }
+    let _ = std::fs::remove_dir_all(&dir);
+}
+
 fn scratch(name: &str) -> PathBuf {
     let dir = std::env::temp_dir().join(format!("soundcraft-{name}-{}", std::process::id()));
     let _ = std::fs::remove_dir_all(&dir);

docs/file-format-parity.md

@@ -1,6 +1,6 @@
 # File-format parity
 
-> **Last reviewed:** 2026-10-13 · **Last updated:** 2026-10-13 · **Change:** trivial (WAV: empty data chunk with trailing metadata (#466); previously minor: continuous fade curvature in SoundCraft sessions) · **Target:** Avid Pro Tools Ultimate 2026.4.1
+> **Last reviewed:** 2026-10-19 · **Last updated:** 2026-10-19 · **Change:** trivial (Float32 file headroom, #791) · **Target:** Avid Pro Tools Ultimate 2026.4.1
 
 Every format Pro Tools reads or writes, and ours. The Pro Tools list comes from the document types
 its bundle declares (`CFBundleDocumentTypes` in Info.plist: names only, nothing else read) and its
@@ -33,10 +33,10 @@ Legend: ✅ supported and tested · 🟡 partial · ❌ missing · — not appli
 
 | Format | Pro Tools | Read | Write | Tests / notes |
 |---|---|---|---|---|
-| WAV / BWF (PCM 16/24/32, float 32), `bext` | native | ✅ | ✅ | Native reader/writer, TPDF dither option; also 8-bit and float 64 read. An empty data chunk followed by metadata reads as no audio; an unfinalised recording's audio is still read (#466). |
+| WAV / BWF (PCM 16/24/32, float 32), `bext` | native | ✅ | ✅ | Native reader/writer, TPDF dither option; Float32 retains finite headroom (#791); also 8-bit and float 64 read. An empty data chunk followed by metadata reads as no audio; an unfinalised recording's audio is still read (#466). |
 | RF64 / BW64 (> 4 GiB) | read/write | ✅ | ✅ | `encode_wav_rf64` |
 | WAV `WAVE_FORMAT_EXTENSIBLE` multichannel with channel mask | read/write | ✅ | ✅ | `encode_with_channel_mask`; default 5.1 import creates a stereo track (#89, PR #128) |
-| AIFF / AIFF-C | native | ✅ | ✅ (`fl32`) | Native |
+| AIFF / AIFF-C | native | ✅ | ✅ (`fl32`) | Native; `fl32` retains finite headroom (#791) |
 | FLAC | import | ✅ | ✅ | Own encoder |
 | MP3 | import, bounce | ✅ (symphonia) | ❌ | G-21 |
 | AAC / M4A / MP4 audio | import, bounce | ✅ (symphonia) | ❌ | G-21 |
@@ -80,6 +80,7 @@ Legend: ✅ supported and tested · 🟡 partial · ❌ missing · — not appli
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-10-19 | trivial | WAV and AIFF-C Float32 encoders retain finite headroom (#791); whole-file, streaming and bounce regression tests |
 | 2026-10-13 | trivial | WAV: empty data chunk with trailing metadata (#466) |
 | 2026-10-13 | minor | Fade curvature round-trips in sessions with a zero default for older files. Format version and readiness estimate unchanged |
 | 2026-10-10 | major | Created: format inventory against Pro Tools 2026.4.1's declared document types and import/bounce options |

docs/gaps.md

@@ -1,6 +1,6 @@
 # Where SoundCraft falls short of Pro Tools
 
-> **Last reviewed:** 2026-10-18 · **Last updated:** 2026-10-18 · **Change:** trivial (G-04: mono device playback fold-down) · **Target:** Avid Pro Tools Ultimate 2026.4.1
+> **Last reviewed:** 2026-10-19 · **Last updated:** 2026-10-19 · **Change:** trivial (G-04: Float32 file headroom) · **Target:** Avid Pro Tools Ultimate 2026.4.1
 
 Every known shortfall, one entry each, ranked by how much it stops a Pro Tools user from doing
 real work in SoundCraft. This is the work list: pick from the top. Rows marked **alpha blocker**
@@ -80,6 +80,8 @@ When you close a gap, delete its entry (or shrink it) in the same PR, and bump t
 
 ### G-04. Correctness bugs in "done" features
 
+**Fixed (2026-10-19, #791):** Float32 WAV and AIFF-C encoding retain finite samples above full scale. Whole-file and streaming tests cover both formats, integer clipping, and the existing NaN/infinity behavior. A bounce regression checks preserved headroom and file/report agreement with normalization off, then checks normalized output.
+
 **Fixed (2026-10-18):** Mono device playback averages the stereo channels before output clipping,
 **Fixed (2026-10-16):** Master fader volume automation uses the first and last samples of each
 **Fixed (2026-10-16):** Aux, folder and master latency calculations now skip inserts already
@@ -214,6 +216,7 @@ missing. Out of scope unless the owner decides otherwise.
 
 | Date | Change | Summary |
 |---|---|---|
+| 2026-10-19 | trivial | G-04: Float32 encoding retains finite headroom (#791); integer clipping and non-finite handling retained |
 | 2026-10-18 | trivial | G-04: mono device stereo/surround fold-down fixed and regression-tested; estimates unchanged |
 | 2026-10-16 | trivial | G-04: master volume automation block boundaries fixed and regression-tested; estimates unchanged |
 | 2026-10-16 | trivial | G-04: failed aux/folder/master inserts excluded from latency compensation after containment; estimates unchanged |