📊 AudioLab Routing Overview - Complete Visual Guide¶
Purpose: Ultra-clear visual diagrams showing every step of audio flow from code to speakers. Target Audience: New developers confused by audio routing complexity. Last Updated: 2025-10-03
📑 Table of Contents¶
- Complete Audio Flow
- Development Testing Routing
- Latency Breakdown
- Multi-DAW Testing Setup
- Compatibility Matrix
📊 DIAGRAM 1: COMPLETE AUDIO FLOW¶
Visual Overview¶
🎹 MIDI INPUT 🎧 AUDIO OUTPUT
Controller/Keyboard Studio Monitors
│ ▲
│ USB/MIDI DIN │ XLR/TRS
│ │
▼ │
┌─────────────────────────────────┐ ┌──────────────────────┐
│ DAW HOST │ │ AUDIO INTERFACE │
│ (Reaper/Cubase/Live) │ │ RME/UA/Focusrite │
│ │ │ │
│ ┌───────────────────────────┐ │ │ ┌────────────────┐ │
│ │ Plugin Slot #1 │ │ │ │ ASIO Driver │ │
│ │ │ │ │ │ (Windows) │ │
│ │ ┌─────────────────┐ │ │ │ │ │ │
│ │ │ AudioLab │ │ │ Processed │ │ CoreAudio │ │
│ │ │ Plugin │ │ │──Audio Buffer────►│ │ (macOS) │ │
│ │ │ (VST3/AU) │ │ │ 44.1/48kHz │ │ │ │
│ │ │ │ │ │ 64-512 samples │ │ Buffer Size: │ │
│ │ │ processBlock() │ │ │ │ │ 128 samples │ │
│ │ │ ↓ │ │ │ │ │ │ │
│ │ │ DSP Chain │ │ │ │ │ Latency: │ │
│ │ │ ↓ │ │ │ │ │ ~3ms │ │
│ │ │ Output Mix │ │ │ │ └────────┬───────┘ │
│ │ └─────────────────┘ │ │ │ │ │
│ │ │ │ │ ▼ │
│ └───────────────────────────┘ │ │ ┌────────────────┐ │
│ │ │ │ D/A Converter │ │
│ Host Features: │ │ │ 24-bit/192kHz │ │
│ • Real-time thread priority │ │ └────────┬───────┘ │
│ • Buffer management │ │ │ │
│ • Latency compensation │ └───────────┼──────────┘
│ • Parameter automation │ │
│ • State save/recall │ ▼
└─────────────────────────────────┘ Analog Output
│
▼
┌─────────────────────────────────┐ [🔊 Speakers]
│ VIRTUAL ROUTING (Dev/Testing) │
│ • VoiceMeeter Banana │
│ • Audio Hijack (macOS) │
│ • JACK Audio (Linux) │
│ • Loopback (macOS) │
└─────────────────────────────────┘
Component Details¶
🎹 MIDI INPUT¶
- Types Supported:
- USB MIDI controllers (Akai, Novation, Arturia)
- Traditional MIDI DIN (via interface)
- Virtual MIDI ports (loopMIDI, IAC Driver)
-
DAW internal MIDI routing
-
Typical Latency: <1ms
- USB MIDI: 0.5-1ms
- DIN MIDI: 1-2ms (physical cable overhead)
-
Virtual: <0.1ms (software only)
-
Message Format:
-
DAW Configuration:
- Input device selection: Preferences → MIDI Devices
- Channel routing: Track input selector
- MIDI learn: Right-click parameter → Learn
🖥️ DAW HOST¶
Role: Audio engine and plugin host container
Buffer Management: | Buffer Size | Latency @ 48kHz | Use Case | |-------------|-----------------|----------| | 64 samples | ~1.3ms | Live performance, low CPU | | 128 samples | ~2.7ms | Recording, balanced | | 256 samples | ~5.3ms | Mixing, more plugins | | 512 samples | ~10.7ms | Mastering, maximum stability |
Sample Rate Options: - 44.1kHz: CD quality, standard - 48kHz: Video standard, pro audio default - 96kHz: High-resolution, double processing cost - 192kHz: Mastering grade, 4× processing cost
Thread Model:
┌─────────────────────────────────────┐
│ GUI Thread (60Hz updates) │ ← Parameter changes
│ - Meter drawing │ ← Visual feedback
│ - User interaction │
└──────────────┬──────────────────────┘
│ Message Queue
▼
┌─────────────────────────────────────┐
│ Audio Thread (Real-time) │ ← HIGHEST PRIORITY
│ - processBlock() calls │ ← NO memory allocation
│ - Buffer processing │ ← NO disk I/O
│ - Plugin chain execution │ ← Lock-free atomics only
└─────────────────────────────────────┘
Critical Rules: - ⚠️ NEVER allocate memory in audio thread - ⚠️ NEVER use mutexes/locks in audio thread - ⚠️ NEVER call file I/O in audio thread - ✅ DO use lock-free FIFOs for inter-thread communication - ✅ DO pre-allocate all buffers in constructor
🔌 PLUGIN (AudioLab)¶
Format Support:
VST3 (Steinberg)
├─ Windows: .vst3 bundle
├─ macOS: .vst3 bundle
└─ Linux: .vst3 bundle
AU (Apple)
└─ macOS only: .component bundle
AAX (Avid)
├─ Windows: .aaxplugin
└─ macOS: .aaxplugin
Processing Modes: | Mode | Input | Output | Use Case | |------|-------|--------|----------| | Mono | 1 | 1 | Vocal processing, bass | | Stereo | 2 | 2 | Mix bus, mastering | | Mono→Stereo | 1 | 2 | Reverb, stereo widener | | Surround 5.1 | 6 | 6 | Film mixing |
Latency Compensation:
// In your AudioProcessor constructor or prepareToPlay:
void MyProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) {
// Calculate fixed latency (e.g., FFT lookahead)
int fftLatency = fftSize / 2; // 2048 / 2 = 1024 samples
// Report to host for automatic delay compensation
setLatencySamples(fftLatency);
}
Parameter Automation (Thread-Safe):
// CORRECT: Atomic parameter access
void MyProcessor::processBlock(AudioBuffer<float>& buffer, MidiBuffer&) {
// Load atomic value ONCE per block
float gain = gainParameter->load();
// Use local copy for processing
for (int ch = 0; ch < buffer.getNumChannels(); ++ch) {
buffer.applyGain(ch, 0, buffer.getNumSamples(), gain);
}
}
// WRONG: Repeated atomic loads (slow)
for (int sample = 0; sample < numSamples; ++sample) {
float val = buffer.getSample(ch, sample);
val *= gainParameter->load(); // ❌ Atomic load every sample!
buffer.setSample(ch, sample, val);
}
🎚️ AUDIO INTERFACE¶
Driver Models:
| Platform | Driver | Latency | Pros | Cons |
|---|---|---|---|---|
| Windows | ASIO | 2-5ms | Professional standard | Exclusive mode |
| WDM/MME | 50-200ms | Universal | Unusable for music | |
| WASAPI | 10-30ms | Modern | Limited DAW support | |
| macOS | CoreAudio | 3-8ms | Built-in, stable | Less control than ASIO |
| Linux | JACK | 2-10ms | Flexible routing | Configuration complex |
| ALSA | 5-20ms | Direct hardware | Limited features |
Popular Interfaces - Latency Performance:
🏆 BEST (2-3ms round-trip @ 64 samples):
• RME Babyface Pro FS
• Universal Audio Apollo Twin
• Antelope Audio Discrete
✅ EXCELLENT (3-5ms @ 128 samples):
• Focusrite Clarett
• PreSonus Quantum
• MOTU M4
⚠️ GOOD (5-8ms @ 256 samples):
• Focusrite Scarlett (3rd gen)
• Audient iD4
• SSL 2+
❌ AVOID for pro work:
• Built-in laptop audio (100-300ms)
• Cheap USB dongles (50-150ms)
• Bluetooth audio (150-500ms + dropouts)
Round-Trip Latency Calculation:
RTL = (Buffer Size / Sample Rate) × 2 + Driver Overhead
Example @ 48kHz, 128 buffer, RME interface:
RTL = (128 / 48000) × 2 + 0.001
RTL = 0.00533 + 0.001
RTL = 6.33ms ✅ Excellent for live monitoring
📊 DIAGRAM 2: DEVELOPMENT TESTING ROUTING¶
Scenario: Testing plugin while developing with A/B reference comparison¶
┌───────────────────────────────────────────────────────────────────────────────┐
│ DEVELOPMENT WORKSTATION │
│ │
│ ┌─────────────────────────┐ ┌─────────────────────────┐ │
│ │ DAW #1 (Reaper) │ │ DAW #2 (Cubase) │ │
│ │ Development DAW │ │ Reference DAW │ │
│ │ │ │ │ │
│ │ Track 1: Test Signal │ │ Track 1: Same Signal │ │
│ │ ├─ White Noise │ │ ├─ White Noise │ │
│ │ ├─ Sine Sweep │ │ ├─ Sine Sweep │ │
│ │ └─ Music Loop │ │ └─ Music Loop │ │
│ │ │ │ │ │ │ │
│ │ ▼ │ │ ▼ │ │
│ │ ┌──────────────────┐ │ │ ┌──────────────────┐ │ │
│ │ │ AudioLab Plugin │ │ │ │ FabFilter Pro-Q │ │ │
│ │ │ (DEV BUILD) │ │ │ │ (Reference) │ │ │
│ │ │ 🔴 TESTING │ │ │ │ ✅ KNOWN GOOD │ │ │
│ │ └────────┬─────────┘ │ │ └────────┬─────────┘ │ │
│ │ │ │ │ │ │ │
│ │ │ Output │ │ │ Output │ │
│ └───────────┼───────────────┘ └───────────┼───────────────┘ │
│ │ │ │
│ │ │ │
│ └───────────────┬───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────┐ │
│ │ VIRTUAL CABLES (VoiceMeeter) │ │
│ │ │ │
│ │ 🔴 BUS A: Development Plugin │ │
│ │ └─ Routable to analyzers │ │
│ │ │ │
│ │ 🔵 BUS B: Reference Plugin │ │
│ │ └─ Routable to analyzers │ │
│ │ │ │
│ │ 🟢 BUS C: Monitor Mix │ │
│ │ └─ A/B switch: BUS A ↔ BUS B │ │
│ │ └─ Output to physical interface │ │
│ │ │ │
│ │ Controls: │ │
│ │ • Instant A/B toggle (hotkey: F1) │ │
│ │ • Volume match (critical!) │ │
│ │ • Polarity invert for null testing │ │
│ └──────────┬────────────────────────────┘ │
│ │ │
│ ├──────────────────┬────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │
│ │ Spectrum │ │ Phase Scope │ │ Level Meters │ │
│ │ Analyzer │ │ (Correlation) │ │ (LUFS/Peak) │ │
│ │ - Voxengo SPAN │ │ - s(M)exoscope │ │ - dpMeter │ │
│ └─────────────────┘ └─────────────────┘ └──────────────┘ │
│ │
│ ▼ │
│ ┌─────────────────────────────────────────┐ │
│ │ PHYSICAL AUDIO INTERFACE │ │
│ │ (RME Babyface Pro) │ │
│ │ │ │
│ │ Outputs: │ │
│ │ • Main L/R → Studio Monitors │ │
│ │ • Headphones → Detailed listening │ │
│ └─────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────────────┘
Bus Configuration Details¶
🔴 BUS A: Development Plugin Output¶
Purpose: Route audio from your in-development plugin
Connection:
Use Cases: - Real-time frequency analysis - Phase correlation checking - LUFS/loudness monitoring - Null test against reference (inverted phase)
Hotkey Setup (Reaper):
Actions → Show action list → Search "Track: Toggle mute for track 01"
Assign: F1 (for instant A/B switching)
🔵 BUS B: Reference Plugin Output¶
Purpose: Known-good commercial plugin for comparison
Selection Criteria:
Good References:
✅ FabFilter Pro-Q 3 (EQ reference)
✅ Valhalla VintageVerb (Reverb reference)
✅ Soundtoys Decapitator (Saturation reference)
Why these work:
• Industry-standard sound quality
• Predictable, well-documented behavior
• Active development (bug-free)
Matching Settings:
⚠️ CRITICAL: Volume-match before comparing!
Steps:
1. Generate pink noise test signal
2. Measure RMS level of BUS A output → -18dBFS
3. Measure RMS level of BUS B output → -16dBFS
4. Adjust BUS B gain: -2dB to match
5. NOW compare (ears are VERY sensitive to level differences)
🟢 BUS C: Final Monitor Mix¶
Purpose: Switchable output to physical speakers
Routing Logic:
IF A/B Switch = Position A:
BUS C Input ← BUS A
ELSE:
BUS C Input ← BUS B
BUS C Output → Physical Interface Main Outs
Controls: - Volume: Master fader (pre-calibrated to -12dBFS = 85dB SPL) - Mute: Emergency silence (SPACE bar) - Solo: Isolate single bus - Polarity Invert: For null testing (if plugins match perfectly, output = silence)
Null Test Procedure:
1. Route identical signal to BUS A and BUS B
2. Set both plugins to IDENTICAL settings
3. Enable "Polarity Invert" on BUS B
4. Sum BUS A + BUS B → BUS C
5. RESULT:
• Perfect null (silence) = plugins are IDENTICAL
• Residual sound = differences exist (expected for analog modeling)
Analyzer Tools Configuration¶
📊 Spectrum Analyzer (Voxengo SPAN)¶
Routing: Insert on BUS C (post-plugin, pre-speakers)
Settings:
FFT Size: 8192 # High resolution for low frequencies
Overlap: 4× # Smooth display
Window: Blackman-Harris # Accurate magnitude
Range: -120dB to 0dB # Full dynamic range
Slope: Flat (0dB/oct) # Not A-weighted (see raw response)
What to Look For: - ✅ Smooth frequency response (no unexpected peaks/dips) - ✅ Low-frequency extension (how low before rolloff?) - ✅ High-frequency air (above 10kHz behavior) - ⚠️ Aliasing artifacts (unexpected content above Nyquist/2)
🎯 Phase Scope (s(M)exoscope)¶
Purpose: Detect stereo imaging issues
Routing: Stereo insert on BUS C
Interpretation:
Display Pattern:
│ Vertical line = MONO (L = R perfectly)
│ ╱ Diagonal = Good stereo imaging
│ ● Circle = Wide stereo (careful of phase issues)
│ ╳ X-pattern = OUT OF PHASE (will disappear in mono!)
Critical Checks: - Bass content (< 120Hz) should be MOSTLY mono - Mid-range can be wider - Extreme width = potential mono compatibility issues
📈 Level Meters (dpMeter)¶
Routing: Post-fader on BUS C
Metrics:
Peak: -6dBFS max (headroom for inter-sample peaks)
RMS: -18dBFS average (mixing level)
LUFS-I: -14 LUFS (streaming target)
Crest: 12-18dB (dynamic range indicator)
Warnings: - 🔴 Peak > -0.1dBFS: Clipping imminent! - 🟡 RMS > -6dBFS: Too loud, reduce gain - 🟢 LUFS-I = -14±1: Perfect for streaming
📊 DIAGRAM 3: LATENCY BREAKDOWN¶
Complete Signal Path Timing¶
🎹 MIDI Note Pressed
│
│ ⏱️ USB MIDI Latency: 0.5-1ms
│
▼
┌─────────────────────────────────────────────────────┐
│ DAW RECEIVES MIDI EVENT │
│ Timestamp: Buffer-aligned │
└──────────────┬──────────────────────────────────────┘
│
│ ⏱️ Input Buffer Fill Time
│ (Buffer Size / Sample Rate)
│ 128 samples @ 48kHz = 2.67ms
│
▼
┌─────────────────────────────────────────────────────┐
│ PLUGIN processBlock() CALLED │
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ Your DSP Processing │ │
│ │ │ │
│ │ Fixed Latency Sources: │ │
│ │ • FFT Lookahead: 1024 samples (21ms) │ │
│ │ • Linear Phase EQ: 2048 samples (43ms) │ │
│ │ • Reverb Pre-delay: 960 samples (20ms) │ │
│ │ │ │
│ │ Variable Latency Sources: │ │
│ │ • Adaptive Algorithms: 0-500 samples │ │
│ │ • Dynamic Oversampling: 64-256 samples │ │
│ └───────────────────────────────────────────────┘ │
└──────────────┬──────────────────────────────────────┘
│
│ ⏱️ Plugin Processing: 0-50ms (algorithm-dependent)
│
▼
┌─────────────────────────────────────────────────────┐
│ OUTPUT BUFFER ACCUMULATION │
│ (Mixing with other tracks) │
└──────────────┬──────────────────────────────────────┘
│
│ ⏱️ Output Buffer: 2.67ms (matches input)
│
▼
┌─────────────────────────────────────────────────────┐
│ AUDIO INTERFACE DRIVER │
│ │
│ • ASIO Buffer Handoff: 0.5-1ms │
│ • USB Transfer (if USB): 1-2ms │
│ • Internal DSP (UA/Antelope): 0-1ms │
└──────────────┬──────────────────────────────────────┘
│
│ ⏱️ Driver + Hardware: 1-5ms
│
▼
┌─────────────────────────────────────────────────────┐
│ D/A CONVERTER │
│ (Digital → Analog) │
│ Conversion time: ~0.1ms │
└──────────────┬──────────────────────────────────────┘
│
▼
🔊 SOUND WAVES
(Propagation: 1ms per foot @ room temp)
═══════════════════════════════════════════════════════
TOTAL ROUND-TRIP LATENCY
═══════════════════════════════════════════════════════
Calculation:
┌────────────────────────────────────────────┐
│ LATENCY CONTRIBUTORS │
├────────────────────────────────────────────┤
│ MIDI Input: 0.5 - 1ms │
│ Input Buffer: 2.67ms (128@48kHz) │
│ Plugin Process: 0 - 50ms (lookahead) │
│ Output Buffer: 2.67ms │
│ Driver Overhead: 1 - 5ms │
│ D/A Conversion: 0.1ms │
│ ──────────────────────────────── │
│ TOTAL: 7 - 61ms │
└────────────────────────────────────────────┘
🎯 ACCEPTABLE LATENCY RANGES:
═══════════════════════════════════════
✅ 0-10ms → IMPERCEPTIBLE
• Live performance ready
• No compensation needed
• Feels "instant"
⚠️ 10-20ms → NOTICEABLE
• Workable for most users
• Tight timing may feel slightly off
• Piano/drums most affected
❌ 20-30ms → PROBLEMATIC
• Live playing is difficult
• Use input monitoring instead
• Acceptable for mixing only
🛑 >30ms → UNUSABLE
• Significant delay perception
• Cannot perform in real-time
• Pre-record or reduce buffer
Latency Source Deep-Dive¶
📥 Input Buffer Latency¶
What It Is: Time to fill buffer before processing starts
Formula:
Input Latency (ms) = (Buffer Size / Sample Rate) × 1000
Examples:
• 64 samples @ 44.1kHz = 1.45ms
• 128 samples @ 48kHz = 2.67ms
• 256 samples @ 96kHz = 2.67ms (same duration!)
• 512 samples @ 48kHz = 10.67ms
Control: ASIO Control Panel → Buffer Size
Trade-offs:
Smaller Buffer (64):
✅ Lower latency (good for tracking)
❌ Higher CPU usage
❌ More prone to dropouts/clicks
Larger Buffer (512):
✅ More stable (good for mixing)
✅ Lower CPU usage
❌ Higher latency (bad for live playing)
Sweet Spot for Development: 128-256 samples - Balanced latency/stability - Matches most users' real-world settings - Catches buffer-size-dependent bugs
⚙️ Plugin Processing Latency¶
Fixed Latency (Algorithmic Requirement):
// FFT-based processing (frequency domain)
int fftSize = 2048;
int latency = fftSize / 2; // 1024 samples = 21ms @ 48kHz
// Linear-phase EQ (symmetric FIR filter)
int firTaps = 2048;
int latency = firTaps / 2; // 1024 samples
// Lookahead limiter/compressor
int lookaheadSamples = 480; // 10ms @ 48kHz
int latency = lookaheadSamples; // Exactly 10ms
Reporting to Host:
void MyAudioProcessor::prepareToPlay(double sampleRate, int samplesPerBlock) {
// Calculate your fixed latency
int totalLatency = fftLatency + lookaheadLatency;
// CRITICAL: Tell host for delay compensation
setLatencySamples(totalLatency);
// Host will now automatically align this track with others
}
What Happens If You Don't Report: - ❌ Multi-track recordings will be out of sync - ❌ Parallel processing will phase-cancel - ❌ Automation will be offset
Variable Latency (Avoid If Possible):
// ⚠️ PROBLEMATIC: Latency changes during playback
void processBlock(AudioBuffer<float>& buffer, MidiBuffer&) {
if (qualityMode == HIGH) {
setLatencySamples(2048); // ❌ Can't change mid-playback!
} else {
setLatencySamples(512);
}
}
// ✅ BETTER: Fix latency at initialization
void prepareToPlay(double sampleRate, int samplesPerBlock) {
// Use MAXIMUM possible latency always
setLatencySamples(2048);
// Lower quality modes just waste some of the buffer
// (Better than glitchy latency changes)
}
📤 Output Buffer Latency¶
What It Is: Matches input buffer (double-buffering)
Why It Exists:
┌────────────────────────────────────────┐
│ DOUBLE BUFFERING (prevents glitches) │
├────────────────────────────────────────┤
│ │
│ Buffer A: [Writing new samples] │
│ Buffer B: [Playing current samples] │
│ │
│ Every buffer period, they SWAP: │
│ • No interruption to playback │
│ • No race conditions │
│ • Smooth, click-free audio │
└────────────────────────────────────────┘
Cannot Be Reduced: This is fundamental to stable audio I/O
🔧 Driver Overhead Latency¶
Platform Differences:
| Driver | Typical Overhead | Notes |
|---|---|---|
| ASIO (Windows) | 0.5-2ms | Best case, professional interfaces |
| WDM (Windows) | 10-30ms | Avoid for music production |
| CoreAudio (macOS) | 1-3ms | Excellent, built-in |
| JACK (Linux) | 1-5ms | Configuration-dependent |
Interface Quality Matters:
🏆 Professional (RME, UA, Antelope):
• Optimized drivers: ~1ms overhead
• Direct hardware control
• Stable at 64-sample buffers
❌ Budget (Generic USB, Realtek):
• Poor drivers: 5-20ms overhead
• Software resampling layers
• Unstable below 512 samples
Latency Debugging Checklist¶
When users report "high latency":
□ Check ASIO buffer size (should be 128-256 for live use)
□ Verify sample rate matches interface settings (no resampling)
□ Disable audio enhancements (Windows: Sound Control Panel → Disable all)
□ Close other audio apps (Spotify, YouTube = buffer conflicts)
□ Check plugin latency reporting (DAW's delay compensation active?)
□ Test with interface's direct monitoring (zero-latency proof-of-concept)
□ Update interface drivers (old drivers = extra overhead)
□ Check CPU usage (overload = buffer underruns = glitches)
📊 DIAGRAM 4: MULTI-DAW TESTING SETUP¶
Cross-DAW Compatibility Validation¶
┌──────────────────────────────────────────────────────────────────────────────┐
│ MULTI-DAW TESTING WORKSTATION │
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ Reaper 7.x │ │ Cubase 13 │ │ Ableton Live12 │ │
│ │ (FREE) │ │ (Trial/Edu) │ │ (Trial 90d) │ │
│ │ │ │ │ │ │ │
│ │ ✅ Tests: │ │ ✅ Tests: │ │ ✅ Tests: │ │
│ │ • VST3 load │ │ • VST3 strict │ │ • VST3/AU │ │
│ │ • Automation │ │ • ASIO-Guard │ │ • Freeze/Flat │ │
│ │ • Rendering │ │ • Sidechain │ │ • MPE MIDI │ │
│ │ • ReaScript │ │ • Expression │ │ • Clip Launch │ │
│ └───────┬────────┘ └───────┬────────┘ └───────┬────────┘ │
│ │ │ │ │
│ └─────────────────────┴─────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────┐ │
│ │ AUTOMATED TEST SUITE │ │
│ │ (Python + DAW Scripts) │ │
│ │ │ │
│ │ Per-DAW Tests: │ │
│ │ 1. Plugin Scan & Load │ │
│ │ 2. Parameter Recall │ │
│ │ 3. Automation Write/Read │ │
│ │ 4. State Save/Load │ │
│ │ 5. Preset Management │ │
│ │ 6. Sidechain Routing │ │
│ │ 7. Crash Recovery │ │
│ │ 8. Sample Rate Change │ │
│ └──────────┬───────────────────┘ │
│ │ │
│ ┌──────────────┴──────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ VALIDATION │ │ AUDIO CAPTURE │ │
│ │ REPORTS │ │ & ANALYSIS │ │
│ │ │ │ │ │
│ │ • Parameters Load: │ │ • Bounce Quality: │ │
│ │ ✅ All correct │ │ Compare bit-exact │ │
│ │ │ │ │ │
│ │ • Automation: │ │ • CPU Usage: │ │
│ │ ✅ Follows curves │ │ Log per DAW │ │
│ │ │ │ │ │
│ │ • State Recall: │ │ • Memory Leaks: │ │
│ │ ✅ No crashes │ │ Valgrind/ASAN │ │
│ │ │ │ │ │
│ │ • Crash Tests: │ │ • Buffer Stability: │ │
│ │ ⚠️ 2 failures │ │ Dropout detection │ │
│ │ (see log) │ │ │ │
│ └─────────────────────┘ └─────────────────────┘ │
│ │
│ Final Report: test_results_2025-10-03.html │
└──────────────────────────────────────────────────────────────────────────────┘
Per-DAW Testing Matrix¶
✅ Reaper (Cockos)¶
Pros for Testing: - ⚡ Fast plugin scan (< 5 seconds for 100 plugins) - 🔄 ReaScript automation (Python/Lua scripting) - 🎚️ Flexible routing (any track to any track) - 💾 Human-readable project files (easy to diff)
Known Quirks:
Issue: Reaper's unique routing matrix
Impact: Sidechain inputs use different API than other DAWs
Solution: Test sidechain via getBusCount() and explicit bus routing
Issue: Non-destructive FX rendering
Impact: Plugin state might not match offline render
Solution: Verify setNonRealtime() is respected in processBlock()
Test Script (ReaScript Lua):
-- automate_parameter_test.lua
function runPluginTest()
-- Load plugin on track 1
track = reaper.GetTrack(0, 0)
fx_idx = reaper.TrackFX_AddByName(track, "AudioLab Plugin", false, -1)
-- Set parameter 0 to 0.5
reaper.TrackFX_SetParam(track, fx_idx, 0, 0.5)
-- Read back (should match within float precision)
value = reaper.TrackFX_GetParam(track, fx_idx, 0)
if math.abs(value - 0.5) < 0.0001 then
reaper.ShowConsoleMsg("✅ Parameter set/get: PASS\n")
else
reaper.ShowConsoleMsg("❌ Parameter set/get: FAIL\n")
end
end
runPluginTest()
✅ Cubase (Steinberg)¶
Pros for Testing: - 🔒 Strictest VST3 validation (catches spec violations) - 🎵 Advanced MIDI (Expression Maps, Note Expression) - 🔊 ASIO-Guard stress test (parallel processing)
Known Quirks:
Issue: ASIO-Guard moves processing to background thread
Impact: Timing assumptions break, race conditions exposed
Solution: All inter-thread communication MUST be lock-free
Issue: Sample rate changes during project (film work)
Impact: prepareToPlay() called mid-session
Solution: Properly reset ALL state in prepareToPlay(), not just constructor
Issue: Strict state validation
Impact: setState() with invalid data = instant crash dialog
Solution: Robust state versioning with fallback to defaults
Critical Test:
// Test ASIO-Guard compatibility
void AudioLabProcessor::processBlock(AudioBuffer<float>& buffer, MidiBuffer& midi) {
// ❌ WRONG: Assumes buffer timestamp is continuous
currentTime += buffer.getNumSamples(); // Breaks with ASIO-Guard!
// ✅ CORRECT: Use PlayHead position
if (auto* playHead = getPlayHead()) {
if (auto pos = playHead->getPosition()) {
currentTime = pos->getTimeInSamples().orFallback(0);
}
}
}
✅ Ableton Live (Ableton AG)¶
Pros for Testing: - 🎭 Unique workflows (clip launching, freeze tracks) - 🎹 MPE MIDI support (polyphonic expression) - ⚡ Session view (non-linear arrangement)
Known Quirks:
Issue: Plugin scanning is VERY sensitive to crashes
Impact: One crash during scan = plugin blacklisted forever
Solution: Clear plugin cache: ~/Library/Preferences/Ableton/Live x.x.x/
Issue: Freeze track converts to audio offline
Impact: Must handle setNonRealtime(true) correctly
Solution: Disable any real-time-only features (spectrum analyzers, etc.)
Issue: Clip automation vs. arrangement automation
Impact: Parameters can have TWO automation sources simultaneously
Solution: Properly handle parameter changes from multiple sources
Test Scenario:
1. Load plugin on MIDI track
2. Create automation in Clip view (sawtooth LFO on cutoff)
3. Create DIFFERENT automation in Arrangement view (step sequence)
4. Switch between Session/Arrangement
5. VERIFY: Plugin responds to correct automation source
6. VERIFY: No clicks/pops on automation switch
✅ Pro Tools (Avid) [If Available]¶
Pros for Testing: - 🏆 Industry standard (film/music post-production) - 🔒 AAX format strictest validation - 📹 Video sync (frame-accurate timing)
Known Quirks:
Issue: Sample rate changes are VERY slow
Impact: Users avoid SR changes; plugin must handle gracefully
Solution: Don't force sample rate; adapt to whatever PT provides
Issue: AAX requires separate build pipeline
Impact: Different SDK, different signing, different bugs
Solution: Test VST3 AND AAX builds separately
Issue: Track freeze is destructive
Impact: No way to "unfreeze" without re-recording
Solution: Ensure offline render is IDENTICAL to real-time
Automated Testing Suite¶
Test Harness (Python + DAW Scripting):
# test_all_daws.py
import subprocess
import os
DAWS = {
'reaper': {
'executable': r'C:\Program Files\REAPER\reaper.exe',
'script': 'reaper_tests.lua',
'timeout': 300
},
'cubase': {
'executable': r'C:\Program Files\Steinberg\Cubase 13\Cubase13.exe',
'project': 'cubase_test_template.cpr',
'timeout': 600
},
'ableton': {
'executable': r'C:\ProgramData\Ableton\Live 12\Program\Ableton Live 12.exe',
'project': 'ableton_test_template.als',
'timeout': 600
}
}
def run_daw_tests(daw_name, config):
"""Run automated tests in specified DAW"""
print(f"🧪 Testing {daw_name.upper()}...")
# Launch DAW with test project
process = subprocess.Popen([
config['executable'],
config.get('project', ''),
'--headless' # If supported
])
# Monitor for crashes
try:
process.wait(timeout=config['timeout'])
except subprocess.TimeoutExpired:
print(f"⚠️ {daw_name} test timed out")
process.kill()
return False
# Parse results
if process.returncode == 0:
print(f"✅ {daw_name} tests PASSED")
return True
else:
print(f"❌ {daw_name} tests FAILED (code {process.returncode})")
return False
# Run all tests
results = {}
for daw, config in DAWS.items():
results[daw] = run_daw_tests(daw, config)
# Generate report
print("\n" + "="*50)
print("FINAL RESULTS:")
for daw, passed in results.items():
status = "✅ PASS" if passed else "❌ FAIL"
print(f" {daw.upper():15} {status}")
Test Checklist by Category¶
1️⃣ Plugin Scan & Load¶
Reaper:
□ Plugin appears in FX browser
□ Loads in < 2 seconds
□ No console warnings
Cubase:
□ Passes VST3 validator (strict mode)
□ Correct category assignment
□ Thumbnail/icon displays
Ableton:
□ Survives initial scan without crash
□ Appears in Browser → Plug-ins
□ Tags/categories correct
2️⃣ Parameter Recall¶
All DAWs:
□ Set all parameters to random values
□ Save project
□ Close DAW
□ Reopen project
□ VERIFY: All parameters match saved values
□ VERIFY: No parameters reset to default
□ VERIFY: No NaN or infinity values
Common Bug:
// ❌ WRONG: Saving GUI state, not audio state
void AudioProcessor::getStateInformation(MemoryBlock& destData) {
// If GUI hasn't opened yet, parameters might be uninitialized!
auto value = editor->getSliderValue(); // ❌ Editor might not exist
}
// ✅ CORRECT: Save audio processor state
void AudioProcessor::getStateInformation(MemoryBlock& destData) {
// Always save from AudioProcessor's parameter objects
auto value = parameters.getRawParameterValue("cutoff")->load();
}
3️⃣ Automation Write/Read¶
All DAWs:
□ Enable automation write on parameter
□ Move parameter while playing
□ Switch to automation read mode
□ VERIFY: Parameter follows recorded automation
□ VERIFY: Smooth curves (no stairstepping)
□ VERIFY: No clicks/pops during automation
Smoothing Requirement:
// Automation can change VERY rapidly (every sample)
// Your plugin MUST smooth parameter changes!
void processBlock(AudioBuffer<float>& buffer, MidiBuffer&) {
// ❌ WRONG: Direct parameter use
float cutoff = *cutoffParam;
filter.setCutoff(cutoff); // Causes clicks!
// ✅ CORRECT: Smoothed parameter
cutoffSmoothed.setTargetValue(*cutoffParam);
for (int sample = 0; sample < buffer.getNumSamples(); ++sample) {
float smoothCutoff = cutoffSmoothed.getNextValue();
// Use smooth value for this sample
}
}
4️⃣ State Save/Load Stress Test¶
All DAWs:
□ Create 100 random presets
□ For each preset:
□ Load preset
□ Save project
□ Load project
□ VERIFY: State matches
□ No memory leaks (check RAM usage)
□ No crashes after 100 iterations
5️⃣ Crash Recovery¶
Cubase (best crash handling):
□ Trigger intentional crash (null pointer dereference)
□ VERIFY: Cubase shows crash dialog
□ VERIFY: Cubase offers to disable plugin
□ VERIFY: Project still loads without plugin
Reaper:
□ Crash should NOT take down entire DAW
□ VERIFY: Track bypasses automatically
Ableton:
□ Crash during scan = blacklisted
□ VERIFY: Can re-scan after fixing bug
6️⃣ Sample Rate Change¶
All DAWs:
□ Load plugin at 44.1kHz
□ Change project to 48kHz
□ VERIFY: prepareToPlay() called with new rate
□ VERIFY: No audio glitches during transition
□ VERIFY: Frequency-dependent parameters scale correctly
Example:
• LPF at 1kHz @ 44.1kHz should stay at 1kHz @ 48kHz
• NOT scale to 1088Hz (ratio-based error)
🗂️ COMPATIBILITY MATRIX¶
Feature Support by DAW¶
| Feature | Reaper | Cubase | Ableton | Pro Tools | Notes |
|---|---|---|---|---|---|
| VST3 | ✅ | ✅ | ✅ | ❌ | PT uses AAX only |
| VST2 (legacy) | ✅ | ✅ | ✅ | ❌ | Deprecated, avoid |
| AU (macOS) | ✅ | ✅ | ✅ | ❌ | |
| AAX | ❌ | ❌ | ❌ | ✅ | Requires iLok licensing |
| Sidechain | ✅ | ✅ | ✅ | ✅ | Different APIs per DAW |
| MIDI Input | ✅ | ✅ | ✅ | ✅ | |
| MPE MIDI | ⚠️ | ✅ | ✅ | ⚠️ | Limited in Reaper/PT |
| Surround | ✅ | ✅ | ❌ | ✅ | Live is stereo-centric |
| Latency Comp | ✅ | ✅ | ✅ | ✅ | All modern DAWs |
| Offline Render | ✅ | ✅ | ✅ | ✅ | Via setNonRealtime() |
| Plugin Delay | ✅ | ✅ | ✅ | ✅ | Via setLatencySamples() |
| Resize GUI | ✅ | ✅ | ⚠️ | ❌ | Live has issues |
| Automation | ✅ | ✅ | ✅ | ✅ | Different curve types |
| Presets (.vstpreset) | ✅ | ✅ | ✅ | ❌ | AAX uses .tfx format |
Platform Support Matrix¶
| Platform | VST3 | AU | AAX | Recommended |
|---|---|---|---|---|
| Windows 10/11 | ✅ | ❌ | ✅ | VST3 primary |
| macOS (Intel) | ✅ | ✅ | ✅ | AU + VST3 |
| macOS (Apple Silicon) | ✅ | ✅ | ✅ | Native ARM builds! |
| Linux | ✅ | ❌ | ❌ | VST3 only |
Architecture Support¶
Windows:
✅ x64 (64-bit) - REQUIRED (32-bit is dead)
❌ x86 (32-bit) - SKIP (no modern DAWs support)
macOS:
✅ x86_64 (Intel)
✅ arm64 (Apple Silicon M1/M2/M3)
⚠️ Universal Binary (both) - RECOMMENDED
Linux:
✅ x86_64
⚠️ ARM64 (Raspberry Pi) - niche but growing
Known DAW-Specific Bugs¶
Reaper¶
Bug: ReaComp sidechain routing differs from spec
Workaround: Detect Reaper via host name, use alternate bus index
Bug: Resizing can cause OpenGL context loss
Workaround: Recreate GL context on resize event
Cubase¶
Bug: ASIO-Guard + fast automation = race condition
Workaround: Use atomic<float> for ALL shared parameters
Bug: Expression Maps don't send Note Off sometimes
Workaround: Implement note timeout (kill after 10 seconds)
Ableton Live¶
Bug: Freeze sometimes renders at wrong sample rate
Workaround: Check getPlayHead() sample rate, resample if needed
Bug: GUI resize can crash on Windows
Workaround: Disable resizing on Windows (check #ifdef _WIN32)
Pro Tools¶
Bug: Bouncing stems doesn't call setNonRealtime()
Workaround: Detect long buffer sizes (> 8192) as offline hint
Bug: Surround bus routing is AAX-specific
Workaround: Read AAX SDK docs (completely different from VST)
🎓 Best Practices Summary¶
Do's ✅¶
- Test in multiple DAWs BEFORE releasing
-
Minimum: Reaper (free) + one commercial DAW trial
-
Report latency accurately
-
Handle sample rate changes gracefully
-
Save complete state
-
Smooth all parameter changes
Don'ts ❌¶
- DON'T assume buffer size is constant
-
Some DAWs change it mid-session!
-
DON'T use malloc/new in audio thread
-
Pre-allocate everything in prepareToPlay()
-
DON'T assume stereo
-
Support mono, surround via getNumInputChannels()
-
DON'T hardcode sample rate
-
Calculate everything from getSampleRate()
-
DON'T ignore setNonRealtime()
- Offline render might need different settings
📚 Further Resources¶
- VST3 SDK Documentation
- JUCE Forum - DAW Compatibility
- Reaper ReaScript API
- Ableton Live Object Model (LOM)
Document Status: ✅ Complete Next Review: When new DAW versions release Maintained By: AudioLab DevOps Team