From 91933ce05ba157dc549d52ed6c00c71c457fca05 Mon Sep 17 00:00:00 2001 From: skal Date: Wed, 4 Feb 2026 19:40:40 +0100 Subject: feat: Audio playback stability, NOTE_ parsing fix, sample caching, and debug logging infrastructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MILESTONE: Audio System Robustness & Debugging Core Audio Backend Optimization: - Fixed stop-and-go audio glitches caused by timing mismatch - Core Audio optimized for 44.1kHz (10ms periods), but 32kHz expected ~13.78ms - Added allowNominalSampleRateChange=TRUE to force OS-level 32kHz native - Added performanceProfile=conservative for 4096-frame buffers (128ms) - Result: Stable ~128ms callbacks, <1ms jitter, zero underruns Ring Buffer Improvements: - Increased capacity from 200ms to 400ms for tempo scaling headroom - Added comprehensive bounds checking with abort() on violations - Fixed tempo-scaled buffer fill: dt * g_tempo_scale - Buffer maintains 400ms fullness during 2.0x acceleration NOTE_ Parsing Fix & Sample Caching: - Fixed is_note_name() checking only first letter (A-G) - ASSET_KICK_1 was misidentified as A0 (27.5 Hz) - Required "NOTE_" prefix to distinguish notes from assets - Updated music.track to use NOTE_E2, NOTE_G4 format - Discovered resource exhaustion: 14 unique samples → 228 registrations - Implemented comprehensive caching in tracker_init() - Assets: loaded once from AssetManager, cached synth_id - Generated notes: created once, stored in persistent pool - Result: MAX_SPECTROGRAMS 256 → 32 (88% memory reduction) Debug Logging Infrastructure: - Created src/util/debug.h with 7 category macros (AUDIO, RING_BUFFER, TRACKER, SYNTH, 3D, ASSETS, GPU) - Added DEMO_ENABLE_DEBUG_LOGS CMake option (defines DEBUG_LOG_ALL) - Converted all diagnostic code to use category macros - Default build: macros compile to ((void)0) for zero runtime cost - Debug build: comprehensive logging for troubleshooting - Updated CONTRIBUTING.md with pre-commit policy Resource Analysis Tool: - Enhanced tracker_compiler to report pool sizes and cache potential - Analysis: 152/228 spectrograms without caching, 14 with caching - Tool generates optimization recommendations during compilation Files Changed: - CMakeLists.txt: Add DEBUG_LOG option - src/util/debug.h: New debug logging header (7 categories) - src/audio/miniaudio_backend.cc: Use DEBUG_AUDIO/DEBUG_RING_BUFFER - src/audio/ring_buffer.cc: Use DEBUG_RING_BUFFER for underruns - src/audio/tracker.cc: Implement sample caching, use DEBUG_TRACKER - src/audio/synth.cc: Use DEBUG_SYNTH for validation - src/audio/synth.h: Update MAX_SPECTROGRAMS (256→32), document caching - tools/tracker_compiler.cc: Fix is_note_name(), add resource analysis - assets/music.track: Update to use NOTE_ prefix format - doc/CONTRIBUTING.md: Add debug logging pre-commit policy - PROJECT_CONTEXT.md: Document milestone - TODO.md: Mark tasks completed Verification: - Default build: No debug output, audio plays correctly - Debug build: Comprehensive logging, audio plays correctly - Caching working: 14 unique samples cached at init - All tests passing (17/17) handoff(Claude): Audio system now stable with robust diagnostic infrastructure. Co-Authored-By: Claude Sonnet 4.5 --- src/audio/ring_buffer.cc | 63 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) (limited to 'src/audio/ring_buffer.cc') diff --git a/src/audio/ring_buffer.cc b/src/audio/ring_buffer.cc index 25cf853..ab51d6b 100644 --- a/src/audio/ring_buffer.cc +++ b/src/audio/ring_buffer.cc @@ -2,8 +2,11 @@ // It implements a lock-free ring buffer for audio streaming. #include "ring_buffer.h" +#include "util/debug.h" #include #include +#include // for abort() +#include // for fprintf() AudioRingBuffer::AudioRingBuffer() : capacity_(RING_BUFFER_CAPACITY_SAMPLES), @@ -48,16 +51,42 @@ int AudioRingBuffer::write(const float* samples, int count) { } const int write = write_pos_.load(std::memory_order_acquire); + + // BOUNDS CHECK: Validate write position + if (write < 0 || write >= capacity_) { + fprintf(stderr, "FATAL: write_pos out of bounds! write=%d, capacity=%d\n", + write, capacity_); + abort(); + } + const int space_to_end = capacity_ - write; if (to_write <= space_to_end) { // Write in one chunk + // BOUNDS CHECK + if (write < 0 || write + to_write > capacity_) { + fprintf(stderr, "BOUNDS ERROR in write(): write=%d, to_write=%d, capacity=%d\n", + write, to_write, capacity_); + abort(); + } memcpy(&buffer_[write], samples, to_write * sizeof(float)); write_pos_.store((write + to_write) % capacity_, std::memory_order_release); } else { // Write in two chunks (wrap around) + // BOUNDS CHECK - first chunk + if (write < 0 || write + space_to_end > capacity_) { + fprintf(stderr, "BOUNDS ERROR in write() chunk1: write=%d, space_to_end=%d, capacity=%d\n", + write, space_to_end, capacity_); + abort(); + } memcpy(&buffer_[write], samples, space_to_end * sizeof(float)); const int remainder = to_write - space_to_end; + // BOUNDS CHECK - second chunk + if (remainder < 0 || remainder > capacity_) { + fprintf(stderr, "BOUNDS ERROR in write() chunk2: remainder=%d, capacity=%d\n", + remainder, capacity_); + abort(); + } memcpy(&buffer_[0], samples + space_to_end, remainder * sizeof(float)); write_pos_.store(remainder, std::memory_order_release); } @@ -71,16 +100,42 @@ int AudioRingBuffer::read(float* samples, int count) { if (to_read > 0) { const int read = read_pos_.load(std::memory_order_acquire); + + // BOUNDS CHECK: Validate read position + if (read < 0 || read >= capacity_) { + fprintf(stderr, "FATAL: read_pos out of bounds! read=%d, capacity=%d\n", + read, capacity_); + abort(); + } + const int space_to_end = capacity_ - read; if (to_read <= space_to_end) { // Read in one chunk + // BOUNDS CHECK + if (read < 0 || read + to_read > capacity_) { + fprintf(stderr, "BOUNDS ERROR in read(): read=%d, to_read=%d, capacity=%d\n", + read, to_read, capacity_); + abort(); + } memcpy(samples, &buffer_[read], to_read * sizeof(float)); read_pos_.store((read + to_read) % capacity_, std::memory_order_release); } else { // Read in two chunks (wrap around) + // BOUNDS CHECK - first chunk + if (read < 0 || read + space_to_end > capacity_) { + fprintf(stderr, "BOUNDS ERROR in read() chunk1: read=%d, space_to_end=%d, capacity=%d\n", + read, space_to_end, capacity_); + abort(); + } memcpy(samples, &buffer_[read], space_to_end * sizeof(float)); const int remainder = to_read - space_to_end; + // BOUNDS CHECK - second chunk + if (remainder < 0 || remainder > capacity_) { + fprintf(stderr, "BOUNDS ERROR in read() chunk2: remainder=%d, capacity=%d\n", + remainder, capacity_); + abort(); + } memcpy(samples + space_to_end, &buffer_[0], remainder * sizeof(float)); read_pos_.store(remainder, std::memory_order_release); } @@ -90,6 +145,14 @@ int AudioRingBuffer::read(float* samples, int count) { // Fill remainder with silence if not enough samples available if (to_read < count) { +#if defined(DEBUG_LOG_RING_BUFFER) + // UNDERRUN DETECTED + static int underrun_count = 0; + if (++underrun_count % 10 == 1) { // Log every 10th underrun + DEBUG_RING_BUFFER("UNDERRUN #%d: requested=%d, available=%d, filling %d with silence\n", + underrun_count, count, to_read, count - to_read); + } +#endif /* defined(DEBUG_LOG_RING_BUFFER) */ memset(samples + to_read, 0, (count - to_read) * sizeof(float)); } -- cgit v1.2.3