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/audio.cc | 31 ++++++++++++++++++++----------- 1 file changed, 20 insertions(+), 11 deletions(-) (limited to 'src/audio/audio.cc') diff --git a/src/audio/audio.cc b/src/audio/audio.cc index 3b7b7fd..6e1e9b7 100644 --- a/src/audio/audio.cc +++ b/src/audio/audio.cc @@ -109,10 +109,12 @@ void audio_render_ahead(float music_time, float dt) { } g_pending_samples = remaining; - // Notify backend + // Notify backend (for testing/tracking) +#if !defined(STRIP_ALL) if (g_audio_backend != nullptr) { g_audio_backend->on_frames_rendered(written / RING_BUFFER_CHANNELS); } +#endif } // If still have pending samples, buffer is full - wait for consumption @@ -127,25 +129,30 @@ void audio_render_ahead(float music_time, float dt) { // Stop if buffer is full enough if (buffered_time >= target_lookahead) break; - // Check if buffer has space for this chunk + // Check available space and render chunk that fits const int available_space = g_ring_buffer.available_write(); - if (available_space < chunk_samples) { - // Buffer is too full, wait for audio callback to consume more + if (available_space == 0) { + // Buffer is completely full, wait for audio callback to consume break; } + // Determine how much we can actually render + // Render the smaller of: desired chunk size OR available space + const int actual_samples = (available_space < chunk_samples) ? available_space : chunk_samples; + const int actual_frames = actual_samples / RING_BUFFER_CHANNELS; + // Allocate temporary buffer (stereo) - float* temp_buffer = new float[chunk_samples]; + float* temp_buffer = new float[actual_samples]; // Render audio from synth (advances synth state incrementally) - synth_render(temp_buffer, chunk_frames); + synth_render(temp_buffer, actual_frames); // Write to ring buffer - const int written = g_ring_buffer.write(temp_buffer, chunk_samples); + const int written = g_ring_buffer.write(temp_buffer, actual_samples); // If partial write, save remaining samples to pending buffer - if (written < chunk_samples) { - const int remaining = chunk_samples - written; + if (written < actual_samples) { + const int remaining = actual_samples - written; if (remaining <= MAX_PENDING_SAMPLES) { for (int i = 0; i < remaining; ++i) { g_pending_buffer[i] = temp_buffer[written + i]; @@ -155,14 +162,16 @@ void audio_render_ahead(float music_time, float dt) { } // Notify backend of frames rendered (count frames sent to synth) +#if !defined(STRIP_ALL) if (g_audio_backend != nullptr) { - g_audio_backend->on_frames_rendered(chunk_frames); + g_audio_backend->on_frames_rendered(actual_frames); } +#endif delete[] temp_buffer; // If we couldn't write everything, stop and retry next frame - if (written < chunk_samples) break; + if (written < actual_samples) break; } } -- cgit v1.2.3