🔨 VS Code Tasks - AudioLab¶

Build automation and workflow tasks for AudioLab audio plugin development

📋 Table of Contents¶

Overview
Files in This Directory
Available Tasks
Running Tasks
Task Categories
Keyboard Shortcuts
Task Configuration
Adding Custom Tasks
Integration with Keybindings
Troubleshooting

Overview¶

Purpose: Automate build, test, validation, and audio processing workflows for AudioLab development.

What are VS Code Tasks? - Shell commands executed from VS Code - Integrated with terminal output - Detects errors and warnings (problem matchers) - Can be triggered via keyboard shortcuts - Supports dependencies (pre/post tasks)

Use Cases: - Build C++ project with CMake - Run unit tests (Catch2) - Validate VST3 plugins (PluginVal) - Process audio test files - Benchmark DSP performance - Format code with clang-format

Files in This Directory¶

`tasks.json`¶

Primary task definitions for AudioLab workflow.

Content: - CMake tasks: Configure, build, clean - Build tasks: Debug, Release, RelWithDebInfo - Test tasks: Unit tests, audio tests, DSP tests - Validation tasks: PluginVal, memory leak checks - Audio tasks: Process audio, benchmark DSP - Utility tasks: Code formatting, documentation generation

Location: vscode/tasks/tasks.json

Used by: - Build system (Ctrl+Shift+B) - Keyboard shortcuts (F7, Ctrl+Alt+R, etc.) - Debug configurations (pre-launch builds)

Available Tasks¶

Build Tasks¶

Task Name	Description	Shortcut
CMake: Configure	Configure CMake build system	`Ctrl+Alt+Shift+C`
Build: Debug	Build debug version with symbols	`Ctrl+Shift+B`
Build: Release	Build optimized release version	-
Build: RelWithDebInfo	Build optimized with debug symbols	-
CMake: Clean	Clean build artifacts	-
CMake: Clean Rebuild	Clean and rebuild from scratch	`Ctrl+Shift+F7`

Test Tasks¶

Task Name	Description	Shortcut
Test: All	Run all unit tests (Catch2)	-
Test: Audio Processing	Run audio processing tests	-
Test: DSP Algorithms	Run DSP algorithm tests	-
Test: Buffer Management	Run buffer/memory tests	-
Test: With Coverage	Run tests with code coverage	-

Validation Tasks¶

Task Name	Description	Shortcut
Validate: Plugin (PluginVal)	Validate VST3 plugin compliance	`Ctrl+Alt+V`
Validate: Memory (Valgrind)	Check for memory leaks (Linux)	-
Validate: Thread Safety	Check for race conditions	-

Audio Workflow Tasks¶

Task Name	Description	Shortcut
Audio: Process Test File	Process audio through plugin	`Ctrl+Alt+P`
Audio: Benchmark DSP	Benchmark DSP performance	`Ctrl+Alt+B`
Audio: Launch in DAW (Reaper)	Open plugin in Reaper	`Ctrl+Alt+R`
Audio: Launch in DAW (Logic)	Open plugin in Logic Pro (macOS)	`Cmd+Option+R`

Utility Tasks¶

Task Name	Description	Shortcut
Format: All Code	Format all C++ files with clang-format	-
Format: Current File	Format current file	`Ctrl+Shift+F`
Docs: Generate Doxygen	Generate API documentation	-
Docs: Serve HTML	Serve docs locally at localhost:8000	-

Running Tasks¶

Method 1: Command Palette (Most Common)¶

1. Press Ctrl+Shift+P (Cmd+Shift+P on macOS)
2. Type: "Tasks: Run Task"
3. Select task from dropdown
4. Task executes in integrated terminal

Method 2: Default Build Task¶

1. Press Ctrl+Shift+B (Cmd+Shift+B on macOS)
2. Default build task runs (usually "Build: Debug")
3. Faster than Command Palette for frequent builds

Method 3: Keyboard Shortcuts¶

AudioLab custom shortcuts (see keybindings):

F7                - CMake build
Ctrl+Shift+F7     - Clean rebuild
Ctrl+Alt+R        - Launch in DAW
Ctrl+Alt+V        - Validate plugin
Ctrl+Alt+P        - Process audio test
Ctrl+Alt+B        - Benchmark DSP

1. Open Terminal menu (top menu bar)
2. Select "Run Task..."
3. Choose task from list

Task Categories¶

🔨 Build Tasks¶

Purpose: Compile AudioLab C++ code with CMake.

Example Task:

{
  "label": "Build: Debug",
  "type": "cmake",
  "command": "build",
  "targets": ["AudioLab_Plugin"],
  "problemMatcher": ["$gcc"],
  "group": {
    "kind": "build",
    "isDefault": true
  }
}

Features: - Uses CMake Tools extension - Auto-detects compiler errors - Shows errors in Problems panel - Supports parallel builds

Build Types: - Debug: Full symbols, no optimization, assertions enabled - Release: Optimized, no symbols, assertions disabled - RelWithDebInfo: Optimized + symbols (for profiling)

🧪 Test Tasks¶

Purpose: Run automated tests (Catch2 framework).

Example Task:

{
  "label": "Test: All",
  "type": "shell",
  "command": "${workspaceFolder}/build/Debug/AudioLab_Tests.exe",
  "args": ["--reporter", "console", "--success"],
  "problemMatcher": []
}

Test Types: - Unit Tests: Test individual functions/classes - Audio Tests: Process audio and verify output - DSP Tests: Validate algorithm accuracy - Performance Tests: Benchmark execution time

Test Output:

===============================================================================
All tests passed (42 assertions in 12 test cases)

✅ Validation Tasks¶

Purpose: Ensure plugin compliance and quality.

PluginVal Example:

{
  "label": "Validate: Plugin (PluginVal)",
  "type": "shell",
  "command": "pluginval",
  "args": [
    "--strictness-level", "5",
    "--validate", "${workspaceFolder}/build/Debug/AudioLab_Plugin.vst3"
  ],
  "problemMatcher": []
}

What PluginVal Checks: - Parameter automation - State save/load - Threading safety - Memory leaks - GUI rendering - MIDI handling

Strictness Levels: - 1: Basic checks only - 5: Strict (recommended for release) - 10: Very strict (catches edge cases)

🎧 Audio Tasks¶

Purpose: Process audio and benchmark performance.

Process Audio Example:

{
  "label": "Audio: Process Test File",
  "type": "shell",
  "command": "${workspaceFolder}/build/Debug/AudioProcessor.exe",
  "args": [
    "--input", "test_audio/sine_440hz.wav",
    "--output", "output/processed.wav",
    "--plugin", "AudioLab_Plugin.vst3"
  ],
  "problemMatcher": []
}

Benchmark Example:

{
  "label": "Audio: Benchmark DSP",
  "type": "shell",
  "command": "${workspaceFolder}/build/Release/BenchmarkDSP.exe",
  "args": ["--iterations", "10000"],
  "problemMatcher": []
}

Output:

Benchmark Results:
  Average: 0.42ms per buffer
  Peak: 1.2ms
  CPU: 8.4% (44.1kHz, 512 samples)

Keyboard Shortcuts¶

Integration with AudioLab keybindings (see keybindings/README.md):

Windows/Linux¶

Ctrl+Shift+B        - Build: Debug (default)
F7                  - CMake: Build
Ctrl+Shift+F7       - CMake: Clean Rebuild
Ctrl+Alt+Shift+C    - CMake: Configure

Ctrl+Alt+T          - Build and Test All
Ctrl+Alt+R          - Launch in DAW (Reaper)
Ctrl+Alt+V          - Validate Plugin
Ctrl+Alt+P          - Process Audio Test
Ctrl+Alt+B          - Benchmark DSP

macOS¶

Cmd+Shift+B         - Build: Debug (default)
F7                  - CMake: Build
Cmd+Shift+F7        - CMake: Clean Rebuild
Cmd+Option+Shift+C  - CMake: Configure

Cmd+Option+T        - Build and Test All
Cmd+Option+R        - Launch in DAW (Logic/Reaper)
Cmd+Option+V        - Validate Plugin
Cmd+Option+P        - Process Audio Test
Cmd+Option+B        - Benchmark DSP

To customize shortcuts:

Open keyboard shortcuts: Ctrl+K Ctrl+S
Search: "Tasks: Run Task"
Add keybinding for specific task

Example custom keybinding:

{
  "key": "ctrl+alt+f",
  "command": "workbench.action.tasks.runTask",
  "args": "Format: All Code"
}

Task Configuration¶

Task Anatomy¶

Basic task structure:

{
  "label": "Task Name",           // Display name
  "type": "shell",                // Type: shell, process, npm, cmake
  "command": "echo",              // Command to execute
  "args": ["Hello World"],        // Command arguments
  "problemMatcher": [],           // Error detection pattern
  "group": "build",               // Group: build, test
  "presentation": {               // Terminal appearance
    "echo": true,
    "reveal": "always",
    "focus": false,
    "panel": "shared"
  },
  "options": {                    // Execution options
    "cwd": "${workspaceFolder}"
  }
}

Task Properties¶

Type: - shell: Run shell command (bash, PowerShell, etc.) - process: Run executable directly (no shell) - cmake: CMake Tools integration - npm: Node.js package scripts

Problem Matchers: - $gcc: GCC/Clang error format - $msCompile: MSVC error format - $cmake: CMake error format - Custom regex patterns

Group: - build: Build tasks (appears in Ctrl+Shift+B menu) - test: Test tasks - none: Uncategorized

Presentation: - reveal: always, never, silent (show terminal) - focus: true (focus terminal), false (keep editor focus) - panel: shared (reuse terminal), new (new terminal per task)

Variables¶

VS Code supports variables in tasks:

{
  "command": "${workspaceFolder}/build/${buildType}/MyApp.exe",
  "args": ["${file}", "${fileBasename}"]
}

Common variables: - ${workspaceFolder}: Root directory - ${file}: Current file path - ${fileBasename}: Current filename - ${fileDirname}: Current file's directory - ${buildType}: CMake build type (Debug/Release) - ${env:PATH}: Environment variable

Adding Custom Tasks¶

Step 1: Open tasks.json¶

Ctrl+Shift+P → "Tasks: Open User Tasks"
Or manually open: vscode/tasks/tasks.json

Step 2: Add Task to Array¶

{
  "version": "2.0.0",
  "tasks": [
    // ... existing tasks ...
    {
      "label": "My Custom Task",
      "type": "shell",
      "command": "echo",
      "args": ["Hello AudioLab"],
      "problemMatcher": []
    }
  ]
}

Step 3: Test Task¶

Ctrl+Shift+P → "Tasks: Run Task" → "My Custom Task"

Example: Custom Audio Processing Task¶

{
  "label": "Audio: Process All Test Files",
  "type": "shell",
  "command": "powershell",
  "args": [
    "-File",
    "${workspaceFolder}/scripts/process_all_audio.ps1"
  ],
  "problemMatcher": [],
  "group": "test",
  "presentation": {
    "reveal": "always",
    "panel": "new"
  }
}

Example: Task with Dependencies¶

{
  "label": "Build and Validate",
  "dependsOn": ["Build: Release", "Validate: Plugin"],
  "dependsOrder": "sequence",
  "problemMatcher": []
}

Execution: Builds first, then validates.

Integration with Keybindings¶

Tasks can be triggered via keyboard shortcuts (see keybindings/README.md).

Bind Shortcut to Task¶

In keybindings.json:

{
  "key": "ctrl+alt+p",
  "command": "workbench.action.tasks.runTask",
  "args": "Audio: Process Test File"
}

Key points: - args must match task label exactly (case-sensitive) - Use unique shortcuts to avoid conflicts - Test shortcut: Press key, verify task runs

AudioLab Pre-configured Shortcuts¶

Already configured (see keybindings/keybindings.json):

Ctrl+Alt+T  → "Build and Test Plugin"
Ctrl+Alt+R  → "Launch in Reaper"
Ctrl+Alt+V  → "Validate Plugin"
Ctrl+Alt+P  → "Process Audio Test"
Ctrl+Alt+B  → "Benchmark DSP"

To add more:

Define task in tasks.json
Add keybinding in keybindings.json
Reload VS Code: Ctrl+Shift+P → "Reload Window"

Troubleshooting¶

Issue 1: Task Not Found¶

Symptoms: - "Task 'X' not found" error - Task doesn't appear in task list

Solutions:

Check task label matches exactly:

// In keybindings.json
"args": "Build: Debug"  // Must match label in tasks.json

// In tasks.json
"label": "Build: Debug"  // Must match exactly (case-sensitive)

Reload tasks:

Ctrl+Shift+P → "Tasks: Run Task"
This refreshes task list

Check tasks.json syntax:

Open tasks.json
Look for red underlines (syntax errors)
Common: Missing comma, extra comma, unmatched brackets

Issue 2: Command Not Found¶

Symptoms: - "'cmake' is not recognized as an internal or external command" - "command not found: pluginval"

Solutions:

Check command in PATH:

# Windows
where cmake
where pluginval

# macOS/Linux
which cmake
which pluginval

Use full path:

{
  "command": "C:/Program Files/CMake/bin/cmake.exe",
  // Instead of: "command": "cmake"
}

Add to PATH:

# Windows (PowerShell as Admin)
$env:Path += ";C:\Program Files\CMake\bin"
setx PATH "$env:Path"

# macOS/Linux
export PATH="$PATH:/usr/local/bin"
echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc

Restart VS Code after PATH changes.

Issue 3: Task Runs but No Output¶

Symptoms: - Task completes instantly - No output in terminal - Exit code 0 but nothing happened

Solutions:

Check presentation settings:

{
  "presentation": {
    "reveal": "always",  // Show terminal
    "focus": false,
    "panel": "shared",
    "echo": true,        // Echo command
    "showReuseMessage": true
  }
}

Test command manually:

# Open terminal in VS Code
Ctrl+` (backtick)

# Run command manually
cmake --build ./build/Debug

# If it works: Task config issue
# If it fails: Command/path issue

Add debug output:

{
  "command": "echo",
  "args": [
    "Starting task...",
    "&&",
    "cmake",
    "--build",
    "./build"
  ]
}

Issue 4: Problem Matcher Not Working¶

Symptoms: - Errors not appearing in Problems panel - Build fails but no errors shown

Solutions:

Check problem matcher is correct:

// For GCC/Clang
"problemMatcher": ["$gcc"]

// For MSVC
"problemMatcher": ["$msCompile"]

// For CMake
"problemMatcher": ["$cmake"]

Test with built-in matcher:

"problemMatcher": {
  "owner": "cpp",
  "fileLocation": ["relative", "${workspaceFolder}"],
  "pattern": {
    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
    "file": 1,
    "line": 2,
    "column": 3,
    "severity": 4,
    "message": 5
  }
}

Verify error output format:

# Expected format for $gcc:
file.cpp:42:10: error: expected ';' before '}' token

# Parts:
# file.cpp     - filename
# 42           - line number
# 10           - column number
# error        - severity
# expected...  - message

Issue 5: Task Hangs (Never Completes)¶

Symptoms: - Task runs indefinitely - Terminal shows no output - Cannot stop task

Solutions:

Kill task manually:

Click trash icon in terminal
Or: Ctrl+C in terminal

Check for infinite loops:

# Example bad task:
"command": "tail -f logfile.txt"  // Never ends!

# Fix: Add timeout or exit condition

Add timeout (custom):

{
  "command": "timeout",
  "args": [
    "30",  // 30 seconds
    "my-long-running-command"
  ]
}

Use background tasks for servers:

{
  "label": "Start Dev Server",
  "isBackground": true,  // Allows task to run in background
  "problemMatcher": {
    "pattern": {
      "regexp": "^Server started$"
    },
    "background": {
      "activeOnStart": true,
      "beginsPattern": "^Starting server",
      "endsPattern": "^Server started$"
    }
  }
}

Best Practices¶

1. Use Descriptive Labels¶

Good:

"label": "Build: Debug (C++20, JUCE 7.0)"

Bad:

"label": "build"

{
  "label": "Build: Debug",
  "group": {
    "kind": "build",
    "isDefault": true  // Makes this the default build task
  }
}

3. Use Problem Matchers¶

Always include problem matcher for build/test tasks:

"problemMatcher": ["$gcc"]

Benefit: Errors appear in Problems panel, clickable to jump to line.

4. Add Presentation Settings¶

"presentation": {
  "reveal": "always",      // Show terminal
  "focus": false,          // Keep focus on editor
  "panel": "shared",       // Reuse terminal
  "clear": true            // Clear terminal before running
}

5. Use Variables for Paths¶

Good:

"command": "${workspaceFolder}/build/Debug/MyApp.exe"

Bad:

"command": "C:/AudioDev/audio-lab/build/Debug/MyApp.exe"

Why: Portable across machines and users.

keybindings/README.md - Keyboard shortcuts for tasks
launch/README.md - Debug configurations
settings/README.md - CMake and build settings
VS Code Tasks Documentation

Examples¶

Complete Task: Build + Test + Validate¶

{
  "label": "Full Pipeline",
  "dependsOn": [
    "Build: Release",
    "Test: All",
    "Validate: Plugin"
  ],
  "dependsOrder": "sequence",
  "problemMatcher": []
}

Workflow: 1. Build Release 2. Run all tests 3. Validate with PluginVal 4. Stop if any step fails

Shortcut:

// In keybindings.json
{
  "key": "ctrl+alt+shift+t",
  "command": "workbench.action.tasks.runTask",
  "args": "Full Pipeline"
}

Last Updated: October 2024 Version: 1.0.0 Maintained by: AudioLab DevOps Team

Questions? Ask in #build-automation Discord channel or open GitHub issue.

🔨 VS Code Tasks - AudioLab¶

📋 Table of Contents¶

Overview¶

Files in This Directory¶

tasks.json¶

Available Tasks¶

Build Tasks¶

Test Tasks¶

Validation Tasks¶

Audio Workflow Tasks¶

Utility Tasks¶

Running Tasks¶

Method 1: Command Palette (Most Common)¶

Method 2: Default Build Task¶

Method 3: Keyboard Shortcuts¶

Method 4: Terminal Menu¶

Task Categories¶

🔨 Build Tasks¶

🧪 Test Tasks¶

✅ Validation Tasks¶

🎧 Audio Tasks¶

Keyboard Shortcuts¶

Windows/Linux¶

macOS¶

Task Configuration¶

Task Anatomy¶

Task Properties¶

Variables¶

Adding Custom Tasks¶

Step 1: Open tasks.json¶

Step 2: Add Task to Array¶

Step 3: Test Task¶

Example: Custom Audio Processing Task¶

Example: Task with Dependencies¶

Integration with Keybindings¶

Bind Shortcut to Task¶

AudioLab Pre-configured Shortcuts¶

Troubleshooting¶

Issue 1: Task Not Found¶

Issue 2: Command Not Found¶

Issue 3: Task Runs but No Output¶

Issue 4: Problem Matcher Not Working¶

Issue 5: Task Hangs (Never Completes)¶

Best Practices¶

1. Use Descriptive Labels¶

2. Group Related Tasks¶

3. Use Problem Matchers¶

4. Add Presentation Settings¶

5. Use Variables for Paths¶

Related Documentation¶

Examples¶

Complete Task: Build + Test + Validate¶

`tasks.json`¶