daw-compatibility-guide

What this skill does

# DAW Compatibility Guide

Comprehensive guide to DAW-specific quirks, known issues, and workarounds for ensuring your JUCE plugin works correctly across all major digital audio workstations.

## Overview

Each DAW has unique behaviors, assumptions, and quirks that can affect plugin operation. This guide documents common issues and proven solutions for Logic Pro, Ableton Live, Pro Tools, Cubase, Reaper, FL Studio, Bitwig, and others.

## When to Use This Guide

- Debugging DAW-specific issues reported by users
- Testing plugin compatibility across multiple DAWs
- Implementing DAW-specific workarounds
- Understanding format-specific requirements (AU, VST3, AAX)
- Planning cross-DAW automation and state compatibility

---

## Logic Pro (macOS - AU/VST3)

### Overview

- **Formats:** Audio Unit (preferred), VST3
- **Strictness:** Very strict AU validation (`auval`)
- **Automation:** Sample-accurate, works well
- **Unique Features:** AU-specific validation, side-chain routing

### AU Validation Requirements

**Issue:** Logic requires plugins to pass `auval` validation.

**Requirements:**
```cpp
// PluginProcessor.h - Ensure these are set correctly
#define JucePlugin_Name                 "MyPlugin"
#define JucePlugin_Desc                 "Description"
#define JucePlugin_Manufacturer         "YourCompany"
#define JucePlugin_ManufacturerCode     'Manu'  // 4 characters, unique!
#define JucePlugin_PluginCode           'Plug'  // 4 characters, unique!
#define JucePlugin_AUMainType           'aufx'  // Effect
// OR 'aumu' for MIDI effect
// OR 'aumf' for instrument
#define JucePlugin_AUSubType            JucePlugin_PluginCode
#define JucePlugin_AUExportPrefix       MyPluginAU
#define JucePlugin_AUExportPrefixQuoted "MyPluginAU"
```

**Validation Command:**
```bash
auval -v aufx Plug Manu
```

**Common auval Failures:**

1. **Failure: "FATAL ERROR: AudioUnitInitialize failed"**
   ```cpp
   // Cause: prepareToPlay() throws exception or asserts
   void prepareToPlay(double sampleRate, int samplesPerBlock) override {
       // ❌ Don't do this:
       jassert(sampleRate == 44100.0);  // Fails in auval!

       // ✅ Do this:
       if (sampleRate < 8000.0 || sampleRate > 192000.0)
           return;  // Handle gracefully
   }
   ```

2. **Failure: "FATAL ERROR: Property size is incorrect"**
   ```cpp
   // Cause: Incorrect I/O configuration
   bool isBusesLayoutSupported(const BusesLayout& layouts) const override {
       // Be permissive for auval
       if (layouts.getMainOutputChannelSet().isDisabled())
           return false;  // Must have output

       return true;  // Allow any channel config for auval
   }
   ```

3. **Failure: "FATAL ERROR: Render called with null buffer"**
   ```cpp
   void processBlock(AudioBuffer<float>& buffer, MidiBuffer&) override {
       // auval sometimes passes zero-size buffers
       if (buffer.getNumSamples() == 0)
           return;  // Early exit for empty blocks
   }
   ```

**Run auval successfully:**
```bash
# Full validation (takes ~5 minutes)
auval -v aufx Plug Manu

# Strict validation (recommended)
auval -strict -v aufx Plug Manu

# If it passes, you'll see:
# * * * * * * * * * * * * * * * * * * * * * * * * * * * *
# AU VALIDATION SUCCEEDED
# * * * * * * * * * * * * * * * * * * * * * * * * * * * *
```

### Logic-Specific Issues

**Issue: Automation writes incorrectly or doesn't play back**

**Cause:** Parameter smoothing interfering with Logic's automation.

**Solution:**
```cpp
// Don't smooth parameters that Logic is automating
void processBlock(AudioBuffer<float>& buffer, MidiBuffer&) override {
    // ❌ Always smoothing
    float cutoff = smoother.getNextValue(*cutoffParam);

    // ✅ Only smooth if parameter changed recently
    if (cutoffParam->load() != lastCutoffValue) {
        smoother.setTargetValue(*cutoffParam);
        lastCutoffValue = *cutoffParam;
    }
    float cutoff = smoother.getNextValue();
}
```

**Issue: Offline bounce doesn't match realtime**

**Cause:** Tempo/time info assumptions.

**Solution:**
```cpp
void processBlock(AudioBuffer<float>& buffer, MidiBuffer&) override {
    // ✅ Always query tempo from host
    auto playHead = getPlayHead();
    if (playHead != nullptr) {
        juce::AudioPlayHead::CurrentPositionInfo posInfo;
        playHead->getCurrentPosition(posInfo);

        float bpm = posInfo.bpm;
        double ppqPosition = posInfo.ppqPosition;
        bool isPlaying = posInfo.isPlaying;

        // Use this info, don't cache tempo!
    }
}
```

**Issue: Side-chain input doesn't work (AU)**

**Cause:** AU side-chain requires special bus configuration.

**Solution:**
```cpp
MyPluginProcessor::MyPluginProcessor()
    : AudioProcessor(BusesProperties()
        .withInput ("Input",  AudioChannelSet::stereo(), true)
        .withOutput("Output", AudioChannelSet::stereo(), true)
        .withInput ("Sidechain", AudioChannelSet::stereo(), false))  // Optional
{
}

void processBlock(AudioBuffer<float>& buffer, MidiBuffer&) override {
    // Get sidechain bus
    auto mainInputOutput = getBusBuffer(buffer, true, 0);
    auto sidechain = getBusBuffer(buffer, true, 1);  // Second input bus

    if (!sidechain.getNumChannels())
        return;  // No sidechain connected

    // Process with sidechain...
}
```

---

## Ableton Live (VST3/AU)

### Overview

- **Formats:** VST3 (Windows/macOS), AU (macOS)
- **Automation:** Works well, supports breakpoint automation
- **Unique Features:** Max for Live integration, Device Racks, Macro mapping

### Live-Specific Issues

**Issue: Plugin doesn't appear in Live's browser**

**Cause:** VST3 not in correct folder or not scanned.

**Solution:**
```bash
# macOS VST3 path
~/Library/Audio/Plug-Ins/VST3/MyPlugin.vst3

# Windows VST3 path
C:\Program Files\Common Files\VST3\MyPlugin.vst3

# Rescan in Live:
# Preferences → Plug-Ins → "Rescan" button
```

**Issue: Undo/Redo causes parameter jumps**

**Cause:** Live's undo system conflicts with plugin parameter changes.

**Solution:**
```cpp
// Mark parameter changes as gestures to prevent undo conflicts
void parameterValueChanged(int parameterIndex, float newValue) override {
    // Notify host of parameter change
    auto* param = getParameters()[parameterIndex];
    param->beginChangeGesture();
    param->setValueNotifyingHost(newValue);
    param->endChangeGesture();
}
```

**Issue: Plugin latency not compensated correctly**

**Cause:** Plugin doesn't report latency.

**Solution:**
```cpp
int getLatencySamples() const override {
    return latencyInSamples;  // Report actual latency
}

void prepareToPlay(double sampleRate, int samplesPerBlock) override {
    // Update latency if it changes
    latencyInSamples = calculateLatency();
    setLatencySamples(latencyInSamples);
}
```

**Issue: Freeze/Flatten produces incorrect audio**

**Cause:** Non-deterministic behavior or offline/realtime mismatch.

**Solution:**
- Ensure processBlock is deterministic
- Reset all state in prepareToPlay()
- Don't use system time or random numbers without seeding

```cpp
void prepareToPlay(double sampleRate, int samplesPerBlock) override {
    // ✅ Reset all state for deterministic processing
    filter.reset();
    envelope.reset();
    rng.setSeed(12345);  // Seeded random for determinism
}
```

**Issue: Macro mapping doesn't work**

**Cause:** Parameter range or normalization issues.

**Solution:**
```cpp
// Ensure parameters use normalized 0-1 range internally
auto param = std::make_unique<AudioParameterFloat>(
    "cutoff",
    "Cutoff",
    NormalisableRange<float>(20.0f, 20000.0f, 0.01f, 0.3f),  // Skew
    1000.0f
);

// Live's macros expect normalized parameter access to work
```

---

## Pro Tools (AAX)

### Overview

- **Format:** AAX (PACE/iLok signed)
- **Strictness:** Very strict, requires code signing
- **Automation:** Sample-accurate, very robust
- **Unique Features:** AudioSuite (offline processing), HDX DSP

### AAX Requirements

**Issue: Plugin doesn't load - "damaged" or "unsigned" error**

**Cause:**