diff options
Diffstat (limited to 'PROJECT_CONTEXT.md')
| -rw-r--r-- | PROJECT_CONTEXT.md | 11 |
1 files changed, 11 insertions, 0 deletions
diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 46ea725..31045ce 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -31,6 +31,17 @@ Style: ### Recently Completed +#### Milestone: Audio Playback Stability & Debug Infrastructure (February 4, 2026) +- **Core Audio Backend Optimization**: Resolved critical audio playback issues (stop-and-go, glitches, eventual silence) caused by timing mismatches in miniaudio's Core Audio backend. Root cause: Core Audio optimized for 44.1kHz with 10ms periods, but our 32kHz system expected uniform ~13.78ms callbacks, causing resampling jitter. Fix: Added `allowNominalSampleRateChange = TRUE` to force OS-level 32kHz native playback and `performanceProfile = conservative` for larger buffers (4096 frames = 128ms). Result: Stable ~128ms callbacks with <1ms jitter, zero underruns during variable tempo (1.0x → 2.0x). + +- **Ring Buffer Capacity Tuning**: Increased ring buffer from 200ms to 400ms (25,600 samples) to handle tempo scaling headroom. Added comprehensive bounds checking with abort() on violations to catch buffer corruption early. Fixed critical bug: tempo-scaled rendering wasn't scaling dt when pre-filling buffer (`audio_render_ahead(g_music_time, dt * g_tempo_scale)`). Buffer now maintains 400ms fullness throughout playback, including 2.0x tempo acceleration. + +- **NOTE_ Parsing Bug Fix & Sample Caching**: Fixed critical `is_note_name()` bug that only checked first letter (A-G), causing ASSET_KICK_1 to be misidentified as A0 (27.5 Hz). Solution: Required "NOTE_" prefix (NOTE_E2, NOTE_G4) to distinguish from ASSET_* samples. Discovered resource exhaustion: every note event created NEW spectrogram (14 unique samples → 228 registrations). Implemented comprehensive caching in `tracker_init()`: pre-register all asset samples (loaded once from AssetManager) and generated notes (created once, stored in persistent pool). Result: 256 → 32 MAX_SPECTROGRAMS (88% memory reduction), zero spectrogram_id=-1 errors, perfect audio playback. + +- **Debug Logging Infrastructure**: Created systematic debug logging system (`src/util/debug.h`) with 7 category macros (DEBUG_LOG_AUDIO, DEBUG_LOG_RING_BUFFER, DEBUG_LOG_TRACKER, DEBUG_LOG_SYNTH, DEBUG_LOG_3D, DEBUG_LOG_ASSETS, DEBUG_LOG_GPU). Added `DEMO_ENABLE_DEBUG_LOGS` CMake option that defines `DEBUG_LOG_ALL` to enable all categories. Converted all diagnostic code in audio subsystem (miniaudio callbacks, ring buffer tracking, tracker validation, synth parameter checks) to use category macros. Default build: macros compile to `((void)0)` for zero runtime cost. Debug build: comprehensive logging (timing, buffer state, caching, validation). Updated `CONTRIBUTING.md` with pre-commit policy requiring debug build verification to ensure diagnostic code remains maintainable. + +- **Resource Analysis Tool**: Enhanced `tracker_compiler` to report required vs recommended pool sizes, cache potential, and memory usage. Analysis showed 152 required / 228 recommended spectrograms without caching, only 14 unique samples with caching. Tool now generates actionable optimization recommendations during music data compilation. + #### Milestone: Audio System Robustness & Variable Tempo (February 4, 2026) - **Event-Based Tracker for Tempo Scaling**: Refactored tracker system from pattern compositing to individual event triggering. Previously, pattern events were baked into single spectrograms at fixed positions, so tempo scaling only affected pattern trigger timing. Now each TrackerEvent triggers as a separate voice with timing calculated dynamically based on music_time. Result: Notes within patterns correctly accelerate/decelerate with tempo changes. At 2.0x tempo, both pattern triggering AND note spacing play 2x faster. Verified with WAV dump showing 61.24s music time in 60s physical time during tempo transitions. All 17 tests pass (100%). |