matlab-write-audio-plugin

MATLAB でのオーディオプラグインの作成

使用する場合

• オーディオエフェクトまたはジェネレータープラグインを作成する場合（audioPlugin または audioPluginSource を継承する classdef）
• validateAudioPlugin または generateAudioPlugin の失敗をトラブルシューティングする場合
• MATLAB のオーディオアルゴリズムを、デプロイ可能な VST/AU プラグインに変換する場合
• ディープラーニングの推論をリアルタイムオーディオプラグインに統合する場合

使用しない場合

• オーディオプラグインに関連しない、一般的な MATLAB クラスの作成
• オーディオファイルの入出力、特徴抽出、分析（プラグインを使用しない場合）
• Simulink のオーディオ処理ブロック
• プラグインではない Audio Toolbox 関数の作成（例：audioDatastore、audioFeatureExtractor）

構造

すべてのオーディオプラグインは、%#codegen、パブリックな調整可能プロパティ、Constant の PluginInterface、および process と reset メソッドを持つ classdef です。

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

ソースプラグインは audioPluginSource を継承し、InputChannels を省略します。また、process はオーディオ入力を受け取りません。出力フレームサイズには getSamplesPerFrame(plugin) を使用してください。

System Object ハイブリッド（matlab.System & audioPlugin）には、(StrictDefaults)、true を返す isInputSizeMutableImpl、および process／reset の代わりに stepImpl／resetImpl が必要です。Simulink との互換性をユーザーが求めている場合に限り使用してください。

---

プラグインのライフサイクル

1. コンストラクター — すべてのサブオブジェクトをリテラル引数で構築します。ここでの getSampleRate の戻り値は 44100 です。初期バッファーサイズの設定にのみ使用してください。
2. reset — サンプルレートまたはフレームサイズが変わると呼び出されます。getSampleRate(plugin) を pSR にキャッシュします。サンプルレートに依存する値をすべて再計算します。各サブオブジェクトのサンプルレートを設定してから、そのすべてに対して reset() を呼び出します。
3. process — オーディオフレームごとに呼び出されます。サイズが [N, numOutputChannels] の double 出力を返します。audioPluginParameter に登録されたプロパティには決して代入しないでください。出力メーター用のプロパティは、パブリックのまま登録せずに保持してください。
4. Set メソッド — パラメーターの変更時に派生値（係数、バッファーサイズ）を再計算します。%#ok<MCSUP> を追加するのは、Set メソッドが obj.PropertyName を通じて別のプロパティに実際にアクセスする場合、またはそのようなアクセスを行うメソッド（例：set.Cutoff からの designFilter(plugin)）を呼び出す場合に限ります。あらかじめ追加しないでください。実際にその行で checkcode が出す警告だけを抑制してください。
5. 保存／読み込み（任意、MATLAB 専用） — reset ではパラメーターとサンプルレートから復元できないプライベート状態（読み込んだデータや、内部バッファーを持つハンドルサブオブジェクトなど）がプラグインにある場合に限り必要です。生成された VST／スタンドアロンにはコンパイルされません。DAW ホストはプラグインインターフェイスを介してパラメーターを保持し、復元時に reset を呼び出します。パターンについては references/advanced-patterns.md を参照してください。

---

コード生成の要件

すべてのコードはコード生成に対応している必要があります。validateAudioPlugin は、5 種類のサンプルレート（8000～192000）、フレームサイズ 2.^(1:13)+1（最大 8193）、およびすべてのパラメーターの極値を対象に検証します。

手作業で実装するより、常に組み込み関数を使用してください。 ツールボックス関数は次の順に優先してください：Audio Toolbox → DSP System Toolbox → Signal Processing Toolbox → base MATLAB。ある処理にコード生成対応の組み込み関数があるかどうかわからない場合は、手作業で実装する前に references/available-functions.md を確認してください。

バッファーと状態

状態は必要な最大サイズで事前に確保してください。コード生成では、コンストラクターで最後に代入された値によってプロパティのサイズが固定されます。パラメーターが取り得る最大値で確保し、実行時には有効な領域をインデックスで指定してください。

インデックス付き代入でシフトします。

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

シフトに連結は使用しないでください。[buf(N+1:end); zeros(N,ch)] は可変サイズの結果を生成するため、コード生成では固定サイズのプロパティへの代入が拒否されます。

固定サイズのプロパティに代入する際は、列方向に : を使用しないでください。コード生成では x(i,:) が可変サイズとして扱われます。列を明示的にインデックスで指定してください。[x(i,1), x(i,2)] のように記述します。

複素数値を格納する配列は、zeros(...) だけでなく complex(zeros(...)) で初期化してください。コード生成では、最初の代入によって実数／複素数の属性が固定されます。配列が実数として始まると、後で FFT の出力を代入した際に「左辺が複素数ではないと制約されています」というエラーが発生します。

dsp.AsyncBuffer の容量は、プラグインが受け取る最大の単一の write サイズを超える必要があります。validateAudioPlugin は最大8193サンプルのフレームを渡すため、バッファーのサイズを決める際は、そのサイズに加えてオーバーラップも考慮してください。

filter() の入力がサブオブジェクト（例：crossoverFilter）に由来する場合、コード生成では列数を伝播できず、返される状態が可変サイズになります。チャンネルを明示的に処理してください。

[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 パラメーター（値の長さが異なる場合）

値が3つ以上の場合は Style='dropdown' を、2つの場合は 'vrocker'／'vtoggle' を使用してください。

Enum 値の文字数が異なる場合（'On'／'Off'、'Short'／'VeryLong' など）は、別の int32 Enum クラスファイルを使用することをおすすめします。フレームワークは文字のパディングを内部で処理できますが、明示的な Enum クラスを使うと、文字列比較ではなく型付きディスパッチを使用する、より簡潔な生成コードになります。

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

プラグインのプロパティ：Mapping={'enum','Normal','Aggressive','Subtle'} を指定して Mode = MyMode.Normal とします。

パラメーターからの派生値

パラメーターから正規化周波数や遅延インデックスを計算する場合は、結果をクランプしてください。

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

遅延ラインの読み取りインデックスは [1, bufferLength] にクランプしてください。これにより、validateAudioPlugin がテストする極端なサンプルレートやパラメーター設定で、範囲外アクセスが発生するのを防げます。

Switch の網羅性

変数に代入するすべての switch には、安全なデフォルト値を設定する otherwise を含めてください。コード生成では、すべての分岐で同じ出力が定義されている必要があります。

サブオブジェクト

コンストラクターではリテラル引数を使って構築してください。reset では、サンプルレートを渡してからリセットします。

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

サブプラグインは process(plugin.pSub, x) として呼び出してください。System Object は plugin.pObj(x) として呼び出してください。set メソッドではパラメーターの変更を転送してください。

外部データと実行時のみの呼び出し

• データファイルを読み込む場合：コンストラクターで coder.load('data.mat') を使用します。データはバイナリに埋め込まれます。
• コード生成の対象外となる呼び出しを保護する場合：fprintf／disp／plot を if isempty(coder.target) で囲みます。

---

検証

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

検証に合格したら、次の手順を行います。

1. 生成されたすべての .m ファイルに対して checkcode を実行し、すべての警告を名前の変更または構造の見直しによって解消してください。%#ok による抑制は追加しないでください（set メソッド内の %#ok<MCSUP> を除く）。警告がゼロになったことを確認するため、checkcode を再実行してください。
2. 機能を確認します。インスタンスを作成し、setSampleRate と reset を実行してテスト信号を処理し、出力が意図どおりであることを確認してください。

生成

デフォルトの出力形式は VST 2 です。他の形式を選択するには、フラグを使用してください。

フラグ	形式	プラットフォーム
-vst	VST 2（デフォルト）	Windows、macOS
-vst3	VST 3	Windows、macOS
-au	Audio Unit v2	macOS のみ
-auv3	Audio Unit v3	macOS のみ
-exe	スタンドアロン実行ファイル	Windows、macOS
-juceproject	JUCE プロジェクト（ソースコード）	すべて（Linux を含む）

ユーザーが現在のプラットフォームで利用できない出力形式（例：Windows での AU、Linux でのコンパイル済みバイナリ）を求めた場合は、その制約を説明し、最も近い代替案を提案してください（Linux では -juceproject、Windows では AU の代わりに -vst／-vst3）。

---

参考資料

• references/available-functions.md — 組み込みのストリーミング DSP オブジェクト（手動で実装するよりこちらを優先してください）
• references/advanced-patterns.md — AsyncBuffer、変調ディレイ、保存／読み込み、コード生成におけるエッジケース
• references/parameters.md — マッピング則、マルチバス I/O、グリッドレイアウトの制約
• references/grid-layout.md — グリッドレイアウトの構文、DisplayNameLocation を使用した行の割り当て
• references/deep-learning.md — coder.loadDeepLearningNetwork を使用したニューラルネットワークの推論

---

Copyright 2026 The MathWorks, Inc.