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 --- tools/tracker_compiler.cc | 46 ++++++++++++++++++++++++++++++---------------- 1 file changed, 30 insertions(+), 16 deletions(-) (limited to 'tools/tracker_compiler.cc') diff --git a/tools/tracker_compiler.cc b/tools/tracker_compiler.cc index 81d7913..59d4187 100644 --- a/tools/tracker_compiler.cc +++ b/tools/tracker_compiler.cc @@ -13,8 +13,9 @@ enum SampleType { ASSET }; -// Convert note name (e.g., "NOTE_C4", "NOTE_A#3", "NOTE_Eb2") to frequency in Hz -// CRITICAL: Now requires "NOTE_" prefix (changed to prevent ASSET_* confusion) +// Convert note name (e.g., "NOTE_C4", "NOTE_A#3", "NOTE_Eb2") to frequency in +// Hz CRITICAL: Now requires "NOTE_" prefix (changed to prevent ASSET_* +// confusion) static float note_name_to_freq(const std::string& note_name) { if (note_name.size() < 7) // "NOTE_" + note + octave minimum return 0.0f; @@ -77,7 +78,8 @@ static bool is_note_name(const std::string& name) { // CRITICAL FIX: Require "NOTE_" prefix to avoid false positives with ASSET_* // Valid: NOTE_E2, NOTE_A4, NOTE_C#3, NOTE_Bb5 // Invalid: ASSET_KICK_1, E2 (no prefix), etc. - if (name.size() < 7) // "NOTE_" + note + octave = minimum 7 chars (e.g. "NOTE_C4") + if (name.size() < + 7) // "NOTE_" + note + octave = minimum 7 chars (e.g. "NOTE_C4") return false; if (name.substr(0, 5) != "NOTE_") return false; @@ -335,20 +337,25 @@ int main(int argc, char** argv) { for (const auto& p : patterns) { total_events += p.events.size(); } - const int avg_events_per_pattern = patterns.empty() ? 0 : total_events / patterns.size(); - const int estimated_max_polyphony = max_simultaneous_patterns * avg_events_per_pattern; + const int avg_events_per_pattern = + patterns.empty() ? 0 : total_events / patterns.size(); + const int estimated_max_polyphony = + max_simultaneous_patterns * avg_events_per_pattern; // Conservative recommendations with safety margins // - Each asset sample needs 1 spectrogram slot (shared across all events) // - Each generated note needs 1 spectrogram slot PER EVENT (no caching yet) // - Add 50% safety margin for peak moments - const int min_spectrograms = asset_sample_count + (generated_sample_count * estimated_max_polyphony); + const int min_spectrograms = + asset_sample_count + (generated_sample_count * estimated_max_polyphony); const int recommended_spectrograms = (int)(min_spectrograms * 1.5f); const int recommended_voices = estimated_max_polyphony * 2; - fprintf(out_file, "// ============================================================\n"); + fprintf(out_file, + "// ============================================================\n"); fprintf(out_file, "// RESOURCE USAGE ANALYSIS (for synth.h configuration)\n"); - fprintf(out_file, "// ============================================================\n"); + fprintf(out_file, + "// ============================================================\n"); fprintf(out_file, "// Total samples: %d (%d assets + %d generated notes)\n", (int)samples.size(), asset_sample_count, generated_sample_count); fprintf(out_file, "// Max simultaneous pattern triggers: %d\n", @@ -358,32 +365,39 @@ int main(int argc, char** argv) { fprintf(out_file, "// \n"); fprintf(out_file, "// REQUIRED (minimum to avoid pool exhaustion):\n"); fprintf(out_file, "// MAX_VOICES: %d\n", estimated_max_polyphony); - fprintf(out_file, "// MAX_SPECTROGRAMS: %d (no caching)\n", min_spectrograms); + fprintf(out_file, "// MAX_SPECTROGRAMS: %d (no caching)\n", + min_spectrograms); fprintf(out_file, "// \n"); fprintf(out_file, "// RECOMMENDED (with 50%% safety margin):\n"); fprintf(out_file, "// MAX_VOICES: %d\n", recommended_voices); - fprintf(out_file, "// MAX_SPECTROGRAMS: %d (no caching)\n", recommended_spectrograms); + fprintf(out_file, "// MAX_SPECTROGRAMS: %d (no caching)\n", + recommended_spectrograms); fprintf(out_file, "// \n"); fprintf(out_file, "// NOTE: With spectrogram caching by note parameters,\n"); fprintf(out_file, "// MAX_SPECTROGRAMS could be reduced to ~%d\n", asset_sample_count + generated_sample_count); - fprintf(out_file, "// ============================================================\n\n"); + fprintf( + out_file, + "// ============================================================\n\n"); fclose(out_file); printf("Tracker compilation successful.\n"); printf(" Patterns: %zu\n", patterns.size()); printf(" Score triggers: %zu\n", score.size()); - printf(" Samples: %d (%d assets + %d generated)\n", - (int)samples.size(), asset_sample_count, generated_sample_count); + printf(" Samples: %d (%d assets + %d generated)\n", (int)samples.size(), + asset_sample_count, generated_sample_count); printf(" Max simultaneous patterns: %d\n", max_simultaneous_patterns); printf(" Estimated max polyphony: %d voices\n", estimated_max_polyphony); printf("\n"); printf("RESOURCE REQUIREMENTS:\n"); printf(" Required MAX_VOICES: %d\n", estimated_max_polyphony); - printf(" Required MAX_SPECTROGRAMS: %d (without caching)\n", min_spectrograms); - printf(" Recommended MAX_VOICES: %d (with safety margin)\n", recommended_voices); - printf(" Recommended MAX_SPECTROGRAMS: %d (with safety margin)\n", recommended_spectrograms); + printf(" Required MAX_SPECTROGRAMS: %d (without caching)\n", + min_spectrograms); + printf(" Recommended MAX_VOICES: %d (with safety margin)\n", + recommended_voices); + printf(" Recommended MAX_SPECTROGRAMS: %d (with safety margin)\n", + recommended_spectrograms); printf(" With caching: MAX_SPECTROGRAMS could be ~%d\n", asset_sample_count + generated_sample_count); -- cgit v1.2.3