ネイティブ DSP オーディオプラグインの開発

ネイティブの Digital Signal Processing (DSP、デジタル信号処理) プラグインを使用して、オーディオを処理し、ユーザーがオーディオエフェクトを試すためのパラメーターを公開できます。Unity が提供するサンプルプラグインは、プラグインを使った試験や、必要なパラメーターについて着想を得るために適しています。

Unity 用のネイティブオーディオプラグインを開発するには、以下を行います。

1. オーディオプラグインファイルを作成します。

2. プラグインファイルでパラメーターを定義します。

3. プラグインをインスタンス化します。

4. プラグインをアンロードします。

5. プラグインのオーディオ処理を実施します。

1. オーディオプラグインファイルの作成

オーディオプラグインファイルを作成するには、以下を行います。

1. 最新のオーディオプラグイン SDK をダウンロードします。

2. フォルダーで、NativeAudioPlugins > NativeCode に移動します。ここでネイティブのサンプルプラグイン .cpp ファイルが見つかります。

3. プラグインの .cpp ファイルの 1 つを複製して、独自のプラグインのテンプレートとして使用できるほか、サンプルプラグインファイル (例えば Plugin_Equalizer.cpp) の 1 つでの直接作業や、独自の .cpp ファイルの作成も可能です。

4. ファイルに AudioPluginUtil.h が含まれていない場合は追加してください。

2. オーディオプラグインファイルでのパラメーターの定義

ユーザーによるプラグインの使用時に操作に役立つようなパラメーターのリストを作成します。パラメーターをプラグインに追加するには、以下を行います。

1. プラグインの .cpp ファイルで、パラメーターを enum 値として定義します。 例:

   enum Param
   {
       P_FREQ, //Frequency parameter
       P_MIX,  //Mix parameter
       P_NUM   //An extra value to keep track of length of the enum
   };
   

2. UnityAudioParameterDefinitions の配列を作成し、そのサイズをパラメーターの数に設定します。

   int numparams = P_NUM;
   definition.paramdefs = new UnityAudioParameterDefinition [numparams];
   

3. RegisterParameter 関数を使用して、各 enum 値を登録します。

   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 関数の概要、そのパラメーター、および前述のコード例での使用方法を示しています。

以上の基本パラメーター定義から、デフォルト GUI が生成されます。

3. ネイティブオーディオ DSP プラグインのインスタンス化

プラグインのインスタンスを作成するには、CreateCallback 関数を使用します。Unity では、プラグインを作成するとすぐに CreateCallback 関数が呼び出されます。null の場合もあります。

struct EffectData
{
    struct Data
    {
        float p[P_NUM]; // Parameters
        float s;        // Sine output of oscillator
        float c;        // Cosine output of oscillator
    };
    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 オブジェクトは、ホストから受信したデータを保存し、そのデータをすべてのコールバック関数に渡します。保存されるデータには以下が含まれます。

• サンプリングレート

• 処理されたサンプルの総数 (タイミング)

• プラグインがバイパスされているかどうか

4. ネイティブオーディオ DSP プラグインのアンロード

プラグインインスタンスを解放するには、ReleaseCallback 関数を使用します。Unity は、プラグインを解放する直前に ReleaseCallback 関数を呼び出し、プラグインのこの特定のインスタンスに関連付けられているデータも解放します。この後、このインスタンスに関連するコールバックは発生しません。

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

5. プラグインでのオーディオ処理の実施

オーディオ処理を行うには、ProcessCallback 関数を使用します。Unity は、読み取り用の入力オーディオのブロックと書き込み用の出力ブロックを使用して、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; // cheap way to calculate a sine-wave
        data->c -= data->s * w;
    }

    return UNITY_AUDIODSP_OK;
}

GetEffectData 関数は、状態変数の effectdata フィールドを、その構造の EffectData::Data にキャストするヘルパー関数です。

GUI のカスタマイズとオーディオプラグインの Unity へのインポート

Unity のプラグインパラメーターの表示をカスタマイズする場合は、オーディオプラグインの GUI のカスタマイズを参照してください。

プラグインを Unity にインポートするには、ネイティブ DSP プラグインと GUI の Unity での使用を参照してください。

追加リソース

• オーディオプラグインの GUI のカスタマイズ

• ネイティブ DSP プラグインと GUI の Unity での使用

• Audio Mixer

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

• オーディオスペーシャライザープラグインの開発

• アンビソニックなデコーダープラグインの開発