docs(audio): Document WavDumpBackend synchronization with MiniaudioBackend

Added detailed comment in write_audio() explaining that the clipping
detection code must stay synchronized with MiniaudioBackend's sample
handling behavior.

Critical requirement: If miniaudio changes how it handles float→int16
conversion or overflow behavior, this code MUST be updated to match.

Verification reference: src/audio/miniaudio_backend.cc data_callback()

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

1 files changed, 17 insertions, 6 deletions

diff --git a/src/audio/wav_dump_backend.cc b/src/audio/wav_dump_backend.cc
index 82803a2..df82f90 100644
--- a/src/audio/wav_dump_backend.cc
+++ b/src/audio/wav_dump_backend.cc
@@ -50,19 +50,30 @@ void WavDumpBackend::write_audio(const float* samples, int num_samples) {
     return;
   }
 
-  // Convert float samples to int16 and write to WAV
-  // Note: We do NOT clamp samples (matches MiniaudioBackend behavior)
-  // Instead, we count samples that would clip during int16 conversion
+  // CRITICAL: This method must match MiniaudioBackend's sample handling
+  // behavior to ensure WAV dumps accurately reflect live audio output.
+  //
+  // Current behavior (verified 2026-02-07):
+  // - MiniaudioBackend passes float samples directly to miniaudio without
+  //   clamping (see miniaudio_backend.cc:140)
+  // - Miniaudio internally converts float→int16 and handles overflow
+  // - We replicate this: no clamping, count out-of-range samples for diagnostics
+  //
+  // If miniaudio's sample handling changes (e.g., they add clamping or
+  // different overflow behavior), this code MUST be updated to match.
+  // Verify by checking: src/audio/miniaudio_backend.cc data_callback()
+
   for (int i = 0; i < num_samples; ++i) {
     float sample = samples[i];
 
-    // Track clipping for diagnostics (but don't prevent it)
+    // Track samples outside [-1.0, 1.0] range for diagnostic reporting
+    // This helps identify audio distortion issues during development
     if (sample > 1.0f || sample < -1.0f) {
       clipped_samples_++;
     }
 
-    // Convert to int16 (allows overflow for diagnostic purposes)
-    // This matches hardware behavior where clipping occurs in the DAC
+    // Convert float→int16 with same overflow behavior as miniaudio
+    // Values outside [-1.0, 1.0] will wrap/clip during conversion
     const int16_t sample_i16 = (int16_t)(sample * 32767.0f);
     fwrite(&sample_i16, sizeof(int16_t), 1, wav_file_);
   }