# test_demo - Audio/Visual Sync Debug Tool

Minimal standalone tool for debugging audio/visual synchronization.

## Features
- Kick-snare drum pattern with crash every 4th bar
- NOTE_A4 reference tone (440 Hz) at bar starts
- Screen flash synchronized to audio peaks
- 16 seconds (8 bars at 120 BPM)
- Variable tempo mode (1.0x ↔ 1.5x / 0.66x)
- Peak logging for gnuplot

## Building
```bash
cmake --build build --target test_demo
```

## Usage

### Basic
```bash
build/test_demo
```

### Command-Line Options
```
--help              Show help
--fullscreen        Fullscreen mode
--resolution WxH    Window size (e.g., 1024x768)
--tempo             Enable tempo variation
--log-peaks FILE    Log audio peaks (beat-aligned)
--log-peaks-fine    Log per-frame (~960 samples)
```

### Examples
```bash
# Fullscreen
build/test_demo --fullscreen

# Tempo test
build/test_demo --tempo

# Peak logging
build/test_demo --log-peaks peaks.txt
gnuplot -p -e "plot 'peaks.txt' using 2:3 with lines"

# Fine-grained logging
build/test_demo --log-peaks peaks_fine.txt --log-peaks-fine
```

**Keyboard:** `Esc` (exit), `F` (toggle fullscreen)

## Audio Pattern
8 bars, 120 BPM:
- Bars 1-2, 4-6, 8: Kick-Snare-Kick-Snare + A4 tone
- Bars 3, 7: Kick+Crash-Snare-Kick-Snare + A4 tone (landmarks)

**Crash landmarks:** T=4.0s (bar 3), T=12.0s (bar 7)

## Tempo Mode
Alternates every bar:
- Even bars: 1.0x → 1.5x (accelerate)
- Odd bars: 1.0x → 0.66x (decelerate)

Music time drifts from physical time. Patterns respect tempo scaling.

## Peak Logging

**Beat-aligned** (32 samples):
```
# Columns: beat_number clock_time raw_peak
0 0.000000 0.850000
1 0.500000 0.720000
```

**Fine-grained** (~960 samples):
```
# Columns: frame_number clock_time raw_peak beat_number
0 0.000000 0.850000 0
1 0.016667 0.845231 0
```

**Use cases:**
- Beat-aligned: Verify sync at beat boundaries, detect clipping
- Fine-grained: Millisecond-resolution analysis, detect jitter

## Files
- `src/test_demo.cc`: Main executable (~220 lines)
- `assets/test_demo.track`: Drum pattern
- `assets/test_demo.seq`: Visual timeline
- `src/generated/test_demo_*.cc`: Generated code

## Verification

**Normal mode:**
- Flashes every ~0.5s, synchronized with kicks
- Crash landmarks at T=4.0s and T=12.0s
- No audio glitches

**Tempo mode:**
- Bar 0 accelerates, bar 1 decelerates
- Music time drifts from physical time
- Smooth transitions

**Peak logging:**
- File created with correct format
- Gnuplot visualization works

## Troubleshooting

**Flash before audio:** Reduce ring buffer size (`ring_buffer.h`)
**Flash after audio:** Increase pre-fill (`audio_render_ahead()`)
**No flash:** Increase `visual_peak` multiplier (currently 8.0×)
**A4 not audible:** Increase volume in `test_demo.track`
**Empty log:** Ensure demo runs ≥0.5s

## Design Rationale

**Why separate?** Isolated testing, no timeline complexity
**Why 16 seconds?** Long enough to verify, short enough to iterate
**Why NOTE_A4?** Standard 440 Hz reference tone
**Why crash landmarks?** Easy visual/audio synchronization verification