ネイティブ オーディオ プラグイン SDK

このドキュメントでは、Unity 5.0に組み込まれたネイティブオーディオプラグインインターフェースについて記述します。いくつかの具体的なプラグイン例について、先へ進むにつれてより複雑なものを見ていきます。この方法により、非常に基本的な概念から始めて、ドキュメントの終わりの方では、より複雑な使用例をご紹介します。

ダウンロード

まず最初に、こちらから最新のオーディオプラグイン SDK をダウンロードしてください。

概要

ネイティブオーディオプラグインシステムは、2つの部分から構成されます。

1. ネイティブ DSP（デジタル信号処理）プラグインは、C または C++の.dll（Windows）または.dylib の（OSX）として実装されます。スクリプトとは違い、パフォーマンス上の高い要求のために、あなたは、プラットフォーム固有の最適化と、および、サポートしたい任意のプラットフォーム用にコンパイルする必要があります。

2. C# で開発される GUI。GUI は任意であることに注意してください。そのため、常に基本的なネイティブ DSP プラグインを作成することから、プラグイン開発を始める事ができます。ネイティブプラグインで公開している、パラメータを設定するためのデフォルトのスライダーベース UI を Unity で表示してみましょう。どのようなプロジェクトでもブートストラップするため、このアプローチをお勧めします。

最初は、 C# による GUI の原型を Assets/Editor フォルダーにドロップするだけで、 .cs ファイルとして作成できることを覚えておいてください（他のエディタースクリプトと全く同じです）。コードが伸び始め、よりよいモジュール化とよりよい IDE サポートが必要になり始めたら、後から適切な MonoDevelop のプロジェクトに移動することができます。これによって .dll にコンパイルすることが可能となるため、ユーザーがプロジェクトにドロップする事が容易になり、またコードを保護する事もできます。

また、ネイティブ DSP と GUI の DLL は両方とも複数のプラグインを含めることができ、そのバインディングは DLL 名に関係なく、プラグイン内のエフェクト名を通してのみ発生する事に気をつけてください。

すべてのこれらのファイルは何だろう？

ネイティブな面では、プラグイン SDK は実際は一つのファイル （AudioPluginInterface.h） からできていますが、同じ DLL 内に複数のプラグインエフェクトを持つことが簡単にできます。私たちは、シンプルな統合された方法 (AudioPluginUtil.h と AudioPluginUtil.cpp) で、エフェクト定義とパラメータ登録の制御をサポートするコードを追加しました。NativePluginDemo プロジェクトには、あなたの手助けになる多くのサンプルプラグインが含まれていることを覚えておいてください。ゲームの状況にあわせるのに便利な、様々な異なるプラグインタイプを見ることができます。このコードはパブリックドメインになっているので、あなた自身による創造のための出発点として、このコードを遠慮なく使ってください。

プラグインの開発は、あなたのプラグインが必要なパラメータの定義から始めます。あなたは、スタートする前に、プラグインが配置するすべてのパラメータの詳細なマスタープランを持っている必要はありません。しかし、それはユーザーにどんな経験をしてもらいたいか、どのコンポーネントが必要になってくるかについての大まかなアイデアを持っていると役立ちます。

提供するプラグインのサンプルには、使いやすいユーティリティ関数がたくさん含まれています。 “Ring Modulator” プラグイン例を見てみましょう。このシンプルなプラグインは、正弦波で入力される信号を掛け合わせます。特に、周波数が異なる複数のリングモジュレーション効果が連鎖すると、ラジオノイズ/壊れた受信機のようなエフェクトを与えます。

例のプラグインのパラメータを扱うための基本的なスキームは、利便性と簡潔さの両方のために float の配列へのインデックスとして使用する列挙値としてそれらを定義することです。

enum Param
{
    P_FREQ,
    P_MIX,
    P_NUM
};

int InternalRegisterEffectDefinition(UnityAudioEffectDefinition& definition)
{
    int numparams = P_NUM;
    definition.paramdefs = new UnityAudioParameterDefinition [numparams];
    RegisterParameter(definition, "Frequency", "Hz",
        0.0f, kMaxSampleRate, 1000.0f,
        1.0f, 3.0f,
        P_FREQ);
    RegisterParameter(definition, "Mix amount", "%",
        0.0f, 1.0f, 0.5f,
        100.0f, 1.0f,
        P_MIX);
    return numparams;
}

RegisterParameter が呼び出す数字は、最小値、最大値、デフォルト値、そして表示のみに使用するスケーリング係数が続きます。すなわち、パーセント値の場合は、実際の値は 0 から 1 で、表示されるときは 100 で拡大されます。このためのカスタム GUI コードはありませんが、前述したように Unity はこれらの基本的なパラメータ定義からデフォルトの GUI を生成します。未定義のパラメータをチェックするシステムはないことに注意してください。AudioPluginUtil システムは、宣言されたすべての列挙型の値 (`P_NUM は除く) は、対応するパラメータ定義とマッチしていると想定しています。

舞台裏では RegisterParameter 関数 (“AudioEffectPluginInterface.h”を参照) は、そのプラグインに関連付けられている UnityAudioEffectDefinition 構造体の UnityAudioParameterDefinition 配列のエントリに記入します。UnityAudioEffectDefinition で設定される必要がある残り部分は関数へのコールバックで、パラメーターを設定/取得し (SetFloatParameterCallback/ UnityAudioEffect_GetFloatParameterCallback)、実際の処理を行い (UnityAudioEffect_ProcessCallback)、終了後、最終的にプラグインのインスタンスを破棄します((UnityAudioEffect_ReleaseCallback)。

同じ DLL で複数のプラグインを持つことを簡単にするために、各プラグインは、独自の名前空間に収納されています。コールバック関数のための特定の命名規則が使用され、例えば、DEFINE_EFFECTとDECLARE_EFFECT` マクロはUnityAudioEffectDefinition 構造に記入することができます。見えないところでは、すべてのエフェクトの定義はポインタがライブラリ UnityGetAudioEffectDefinitions の唯一のエントリポイントで返さされた配列に格納されます。

これは、あなたが、VST や AudioUnits など他のプラグイン形式から、または、Unity オーディオプラグインインターフェースからマップするブリッジプラグインを開発したい場合、知っておくと便利です。その場合、ロード時にパラメータの記述を設定する、よりダイナミックな方法を開発する必要があります。

プラグインのインスタンス化

次は、プラグインのインスタンスのためのデータです。プラグイン例では、EffectData 構造体にこのすべてを置きます。これの割り当ては、ミキサー内のプラグインのインスタンスごとに呼び出され、対応する CreateCallback に起こる必要があります。この簡単な例では、すべてのチャネルに掛け合わせられた一つのサイン波があると、他のより高度なプラグインは、入力チャンネル毎の追加データを割り当てる必要があります。

struct EffectData
{
    struct Data
    {
        float p[P_NUM]; // パラメーター
        float s;        // オシレーターの正弦出力
        float c;        // オシレーターの余弦出力
    };
    union
    {
        Data data;
        unsigned char pad[(sizeof(Data) + 15) & ~15];
    };
};

UNITY_AUDIODSP_RESULT UNITY_AUDIODSP_CALLBACK CreateCallback(
    UnityAudioEffectState* state)
{
    EffectData* effectdata = new EffectData;
    memset(effectdata, 0, sizeof(EffectData));
    effectdata->data.c = 1.0f;
    state->effectdata = effectdata;
    InitParametersFromDefinitions(
        InternalRegisterEffectDefinition, effectdata->data.p);
    return UNITY_AUDIODSP_OK;
}

UnityAudioEffectState には、サンプリングレート、（タイミング）処理されるサンプル、またはプラグインがバイパスされているか、すべてのコールバック関数にするか、など、ホストからさまざまなデータが含まれます。

そして、もちろん、プラグインインスタンスをフリーにすることに該当する機能でもあります:

UNITY_AUDIODSP_RESULT UNITY_AUDIODSP_CALLBACK ReleaseCallback(
    UnityAudioEffectState* state)
{
    EffectData::Data* data = &state->GetEffectData<EffectData>()->data;
    delete data;
    return UNITY_AUDIODSP_OK;
}

オーディオの主な処理は ProcessCallback で起こります:

UNITY_AUDIODSP_RESULT UNITY_AUDIODSP_CALLBACK ProcessCallback(
    UnityAudioEffectState* state,
    float* inbuffer, float* outbuffer,
    unsigned int length,
    int inchannels, int outchannels)
{
    EffectData::Data* data = &state->GetEffectData<EffectData>()->data;
 
    float w = 2.0f * sinf(kPI * data->p[P_FREQ] / state->samplerate);
    for(unsigned int n = 0; n < length; n++)
    {
        for(int i = 0; i < outchannels; i++)
        {
            outbuffer[n * outchannels + i] =
                inbuffer[n * outchannels + i] *
                (1.0f - data->p[P_MIX] + data->p[P_MIX] * data->s);
        }
        data->s += data->c * w; // 正弦波を計算する負担の軽い方法
        data->c -= data->s * w;
    }
 
    return UNITY_AUDIODSP_OK;
}

GetEffectData 関数は、我々が上記で宣言した構造体の EffectData::data に状態変数の effectdata フィールドをキャストするヘルパー関数です。

含まれる他のシンプルなプラグインは、NoiseBox プラグインです。これは、可変周波数でのホワイトノイズ、または Lofinator のプラグインの入力信号を加えて、掛け合わせ、シンプルにダウンサンプリングし、信号の量子化を行います。これらのすべてを組み合わせ用いて、携帯電話、通信状態が悪い携帯無線、壊れた拡声器など何かをためにゲームドリブンアニメーションパラメータを使用してシミュレートすることができます。

StereoWidener は、可変遅延で mono(モノラル) や side コンポーネントにステレオ入力信号を分解し、その後、それらをステレオ効果の感じを高めるために再結合します。

どのプラットフォーム上にどのプラグインをロードする？

ネイティブオーディオプラグインは、それらはプラグインのインポーターインスペクター経由で、それぞれのプラットフォームに関連付けられてなければならず、他のネイティブまたは管理プラグインと同じスキームを使用します。あなたは デスクトップ向け のプラグインを配置して、サブフォルダーの詳細を読むことができます。プラットフォームの関連付けが必要です。そのため、スタンドアロンビルドで各ビルドターゲットに含めるプラグインをシステムは知っています。64ビットサポートの導入でもプラットフォーム内で指定する必要があります。ユニバーサルバイナリフォーマットは、同じバンドル内に32ビットおよび64ビットの両方のバリアントを含むのを許可しています。

マネージコードから呼び出される Unity のネイティブプラグインは、ネイティブ DLL からインポートする関数を参照している [DllImport] 属性を使用してロードされます。しかし、ネイティブオーディオプラグインの場合、事情が違います。ここで起こる特別な問題は、プラグインからエフェクトを必要とするかもしれないミキサーアセットを、Unity が作成を開始する前にオーディオプラグインをロードする必要があるということです。エディターでは、これは問題ありません。プラグインに依存するミキサーをリロードやリビルドできるからです。しかし、しかし、ミキサーアセットを作成する前に、スタンドアロンビルドでプラグインがロードされなければなりません。この問題を解決するには、現在のやり方は、プラグイン“audioplugin” (大文字小文字を区別しない) の DLL の前に付けることです。そのため、システムは、これを検出することができ、自動的に起動時にロードされるプラグインのリストに追加されます。Unity のミキサーの中に示されるエフェクトの名前を定義し、プラグイン内部でのみ定義することを忘れないでください。DLL は、何かを呼び出すことができますが、検出されるために文字列が、“audioplugin” で始まる必要があります。

iOS のようなプラットフォーム用のプラグインコードは、ジェネレートされた Xcode プロジェクトによって生成される Unity バイナリに静的にリンクされる必要があります。そして、そこに - レンダリングデバイスプラグインと同じように - プラグインの登録をアプリの起動コードに明示的に追加する必要があります。

OSX上で1つのバンドルには、32ビットおよび64ビット版の両方のプラグインを含むことができます。また、サイズを保存するためにそれらを分割することができます。

カスタム GUI を持つプラグイン

今度は、もう少し高度な応用例を見てみましょう:イコライゼーションおよびマルチバンド圧縮のためのエフェクトです。このようなプラグインは、前節で示したシンプルなプラグインよりも、はるかに多いパラメータ数を持っており、パラメータ間にいくつかの物理的な結合があります。それは、パラメータを視覚化するために、たくさんのシンプルなスライダーよりも、よりよい方法が必要です。インスタンスのためのイコライザーを考えてみましょう: 各バンドは、寄り集まって最終的にイコライゼーションカーブに貢献する3つの異なるフィルタを持ち、このフィルタそれぞれは、物理的にリンクされ、各フィルタの形状を定義している3つのパラメータ、周波数、Q 値およびゲインを持っています。だから、イコライザープラグインが結果の曲線を示す素敵な大きなディスプレイを持っている場合、個々のフィルタが寄与する、一度に1つのスライダーを変更する制御の代わりに簡単なドラッグ操作で複数のパラメータを同時に設定する方法で操作することができ、ユーザーに大いに役立ちます。

Equalizer プラグインのカスタム GUI。フィルタカーブのゲインと周波数を変更するには3つのバンドをドラッグします。各バンドの形状を変更するためにシフトボタンを押しながらドラッグしてください。

だから、もう一度、定義、初期化、初期化解除およびパラメータ処理は、単純なプラグインが使用する正確な同じ列挙型ベースの方法に従います。さらに ProcessCallback コードはかなり短いです。さて、タイムはネイティブコードを見て停止し、MonoDevelop で AudioPluginDemoGUI.sln プロジェクトを開きます。ここにあなたは、GUI コードのための associated C# クラスを見つけるでしょう。それが動作する方法は簡単です: いったん、Unity はネイティブプラグインの DLL をロードし、含まれるオーディオプラグインを登録したならば、それは登録されたプラグインの名前と一致する対応する GUI を探して起動します。これは、すべてのカスタムプラグインの GUI のように、IAudioEffectPluginGUI から継承する必要があり、EqualizerCustomGUI クラスの Name プロパティーを介して行われます。このクラス内に一つだけ重要な機能があります。ブール OnGUI(IAudioEffectPlugin plugin) 関数です。IAudioEffectPlugin プラグイン引数をを通して、ネイティブプラグインが定義したパラメータを読み書きするために、この関数はネイティブプラグインのハンドルを取得します。だから、パラメータを読むために、それをコールします:

plugin.GetFloatParameter("MasterGain", out masterGain);

どれかパラメータが見つかった場合、true を返し、それを設定し、それをコールします:

plugin.SetFloatParameter("MasterGain", masterGain);

どのパラメータが存在する場合にも true を返します。そして、それは基本的に GUI とネイティブコード間のもっとも重要な結合です。また、関数を使用することができます。

plugin.GetFloatParameterInfo("NAME", out minVal, out maxVal, out defVal);

クエリパラメータ “NAME” にとって、ネイティブと UI コードでこれらの最小値、最大値およびデフォルト値の複製定義を避けなければなりません。あなたの OnGUI 関数が true を返す場合には、インスペクターがカスタム GUI 下のデフォルトの UI のスライダーが表示されることに注意してください。これは、あなたのカスタム GUI を開発している間、使用可能なすべてのパラメータを持っていて、あなたの GUI 開発をブートストラップするために、再度便利で、それに対して正しいアクションの実行が期待されるようにパラメータに変化をもたらす簡単なチェックする方法を持っています。

私たちは、ここのイコライザおよびマルチバンドのプラグインの中で起こっている DSP 処理の詳細について説明しません。興味のある方のために、Robert Bristow-Johnson の名著 “Audio EQ Cookbook” からフィルタを取り上げます。曲線をプロットする Unity は、周波数応答のためのアンチエイリアス曲線を描くためにいくつかの内部 API 関数を提供します。

もう一つ言及することは、イコライザおよびマルチバンド両方のプラグインに興味深いポイントが表示され、プラグインのエフェクトを可視化するために、入出力のスペクトルをオーバーレイするためのコードが提供されることです: GUI コードは、オーディオ処理よりもはるかに低い更新速度（フレームレート）で実行し、オーディオストリームへのアクセス権を持っていないので、どのように、このデータを読んでいるのでしょうか？　このために、ネイティブコードで特別な関数があります:

UNITY_AUDIODSP_RESULT UNITY_AUDIODSP_CALLBACK GetFloatParameterCallback(
    UnityAudioEffectState* state,
    int index,
    float* value,
    char *valuestr)
{
    EffectData::Data* data = &state->GetEffectData<EffectData>()->data;
    if(index >= P_NUM)
        return UNITY_AUDIODSP_ERR_UNSUPPORTED;
    if(value != NULL)
        *value = data->p[index];
    if(valuestr != NULL)
        valuestr[0] = 0;
  return UNITY_AUDIODSP_OK;
}

これは単に、ネイティブプラグインからの浮動小数点データの配列を読むことができます。リそのデータが何であれ、プラグインシステムはクエストが大量に UI またはネイティブコードを遅くしない限り、気にしません。イコライザおよびマルチバンドコードについて、プラグインから入出力データを供給し、戻って、スペクトルを取り戻すことが容易になる FFTAnalyzer と呼ばれるユーティリティクラスがあります。このスペクトルデータは GetFloatBufferCallback によって再度サンプリングされて、C# の UI コードに渡されます。データが再サンプリングされる必要がある理由は、GetFloatBufferCallback がリクエストされるサンプルの数を返す間、FFTAnalyzer が一定の周波数分解能で解析を実行させ、それはデータを表示しているビューの幅によって決まります。最小限の量の DSP コードの非常に簡単なプラグインについて、あなたも CorrelationMeter のプラグインを見てみるかもしれません。それは、単に信号が“どうやってステレオ化する”を示すために、右チャネルの振幅に対して左チャンネルの振幅をプロットします。

左: CorrelationMeter プラグインのカスタム GUI。

右: オーバーレイスペクトラム解析とイコライザーGUI（緑のカーブがソース、赤は処理後）。

この時点で、私たちはまた、イコライザおよびマルチバンドエフェクトの両方が意図的にシンプルかつ最適化されずに保持されていることを指摘したいと思います。それらがプラグインシステムでサポートされているより複雑な UI のよい例だと思います。関連するプラットホーム特有の最適化を行う際に、本当に正しいと感じもっとも音楽的に思えるようにたくさんのパラメータの調整するなど、明らかにやるべきことがたくさんあります。Unity のプラグインの標準レパートリーを増やす便宜のために、ある時点で、これらのエフェクトのいくつかをUnity のビルトインのプラグインとして実装するかもしれません。しかし、ユーザーもこの難題に立ち向かい本当に良いプラグインを作成してくださるよう心から願っています。それに、ある時点で、それらがビルトインプラグインになっていないともかぎらないじゃないですか。

コンボリューションリバーブのプラグイン例。インパルス応答は、パラメーターによって定義される減衰するランダムノイズです。リリース用のプラグインでは任意に記録されたインパルスをユーザーがロードできるようにしなければならないので、これはデモンストレーションのためだけに限られます。基本となるコンボリューションアルゴリズムは変わりません。

3 つの異なる時間スケールでレベルを測定するラウドネスモニターツールの例。 これもデモンストレーションを目的としたものですが、現在良く使われるラウドネス標準に準拠しており、モニターツールの構築し始めに適しています。 カーブレンダリングコードは Unity に組み込まれています。

DSP クロックに同期させる

いくつかの楽しい演習の時間です。なぜそれを処理するのではなく、音を生み出すためにプラグインシステムを使用しないのですか？アシッドトランス ― このジャンルを定めた主なシンセの一部のいくつかの簡単なクローン - を聞く人々には、精通している必要がある、いくつかの簡単なベースラインとドラムシンセサイザーを実行してみましょう。Plugin_TeeBee.cpp と Plugin_TeeDee.cpp を見てください。これらの単純なシンセだけで、ランダムなリアクションパターンを生成し、合成エンジンでフィルター、エンベロープを微調整るなどのためにいくつかのパラメータを持っています。ここでも、私たちはここでそれらの詳細については説明しませんが、ちょうど state->dsptick パラメータは “song” の中の位置を決定するために、ProcessCallback で読まれることを指摘しておきます。このカウンタは、グローバルなサンプルのポジションです。私たちはただのサンプルで指定された各音符の長さでそれを分割し、この除算が 0 余りを持つたびに、合成エンジンにノートイベントを発生させます。このように、すべてのプラグインのエフェクトは同じサンプルベースクロックに同期してとどまります。あなたが例えば、このようなエフェクトを通して、既知のテンポであらかじめ録音してある音楽を再生したい場合は、音楽の上で tempo-synchronized フィルタエフェクト、または遅延を適用するためにタイミング情報を使うことができます。

Spatialization (立体化)

ネイティブのオーディオプラグイン SDK は Spatialization SDK の基礎で、オーディオソースごとにインスタンス化するカスタムの立体化エフェクトの開発を可能にします。 詳しい情報は Audio Spatializer SDK を参照してください。

展望

これは、ちょうど、高性能ネイティブコードにサウンドシステムの一部を切り開くための努力のスタートです。Unity の他の部分で、ミキサーの外側で使用可能なをエフェクトを作ること、SDK を拡張し、よりよいデフォルトの GUI のサポートを持つフロート以外のパラメータタイプをサポートすること、バイナリデータを格納することを統合する計画があります。

独自のプラグインを作成するたくさんの楽しみををどうぞ。アセットストアでそれらを見せてほしいです。;-）

おことわり

設計に多くの類維持性はありますが、Unity のネイティブオーディオ SDK は Steinberg VST や Apple AudioUnits など他のプラグイン SDK より優位に立ってビルドされたものではありません。興味があるユーザーが、他のプラグイン SDK を Unity で使用するために、ネイティブオーディオ SDK を利用して基本ラッパーを実装するのはたやすいことでしょう。しかし、それは、Unity の開発チームが意図していることではありません。どんなプラグインの適切なホスティングも、あっという間にとても複雑になります。予想される不満の錯綜にかかわったり、ネイティブコードが急速に拡張されたことによってカスタム GUI 画面を扱うなど、コード例としてあまり役立たなくなってしまいます。

VST や AU プラグインや、サウンドデザインを単に模写したりテストするためのエフェクトでさえ、ロードするととても役立つ可能性があるということを理解する反面、VST/AU の使用は、数種の特定のプラットフォームに制限されるということに注意してください。Unity SDK に基づいてオーディオプラグインを書く有効性は、すべてのプラットフォームで拡張可能で、ソフトウェアミキシングや動的に読み込んだネイティブコードに対応しているということです。とはいえ、カスタムプラグインの開発に時間を費やすことを決める前に、早期のサウンドデザインを好みのツールで模写するのに有効なケースもあります (または、単に、サウンドが変わらないエディター内で、プラグインを試すのに使用できます)。何かよい解決案のあるひとは、やってみてください。