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/main.cc | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) (limited to 'src/main.cc') diff --git a/src/main.cc b/src/main.cc index 1f9e235..2d630ac 100644 --- a/src/main.cc +++ b/src/main.cc @@ -123,27 +123,28 @@ int main(int argc, char** argv) { int beat_count = 0; auto update_game_logic = [&](double t) { - // Variable tempo test: Accelerate and decelerate based on physical time - // Phase 1 (0-10s): Steady at 1.0x - // Phase 2 (10-15s): Accelerate from 1.0x to 2.0x - // Phase 3 (15-20s): Reset to 1.0x (with denser patterns in track) - // Phase 4 (20-25s): Decelerate from 1.0x to 0.5x - // Phase 5 (25s+): Reset to 1.0x (back to normal) + // Variable tempo system - acceleration phases for demo effect + // Phase 1 (0-5s): Steady 1.0x + // Phase 2 (5-10s): Steady 1.0x + // Phase 3 (10-15s): Accelerate from 1.0x to 2.0x + // Phase 4 (15-20s): Steady 1.0x (reset after acceleration) + // Phase 5 (20-25s): Decelerate from 1.0x to 0.5x + // Phase 6 (25s+): Steady 1.0x (reset after deceleration) const float prev_tempo = g_tempo_scale; if (t < 10.0) { - g_tempo_scale = 1.0f; // Phase 1: Steady + g_tempo_scale = 1.0f; // Steady at start } else if (t < 15.0) { - // Phase 2: Linear acceleration + // Phase 3: Linear acceleration const float progress = (float)(t - 10.0) / 5.0f; g_tempo_scale = 1.0f + progress * 1.0f; // 1.0 → 2.0 } else if (t < 20.0) { - g_tempo_scale = 1.0f; // Phase 3: Reset to normal + g_tempo_scale = 1.0f; // Reset to normal } else if (t < 25.0) { - // Phase 4: Linear deceleration + // Phase 5: Linear deceleration const float progress = (float)(t - 20.0) / 5.0f; g_tempo_scale = 1.0f - progress * 0.5f; // 1.0 → 0.5 } else { - g_tempo_scale = 1.0f; // Phase 5: Reset to normal + g_tempo_scale = 1.0f; // Reset to normal } #if !defined(STRIP_ALL) @@ -183,7 +184,9 @@ int main(int argc, char** argv) { tracker_update(g_music_time); // Fill ring buffer with upcoming audio (look-ahead rendering) - audio_render_ahead(g_music_time, dt); + // CRITICAL: Scale dt by tempo to render enough audio during acceleration/deceleration + // At 2.0x tempo, we consume 2x audio per physical second, so we must render 2x per frame + audio_render_ahead(g_music_time, dt * g_tempo_scale); }; #if !defined(STRIP_ALL) @@ -203,6 +206,11 @@ int main(int argc, char** argv) { } #endif /* !defined(STRIP_ALL) */ + // PRE-FILL: Fill ring buffer with initial 200ms before starting audio device + // This prevents underrun on first callback + tracker_update(g_music_time); + audio_render_ahead(g_music_time, 1.0f / 60.0f); // Fill buffer with lookahead + // Start audio (or render to WAV file) audio_start(); -- cgit v1.2.3