matlab-write-audio-plugin

name	matlab-write-audio-plugin
description	Guide authoring of Audio Toolbox plugins (audioPlugin, audioPluginSource) that pass validateAudioPlugin and generate deployable VST/AU code. Use when creating audio effect or generator plugins, writing classdef files inheriting from audioPlugin, or troubleshooting validateAudioPlugin failures.
license	https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md
metadata	{"author":"MathWorks","version":"1.0"}

Writing Audio Plugins in MATLAB

When To Use

• Creating audio effect or generator plugins (classdef inheriting from audioPlugin or audioPluginSource)
• Troubleshooting validateAudioPlugin or generateAudioPlugin failures
• Converting a MATLAB audio algorithm into a deployable VST/AU plugin
• Integrating deep learning inference into a real-time audio plugin

When NOT To Use

• General MATLAB class authoring unrelated to audio plugins
• Audio file I/O, feature extraction, or analysis (no plugin involved)
• Simulink audio processing blocks
• Writing Audio Toolbox functions that are not plugins (e.g., audioDatastore, audioFeatureExtractor)

Structure

Every audio plugin is a classdef with %#codegen, public tunable properties, a Constant PluginInterface, and methods process + reset.

classdef MyPlugin < audioPlugin
%#codegen

    properties
        Gain = 0.5
        Cutoff = 1000
    end

    properties (Access = private)
        pSR = 44100
        pB = [1 0 0]
        pA = [1 0 0]
        pState = zeros(2, 2)  % (filterOrder, numChannels)
    end

    properties (Constant)
        PluginInterface = audioPluginInterface( ...
            audioPluginParameter('Gain', ...
                DisplayName='Gain', Label='dB', Mapping={'lin', 0, 1}), ...
            audioPluginParameter('Cutoff', ...
                DisplayName='Cutoff', Label='Hz', Mapping={'log', 20, 20000}), ...
            InputChannels=2, OutputChannels=2)
    end

    methods
        function y = process(plugin, x)
            [y, plugin.pState] = filter(plugin.pB, plugin.pA, x, plugin.pState);
            y = y * plugin.Gain;
        end

        function reset(plugin)
            plugin.pSR = getSampleRate(plugin);
            plugin.pState = zeros(2, 2);
            designFilter(plugin);
        end

        function set.Cutoff(plugin, val)
            plugin.Cutoff = val;
            designFilter(plugin); %#ok<MCSUP>
        end
    end

    methods (Access = private)
        function designFilter(plugin)
            wn = plugin.Cutoff / (plugin.pSR / 2);
            wn = max(eps, min(wn, 1 - eps));
            [plugin.pB, plugin.pA] = butter(2, wn);
        end
    end
end

Source plugins inherit audioPluginSource, omit InputChannels, and process takes no audio input — use getSamplesPerFrame(plugin) for output frame size.

System Object hybrids (matlab.System & audioPlugin) require (StrictDefaults), isInputSizeMutableImpl returning true, and stepImpl/resetImpl instead of process/reset. Use only when user requests Simulink compatibility.

---

Plugin Lifecycle

1. Constructor — Construct all sub-objects with literal arguments. getSampleRate returns 44100 here; use for initial buffer sizing only.
2. reset — Called when sample rate or frame size changes. Cache getSampleRate(plugin) in pSR. Recompute all SR-dependent values. Call reset() on every sub-object (after setting their sample rate).
3. process — Called per audio frame. Return double output sized [N, numOutputChannels]. Never assign to properties registered in audioPluginParameter — for output meters, keep properties public but unregistered.
4. Set methods — Recompute derived values (coefficients, buffer sizes) when parameters change. Add %#ok<MCSUP> only when the set method actually accesses another property through obj.PropertyName or calls a method that does (e.g., designFilter(plugin) from set.Cutoff). Do not add it preemptively — only suppress warnings that checkcode actually raises on that line.
5. Save/load (optional, MATLAB-only) — Only needed when the plugin has private state that reset cannot reconstruct from parameters and sample rate (e.g., loaded data, handle sub-objects with internal buffers). Not compiled into generated VSTs/standalones — DAW hosts persist parameters via the plugin interface and call reset on restore. See references/advanced-patterns.md for the pattern.

---

Codegen Requirements

All code must be codegen-compatible. validateAudioPlugin sweeps 5 sample rates (8000–192000), frame sizes 2.^(1:13)+1 (max 8193), and all parameter extremes.

Always use built-in functions over hand-implementations. Prefer toolbox functions in this order: Audio Toolbox → DSP System Toolbox → Signal Processing Toolbox → base MATLAB. If unsure whether a codegen-compatible built-in exists for an operation, consult references/available-functions.md before implementing manually.

Buffers and State

Pre-allocate all state to maximum needed size. Codegen locks property size from the constructor's last assignment — allocate at the maximum the parameter can reach, then index into the active region at runtime.

Shift with indexed assignment:

buf(1:end-N) = buf(N+1:end);   % shift left by N
buf(end-N+1:end) = newData;     % fill tail

Never concatenate to shift — [buf(N+1:end); zeros(N,ch)] produces a variable-size result that codegen rejects on assignment to a fixed-size property.

Never use : on the column dimension when assigning to a fixed-size property — codegen treats x(i,:) as variable-size. Index columns explicitly: [x(i,1), x(i,2)].

Initialize arrays that will hold complex values with complex(zeros(...)) — not bare zeros(...). Codegen locks the real/complex attribute from the first assignment. If the array starts real, assigning FFT output into it later fails with "left-hand side constrained to be non-complex."

dsp.AsyncBuffer capacity must exceed the largest single write the plugin will receive. validateAudioPlugin delivers frames up to 8193 samples; account for that plus any overlap when sizing the buffer.

When filter() input comes from a sub-object (e.g., crossoverFilter), codegen cannot propagate the column count — the returned state becomes variable-size. Process channels explicitly:

[low(:,1), plugin.pState(:,1)] = filter(b, a, low(:,1), plugin.pState(:,1));
[low(:,2), plugin.pState(:,2)] = filter(b, a, low(:,2), plugin.pState(:,2));

Enum Parameters (Different-Length Values)

Use Style='dropdown' for 3+ values, 'vrocker'/'vtoggle' for exactly 2.

When enum values have different character lengths ('On'/'Off', 'Short'/'VeryLong'), prefer a separate int32 enum class file. The framework can handle char padding internally, but an explicit enum class produces cleaner generated code with typed dispatch instead of string comparisons:

% MyMode.m
classdef MyMode < int32
    enumeration
        Normal     (0)
        Aggressive (1)
        Subtle     (2)
    end
end

Plugin property: Mode = MyMode.Normal with Mapping={'enum','Normal','Aggressive','Subtle'}.

Derived Values from Parameters

When computing normalized frequency or delay indices from parameters, clamp the result:

wn = plugin.Cutoff / (plugin.pSR / 2);
wn = max(eps, min(wn, 1 - eps));   % keep in valid (0,1) range for butter/cheby

Clamp delay-line read indices to [1, bufferLength]. This prevents out-of-bounds at extreme sample rates or parameter settings that validateAudioPlugin will exercise.

Switch Completeness

Every switch that assigns a variable must include otherwise with a safe default — codegen requires all branches to define the same outputs.

Sub-Objects

Construct with literal arguments in the constructor. In reset, propagate sample rate then reset:

function reset(plugin)
    fs = getSampleRate(plugin);
    setSampleRate(plugin.pEcho, fs);
    reset(plugin.pEcho);
    plugin.pCompressor.SampleRate = fs;
    reset(plugin.pCompressor);
end

Call sub-plugins as process(plugin.pSub, x). Call System Objects as plugin.pObj(x). Forward parameter changes in set methods.

External Data and Runtime-Only Calls

• Load data files: coder.load('data.mat') in the constructor — baked into the binary
• Guard non-codegen calls: wrap fprintf/disp/plot in if isempty(coder.target)

---

Validation

validateAudioPlugin -nomex ClassName   % structural + testbench
validateAudioPlugin ClassName          % full MEX codegen
generateAudioPlugin ClassName          % produce VST/AU binary

After validation passes:

1. Run checkcode on all produced .m files — resolve every warning by renaming or restructuring, not by adding %#ok suppressions (except %#ok<MCSUP> in set methods). Re-run checkcode to confirm zero warnings remain.
2. Verify functional behavior: instantiate, setSampleRate, reset, process a test signal, confirm output matches intent.

Generation

Default output is VST 2. Use flags to select other formats:

Flag	Format	Platform
-vst	VST 2 (default)	Windows, macOS
-vst3	VST 3	Windows, macOS
-au	Audio Unit v2	macOS only
-auv3	Audio Unit v3	macOS only
-exe	Standalone executable	Windows, macOS
-juceproject	JUCE project (source code)	All (including Linux)

When the user requests an output format unavailable on the current platform (e.g., AU on Windows, or any compiled binary on Linux), explain the constraint and suggest the closest alternative (-juceproject on Linux, -vst/-vst3 on Windows instead of AU).

---

References

• references/available-functions.md — Built-in streaming DSP objects (prefer over manual implementations)
• references/advanced-patterns.md — AsyncBuffer, modulated delay, save/load, codegen edge cases
• references/parameters.md — Mapping laws, multi-bus I/O, grid layout constraints
• references/grid-layout.md — Grid layout syntax, row allocation with DisplayNameLocation
• references/deep-learning.md — Neural network inference with coder.loadDeepLearningNetwork

---

Copyright 2026 The MathWorks, Inc.