AudioLab Compatibility Matrix

Overview

This document defines compatibility rules between different AudioLab versions, dependencies, and target platforms.

---

Version Compatibility

Semantic Versioning Compatibility Rules

Change Type	Example	Backward Compatible?	Forward Compatible?
MAJOR	1.x → 2.x	❌ No	❌ No
MINOR	2.1.x → 2.2.x	✅ Yes	❌ No
PATCH	2.2.1 → 2.2.2	✅ Yes	✅ Yes (usually)

Definitions: - Backward Compatible: New version can load/use data from old version - Forward Compatible: Old version can load/use data from new version

---

Plugin Compatibility

DAW Project Compatibility

Scenario	Compatibility	Notes
Load project created with same MAJOR version	✅ Full	Parameters map 1:1
Load project from older MINOR version	✅ Full	New params use defaults
Load project from newer MINOR version	⚠️ Partial	Newer params ignored
Load project from different MAJOR version	❌ None	May crash or sound wrong

Example:

Project created with: 2.1.0
Current plugin:       2.2.0
Result:              ✅ Works perfectly

Project created with: 2.2.0
Current plugin:       2.1.0
Result:              ⚠️ Works, but new 2.2 features missing

Project created with: 2.0.0
Current plugin:       3.0.0
Result:              ❌ May not load correctly

Preset File Compatibility

Version Change	Load Old Presets	Save Compatible Presets
PATCH update	✅ Yes	✅ Yes
MINOR update	✅ Yes	⚠️ Not for older MINOR
MAJOR update	⚠️ Migration tool	❌ No

Preset File Format Versioning:

{
  "preset_version": "2.1",
  "audiolab_version": "2.1.3",
  "parameters": { ... }
}

Loading Logic:

bool canLoadPreset(const PresetFile& preset) {
    int presetMajor = preset.version.major;
    int currentMajor = audiolab::VERSION_MAJOR;

    // Only load presets from same MAJOR version
    if (presetMajor != currentMajor) {
        showMigrationDialog();
        return false;
    }
    return true;
}

---

Platform Compatibility

Operating System Requirements

OS	Minimum Version	Recommended	Notes
Windows	Windows 10 (1809)	Windows 11	Requires MSVC 2019+ runtime
macOS	macOS 10.13 (High Sierra)	macOS 13+	Intel & Apple Silicon
Linux	Ubuntu 20.04 LTS	Ubuntu 22.04 LTS	Debian, Fedora also supported

Plugin Format Compatibility

Format	Windows	macOS	Linux	Notes
VST3	✅	✅	✅	Primary format
AU	❌	✅	❌	macOS only
AAX	✅	✅	❌	Requires Pro Tools
CLAP	⏳	⏳	⏳	Planned for v3.0
LV2	❌	❌	✅	Linux only

DAW Compatibility

Tested and supported DAWs:

DAW	Minimum Version	VST3	AU	AAX	Notes
Ableton Live	11.0	✅	✅	❌	Full support
FL Studio	20.9	✅	❌	❌	Windows/Mac
Logic Pro	10.7	❌	✅	❌	macOS only
Pro Tools	2022.12	✅	❌	✅	AAX preferred
Reaper	6.70	✅	✅	❌	Excellent compat
Studio One	6.0	✅	✅	❌	Full support
Cubase	12.0	✅	❌	❌	VST3 native
Bitwig	4.4	✅	❌	❌	Modern DAW

---

Dependency Compatibility

JUCE Framework

AudioLab Version	JUCE Version	Notes
1.x	6.1.x	Initial release
2.0-2.5	7.0.x	Current stable
3.0+	8.0.x	Planned upgrade

Compatibility Rule: AudioLab major version ties to JUCE major version.

C++ Standard Library

AudioLab Version	C++ Standard	Compiler Requirements
1.x	C++17	MSVC 2017+, GCC 8+, Clang 7+
2.x	C++20	MSVC 2019+, GCC 10+, Clang 10+
3.x	C++23	MSVC 2022+, GCC 11+, Clang 15+

Third-Party Dependencies

Current dependencies (AudioLab 2.x):

Library	Version Range	Purpose
Eigen3	^3.4.0	Matrix math
FFTW3	~3.3.10	FFT algorithms
Catch2	^3.4.0	Unit testing
spdlog	^1.12.0	Logging

Version Range Notation: - ^3.4.0: Compatible with 3.4.0 ≤ version < 4.0.0 (SemVer MINOR updates) - ~3.3.10: Compatible with 3.3.10 ≤ version < 3.4.0 (SemVer PATCH updates)

---

State File Compatibility

Project State Format

AudioLab uses versioned state serialization:

struct StateHeader {
    uint32_t magic = 0x414C4142; // "ALAB"
    uint16_t major = 2;
    uint16_t minor = 1;
    uint32_t checksum;
};

Compatibility Matrix:

Current	Can Load From	Can Save For
2.0.x	2.0.x	2.0.x
2.1.x	2.0.x, 2.1.x	2.0.x, 2.1.x
2.2.x	2.0.x, 2.1.x, 2.2.x	2.0.x, 2.1.x, 2.2.x
3.0.x	2.x (migration), 3.0.x	3.0.x

Migration Strategy:

StateManager::loadState(const std::vector<uint8_t>& data) {
    auto header = parseHeader(data);

    if (header.major < VERSION_MAJOR) {
        // Old major version - migrate
        return migrateFromV2(data);
    }
    else if (header.major == VERSION_MAJOR) {
        // Same major - compatible
        return loadNatively(data);
    }
    else {
        // Future version - can't load
        throw IncompatibleVersionError();
    }
}

---

API Compatibility

Public API Stability Guarantees

Within Same MAJOR Version:

// AudioLab 2.0
class AudioBuffer {
    void process(float* data, int size);  // Original API
};

// AudioLab 2.1 - COMPATIBLE (added overload)
class AudioBuffer {
    void process(float* data, int size);              // Kept for compatibility
    void process(std::span<float> data);              // New API added
};

// AudioLab 2.2 - COMPATIBLE (added method)
class AudioBuffer {
    void process(float* data, int size);
    void process(std::span<float> data);
    void processInPlace(std::span<float> data);       // New method
};

// AudioLab 3.0 - BREAKING
class AudioBuffer {
    void process(std::span<float> data);              // Old API removed!
    void processInPlace(std::span<float> data);
};

Deprecation Policy: 1. Mark as deprecated in MINOR release 2. Keep for rest of MAJOR version 3. Remove in next MAJOR release

Example:

// AudioLab 2.1
[[deprecated("Use process(std::span<float>) instead")]]
void process(float* data, int size);

// AudioLab 2.x - Still available (deprecated)
// AudioLab 3.0 - Removed

---

CPU Instruction Set Compatibility

SIMD Requirements

AudioLab Version	x86-64	ARM64	Required Extensions
2.0-2.5	SSE2+	NEON	Baseline
2.6+	AVX	NEON	Optional acceleration
3.0+	AVX2	NEON + SVE	New baseline

Runtime Detection:

if (CPUFeatures::hasAVX2()) {
    useAVX2Implementation();
} else if (CPUFeatures::hasSSE2()) {
    useSSE2Implementation();
} else {
    useScalarImplementation();
}

---

Migration Guides

Upgrading from 1.x to 2.x

Breaking Changes: - AudioBuffer API changed from pointers to std::span - Preset format changed (migration tool provided) - Minimum C++ version now C++20

Migration Steps: 1. Run audiolab-migrate-v1-to-v2.exe on presets 2. Update code:

// Old (1.x)
buffer.process(data, size);

// New (2.x)
buffer.process(std::span(data, size));

3. Recompile with C++20

Upgrading from 2.x to 3.x

Planned Breaking Changes (3.0 roadmap): - Removal of all deprecated APIs - New state serialization format - CLAP plugin format support - Minimum C++23

---

Version Matrix Quick Reference

AudioLab	JUCE	C++	Windows	macOS	Linux
1.0-1.9	6.1	17	10+	10.13+	Ubuntu 18.04+
2.0-2.9	7.0	20	10+	10.13+	Ubuntu 20.04+
3.0+	8.0	23	11+	11.0+	Ubuntu 22.04+

---

Compatibility Testing Checklist

Before releasing new version:

Version Compatibility

• Load projects from previous MINOR versions
• Load presets from previous MINOR versions
• Verify state files from previous PATCH versions
• Test upgrade path from previous MAJOR (if applicable)

Platform Compatibility

• Test on minimum supported OS version
• Test on latest OS version
• Verify all plugin formats load in DAWs
• Check installer on all platforms

Dependency Compatibility

• Verify dependency version ranges in vcpkg.json
• Test with minimum dependency versions
• Test with latest dependency versions
• Check for breaking changes in dependencies

API Compatibility

• Run API compatibility checker
• Verify deprecated APIs still work
• Check for accidental API breaks
• Update API documentation

---

Remember: Compatibility is a promise to users. Breaking it breaks trust.