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_maths.cc | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) (limited to 'src/tests/test_maths.cc') diff --git a/src/tests/test_maths.cc b/src/tests/test_maths.cc index ffc56f2..0fed85c 100644 --- a/src/tests/test_maths.cc +++ b/src/tests/test_maths.cc @@ -49,7 +49,8 @@ template void test_vector_ops(int n) { // Normalize zero vector T zero_vec = T(); // Default construct to zero T norm_zero = zero_vec.normalize(); - for(int i = 0; i < n; ++i) assert(near(norm_zero[i], 0.0f)); + for (int i = 0; i < n; ++i) + assert(near(norm_zero[i], 0.0f)); // Lerp T l = lerp(a, b, 0.3f); @@ -82,17 +83,18 @@ void test_quat() { assert(near(r.x, 0) && near(r.z, -1)); // Rotation edge cases: 0 deg, 180 deg, zero vector - quat zero_rot = quat::from_axis({1,0,0}, 0.0f); + quat zero_rot = quat::from_axis({1, 0, 0}, 0.0f); vec3 rotated_zero = zero_rot.rotate(v); assert(near(rotated_zero.x, 1.0f)); // Original vector - quat half_pi_rot = quat::from_axis({0,1,0}, 3.14159f); // 180 deg Y + quat half_pi_rot = quat::from_axis({0, 1, 0}, 3.14159f); // 180 deg Y vec3 rotated_half_pi = half_pi_rot.rotate(v); assert(near(rotated_half_pi.x, -1.0f)); // Rotated 180 deg around Y - vec3 zero_vec(0,0,0); + vec3 zero_vec(0, 0, 0); vec3 rotated_zero_vec = q.rotate(zero_vec); - assert(near(rotated_zero_vec.x, 0.0f) && near(rotated_zero_vec.y, 0.0f) && near(rotated_zero_vec.z, 0.0f)); + assert(near(rotated_zero_vec.x, 0.0f) && near(rotated_zero_vec.y, 0.0f) && + near(rotated_zero_vec.z, 0.0f)); // Look At // Looking from origin to +X, with +Y as up. @@ -109,13 +111,16 @@ void test_quat() { // Slerp edge cases quat slerp_mid_edge = slerp(q1, q2, 0.0f); - assert(near(slerp_mid_edge.w, q1.w) && near(slerp_mid_edge.x, q1.x) && near(slerp_mid_edge.y, q1.y) && near(slerp_mid_edge.z, q1.z)); + assert(near(slerp_mid_edge.w, q1.w) && near(slerp_mid_edge.x, q1.x) && + near(slerp_mid_edge.y, q1.y) && near(slerp_mid_edge.z, q1.z)); slerp_mid_edge = slerp(q1, q2, 1.0f); - assert(near(slerp_mid_edge.w, q2.w) && near(slerp_mid_edge.x, q2.x) && near(slerp_mid_edge.y, q2.y) && near(slerp_mid_edge.z, q2.z)); + assert(near(slerp_mid_edge.w, q2.w) && near(slerp_mid_edge.x, q2.x) && + near(slerp_mid_edge.y, q2.y) && near(slerp_mid_edge.z, q2.z)); // FromTo - quat from_to_test = quat::from_to({1,0,0}, {0,1,0}); // 90 deg rotation around Z - vec3 rotated = from_to_test.rotate({1,0,0}); + quat from_to_test = + quat::from_to({1, 0, 0}, {0, 1, 0}); // 90 deg rotation around Z + vec3 rotated = from_to_test.rotate({1, 0, 0}); assert(near(rotated.y, 1.0f)); } @@ -172,8 +177,10 @@ void test_ease() { assert(near(ease::out_expo(1.0f), 1.0f)); // Midpoint/Logic tests - assert(ease::out_cubic(0.5f) > 0.5f); // Out curves should exceed linear value early - assert(near(ease::in_out_quad(0.5f), 0.5f)); // Symmetric curves hit 0.5 at 0.5 + assert(ease::out_cubic(0.5f) > + 0.5f); // Out curves should exceed linear value early + assert( + near(ease::in_out_quad(0.5f), 0.5f)); // Symmetric curves hit 0.5 at 0.5 assert(ease::out_expo(0.5f) > 0.5f); // Exponential out should be above linear } @@ -187,7 +194,8 @@ void test_spring() { assert(p > 8.5f); // Should be close to 10 after 1 sec // Test convergence over longer period - p = 0; v = 0; + p = 0; + v = 0; for (int i = 0; i < 200; ++i) spring::solve(p, v, 10.0f, 0.5f, 0.016f); assert(near(p, 10.0f, 0.1f)); // Should be very close to target @@ -264,7 +272,8 @@ void test_matrix_inversion() { mat4 singular_scale; singular_scale.m[5] = 0.0f; // Scale Y by zero, making it singular mat4 singular_inv = singular_scale.inverse(); - // The inverse of a singular matrix should be the identity matrix as per the implementation + // The inverse of a singular matrix should be the identity matrix as per the + // implementation check_identity(singular_inv); } -- cgit v1.2.3