From 41876cd44b29113fbe72749665f1dd4fd473f27a Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Sat, 7 Feb 2026 10:53:28 +0100
Subject: fix(audio): Remove clipping from WavDumpBackend, add diagnostics
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixed design flaw where WavDumpBackend was clamping samples to [-1.0, 1.0]
before writing to file. This prevented detection of audio problems.

Changes:
- Removed sample clamping (lines 57-60 in old code)
- WAV dump now records audio "as is" (matches MiniaudioBackend behavior)
- Added clipped_samples_ counter to track diagnostic metric
- Added get_clipped_samples() method for programmatic access
- Report clipping statistics in shutdown():
  - "✓ No clipping detected" when clean
  - "WARNING: N samples clipped (X% of total)" when clipping occurs
  - Suggests reducing volume to fix

Why this matters:
- MiniaudioBackend does NOT clip samples (passes directly to miniaudio)
- WavDumpBackend should match this behavior
- Clipping in WAV files helps identify audio distortion problems
- Developers can compare WAV output to expected values
- Diagnostic metric helps tune audio levels

Testing:
- Added test_clipping_detection() test case
- Verifies clipping counter works correctly (200 clipped / 1000 samples)
- Existing tests show "✓ No clipping detected" for normal audio
- All 27 tests pass

Example output:
  WAV file written: test.wav (2.02 seconds, 128986 samples)
  ✓ No clipping detected

  WAV file written: loud.wav (10.5 seconds, 336000 samples)
  WARNING: 4521 samples clipped (1.35% of total)
  This indicates audio distortion - consider reducing volume

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 src/tests/test_wav_dump.cc | 49 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

(limited to 'src/tests')

diff --git a/src/tests/test_wav_dump.cc b/src/tests/test_wav_dump.cc
index cc2de19..aa195cc 100644
--- a/src/tests/test_wav_dump.cc
+++ b/src/tests/test_wav_dump.cc
@@ -190,6 +190,54 @@ void test_wav_stereo_buffer_size() {
   printf("  ✓ Buffer size calculations correct for stereo\n");
 }
 
+void test_clipping_detection() {
+  printf("Test: Clipping detection and reporting...\n");
+
+  const char* test_file = "test_clipping.wav";
+
+  audio_init();
+  AudioEngine engine;
+  engine.init();
+
+  WavDumpBackend wav_backend;
+  wav_backend.set_output_file(test_file);
+  wav_backend.init();
+  wav_backend.start();
+
+  // Create test samples with intentional clipping
+  const int num_samples = 1000;
+  float test_samples[1000];
+
+  // Mix of normal and clipped samples
+  for (int i = 0; i < num_samples; ++i) {
+    if (i % 10 == 0) {
+      test_samples[i] = 1.5f;  // Clipped high
+    } else if (i % 10 == 1) {
+      test_samples[i] = -1.2f; // Clipped low
+    } else {
+      test_samples[i] = 0.5f;  // Normal
+    }
+  }
+
+  // Write samples
+  wav_backend.write_audio(test_samples, num_samples);
+
+  // Verify clipping was detected (20% of samples should be clipped)
+  const size_t clipped = wav_backend.get_clipped_samples();
+  assert(clipped == 200); // 10% + 10% = 20% of 1000
+
+  printf("  Detected %zu clipped samples (expected 200)\n", clipped);
+
+  wav_backend.shutdown();
+  engine.shutdown();
+  audio_shutdown();
+
+  // Clean up
+  remove(test_file);
+
+  printf("  ✓ Clipping detection works correctly\n");
+}
+
 #endif /* !defined(STRIP_ALL) */
 
 int main() {
@@ -197,6 +245,7 @@ int main() {
   printf("Running WAV Dump Backend tests...\n\n");
   test_wav_format_matches_live_audio();
   test_wav_stereo_buffer_size();
+  test_clipping_detection();
   printf("\n✅ All WAV Dump tests PASSED\n");
   return 0;
 #else
-- 
cgit v1.2.3