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/generated/test_assets_data.cc | 85 +++++++++++++++++++++------------------ 1 file changed, 46 insertions(+), 39 deletions(-) (limited to 'src/generated/test_assets_data.cc') diff --git a/src/generated/test_assets_data.cc b/src/generated/test_assets_data.cc index 8445ed3..bb222f0 100644 --- a/src/generated/test_assets_data.cc +++ b/src/generated/test_assets_data.cc @@ -1,45 +1,46 @@ // This file is auto-generated by asset_packer.cc. Do not edit. -#include "util/asset_manager.h" #include "test_assets.h" -namespace procedural { void gen_noise(uint8_t*, int, int, const float*, int); } -namespace procedural { void gen_grid(uint8_t*, int, int, const float*, int); } -namespace procedural { void make_periodic(uint8_t*, int, int, const float*, int); } +#include "util/asset_manager.h" +namespace procedural { +void gen_noise(uint8_t*, int, int, const float*, int); +} +namespace procedural { +void gen_grid(uint8_t*, int, int, const float*, int); +} +namespace procedural { +void make_periodic(uint8_t*, int, int, const float*, int); +} const size_t ASSET_SIZE_TEST_ASSET_1 = 101; alignas(16) static const uint8_t ASSET_DATA_TEST_ASSET_1[] = { - 0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x74, 0x65, - 0x73, 0x74, 0x20, 0x61, 0x73, 0x73, 0x65, 0x74, 0x20, 0x66, 0x69, 0x6c, - 0x65, 0x2e, 0x0a, 0x49, 0x74, 0x20, 0x63, 0x6f, 0x6e, 0x74, 0x61, 0x69, - 0x6e, 0x73, 0x20, 0x73, 0x6f, 0x6d, 0x65, 0x20, 0x74, 0x65, 0x78, 0x74, - 0x20, 0x64, 0x61, 0x74, 0x61, 0x20, 0x74, 0x6f, 0x20, 0x76, 0x65, 0x72, - 0x69, 0x66, 0x79, 0x20, 0x74, 0x68, 0x65, 0x20, 0x61, 0x73, 0x73, 0x65, - 0x74, 0x20, 0x70, 0x61, 0x63, 0x6b, 0x69, 0x6e, 0x67, 0x20, 0x73, 0x79, - 0x73, 0x74, 0x65, 0x6d, 0x2e, 0x0a, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, - 0x37, 0x38, 0x39, 0x30, 0x0a, 0x00 -}; + 0x54, 0x68, 0x69, 0x73, 0x20, 0x69, 0x73, 0x20, 0x61, 0x20, 0x74, 0x65, + 0x73, 0x74, 0x20, 0x61, 0x73, 0x73, 0x65, 0x74, 0x20, 0x66, 0x69, 0x6c, + 0x65, 0x2e, 0x0a, 0x49, 0x74, 0x20, 0x63, 0x6f, 0x6e, 0x74, 0x61, 0x69, + 0x6e, 0x73, 0x20, 0x73, 0x6f, 0x6d, 0x65, 0x20, 0x74, 0x65, 0x78, 0x74, + 0x20, 0x64, 0x61, 0x74, 0x61, 0x20, 0x74, 0x6f, 0x20, 0x76, 0x65, 0x72, + 0x69, 0x66, 0x79, 0x20, 0x74, 0x68, 0x65, 0x20, 0x61, 0x73, 0x73, 0x65, + 0x74, 0x20, 0x70, 0x61, 0x63, 0x6b, 0x69, 0x6e, 0x67, 0x20, 0x73, 0x79, + 0x73, 0x74, 0x65, 0x6d, 0x2e, 0x0a, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, + 0x37, 0x38, 0x39, 0x30, 0x0a, 0x00}; const size_t ASSET_SIZE_NULL_ASSET = 0; -alignas(16) static const uint8_t ASSET_DATA_NULL_ASSET[] = { - 0x00 -}; +alignas(16) static const uint8_t ASSET_DATA_NULL_ASSET[] = {0x00}; const size_t ASSET_SIZE_SHADER_SNIPPET_A = 65; alignas(16) static const uint8_t ASSET_DATA_SHADER_SNIPPET_A[] = { - 0x2f, 0x2f, 0x20, 0x74, 0x65, 0x73, 0x74, 0x5f, 0x73, 0x6e, 0x69, 0x70, - 0x70, 0x65, 0x74, 0x5f, 0x61, 0x2e, 0x77, 0x67, 0x73, 0x6c, 0x0a, 0x66, - 0x6e, 0x20, 0x73, 0x6e, 0x69, 0x70, 0x70, 0x65, 0x74, 0x5f, 0x61, 0x28, - 0x29, 0x20, 0x2d, 0x3e, 0x20, 0x66, 0x33, 0x32, 0x20, 0x7b, 0x0a, 0x20, - 0x20, 0x20, 0x20, 0x72, 0x65, 0x74, 0x75, 0x72, 0x6e, 0x20, 0x31, 0x2e, - 0x30, 0x3b, 0x0a, 0x7d, 0x0a, 0x00 -}; + 0x2f, 0x2f, 0x20, 0x74, 0x65, 0x73, 0x74, 0x5f, 0x73, 0x6e, 0x69, + 0x70, 0x70, 0x65, 0x74, 0x5f, 0x61, 0x2e, 0x77, 0x67, 0x73, 0x6c, + 0x0a, 0x66, 0x6e, 0x20, 0x73, 0x6e, 0x69, 0x70, 0x70, 0x65, 0x74, + 0x5f, 0x61, 0x28, 0x29, 0x20, 0x2d, 0x3e, 0x20, 0x66, 0x33, 0x32, + 0x20, 0x7b, 0x0a, 0x20, 0x20, 0x20, 0x20, 0x72, 0x65, 0x74, 0x75, + 0x72, 0x6e, 0x20, 0x31, 0x2e, 0x30, 0x3b, 0x0a, 0x7d, 0x0a, 0x00}; const size_t ASSET_SIZE_SHADER_SNIPPET_B = 65; alignas(16) static const uint8_t ASSET_DATA_SHADER_SNIPPET_B[] = { - 0x2f, 0x2f, 0x20, 0x74, 0x65, 0x73, 0x74, 0x5f, 0x73, 0x6e, 0x69, 0x70, - 0x70, 0x65, 0x74, 0x5f, 0x62, 0x2e, 0x77, 0x67, 0x73, 0x6c, 0x0a, 0x66, - 0x6e, 0x20, 0x73, 0x6e, 0x69, 0x70, 0x70, 0x65, 0x74, 0x5f, 0x62, 0x28, - 0x29, 0x20, 0x2d, 0x3e, 0x20, 0x66, 0x33, 0x32, 0x20, 0x7b, 0x0a, 0x20, - 0x20, 0x20, 0x20, 0x72, 0x65, 0x74, 0x75, 0x72, 0x6e, 0x20, 0x32, 0x2e, - 0x30, 0x3b, 0x0a, 0x7d, 0x0a, 0x00 -}; + 0x2f, 0x2f, 0x20, 0x74, 0x65, 0x73, 0x74, 0x5f, 0x73, 0x6e, 0x69, + 0x70, 0x70, 0x65, 0x74, 0x5f, 0x62, 0x2e, 0x77, 0x67, 0x73, 0x6c, + 0x0a, 0x66, 0x6e, 0x20, 0x73, 0x6e, 0x69, 0x70, 0x70, 0x65, 0x74, + 0x5f, 0x62, 0x28, 0x29, 0x20, 0x2d, 0x3e, 0x20, 0x66, 0x33, 0x32, + 0x20, 0x7b, 0x0a, 0x20, 0x20, 0x20, 0x20, 0x72, 0x65, 0x74, 0x75, + 0x72, 0x6e, 0x20, 0x32, 0x2e, 0x30, 0x3b, 0x0a, 0x7d, 0x0a, 0x00}; static const float ASSET_PROC_PARAMS_PROC_NOISE_256[] = {4321.000000, 8.000000}; static const char* ASSET_PROC_FUNC_STR_PROC_NOISE_256 = "gen_noise"; @@ -54,13 +55,20 @@ static const char* ASSET_PROC_FUNC_STR_PROC_FAIL = "gen_noise"; const AssetRecord* GetAssetRecordTable() { static const AssetRecord assets[] = { - { ASSET_DATA_TEST_ASSET_1, ASSET_SIZE_TEST_ASSET_1, false, nullptr, nullptr, 0 }, - { ASSET_DATA_NULL_ASSET, ASSET_SIZE_NULL_ASSET, false, nullptr, nullptr, 0 }, - { ASSET_DATA_SHADER_SNIPPET_A, ASSET_SIZE_SHADER_SNIPPET_A, false, nullptr, nullptr, 0 }, - { ASSET_DATA_SHADER_SNIPPET_B, ASSET_SIZE_SHADER_SNIPPET_B, false, nullptr, nullptr, 0 }, - { nullptr, 0, true, ASSET_PROC_FUNC_STR_PROC_NOISE_256, ASSET_PROC_PARAMS_PROC_NOISE_256, 2 }, - { nullptr, 0, true, ASSET_PROC_FUNC_STR_PROC_UNKNOWN, ASSET_PROC_PARAMS_PROC_UNKNOWN, 1 }, - { nullptr, 0, true, ASSET_PROC_FUNC_STR_PROC_FAIL, ASSET_PROC_PARAMS_PROC_FAIL, 2 }, + {ASSET_DATA_TEST_ASSET_1, ASSET_SIZE_TEST_ASSET_1, false, nullptr, + nullptr, 0}, + {ASSET_DATA_NULL_ASSET, ASSET_SIZE_NULL_ASSET, false, nullptr, nullptr, + 0}, + {ASSET_DATA_SHADER_SNIPPET_A, ASSET_SIZE_SHADER_SNIPPET_A, false, nullptr, + nullptr, 0}, + {ASSET_DATA_SHADER_SNIPPET_B, ASSET_SIZE_SHADER_SNIPPET_B, false, nullptr, + nullptr, 0}, + {nullptr, 0, true, ASSET_PROC_FUNC_STR_PROC_NOISE_256, + ASSET_PROC_PARAMS_PROC_NOISE_256, 2}, + {nullptr, 0, true, ASSET_PROC_FUNC_STR_PROC_UNKNOWN, + ASSET_PROC_PARAMS_PROC_UNKNOWN, 1}, + {nullptr, 0, true, ASSET_PROC_FUNC_STR_PROC_FAIL, + ASSET_PROC_PARAMS_PROC_FAIL, 2}, }; return assets; } @@ -68,4 +76,3 @@ const AssetRecord* GetAssetRecordTable() { size_t GetAssetCount() { return 7; } - -- cgit v1.2.3