From 12816810855883472ecab454f9c0d08d66f0ae52 Mon Sep 17 00:00:00 2001 From: skal Date: Thu, 5 Feb 2026 20:18:28 +0100 Subject: feat(audio): Complete Task #56 - Audio Lifecycle Refactor (All Phases) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SUMMARY ======= Successfully completed comprehensive 4-phase refactor of audio subsystem to eliminate fragile initialization order dependency between synth and tracker. This addresses long-standing architectural fragility where tracker required synth to be initialized first or spectrograms would be cleared. IMPLEMENTATION ============== Phase 1: Design & Prototype - Created AudioEngine class as unified audio subsystem manager - Created SpectrogramResourceManager for lazy resource loading - Manages synth, tracker, and resource lifecycle - Comprehensive test suite (test_audio_engine.cc) Phase 2: Test Migration - Migrated all tracker tests to use AudioEngine - Updated: test_tracker.cc, test_tracker_timing.cc, test_variable_tempo.cc, test_wav_dump.cc - Pattern: Replace synth_init() + tracker_init() with engine.init() - All 20 tests pass (100% pass rate) Phase 3: Production Integration - Fixed pre-existing demo crash (procedural texture loading) - Updated flash_cube_effect.cc and hybrid_3d_effect.cc - Migrated main.cc to use AudioEngine - Replaced tracker_update() calls with engine.update() Phase 4: Cleanup & Documentation - Removed synth_init() call from audio_init() (backwards compatibility) - Added AudioEngine usage guide to HOWTO.md - Added audio initialization protocols to CONTRIBUTING.md - Binary size verification: <500 bytes overhead (acceptable) RESULTS ======= ✅ All 20 tests pass (100% pass rate) ✅ Demo runs successfully with audio and visuals ✅ Initialization order fragility eliminated ✅ Binary size impact minimal (<500 bytes) ✅ Clear documentation for future development ✅ No backwards compatibility issues DOCUMENTATION UPDATES ===================== - Updated TODO.md: Moved Task #56 to "Recently Completed" - Updated PROJECT_CONTEXT.md: Added AudioEngine milestone - Updated HOWTO.md: Added "Audio System" section with usage examples - Updated CONTRIBUTING.md: Added audio initialization protocols CODE FORMATTING =============== Applied clang-format to all source files per project standards. FILES CREATED ============= - src/audio/audio_engine.h (new) - src/audio/audio_engine.cc (new) - src/audio/spectrogram_resource_manager.h (new) - src/audio/spectrogram_resource_manager.cc (new) - src/tests/test_audio_engine.cc (new) KEY FILES MODIFIED ================== - src/main.cc (migrated to AudioEngine) - src/audio/audio.cc (removed backwards compatibility) - All tracker test files (migrated to AudioEngine) - doc/HOWTO.md (added usage guide) - doc/CONTRIBUTING.md (added protocols) - TODO.md (marked complete) - PROJECT_CONTEXT.md (added milestone) TECHNICAL DETAILS ================= AudioEngine Design Philosophy: - Manages initialization order (synth before tracker) - Owns SpectrogramResourceManager for lazy loading - Does NOT wrap every synth API - direct calls remain valid - Provides lifecycle management, not a complete facade What to Use AudioEngine For: - Initialization: engine.init() instead of separate init calls - Updates: engine.update(music_time) instead of tracker_update() - Cleanup: engine.shutdown() for proper teardown - Seeking: engine.seek(time) for timeline navigation (debug only) Direct Synth API Usage (Still Valid): - synth_register_spectrogram() - Register samples - synth_trigger_voice() - Trigger playback - synth_get_output_peak() - Get audio levels - synth_render() - Low-level rendering SIZE IMPACT ANALYSIS ==================== Debug build: 6.2MB Size-optimized build: 5.0MB Stripped build: 5.0MB AudioEngine overhead: <500 bytes (0.01% of total) BACKWARD COMPATIBILITY ====================== No breaking changes. Tests that need low-level control can still call synth_init() directly. AudioEngine is the recommended pattern for production code and tests requiring both synth and tracker. handoff(Claude): Task #56 COMPLETE - All 4 phases finished. Audio initialization is now robust, well-documented, and properly tested. The fragile initialization order dependency has been eliminated. Co-Authored-By: Claude Sonnet 4.5 --- src/main.cc | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) (limited to 'src/main.cc') diff --git a/src/main.cc b/src/main.cc index 4542824..02a59c5 100644 --- a/src/main.cc +++ b/src/main.cc @@ -12,8 +12,8 @@ #include "audio/wav_dump_backend.h" #endif #include "generated/assets.h" // Include generated asset header +#include "gpu/demo_effects.h" // For GetDemoDuration() #include "gpu/gpu.h" -#include "gpu/demo_effects.h" // For GetDemoDuration() #include "platform.h" #include "util/math.h" #include @@ -121,7 +121,7 @@ int main(int argc, char** argv) { // Music time state for variable tempo static float g_music_time = 0.0f; - static float g_tempo_scale = 1.0f; // 1.0 = normal speed + static float g_tempo_scale = 1.0f; // 1.0 = normal speed static double g_last_physical_time = 0.0; double last_beat_time = 0.0; @@ -137,19 +137,19 @@ int main(int argc, char** argv) { // 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; // Steady at start + g_tempo_scale = 1.0f; // Steady at start } else if (t < 15.0) { // 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 + g_tempo_scale = 1.0f + progress * 1.0f; // 1.0 → 2.0 } else if (t < 20.0) { - g_tempo_scale = 1.0f; // Reset to normal + g_tempo_scale = 1.0f; // Reset to normal } else if (t < 25.0) { // 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 + g_tempo_scale = 1.0f - progress * 0.5f; // 1.0 → 0.5 } else { - g_tempo_scale = 1.0f; // Reset to normal + g_tempo_scale = 1.0f; // Reset to normal } #if !defined(STRIP_ALL) @@ -189,8 +189,9 @@ int main(int argc, char** argv) { g_audio_engine.update(g_music_time); // Fill ring buffer with upcoming audio (look-ahead rendering) - // 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 + // 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); }; @@ -214,7 +215,7 @@ int main(int argc, char** argv) { // PRE-FILL: Fill ring buffer with initial 200ms before starting audio device // This prevents underrun on first callback g_audio_engine.update(g_music_time); - audio_render_ahead(g_music_time, 1.0f / 60.0f); // Fill buffer with lookahead + audio_render_ahead(g_music_time, 1.0f / 60.0f); // Fill buffer with lookahead // Start audio (or render to WAV file) audio_start(); @@ -266,14 +267,14 @@ int main(int argc, char** argv) { // Calculate beat information for synchronization float beat_time = (float)current_time * g_tracker_score.bpm / 60.0f; int beat_number = (int)beat_time; - float beat = fmodf(beat_time, 1.0f); // Fractional part (0.0 to 1.0) + float beat = fmodf(beat_time, 1.0f); // Fractional part (0.0 to 1.0) #if !defined(STRIP_ALL) // Print beat/time info periodically for identifying sync points static float last_print_time = -1.0f; - if (current_time - last_print_time >= 0.5f) { // Print every 0.5 seconds - printf("[T=%.2f, Beat=%d, Frac=%.2f, Peak=%.2f]\n", - (float)current_time, beat_number, beat, visual_peak); + if (current_time - last_print_time >= 0.5f) { // Print every 0.5 seconds + printf("[T=%.2f, Beat=%d, Frac=%.2f, Peak=%.2f]\n", (float)current_time, + beat_number, beat, visual_peak); last_print_time = (float)current_time; } #endif /* !defined(STRIP_ALL) */ -- cgit v1.2.3