From 8ddf99789e0ff54bc51b5b517c42f40a6d40d2a4 Mon Sep 17 00:00:00 2001 From: skal Date: Wed, 4 Feb 2026 14:42:02 +0100 Subject: docs: Update project state with event-based tracker and WAV dump Updated PROJECT_CONTEXT.md and TODO.md to reflect recent milestones: PROJECT_CONTEXT.md changes: - Updated Audio section: stereo format, variable tempo, event-based triggering - Added milestone for "Event-Based Tracker for Tempo Scaling" - Added milestone for "WAV Dump Backend for Debugging" - Updated Audio Engine architecture section with new details - Updated test counts (17/17 passing) TODO.md changes: - Added "Event-Based Tracker for Tempo Scaling" to Recently Completed * Refactored from pattern compositing to individual event triggering * Dynamic beat calculation enables notes to respect tempo scaling * ActivePattern tracking with start_music_time and next_event_idx * All 17 tests pass, WAV dump confirms correct behavior - Added "WAV Dump Backend for Debugging" to Recently Completed * WavDumpBackend for offline rendering to .wav files * Fixed critical stereo format bug (mono/stereo mismatch) * Added regression test with stereo format assertion * Command-line option: --dump_wav output.wav Current State: - All tests passing: 17/17 (100%) - Audio system: Stereo, variable tempo, event-based tracking - Documentation: Up to date with latest architecture Ready for handoff to Gemini. Co-Authored-By: Claude Sonnet 4.5 --- PROJECT_CONTEXT.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'PROJECT_CONTEXT.md') diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index ba66bf4..46ea725 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -10,9 +10,11 @@ Graphics: - Hybrid rendering: Rasterized proxy geometry + SDF raymarching Audio: -- 32 kHz, 16-bit mono +- 32 kHz, 16-bit stereo - Procedurally generated samples - Real-time additive synthesis from spectrograms (IDCT) +- Variable tempo system with music time abstraction +- Event-based pattern triggering for dynamic tempo scaling - Modifiable Loops and Patterns, w/ script to generate them (like a Tracker) Constraints: @@ -30,9 +32,13 @@ Style: ### Recently Completed #### Milestone: Audio System Robustness & Variable Tempo (February 4, 2026) +- **Event-Based Tracker for Tempo Scaling**: Refactored tracker system from pattern compositing to individual event triggering. Previously, pattern events were baked into single spectrograms at fixed positions, so tempo scaling only affected pattern trigger timing. Now each TrackerEvent triggers as a separate voice with timing calculated dynamically based on music_time. Result: Notes within patterns correctly accelerate/decelerate with tempo changes. At 2.0x tempo, both pattern triggering AND note spacing play 2x faster. Verified with WAV dump showing 61.24s music time in 60s physical time during tempo transitions. All 17 tests pass (100%). + +- **WAV Dump Backend for Debugging**: Added `WavDumpBackend` implementing `AudioBackend` interface to render audio offline to .wav files instead of playing on device. Enabled via `--dump_wav output.wav` flag. Critical bug fix: Synth outputs STEREO (interleaved L/R) but initial implementation wrote MONO, causing severe distortion. Fixed by allocating `frames * 2` samples and writing stereo format (num_channels = 2). Added regression test (`test_wav_dump.cc`) with critical assertion `assert(header.num_channels == 2)` to prevent future mono/stereo mismatches. WAV format now matches live audio exactly: 16-bit PCM, stereo, 32kHz. + - **Variable Tempo System**: Implemented unified music time abstraction in `main.cc` that decouples tracker timing from physical time. Music time advances at configurable `tempo_scale` rate (default 1.0), enabling dynamic tempo changes without pitch shifting. Created comprehensive test suite (`test_variable_tempo.cc`) verifying 2x speed-up and 2x slow-down "reset tricks" work perfectly. All 6 test scenarios pass with mathematical precision. System ready for expressive tempo control in demo with zero size impact. -- **Task #51: Tracker Timing Verification System**: Created robust audio testing infrastructure with mock backend abstraction. Implemented `AudioBackend` interface separating synthesis from output, `MiniaudioBackend` for production, and `MockAudioBackend` for testing. Added event recording with precise timestamp tracking (32kHz sample rate). Created comprehensive test suite (`test_tracker_timing.cc`) that **verified simultaneous pattern triggers have 0.000ms delta** (perfect synchronization). All test infrastructure under `#if !defined(STRIP_ALL)` for zero production impact. 16/16 tests passing. +- **Task #51: Tracker Timing Verification System**: Created robust audio testing infrastructure with mock backend abstraction. Implemented `AudioBackend` interface separating synthesis from output, `MiniaudioBackend` for production, and `MockAudioBackend` for testing. Added event recording with precise timestamp tracking (32kHz sample rate). Created comprehensive test suite (`test_tracker_timing.cc`) that **verified simultaneous pattern triggers have 0.000ms delta** (perfect synchronization). All test infrastructure under `#if !defined(STRIP_ALL)` for zero production impact. 17/17 tests passing. - **Task #50: WGSL Modularization**: Updated `ShaderComposer` to support recursive `#include` directives, refactored the entire shader library into granular snippets (shapes, utils, lighting), and updated the 3D renderer to use this modular system. This resolved macOS shader compilation issues and significantly improved shader maintainability. - **Task #48: Improve Audio Coverage**: Achieved 93% coverage for `src/audio/` by adding dedicated tests for DCT transforms, procedural generation, and synthesis rendering. @@ -102,7 +108,10 @@ Style: - **Automation**: `gen_assets.sh`, `build_win.sh`, and `check_all.sh` for multi-platform validation. ### Audio Engine -- **Synthesis**: Real-time additive synthesis from spectrograms via IDCT. +- **Synthesis**: Real-time additive synthesis from spectrograms via IDCT. Stereo output (32kHz, 16-bit, interleaved L/R). +- **Variable Tempo**: Music time abstraction with configurable tempo_scale. Tempo changes don't affect pitch. +- **Event-Based Tracker**: Individual TrackerEvents trigger as separate voices with dynamic beat calculation. Notes within patterns respect tempo scaling. +- **Backend Abstraction**: `AudioBackend` interface with `MiniaudioBackend` (production), `MockAudioBackend` (testing), and `WavDumpBackend` (offline rendering). - **Dynamic Updates**: Double-buffered spectrograms for live thread-safe updates. - **Procedural Library**: Melodies and spectral filters (noise, comb) generated at runtime. -- **Pattern and loop**: spectrograms grouped as pattern and loops, and modifiers can be applied to loops (randomize, accents, etc.) \ No newline at end of file +- **Pattern System**: TrackerPatterns contain lists of TrackerEvents (beat, sample_id, volume, pan). Events trigger individually based on elapsed music time. \ No newline at end of file -- cgit v1.2.3