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/tests/test_audio_gen.cc | 144 ++++++++++++++++++++++---------------------- 1 file changed, 72 insertions(+), 72 deletions(-) (limited to 'src/tests/test_audio_gen.cc') diff --git a/src/tests/test_audio_gen.cc b/src/tests/test_audio_gen.cc index 2877fc4..ebdcb25 100644 --- a/src/tests/test_audio_gen.cc +++ b/src/tests/test_audio_gen.cc @@ -1,97 +1,97 @@ // This file is part of the 64k demo project. // It tests the procedural audio generation functions. -#include "audio/gen.h" #include "audio/dct.h" -#include +#include "audio/gen.h" #include -#include #include +#include +#include void test_generate_note() { - NoteParams params; - params.base_freq = 440.0f; - params.duration_sec = 0.1f; // ~3 frames - params.amplitude = 0.5f; - params.attack_sec = 0.01f; - params.decay_sec = 0.0f; - params.vibrato_rate = 0.0f; - params.vibrato_depth = 0.0f; - params.num_harmonics = 1; - params.harmonic_decay = 1.0f; - params.pitch_randomness = 0.0f; - params.amp_randomness = 0.0f; + NoteParams params; + params.base_freq = 440.0f; + params.duration_sec = 0.1f; // ~3 frames + params.amplitude = 0.5f; + params.attack_sec = 0.01f; + params.decay_sec = 0.0f; + params.vibrato_rate = 0.0f; + params.vibrato_depth = 0.0f; + params.num_harmonics = 1; + params.harmonic_decay = 1.0f; + params.pitch_randomness = 0.0f; + params.amp_randomness = 0.0f; - int num_frames = 0; - std::vector data = generate_note_spectrogram(params, &num_frames); + int num_frames = 0; + std::vector data = generate_note_spectrogram(params, &num_frames); - assert(num_frames > 0); - assert(data.size() == (size_t)num_frames * DCT_SIZE); - - // Check if data is not all zero - bool non_zero = false; - for (float v : data) { - if (std::abs(v) > 1e-6f) { - non_zero = true; - break; - } + assert(num_frames > 0); + assert(data.size() == (size_t)num_frames * DCT_SIZE); + + // Check if data is not all zero + bool non_zero = false; + for (float v : data) { + if (std::abs(v) > 1e-6f) { + non_zero = true; + break; } - assert(non_zero); + } + assert(non_zero); } void test_paste() { - std::vector dest; - int dest_frames = 0; - std::vector src(DCT_SIZE * 2, 1.0f); // 2 frames of 1.0s - - paste_spectrogram(dest, &dest_frames, src, 2, 0); - assert(dest_frames == 2); - assert(dest.size() == 2 * DCT_SIZE); - assert(dest[0] == 1.0f); + std::vector dest; + int dest_frames = 0; + std::vector src(DCT_SIZE * 2, 1.0f); // 2 frames of 1.0s + + paste_spectrogram(dest, &dest_frames, src, 2, 0); + assert(dest_frames == 2); + assert(dest.size() == 2 * DCT_SIZE); + assert(dest[0] == 1.0f); - // Paste with offset - paste_spectrogram(dest, &dest_frames, src, 2, 1); - // Dest was 2 frames. We paste 2 frames at offset 1. - // Result should be 1 + 2 = 3 frames. - assert(dest_frames == 3); - assert(dest.size() == 3 * DCT_SIZE); - // Overlap at frame 1: 1.0 + 1.0 = 2.0 - assert(dest[DCT_SIZE] == 2.0f); - // Frame 2: 0.0 (original) + 1.0 (new) = 1.0 - assert(dest[2 * DCT_SIZE] == 1.0f); + // Paste with offset + paste_spectrogram(dest, &dest_frames, src, 2, 1); + // Dest was 2 frames. We paste 2 frames at offset 1. + // Result should be 1 + 2 = 3 frames. + assert(dest_frames == 3); + assert(dest.size() == 3 * DCT_SIZE); + // Overlap at frame 1: 1.0 + 1.0 = 2.0 + assert(dest[DCT_SIZE] == 2.0f); + // Frame 2: 0.0 (original) + 1.0 (new) = 1.0 + assert(dest[2 * DCT_SIZE] == 1.0f); } void test_filters() { - int num_frames = 1; - std::vector data(DCT_SIZE, 1.0f); + int num_frames = 1; + std::vector data(DCT_SIZE, 1.0f); - // Lowpass - apply_spectral_lowpass(data, num_frames, 0.5f); - // Bins >= 256 should be 0 - assert(data[0] == 1.0f); - assert(data[DCT_SIZE - 1] == 0.0f); - assert(data[256] == 0.0f); - assert(data[255] == 1.0f); // Boundary check + // Lowpass + apply_spectral_lowpass(data, num_frames, 0.5f); + // Bins >= 256 should be 0 + assert(data[0] == 1.0f); + assert(data[DCT_SIZE - 1] == 0.0f); + assert(data[256] == 0.0f); + assert(data[255] == 1.0f); // Boundary check - // Comb - data.assign(DCT_SIZE, 1.0f); - apply_spectral_comb(data, num_frames, 10.0f, 1.0f); - // Just check modification - assert(data[0] != 1.0f || data[1] != 1.0f); // It should change values + // Comb + data.assign(DCT_SIZE, 1.0f); + apply_spectral_comb(data, num_frames, 10.0f, 1.0f); + // Just check modification + assert(data[0] != 1.0f || data[1] != 1.0f); // It should change values - // Noise - data.assign(DCT_SIZE, 1.0f); - srand(42); - apply_spectral_noise(data, num_frames, 0.5f); - // Should be noisy - assert(data[0] != 1.0f); + // Noise + data.assign(DCT_SIZE, 1.0f); + srand(42); + apply_spectral_noise(data, num_frames, 0.5f); + // Should be noisy + assert(data[0] != 1.0f); } int main() { - std::cout << "Running Audio Gen tests..." << std::endl; - test_generate_note(); - test_paste(); - test_filters(); - std::cout << "Audio Gen tests PASSED" << std::endl; - return 0; + std::cout << "Running Audio Gen tests..." << std::endl; + test_generate_note(); + test_paste(); + test_filters(); + std::cout << "Audio Gen tests PASSED" << std::endl; + return 0; } -- cgit v1.2.3