🛠️ Software Checklist - AudioLab Development Stack¶

Goal: Complete development environment setup in < 2 hours for new developers.

Target Onboarding Time: 90 minutes (download + install + verify)

🎯 Core Development Tools¶

These are mandatory for AudioLab development. All other work depends on this foundation.

Tool	Version	Purpose	Download	Install Time
Visual Studio 2022	17.8+	Primary C++ IDE (Windows)	Download	~30 min
CMake	3.28+	Build system generator	Download	~2 min
Git	2.40+	Version control	Download	~3 min
JUCE Framework	7.0.5+	Audio plugin framework	Download	~5 min

🪟 Visual Studio 2022 (Windows Primary)¶

Version: 17.8.0 or newer (Current: 17.11+)

Why this version? - C++20 standard: Full support for modules, concepts, ranges - CMake integration: Native support for CMake projects (no VS project files needed) - ASAN: AddressSanitizer for memory debugging in audio code - Clang-Cl: Drop-in Clang compiler for better diagnostics

Download: Visual Studio 2022 Community

Required Workloads¶

Select these during installation (via Visual Studio Installer):

✅ Desktop development with C++
   ├─ MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)
   ├─ C++ CMake tools for Windows
   ├─ C++ AddressSanitizer
   ├─ C++ Clang Compiler for Windows
   ├─ C++ Clang-cl for v143 build tools
   └─ Windows 10 SDK (10.0.22621.0 or newer)

✅ Optional (Recommended):
   ├─ C++ profiling tools
   ├─ C++ ATL for latest v143 build tools (for VST2 legacy)
   └─ Just-In-Time debugger

Installation Flags (silent install):

vs_community.exe --passive --wait ^
  --add Microsoft.VisualStudio.Workload.NativeDesktop ^
  --add Microsoft.VisualStudio.Component.VC.CMake.Project ^
  --add Microsoft.VisualStudio.Component.VC.ASAN ^
  --add Microsoft.VisualStudio.Component.VC.Llvm.Clang ^
  --add Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset ^
  --add Microsoft.VisualStudio.Component.Windows10SDK.22621

Environment Variables (auto-configured): - VSINSTALLDIR → C:\Program Files\Microsoft Visual Studio\2022\Community\ - VCToolsInstallDir → ...\VC\Tools\MSVC\14.XX.XXXXX\ - Add to PATH: %VSINSTALLDIR%\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin

Verify Installation:

# Check MSVC compiler
cl.exe

# Check CMake integration
cmake --version  # Should show 3.27+ bundled with VS

# Check Clang-Cl
clang-cl.exe --version

🔨 CMake¶

Version: 3.28+ (Current stable: 3.30+)

Why 3.28+? - C++20 modules: Full support via CMAKE_CXX_SCAN_FOR_MODULES - Presets v6: CMakePresets.json with workflow presets - JUCE compatibility: JUCE 7.0.5 requires CMake 3.22+, we go further for modules

Download: CMake Official - Windows: .msi installer (64-bit) - macOS: .dmg or brew install cmake - Linux: snap install cmake --classic or build from source

Installation Flags (Windows MSI):

msiexec /i cmake-3.30.0-windows-x86_64.msi /quiet ^
  ADD_CMAKE_TO_PATH=System ^
  INSTALLDIR="C:\Program Files\CMake"

Environment Variables: - Add to PATH: C:\Program Files\CMake\bin - Set CMAKE_GENERATOR → Ninja (if using Ninja, see below)

Verify:

cmake --version
# CMake version 3.30.x

cmake --help-module CMakeFindDependencyMacro
# Should list available modules

🌳 Git¶

Version: 2.40+ (Current: 2.46+)

Why 2.40+? - Sparse checkout: Clone only needed folders (huge repos) - Git LFS improvements: Better handling of audio samples - SHA-256 support: Future-proof cryptographic hashing

Download: Git for Windows

Recommended Installation Options:

✅ Git Bash + Git GUI
✅ Add Git to PATH (Use Git from the Windows Command Prompt)
✅ Use bundled OpenSSH
✅ Checkout as-is, commit Unix-style line endings (LF)
✅ Use MinTTY terminal
✅ Enable file system caching
✅ Enable symbolic links

Post-Install Configuration:

# Identity (required for commits)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Line endings (CRITICAL for cross-platform)
git config --global core.autocrlf false   # Preserve LF on Windows
git config --global core.eol lf           # Force LF

# Performance tweaks
git config --global core.preloadindex true
git config --global core.fscache true
git config --global gc.auto 256

# LFS (if working with large audio samples)
git lfs install

Verify:

git --version
# git version 2.46.x

git config --global --list
# Should show user.name, user.email, core.autocrlf=false

🎵 JUCE Framework¶

Version: 7.0.5+ (Current: 7.0.12+)

Why 7.0.5+? - C++17 minimum (AudioLab uses C++20, fully compatible) - Native Apple Silicon: ARM64 builds without Rosetta - VST3 SDK bundled: No separate Steinberg SDK download - WebView2: Modern web views for plugin UIs - CMake first-class: juce_add_plugin() is production-ready

Download: JUCE Website (free GPLv3 or paid license)

Installation Methods:

Option A: Download ZIP (Recommended)¶

# Download from https://juce.com/get-juce/
# Extract to: C:\SDKs\JUCE (Windows) or ~/SDKs/JUCE (macOS/Linux)

# Verify structure:
C:\SDKs\JUCE\
├── JUCE\               # Framework source
├── Projucer.exe        # GUI project manager (optional)
├── extras\             # Demo projects
└── modules\            # JUCE modules

Option B: Git Clone (For Tracking Updates)¶

cd C:\SDKs  # or ~/SDKs
git clone https://github.com/juce-framework/JUCE.git --branch 7.0.12 --depth 1

Environment Variables:

# Add to system variables:
JUCE_DIR = C:\SDKs\JUCE   (Windows)
JUCE_DIR = ~/SDKs/JUCE    (macOS/Linux)

CMake Integration: Add to your CMakeLists.txt:

# Method 1: FetchContent (downloads JUCE automatically)
include(FetchContent)
FetchContent_Declare(
    JUCE
    GIT_REPOSITORY https://github.com/juce-framework/JUCE.git
    GIT_TAG 7.0.12
)
FetchContent_MakeAvailable(JUCE)

# Method 2: Use local JUCE installation
list(APPEND CMAKE_PREFIX_PATH "${JUCE_DIR}")
find_package(JUCE CONFIG REQUIRED)

Verify:

# Check JUCE directory
ls "$JUCE_DIR/modules/juce_core"

# Build a test JUCE plugin (from AudioLab repo)
cmake -B build -S .
cmake --build build --config Release

🧪 Testing & Validation Tools¶

Mandatory for CI/CD and quality assurance.

Tool	Version	Purpose	Download
Catch2	v3.4.0+	C++ unit testing framework	GitHub
RenderMan	Latest	Audio render capture/compare	Tracktion GitHub
PluginVal	Latest	Plugin validation (VST3/AU)	Tracktion GitHub
LatencyMon	Latest (Windows)	Real-time profiling	Resplendence

🧪 Catch2 (Unit Testing)¶

Version: v3.4.0+

Installation via CMake (Automatic):

include(FetchContent)
FetchContent_Declare(
    Catch2
    GIT_REPOSITORY https://github.com/catchorg/Catch2.git
    GIT_TAG v3.4.0
)
FetchContent_MakeAvailable(Catch2)

Manual Installation (Optional):

git clone https://github.com/catchorg/Catch2.git --branch v3.4.0
cd Catch2
cmake -B build -DCMAKE_INSTALL_PREFIX=C:/SDKs/Catch2
cmake --build build --target install

Usage in AudioLab:

#include <catch2/catch_test_macros.hpp>

TEST_CASE("Sample32 normalizes correctly") {
    using namespace audiolab::core::types;
    NormalizedSample sample(2.0f);  // Over range
    REQUIRE(sample.get() == 1.0f);  // Clamped
}

🎨 RenderMan (Audio Render Testing)¶

Purpose: Capture plugin audio output and compare against golden reference files.

Installation:

# Clone AudioLab tools (includes RenderMan wrapper)
git clone https://github.com/YourOrg/audiolab-tools.git
cd audiolab-tools/renderman
cmake -B build && cmake --build build

Usage:

# Render plugin output to WAV
renderman --plugin MyPlugin.vst3 --input test_sweep.wav --output result.wav

# Compare against reference (returns diff in dB)
renderman --compare result.wav reference.wav --tolerance -60dB

✅ PluginVal (Plugin Validation)¶

Purpose: Automated testing of VST3/AU plugins (crashes, threading, automation, etc.)

Download: GitHub Releases

Installation:

# Windows
curl -L -o pluginval.exe https://github.com/Tracktion/pluginval/releases/download/vX.X.X/pluginval.exe

# macOS
brew install pluginval

# Linux
wget https://github.com/Tracktion/pluginval/releases/download/vX.X.X/pluginval
chmod +x pluginval

Usage:

# Validate plugin (runs 100+ tests)
pluginval --strictness-level 10 --validate "C:\Plugins\AudioLab\MyPlugin.vst3"

# CI integration (exit code 0 = pass)
pluginval --strictness-level 10 --validate MyPlugin.vst3 || exit 1

📊 LatencyMon (Real-Time Profiling - Windows Only)¶

Purpose: Detect DPC/ISR latency issues that cause audio dropouts.

Download: Resplendence Software

Installation: Run LatencyMon.exe (portable, no install needed)

Usage: 1. Launch LatencyMon 2. Click "▶ Start" button 3. Run your DAW + AudioLab plugins at 64-sample buffer 4. Check for red warnings: - ✅ "Your system is suitable for real-time audio" = GOOD - ❌ "Highest DPC latency > 2000 μs" = BAD (find culprit driver)

Common Culprits: - nvlddmkm.sys (NVIDIA GPU driver) → Disable "Hardware-accelerated GPU scheduling" - USBXHCI.SYS (USB 3.0 controller) → Update chipset drivers - Wdf01000.sys (Windows Driver Framework) → Usually benign, ignore if < 500 μs

🛠️ Auxiliary Tools¶

Recommended for productivity and debugging. Not strictly required.

Tool	Version	Purpose	Download
Python	3.11+	Build scripts, automation	Python.org
Node.js	18 LTS	Web tooling (docs generation)	NodeJS.org
Ninja	Latest	Fast parallel builds	GitHub

🐍 Python 3.11+¶

Purpose: Build automation, test runners, sample generators

Download: Python Downloads

Installation (Windows):

✅ Add Python to PATH
✅ Install pip
✅ Install for all users (if admin)

Verify:

python --version  # Python 3.11.x
pip --version

Required Packages:

pip install --upgrade pip
pip install numpy scipy matplotlib  # Audio analysis
pip install pyyaml jinja2            # Config templating
pip install pytest                   # Testing

📦 Node.js 18 LTS¶

Purpose: Documentation generation (via Docsify, VitePress), web-based tools

Download: Node.js LTS

Verify:

node --version  # v18.x.x
npm --version

Global Packages:

npm install -g docsify-cli   # Live docs server
npm install -g vitepress     # Static site generator
npm install -g prettier      # Code formatting

⚡ Ninja Build System¶

Purpose: 10x faster incremental builds than MSBuild/Make

Why? - MSBuild (VS default): ~45 seconds for AudioLab rebuild - Ninja: ~4.5 seconds for same rebuild

Download: GitHub Releases

Installation (Windows):

# Download ninja.exe
curl -L -o ninja.exe https://github.com/ninja-build/ninja/releases/download/v1.12.1/ninja-win.zip
# Extract and add to PATH: C:\Tools\Ninja\ninja.exe

Configuration:

# Tell CMake to use Ninja
cmake -G Ninja -B build -S .
cmake --build build  # Uses Ninja instead of MSBuild

Verify:

ninja --version  # 1.12.1

🎨 Optional (But Highly Recommended)¶

Tools that significantly improve workflow but aren't required.

Tool	Purpose	Download	Price
Beyond Compare	Audio file diffing	Scooter Software	$60
WinMerge	Free alternative to Beyond Compare	WinMerge	Free
Meld (Linux/macOS)	Visual diff/merge tool	Meld	Free
ILSpy	.NET decompiler (inspect JUCE binaries)	ILSpy	Free
dnSpy	Advanced .NET debugger	dnSpy	Free

🎧 Beyond Compare (Audio File Diff)¶

Why? Compare audio renders byte-by-byte or waveform visually.

Setup: 1. Install Beyond Compare 2. Go to Tools > File Formats 3. Add custom format: *.wav → "Audio Waveform Compare" 4. Right-click two .wav files → "Compare"

Features: - Visual waveform overlay - Phase alignment - dB difference calculation - Spectrogram comparison

📦 Audio Utilities (Virtual Routing)¶

Purpose: Route audio between DAW and plugin instances for testing.

OS	Tool	Purpose	Download
Windows	VoiceMeeter Banana	Virtual audio mixer	VB-Audio
macOS	BlackHole	Virtual audio driver	ExistentialAudio
macOS	Loopback	Pro virtual routing (paid)	Rogue Amoeba
Linux/macOS	JACK Audio	Low-latency audio routing	JACK

🎛️ VoiceMeeter Banana (Windows)¶

Download: VB-Audio VoiceMeeter

Setup: 1. Install VoiceMeeter Banana 2. Set Windows default output to "VoiceMeeter Input" 3. In DAW: Output to "VoiceMeeter Input" 4. In VoiceMeeter: Route to physical interface or virtual outputs

Use Case: Test AudioLab plugins in a DAW while capturing output for analysis.

🕳️ BlackHole (macOS)¶

Download: BlackHole GitHub

Installation:

brew install blackhole-2ch  # 2-channel version
# Or download .pkg from GitHub releases

Setup: 1. Install BlackHole 2. Open Audio MIDI Setup.app 3. Create Multi-Output Device: Built-in Output + BlackHole 2ch 4. Set DAW output to Multi-Output Device 5. Set analyzer/recorder input to BlackHole 2ch

🔌 JACK Audio (Linux/macOS)¶

Download: JACK2

Installation (Linux):

sudo apt install jackd2 qjackctl  # Ubuntu/Debian
sudo pacman -S jack2 qjackctl     # Arch Linux

Setup: 1. Launch qjackctl (GUI) 2. Click "Setup" → Set sample rate/buffer size 3. Click "Start" to launch JACK server 4. Connect apps via "Connections" button

Use Case: Professional low-latency routing on Linux. Alternative to PulseAudio/PipeWire.

🚀 Quick Install Commands¶

Copy-paste these for fast environment setup.

🪟 Windows (PowerShell - Run as Administrator)¶

# Using Chocolatey package manager
Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install all tools
choco install -y `
  visualstudio2022community `
  visualstudio2022-workload-nativedesktop `
  cmake --version=3.30.0 `
  git --version=2.46.0 `
  python311 `
  nodejs-lts `
  ninja `
  winmerge

# Verify installations
cmake --version && git --version && python --version && node --version && ninja --version

Manual Steps After: - Download JUCE: https://juce.com/get-juce/ → Extract to C:\SDKs\JUCE - Set JUCE_DIR environment variable - Download LatencyMon: https://www.resplendence.com/latencymon - Download PluginVal: https://github.com/Tracktion/pluginval/releases

🍎 macOS (Homebrew)¶

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install all tools
brew install cmake git python@3.11 node ninja
brew install --cask visual-studio-code  # Alternative to Xcode for editing

# Install Xcode Command Line Tools (required for compilers)
xcode-select --install

# Install audio utilities
brew install blackhole-2ch
brew install jack  # Optional: JACK audio

# Download JUCE
mkdir -p ~/SDKs
cd ~/SDKs
git clone https://github.com/juce-framework/JUCE.git --branch 7.0.12 --depth 1

# Set environment variable (add to ~/.zshrc or ~/.bash_profile)
echo 'export JUCE_DIR="$HOME/SDKs/JUCE"' >> ~/.zshrc
source ~/.zshrc

# Verify installations
cmake --version && git --version && python3 --version && node --version && ninja --version

Manual Steps After: - Download PluginVal: https://github.com/Tracktion/pluginval/releases - Install Xcode (full IDE) from App Store if needed

🐧 Linux (Ubuntu/Debian)¶

# Update package lists
sudo apt update

# Install core tools
sudo apt install -y \
  build-essential \
  cmake \
  git \
  python3.11 \
  python3-pip \
  nodejs \
  npm \
  ninja-build \
  clang-17 \
  libc++-17-dev \
  libc++abi-17-dev

# Install audio development libraries
sudo apt install -y \
  libasound2-dev \
  libjack-jackd2-dev \
  libfreetype6-dev \
  libx11-dev \
  libxrandr-dev \
  libxinerama-dev \
  libxcursor-dev \
  libwebkit2gtk-4.0-dev \
  mesa-common-dev

# Install JACK audio (optional)
sudo apt install -y jackd2 qjackctl

# Download JUCE
mkdir -p ~/SDKs
cd ~/SDKs
git clone https://github.com/juce-framework/JUCE.git --branch 7.0.12 --depth 1

# Set environment variable (add to ~/.bashrc)
echo 'export JUCE_DIR="$HOME/SDKs/JUCE"' >> ~/.bashrc
source ~/.bashrc

# Verify installations
cmake --version && git --version && python3 --version && node --version && ninja --version

Manual Steps After: - Download PluginVal: wget https://github.com/Tracktion/pluginval/releases/... - Configure JACK: Launch qjackctl, set sample rate/buffer size

⚡ Alternative: Winget (Windows Package Manager - Windows 11)¶

# Install tools via winget
winget install --id Kitware.CMake --version 3.30.0
winget install --id Git.Git
winget install --id Python.Python.3.11
winget install --id OpenJS.NodeJS.LTS
winget install --id Ninja-build.Ninja
winget install --id Microsoft.VisualStudio.2022.Community --override "--passive --wait --add Microsoft.VisualStudio.Workload.NativeDesktop"

# Verify
cmake --version && git --version && python --version && node --version

✅ Post-Install Verification¶

Run this script to verify your environment:

`verify_environment.sh` (Cross-Platform)¶

#!/bin/bash
# Save as verify_environment.sh, run: bash verify_environment.sh

echo "🔍 AudioLab Environment Check"
echo "=============================="

# Check CMake
if command -v cmake &> /dev/null; then
    VERSION=$(cmake --version | head -n1 | awk '{print $3}')
    echo "✅ CMake: $VERSION"
else
    echo "❌ CMake not found"
fi

# Check Git
if command -v git &> /dev/null; then
    VERSION=$(git --version | awk '{print $3}')
    echo "✅ Git: $VERSION"
else
    echo "❌ Git not found"
fi

# Check Python
if command -v python3 &> /dev/null; then
    VERSION=$(python3 --version | awk '{print $2}')
    echo "✅ Python: $VERSION"
else
    echo "❌ Python not found"
fi

# Check Node.js
if command -v node &> /dev/null; then
    VERSION=$(node --version)
    echo "✅ Node.js: $VERSION"
else
    echo "❌ Node.js not found"
fi

# Check Ninja
if command -v ninja &> /dev/null; then
    VERSION=$(ninja --version)
    echo "✅ Ninja: $VERSION"
else
    echo "⚠️  Ninja not found (optional but recommended)"
fi

# Check JUCE
if [ -n "$JUCE_DIR" ] && [ -d "$JUCE_DIR" ]; then
    echo "✅ JUCE: $JUCE_DIR"
else
    echo "❌ JUCE_DIR not set or directory not found"
fi

echo ""
echo "=============================="
echo "Setup complete! 🚀"

Expected Output:

🔍 AudioLab Environment Check
==============================
✅ CMake: 3.30.0
✅ Git: 2.46.0
✅ Python: 3.11.9
✅ Node.js: v18.20.4
✅ Ninja: 1.12.1
✅ JUCE: /home/user/SDKs/JUCE

==============================
Setup complete! 🚀

📝 Notes¶

Estimated Total Install Time: 90 minutes - Visual Studio: ~30 min (download + install) - CMake/Git/Python/Node: ~10 min combined - JUCE: ~5 min (download/extract) - Configuration/verification: ~15 min - Buffer for downloads on slow connections: ~30 min

Disk Space Required: - Visual Studio 2022: ~10 GB (with C++ workload) - JUCE: ~500 MB - CMake/Git/Python/Node: ~1 GB combined - Total: ~12 GB minimum

Last Updated: October 2024 Tested On: Windows 11 23H2, macOS Sonoma 14.5, Ubuntu 22.04 LTS

Next: IDE Configuration - VS Code, CLion, and Visual Studio settings

🛠️ Software Checklist - AudioLab Development Stack¶

🎯 Core Development Tools¶

🪟 Visual Studio 2022 (Windows Primary)¶

Required Workloads¶

🔨 CMake¶

🌳 Git¶

🎵 JUCE Framework¶

Option A: Download ZIP (Recommended)¶

Option B: Git Clone (For Tracking Updates)¶

🧪 Testing & Validation Tools¶

🧪 Catch2 (Unit Testing)¶

🎨 RenderMan (Audio Render Testing)¶

✅ PluginVal (Plugin Validation)¶

📊 LatencyMon (Real-Time Profiling - Windows Only)¶

🛠️ Auxiliary Tools¶

🐍 Python 3.11+¶

📦 Node.js 18 LTS¶

⚡ Ninja Build System¶

🎨 Optional (But Highly Recommended)¶

🎧 Beyond Compare (Audio File Diff)¶

📦 Audio Utilities (Virtual Routing)¶

🎛️ VoiceMeeter Banana (Windows)¶

🕳️ BlackHole (macOS)¶

🔌 JACK Audio (Linux/macOS)¶

🚀 Quick Install Commands¶

🪟 Windows (PowerShell - Run as Administrator)¶

🍎 macOS (Homebrew)¶

🐧 Linux (Ubuntu/Debian)¶

⚡ Alternative: Winget (Windows Package Manager - Windows 11)¶

✅ Post-Install Verification¶

verify_environment.sh (Cross-Platform)¶

📝 Notes¶

`verify_environment.sh` (Cross-Platform)¶