feat(test_demo): Add fine-grained peak logging at frame resolution

Adds --log-peaks-fine option to log audio peaks at every frame (~60 Hz)
instead of just at beat boundaries, enabling millisecond-resolution
synchronization analysis.

Features:
- --log-peaks-fine flag for per-frame logging
- Logs ~960 samples over 16 seconds (vs 32 for beat-aligned)
- Header indicates logging mode (beat-aligned vs fine)
- Frame number instead of beat number in fine mode
- Updated gnuplot command (using column 2 for time)

Use cases:
- Millisecond-resolution synchronization debugging
- Frame-level timing jitter detection
- Audio envelope analysis (attack/decay characteristics)
- Sub-beat artifact identification

Example usage:
  build/test_demo --log-peaks peaks.txt --log-peaks-fine

The fine mode provides approximately 16.67ms resolution (60 Hz) compared
to 500ms resolution (beat boundaries at 120 BPM).

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

1 files changed, 54 insertions, 8 deletions

diff --git a/test_demo_README.md b/test_demo_README.md
index f84f972..b8abfc2 100644
--- a/test_demo_README.md
+++ b/test_demo_README.md
@@ -34,7 +34,9 @@ build/test_demo
   --fullscreen        Run in fullscreen mode
   --resolution WxH    Set window resolution (e.g., 1024x768)
   --tempo             Enable tempo variation test mode
-  --log-peaks FILE    Log audio peaks to FILE for gnuplot visualization
+  --log-peaks FILE    Log audio peaks at each beat (32 samples for 16s)
+  --log-peaks-fine    Log at each frame for fine analysis (~960 samples)
+                      (use with --log-peaks for millisecond resolution)
 ```
 
 ### Examples
@@ -49,16 +51,23 @@ build/test_demo --fullscreen
 build/test_demo --resolution 1024x768 --tempo
 ```
 
-#### Log audio peaks for analysis
+#### Log audio peaks for analysis (beat-aligned)
 ```bash
 build/test_demo --log-peaks peaks.txt
 ```
 
 After running, visualize with gnuplot:
 ```bash
-gnuplot -p -e "set xlabel 'Time (s)'; set ylabel 'Peak'; plot 'peaks.txt' using 1:3 with lines title 'Raw Peak'"
+gnuplot -p -e "set xlabel 'Time (s)'; set ylabel 'Peak'; plot 'peaks.txt' using 2:3 with lines title 'Raw Peak'"
 ```
 
+#### Log audio peaks with fine resolution (every frame)
+```bash
+build/test_demo --log-peaks peaks_fine.txt --log-peaks-fine
+```
+
+This logs at ~60 Hz (every frame) instead of every beat, providing millisecond-resolution data for detailed synchronization analysis. Produces ~960 samples for the 16-second demo.
+
 ## Keyboard Controls
 
 - **ESC**: Exit the demo
@@ -109,12 +118,17 @@ This tests the variable tempo system where music time advances independently of
 
 ## Peak Logging Format
 
-The `--log-peaks` option writes a text file with three columns:
+The `--log-peaks` option writes a text file with three columns.
+
+### Beat-Aligned Mode (default)
+
+Logs once per beat (32 samples for 16 seconds):
 
 ```
 # Audio peak log from test_demo
+# Mode: beat-aligned
 # To plot with gnuplot:
-#   gnuplot -p -e "set xlabel 'Time (s)'; set ylabel 'Peak'; plot 'peaks.txt' using 1:3 with lines title 'Raw Peak'"
+#   gnuplot -p -e "set xlabel 'Time (s)'; set ylabel 'Peak'; plot 'peaks.txt' using 2:3 with lines title 'Raw Peak'"
 # Columns: beat_number clock_time raw_peak
 #
 0 0.000000 0.850000
@@ -128,12 +142,44 @@ The `--log-peaks` option writes a text file with three columns:
 2. **clock_time**: Physical time in seconds
 3. **raw_peak**: Audio peak value (0.0-1.0+)
 
+### Fine-Grained Mode (`--log-peaks-fine`)
+
+Logs at every frame (approximately 960 samples for 16 seconds at 60 Hz):
+
+```
+# Audio peak log from test_demo
+# Mode: fine (per-frame)
+# To plot with gnuplot:
+#   gnuplot -p -e "set xlabel 'Time (s)'; set ylabel 'Peak'; plot 'peaks_fine.txt' using 2:3 with lines title 'Raw Peak'"
+# Columns: frame_number clock_time raw_peak
+#
+0 0.000000 0.850000
+1 0.016667 0.845231
+2 0.033333 0.823445
+3 0.050000 0.802891
+...
+```
+
+**Columns:**
+1. **frame_number**: Frame index (0, 1, 2, ...)
+2. **clock_time**: Physical time in seconds (millisecond precision)
+3. **raw_peak**: Audio peak value (0.0-1.0+)
+
 **Use Cases:**
-- Verify audio/visual synchronization timing
-- Detect clipping (peak > 1.0)
-- Analyze tempo scaling effects
+
+*Beat-Aligned Mode:*
+- Verify audio/visual synchronization at beat boundaries
+- Detect clipping at specific beats (peak > 1.0)
+- Analyze tempo scaling effects on pattern triggering
 - Compare expected vs actual beat times
 
+*Fine-Grained Mode:*
+- Millisecond-resolution synchronization analysis
+- Detect frame-level timing jitter or drift
+- Analyze audio envelope shape and attack/decay characteristics
+- Debug precise flash-to-audio alignment issues
+- Identify sub-beat audio artifacts or glitches
+
 ## Files
 
 - **`src/test_demo.cc`**: Main executable (~220 lines)