| Age | Commit message (Collapse) | Author |
|---|
|
Changes tracker timing from beat-based to unit-less system to separate
musical structure from BPM-dependent playback speed.
TIMING CONVENTION:
- 1 unit = 4 beats (by convention)
- Conversion: seconds = units * (4 / BPM) * 60
- At 120 BPM: 1 unit = 2 seconds
BENEFITS:
- Pattern structure independent of BPM
- BPM changes only affect playback speed, not structure
- Easier pattern composition (0.00-1.00 for typical 4-beat pattern)
- Fixes issue where patterns played for 2s instead of expected duration
DATA STRUCTURES (tracker.h):
- TrackerEvent.beat → TrackerEvent.unit_time
- TrackerPattern.num_beats → TrackerPattern.unit_length
- TrackerPatternTrigger.time_sec → TrackerPatternTrigger.unit_time
RUNTIME (tracker.cc):
- Added BEATS_PER_UNIT constant (4.0)
- Convert units to seconds at playback time using BPM
- Pattern remains active for full unit_length duration
- Fixed premature pattern deactivation bug
COMPILER (tracker_compiler.cc):
- Parse LENGTH parameter from PATTERN lines (defaults to 1.0)
- Parse unit_time instead of beat values
- Generate code with unit-less timing
ASSETS:
- test_demo.track: converted to unit-less (8 score triggers)
- music.track: converted to unit-less (all patterns)
- Events: beat/4 conversion (e.g., beat 2.0 → unit 0.50)
- Score: seconds/unit_duration (e.g., 4s → 2.0 units at 120 BPM)
VISUALIZER (track_visualizer/index.html):
- Parse LENGTH parameter and BPM directive
- Convert unit-less time to seconds for rendering
- Update tick positioning to use unit_time
- Display correct pattern durations
DOCUMENTATION (doc/TRACKER.md):
- Added complete .track format specification
- Timing conversion reference table
- Examples with unit-less timing
- Pattern LENGTH parameter documentation
FILES MODIFIED:
- src/audio/tracker.{h,cc} (data structures + runtime conversion)
- tools/tracker_compiler.cc (parser + code generation)
- assets/{test_demo,music}.track (converted to unit-less)
- tools/track_visualizer/index.html (BPM-aware rendering)
- doc/TRACKER.md (format documentation)
- convert_track.py (conversion utility script)
TEST RESULTS:
- test_demo builds and runs correctly
- demo64k builds successfully
- Generated code verified (unit-less values in music_data.cc)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
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 <noreply@anthropic.com>
|
|
Refactored tracker system to trigger individual events as separate voices
instead of compositing patterns into single spectrograms. This enables
notes within patterns to respect tempo scaling dynamically.
Key Changes:
- Added ActivePattern tracking with start_music_time and next_event_idx
- Individual events trigger when their beat time is reached
- Elapsed beats calculated dynamically: (music_time - start_time) / beat_duration
- Removed pattern compositing logic (paste_spectrogram)
- Each note now triggers as separate voice with volume/pan parameters
Behavior:
- Tempo scaling (via music_time) now affects note spacing within patterns
- At 2.0x tempo: patterns trigger 2x faster AND notes within play 2x faster
- At 0.5x tempo: patterns trigger 2x slower AND notes within play 2x slower
Testing:
- Updated test_tracker to verify event-based triggering at specific beat times
- All 17 tests pass (100%)
- WAV dump confirms tempo scaling works correctly:
* 0-10s: steady 1.00x tempo
* 10-15s: acceleration to 2.00x tempo
* 15-20s: reset to 1.00x tempo
* 20-25s: deceleration to 0.50x tempo
* 25s+: return to normal
Result: Music time advances at variable rates (61.24s in 60s physical time),
and notes within patterns correctly accelerate/decelerate with tempo changes.
handoff(Claude): Tempo scaling now affects notes within patterns
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
|
|
|
- Implemented the basic tracker system with runtime support (tracker.h, tracker.cc).
- Added a sample music track file (assets/music.track).
- Created a tracker compiler tool (tools/tracker_compiler.cc) to generate music data.
- Updated CMakeLists.txt to build the tracker compiler and integrate generated data.
- Updated GEMINI.md to reflect new file locations and project context.
|
