From f28aef533e039def7c356ecac2dd0f45c6114209 Mon Sep 17 00:00:00 2001 From: skal Date: Sat, 7 Feb 2026 08:51:29 +0100 Subject: docs: Document test_demo milestone and recent project state Updates PROJECT_CONTEXT.md with recently completed work (February 7, 2026): **test_demo - Audio/Visual Sync Debug Tool:** - Standalone minimal executable for sync debugging - Drum beat with NOTE_A4 reference tone (440 Hz) - Variable tempo mode (--tempo) for music time testing - Peak logging: beat-aligned and fine-grained (~960 samples) - Command-line options: --help, --fullscreen, --resolution, --log-peaks - Error handling for invalid options - 220 lines of code, comprehensive documentation - Use cases: millisecond-precision sync verification, timing jitter detection **CMake Configuration Summary:** - Formatted display of all build options (ON/OFF status) - Shows build type and compiler information - Improves developer experience and debugging **Code Quality:** - Fixed deprecated sprintf warning in asset_packer.cc - Replaced with snprintf for buffer safety This captures the current stable state of the project with the new debug tooling infrastructure in place. Co-Authored-By: Claude Sonnet 4.5 --- PROJECT_CONTEXT.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 7fcef97..e5adfb6 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -32,6 +32,13 @@ Style: ### Recently Completed +#### Milestone: test_demo - Audio/Visual Sync Debug Tool (February 7, 2026) 🎯 +- **Standalone Debug Tool**: Created minimal test executable for debugging audio/visual synchronization and variable tempo system without full demo complexity. **Core Features**: Simple drum beat (kick-snare) with crash landmarks at bars 3 and 7, NOTE_A4 (440 Hz) reference tone at start of each bar for testing, screen flash effect synchronized to audio peaks, 16 second duration (8 bars at 120 BPM). **Variable Tempo Mode**: `--tempo` flag enables alternating tempo scaling (even bars: 1.0x → 1.5x acceleration, odd bars: 1.0x → 0.66x deceleration) to test music time vs physical time system. **Peak Logging**: `--log-peaks FILE` exports audio peak data for gnuplot visualization, `--log-peaks-fine` adds millisecond-resolution per-frame logging (~960 samples vs 32 beat-aligned samples). **Command-Line Options**: `--help` shows usage, `--fullscreen` for fullscreen mode, `--resolution WxH` for custom window size. **Error Handling**: Unknown options print error message and help text before exiting with status 1. **File Structure**: `src/test_demo.cc` (main executable, ~220 lines), `assets/test_demo.track` (drum patterns with NOTE_A4), `assets/test_demo.seq` (visual timeline), `test_demo_README.md` (comprehensive documentation). **Peak Log Format**: Beat-aligned mode logs at beat boundaries (32 samples), fine-grained mode logs every frame with beat_number column for correlation. **Build Integration**: CMake target with timeline/music generation, proper dependencies, size optimizations. **Use Cases**: Verify millisecond-precision sync, detect timing jitter, analyze tempo scaling effects, debug flash-to-audio alignment. **Impact**: Provides isolated testing environment for sync verification without demo64k complexity, enables data-driven analysis via exported logs. + +- **CMake Configuration Summary**: Added formatted configuration summary to CMake output displaying all build options (DEMO_SIZE_OPT, DEMO_STRIP_ALL, DEMO_BUILD_TESTS, etc.) with ON/OFF status, build type, and compiler information. Appears automatically at end of `cmake` command for easy verification of enabled options. + +- **Code Quality Fixes**: Replaced deprecated `std::sprintf` with `std::snprintf` in `asset_packer.cc` to eliminate compiler warnings and add buffer overflow protection during OBJ mesh vertex key generation. + #### Milestone: Audio Playback Stability & Debug Infrastructure (February 4, 2026) - **Core Audio Backend Optimization**: Resolved critical audio playback issues (stop-and-go, glitches, eventual silence) caused by timing mismatches in miniaudio's Core Audio backend. Root cause: Core Audio optimized for 44.1kHz with 10ms periods, but our 32kHz system expected uniform ~13.78ms callbacks, causing resampling jitter. Fix: Added `allowNominalSampleRateChange = TRUE` to force OS-level 32kHz native and `performanceProfile = conservative` for larger buffers (4096 frames = 128ms). Result: Stable ~128ms callbacks with <1ms jitter, zero underruns during variable tempo (1.0x → 2.0x). -- cgit v1.2.3