08_01 - Composition Tools

Visual plugin composition system for AudioLab

Build audio plugins by composing DSP components through JSON manifests, with automatic code generation and validation.

📋 Overview

The Composition Tools module enables rapid plugin development through a component-based visual approach:

1. Select components from a curated catalog (filters, dynamics, effects)
2. Define routing and parameter mappings in a JSON manifest
3. Validate the design (syntax, semantics, performance)
4. Generate C++ code automatically from templates
5. Build and deploy your plugin

🏗️ Architecture

08_01_composition_tools/
├── 08_01_00_component_library/    # DSP component catalog (15 components)
├── 08_01_01_visual_composer/      # Manifest parser + routing validation
├── 08_01_02_manifest_compiler/    # Code generation engine
├── 08_01_03_template_system/      # Plugin templates (L4/L5)
├── 08_01_04_validation_engine/    # Multi-level validation
├── tests/                         # Comprehensive test suite
└── examples/                      # Usage examples

🚀 Quick Start

1. Create a Plugin Manifest

{
  "name": "MyCompressor",
  "version": "1.0.0",
  "components": [
    {
      "id": "comp1",
      "type": "compressor_rms",
      "parameters": {
        "threshold": -20.0,
        "ratio": 4.0,
        "attack": 10.0,
        "release": 100.0
      }
    }
  ],
  "connections": [
    {"from": "input", "to": "comp1"},
    {"from": "comp1", "to": "output"}
  ],
  "parameters": [
    {
      "id": "threshold",
      "name": "Threshold",
      "min": -60.0,
      "max": 0.0,
      "default": -20.0,
      "unit": "dB",
      "mappings": [
        {"component": "comp1", "parameter": "threshold"}
      ]
    }
  ]
}

2. Validate & Compile

#include "composition_tools.hpp"

// Load components
ComponentRegistry::getInstance().loadFromJson("component_catalog.json");

// Parse manifest
ManifestParser parser;
parser.parse("my_plugin.json");
auto manifest = parser.getManifest();

// Validate
ManifestValidator validator;
auto messages = validator.validate(manifest, ComponentRegistry::getInstance());

if (validator.isValid()) {
    // Compile to C++
    ManifestCompiler compiler;
    auto result = compiler.compile(manifest, ComponentRegistry::getInstance());

    std::cout << "Generated: " << result.outputDirectory << std::endl;
}

3. Build the Generated Plugin

cd generated/MyCompressor
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .

📦 Module Details

Component Library (08_01_00)

15 Pre-built DSP Components:

Category	Components
Filters	Biquad Filter, Parametric EQ
Dynamics	RMS Compressor, Gate/Expander, Lookahead Limiter
Time	Simple Delay
Space	Algorithmic Reverb
Distortion	Soft Saturator
Modulation	Stereo Chorus, Classic Phaser, Multi-Wave LFO
Utility	Stereo Panner, Gain Utility, Envelope Follower
Analysis	Spectrum Analyzer

Features: - Component metadata (CPU cost, latency, I/O configuration) - Factory pattern for dynamic instantiation - JSON catalog with searchability

Visual Composer (08_01_01)

Manifest Parser: - JSON schema validation - Component/connection parsing - Parameter mapping resolution

NodeGraph: - Directed acyclic graph (DAG) representation - Cycle detection (DFS-based) - Topological sort for processing order

RoutingValidator: - Port index validation - Type compatibility checking - Latency analysis

Manifest Compiler (08_01_02)

Code Generation: - Plugin class generation (header + source) - Parameter enums and metadata - CMakeLists.txt generation

Template Engine: - Variable substitution: {{variable_name}} - Conditionals: {% if condition %}...{% endif %} - Comments: {# comment #}

Template System (08_01_03)

4 Plugin Templates:

Template	Description	Use Case
L4 Simple	Basic effect plugin	Simple processors
L4 Modulation	LFO/envelope support	Modulated effects
L5 Suite	Multi-module suite	Complex processors
L5 Channel Strip	Complete channel chain	Mixing tools

Template Variables: - {{plugin_name}}, {{plugin_version}} - {{num_inputs}}, {{num_outputs}} - {{base_class}}, {{components}}

Validation Engine (08_01_04)

5 Specialized Validators:

1. SyntaxValidator - Structure and naming
2. SemanticValidator - Type and reference checking
3. DependencyValidator - Graph structure and cycles
4. PerformanceValidator - CPU/latency/memory budgets
5. RoutingValidator - Connection validity

Validation Rules (Configurable):

ValidationRules rules;
rules.maxComponents = 50;
rules.maxCpuCost = 100;
rules.maxLatencySamples = 8192;
rules.allowCycles = false;
rules.requireRealTimeSafety = true;

Severity Levels: - Info → Informational messages - Warning → Best practice violations - Error → Blocking issues - Critical → Fatal errors

🧪 Testing

Run Tests

cd tests
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build .
ctest --output-on-failure

Test Coverage

• test_component_library.cpp - Component registration and discovery
• test_manifest_parser.cpp - JSON parsing and node graph
• test_validator.cpp - All validation layers

Coverage: >80%

📚 Examples

Complete Workflow

See examples/example_workflow.cpp for a full demonstration:

1. Load component catalog
2. Parse manifest
3. Validate design
4. Compile to C++
5. Instantiate from template

Example Plugins

• examples/simple_filter_plugin.json - Basic filter
• schemas/example_compressor.json - Compressor with gain

🔧 Build System

Main CMakeLists Structure

# Component Library
add_library(component_library STATIC ...)
target_link_libraries(component_library PUBLIC nlohmann_json::nlohmann_json)

# Visual Composer
add_library(visual_composer STATIC ...)

# Manifest Compiler
add_library(manifest_compiler STATIC ...)

# Template System
add_library(template_system STATIC ...)

# Validation Engine
add_library(validation_engine STATIC ...)

Dependencies

• nlohmann/json - JSON parsing (via vcpkg)
• Catch2 - Testing framework (via vcpkg)
• 08_00 - Plugin infrastructure (internal)

📊 Performance

Component Costs (CPU 0-100 scale)

Component	CPU Cost	Latency	Memory
Biquad Filter	10	0	512 B
RMS Compressor	25	0	2 KB
Algorithmic Reverb	45	0	32 KB
Spectrum Analyzer	40	0	16 KB

Validation Performance

• Syntax validation: <1ms
• Semantic validation: <5ms (depends on component count)
• Full validation: <10ms for typical plugins

Code Generation

• Compilation time: <100ms
• Template instantiation: <50ms

🎯 Design Patterns

Component Pattern

• Registry for discovery
• Factory for instantiation
• Metadata for introspection

Graph Pattern

• Topological sort for execution order
• DFS cycle detection
• Connection validation

Template Method Pattern

• Base validator with specialized implementations
• Configurable validation rules

⚠️ Best Practices

Manifest Design

✅ DO: - Keep component count reasonable (<20) - Use descriptive component IDs - Map parameters to actual controls - Validate before compiling

❌ DON'T: - Create feedback loops (cycles) - Exceed CPU budget - Use invalid component types - Skip validation

Real-Time Safety

✅ Ensure: - No allocations in audio thread - Pre-allocated buffers - Lock-free communication - Deterministic execution

📝 Manifest Schema

Full JSON schema: 08_01_01_visual_composer/schemas/manifest_schema.json

Required fields: - name, components, connections

Optional fields: - description, author, category - io (defaults: 2 in, 2 out) - parameters (exposed controls) - build settings

🚧 Future Enhancements

• Visual graph editor (web-based)
• Hot-reload for rapid iteration
• Component marketplace
• Preset management
• A/B comparison tools
• Automated testing generation

📖 Related Modules

• 08_00 - Plugin Infrastructure (base classes)
• 08_02 - DSP Integration Layer (signal routing)
• 08_10 - L4 Plugin Architecture (simple plugins)
• 08_11 - L5 Suite Architecture (complex plugins)

📄 License

Part of the AudioLab framework. See main project LICENSE.

---

Generated by AudioLab Composition Tools Build audio plugins visually, compile automatically, validate thoroughly.