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/asset_packer.cc | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) (limited to 'tools/asset_packer.cc') diff --git a/tools/asset_packer.cc b/tools/asset_packer.cc index 39169e4..04b74a4 100644 --- a/tools/asset_packer.cc +++ b/tools/asset_packer.cc @@ -31,8 +31,11 @@ static const std::map kAssetPackerProcGenFuncMap = { static bool HasImageExtension(const std::string& filename) { std::string ext = filename.substr(filename.find_last_of(".") + 1); - // simple case-insensitive check (assuming lowercase for simplicity or just basic checks) - if (ext == "png" || ext == "jpg" || ext == "jpeg" || ext == "tga" || ext == "bmp") return true; + // simple case-insensitive check (assuming lowercase for simplicity or just + // basic checks) + if (ext == "png" || ext == "jpg" || ext == "jpeg" || ext == "tga" || + ext == "bmp") + return true; return false; } @@ -190,7 +193,8 @@ int main(int argc, char* argv[]) { if (kAssetPackerProcGenFuncMap.find(info.proc_func_name) == kAssetPackerProcGenFuncMap.end()) { fprintf(stderr, - "Warning: Unknown procedural function: %s for asset: %s (Runtime error will occur)\n", + "Warning: Unknown procedural function: %s for asset: %s " + "(Runtime error will occur)\n", info.proc_func_name.c_str(), info.name.c_str()); // return 1; // Allow unknown functions for testing runtime handling } @@ -223,31 +227,35 @@ int main(int argc, char* argv[]) { std::string base_dir = assets_txt_path.substr(0, assets_txt_path.find_last_of("/\\") + 1); std::string full_path = base_dir + info.filename; - + std::vector buffer; bool is_image = HasImageExtension(info.filename); if (is_image) { int w, h, channels; - unsigned char* img_data = stbi_load(full_path.c_str(), &w, &h, &channels, 4); // Force 4 channels (RGBA) + unsigned char* img_data = stbi_load( + full_path.c_str(), &w, &h, &channels, 4); // Force 4 channels (RGBA) if (!img_data) { - fprintf(stderr, "Error: Could not load image file: %s (Reason: %s)\n", full_path.c_str(), stbi_failure_reason()); + fprintf(stderr, "Error: Could not load image file: %s (Reason: %s)\n", + full_path.c_str(), stbi_failure_reason()); return 1; } - + // Format: [Width(4)][Height(4)][Pixels...] buffer.resize(sizeof(uint32_t) * 2 + w * h * 4); uint32_t* header = reinterpret_cast(buffer.data()); header[0] = (uint32_t)w; header[1] = (uint32_t)h; std::memcpy(buffer.data() + sizeof(uint32_t) * 2, img_data, w * h * 4); - + stbi_image_free(img_data); - printf("Processed image asset %s: %dx%d RGBA\n", info.name.c_str(), w, h); + printf("Processed image asset %s: %dx%d RGBA\n", info.name.c_str(), w, + h); } else { std::ifstream asset_file(full_path, std::ios::binary); if (!asset_file.is_open()) { - fprintf(stderr, "Error: Could not open asset file: %s\n", full_path.c_str()); + fprintf(stderr, "Error: Could not open asset file: %s\n", + full_path.c_str()); return 1; } buffer.assign((std::istreambuf_iterator(asset_file)), -- cgit v1.2.3