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/audio/tracker.cc | 41 ++++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 17 deletions(-) (limited to 'src/audio/tracker.cc') diff --git a/src/audio/tracker.cc b/src/audio/tracker.cc index 5e30281..7ad5a67 100644 --- a/src/audio/tracker.cc +++ b/src/audio/tracker.cc @@ -30,7 +30,7 @@ static int g_next_pool_slot = 0; // Round-robin allocation // CACHE: Pre-registered synth_ids for all samples (indexed by sample_id) // This eliminates redundant spectrogram generation and registration -static int g_sample_synth_cache[256]; // Max 256 unique samples +static int g_sample_synth_cache[256]; // Max 256 unique samples static bool g_cache_initialized = false; // Forward declarations @@ -80,7 +80,8 @@ void tracker_init() { if (data && size >= sizeof(SpecHeader)) { const SpecHeader* header = (const SpecHeader*)data; const int note_frames = header->num_frames; - const float* spectral_data = (const float*)(data + sizeof(SpecHeader)); + const float* spectral_data = + (const float*)(data + sizeof(SpecHeader)); Spectrogram spec; spec.spectral_data_a = spectral_data; @@ -91,8 +92,9 @@ void tracker_init() { #if defined(DEBUG_LOG_TRACKER) if (g_sample_synth_cache[sid] == -1) { - DEBUG_TRACKER( "[TRACKER INIT] Failed to cache asset sample_id=%d (aid=%d)\n", - sid, (int)aid); + DEBUG_TRACKER( + "[TRACKER INIT] Failed to cache asset sample_id=%d (aid=%d)\n", + sid, (int)aid); } #endif /* defined(DEBUG_LOG_TRACKER) */ } @@ -100,7 +102,8 @@ void tracker_init() { // GENERATED note: Generate once and cache const NoteParams& params = g_tracker_samples[sid]; int note_frames = 0; - std::vector note_data = generate_note_spectrogram(params, ¬e_frames); + std::vector note_data = + generate_note_spectrogram(params, ¬e_frames); if (note_frames > 0) { // Allocate persistent storage for this note @@ -116,12 +119,14 @@ void tracker_init() { g_sample_synth_cache[sid] = synth_register_spectrogram(&spec); g_spec_pool[slot].synth_id = g_sample_synth_cache[sid]; - g_spec_pool[slot].active = true; // Mark as permanently allocated + g_spec_pool[slot].active = true; // Mark as permanently allocated #if defined(DEBUG_LOG_TRACKER) if (g_sample_synth_cache[sid] == -1) { - DEBUG_TRACKER( "[TRACKER INIT] Failed to cache generated sample_id=%d (freq=%.2f)\n", - sid, params.base_freq); + DEBUG_TRACKER( + "[TRACKER INIT] Failed to cache generated sample_id=%d " + "(freq=%.2f)\n", + sid, params.base_freq); } #endif /* defined(DEBUG_LOG_TRACKER) */ } @@ -131,7 +136,8 @@ void tracker_init() { g_cache_initialized = true; #if defined(DEBUG_LOG_TRACKER) - DEBUG_TRACKER( "[TRACKER INIT] Cached %d unique samples\n", g_tracker_samples_count); + DEBUG_TRACKER("[TRACKER INIT] Cached %d unique samples\n", + g_tracker_samples_count); #endif /* defined(DEBUG_LOG_TRACKER) */ } } @@ -170,18 +176,18 @@ static void trigger_note_event(const TrackerEvent& event) { #if defined(DEBUG_LOG_TRACKER) // VALIDATION: Check sample_id bounds if (event.sample_id >= g_tracker_samples_count) { - DEBUG_TRACKER( "[TRACKER ERROR] Invalid sample_id=%d (max=%d)\n", - event.sample_id, g_tracker_samples_count - 1); + DEBUG_TRACKER("[TRACKER ERROR] Invalid sample_id=%d (max=%d)\n", + event.sample_id, g_tracker_samples_count - 1); return; } // VALIDATION: Check volume and pan ranges if (event.volume < 0.0f || event.volume > 2.0f) { - DEBUG_TRACKER( "[TRACKER WARNING] Unusual volume=%.2f for sample_id=%d\n", - event.volume, event.sample_id); + DEBUG_TRACKER("[TRACKER WARNING] Unusual volume=%.2f for sample_id=%d\n", + event.volume, event.sample_id); } if (event.pan < -1.0f || event.pan > 1.0f) { - DEBUG_TRACKER( "[TRACKER WARNING] Invalid pan=%.2f for sample_id=%d\n", - event.pan, event.sample_id); + DEBUG_TRACKER("[TRACKER WARNING] Invalid pan=%.2f for sample_id=%d\n", + event.pan, event.sample_id); } #endif /* defined(DEBUG_LOG_TRACKER) */ @@ -190,8 +196,9 @@ static void trigger_note_event(const TrackerEvent& event) { #if defined(DEBUG_LOG_TRACKER) if (cached_synth_id == -1) { - DEBUG_TRACKER( "[TRACKER ERROR] No cached synth_id for sample_id=%d (init failed?)\n", - event.sample_id); + DEBUG_TRACKER( + "[TRACKER ERROR] No cached synth_id for sample_id=%d (init failed?)\n", + event.sample_id); return; } #endif /* defined(DEBUG_LOG_TRACKER) */ -- cgit v1.2.3