カスタムのオーディオ特殊効果

[アーティクル]
07/13/2023

この記事では、オーディオストリームのカスタム効果を作成するための IBasicAudioEffect インターフェイスを実装する Windows ランタイムコンポーネントを作成する方法について説明します。カスタム効果は、デバイスのカメラへのアクセスを提供する MediaCapture、メディアクリップから複雑なコンポジションを作成するための MediaComposition、さまざまなオーディオ入力、出力、サブミックスノードのグラフをすばやくアセンブルできる AudioGraph など、さまざまな Windows ランタイム API で使用できます。

アプリへのカスタム効果の追加

カスタムのオーディオ効果は、IBasicAudioEffect インターフェイスを実装するクラスで定義します。このクラスは、アプリのプロジェクトに直接含めることはできません。代わりに、Windows ランタイムコンポーネントを使ってオーディオ特殊効果のクラスをホストする必要があります。

オーディオ特殊効果用の Windows ランタイムコンポーネントの追加

Microsoft Visual Studio で、ソリューションを開き、[ファイル] メニューから [追加] -> [新しいプロジェクト] の順に選択します。
プロジェクトの種類として [Windows ランタイムコンポーネント (ユニバーサル Windows)] を選びます。
この例では、プロジェクトに AudioEffectComponent という名前を付けます。この名前は後でコードで参照されます。
[OK] をクリックします。
プロジェクトテンプレートに基づいて、Class1.cs という名前のクラスが作成されます。 ソリューションエクスプローラーで、Class1.cs のアイコンを右クリックし、[名前の変更] をクリックします。
ファイル名を ExampleAudioEffect.cs に変更します。すべての参照を新しい名前に更新するかどうかを確認するメッセージが表示されたら、 [はい] をクリックします。
ExampleAudioEffect.cs を開き、クラス定義を更新して IBasicAudioEffect インターフェイスを実装します。

public sealed class ExampleAudioEffect : IBasicAudioEffect

この記事の例で使うすべての型にアクセスできるように、効果のクラスファイルに次の名前空間を含める必要があります。

using Windows.Media.Effects;
using Windows.Media.MediaProperties;
using Windows.Foundation.Collections;
using System.Runtime.InteropServices;
using Windows.Media;
using Windows.Foundation;

IBasicAudioEffect インターフェイスを実装する

オーディオ特殊効果では、IBasicAudioEffect インターフェイスのすべてのメソッドとプロパティを実装する必要があります。このセクションでは、基本的なエコー効果を作成する、このインターフェイスの簡単な実装について説明します。

SupportedEncodingProperties プロパティ

SupportedEncodingProperties プロパティは、効果でサポートされるエンコードプロパティを確認するためにシステムでチェックされます。効果で指定したプロパティを使ってオーディオをエンコードできない場合、Close が呼び出され、効果がオーディオパイプラインから削除されます。この例では、AudioEncodingProperties オブジェクトが作成され、返される一覧に追加されて、44.1 kHz と 48 kHz、32 ビットの浮動小数点、モノラルエンコードをサポートします。

public IReadOnlyList<AudioEncodingProperties> SupportedEncodingProperties
{
    get
    {
        var supportedEncodingProperties = new List<AudioEncodingProperties>();
        AudioEncodingProperties encodingProps1 = AudioEncodingProperties.CreatePcm(44100, 1, 32);
        encodingProps1.Subtype = MediaEncodingSubtypes.Float;
        AudioEncodingProperties encodingProps2 = AudioEncodingProperties.CreatePcm(48000, 1, 32);
        encodingProps2.Subtype = MediaEncodingSubtypes.Float;

        supportedEncodingProperties.Add(encodingProps1);
        supportedEncodingProperties.Add(encodingProps2);

        return supportedEncodingProperties;
        
    }
}

SetEncodingProperties メソッド

SetEncodingProperties は、効果の対象となるオーディオストリームのエンコードプロパティを示すために呼び出されます。エコー効果を実装するため、この例では 1 秒間のオーディオデータを格納するバッファーを使用します。このメソッドは、オーディオをエンコードするサンプルレートに基づいて、バッファーのサイズを 1 秒間のオーディオのサンプル数に初期化する機会を提供します。遅延効果では、遅延バッファー内の現在位置を追跡する整数カウンターも使います。オーディオパイプラインに効果が追加されるたびに SetEncodingProperties 効果が呼び出されるため、これは値を 0 に初期化する良い機会です。このメソッドに渡された AudioEncodingProperties オブジェクトをキャプチャして、効果の他の場所で使用することもできます。

private float[] echoBuffer;
private int currentActiveSampleIndex;
private AudioEncodingProperties currentEncodingProperties;

public void SetEncodingProperties(AudioEncodingProperties encodingProperties)
{
    currentEncodingProperties = encodingProperties;
    echoBuffer = new float[encodingProperties.SampleRate]; // exactly one second delay
    currentActiveSampleIndex = 0;
}

SetProperties メソッド

SetProperties メソッドは、呼び出し元のアプリで効果のパラメーターを調整するために使われます。プロパティは、プロパティ名と値の IPropertySet マップとして渡されます。

IPropertySet configuration;
public void SetProperties(IPropertySet configuration)
{
    this.configuration = configuration;
}

このシンプルな例では、現在のオーディオサンプルを、Mix プロパティの値に従って、遅延バッファーからの値とミキシングします。プロパティを宣言し、呼び出し元アプリで設定された値を TryGetValue で取得しています。値が設定されていない場合は、既定値の .5 が使われます。このプロパティは読み取り専用であることに注意してください。プロパティの値は SetProperties を使って設定する必要があります。

public float Mix
{
    get
    {
        object val;
        if (configuration != null && configuration.TryGetValue("Mix", out val))
        {
            return (float)val;
        }
        return .5f;
    }
}

ProcessFrame メソッド

ProcessFrame メソッドは、効果によって、ストリームのオーディオデータを変更するためのメソッドです。このメソッドはフレームごとに 1 回呼び出され、ProcessAudioFrameContext オブジェクトが渡されます。このオブジェクトには、処理対象の着信フレームを格納する入力 AudioFrame オブジェクトと、オーディオパイプラインの残りの部分に渡すオーディオデータを書き込む出力 AudioFrame オブジェクトが含まれています。オーディオフレームは、オーディオデータの短いスライスを表す、オーディオサンプルバッファーです。

AudioFrame のデータバッファーにアクセスするには COM 相互運用機能が必要であるため、効果のクラスファイルに System.Runtime.InteropServices 名前空間を含め、効果の名前空間内に次のコードを追加して、オーディオバッファーにアクセスするためのインターフェイスをインポートする必要があります。

[ComImport]
[Guid("5B0D3235-4DBA-4D44-865E-8F1D0E4FD04D")]
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
unsafe interface IMemoryBufferByteAccess
{
    void GetBuffer(out byte* buffer, out uint capacity);
}

注意

この手法では管理対象外のネイティブの画像バッファーにアクセスするため、アンセーフコードを許可するようにプロジェクトを構成する必要があります。

ソリューションエクスプローラーで、AudioEffectComponent プロジェクトを右クリックし、[プロパティ] を選択します。
[ビルド] タブを選択します。
[アンセーフコードの許可] チェックボックスをオンにします。

これで、ProcessFrame メソッドの実装を効果に追加できます。最初に、入力と出力の両方のオーディオフレームから AudioBuffer オブジェクトを取得します。出力フレームが書き込み用で、入力フレームが読み取り用です。次に、CreateReference を呼び出して、各バッファーの IMemoryBufferReference を取得します。その後、実際のデータバッファーを取得するために、先ほど定義した COM 相互運用機能のインターフェイス (IMemoryByteAccess) として IMemoryBufferReference オブジェクトをキャストし、GetBuffer を呼び出します。

これで、データバッファーが取得され、入力バッファーからの読み取りと出力バッファーへの書き込みが可能になります。入力バッファーの各サンプルで値が取得され、1 - Mixが乗算されて、効果のドライ信号値が設定されます。次にエコーバッファー内の現在の位置からサンプルが取得され、Mix が乗算されて、効果のウェット値が設定されます。出力サンプルはドライとウェット値の合計に設定されます。最後に、各入力サンプルがエコーバッファーに格納され、現在のサンプルのインデックスがインクリメントされます。

unsafe public void ProcessFrame(ProcessAudioFrameContext context)
{
    AudioFrame inputFrame = context.InputFrame;
    AudioFrame outputFrame = context.OutputFrame;

    using (AudioBuffer inputBuffer = inputFrame.LockBuffer(AudioBufferAccessMode.Read),
                        outputBuffer = outputFrame.LockBuffer(AudioBufferAccessMode.Write))
    using (IMemoryBufferReference inputReference = inputBuffer.CreateReference(),
                                    outputReference = outputBuffer.CreateReference())
    {
        byte* inputDataInBytes;
        byte* outputDataInBytes;
        uint inputCapacity;
        uint outputCapacity;

        ((IMemoryBufferByteAccess)inputReference).GetBuffer(out inputDataInBytes, out inputCapacity);
        ((IMemoryBufferByteAccess)outputReference).GetBuffer(out outputDataInBytes, out outputCapacity);

        float* inputDataInFloat = (float*)inputDataInBytes;
        float* outputDataInFloat = (float*)outputDataInBytes;

        float inputData;
        float echoData;

        // Process audio data
        int dataInFloatLength = (int)inputBuffer.Length / sizeof(float);

        for (int i = 0; i < dataInFloatLength; i++)
        {
            inputData = inputDataInFloat[i] * (1.0f - this.Mix);
            echoData = echoBuffer[currentActiveSampleIndex] * this.Mix;
            outputDataInFloat[i] = inputData + echoData;
            echoBuffer[currentActiveSampleIndex] = inputDataInFloat[i];
            currentActiveSampleIndex++;

            if (currentActiveSampleIndex == echoBuffer.Length)
            {
                // Wrap around (after one second of samples)
                currentActiveSampleIndex = 0;
            }
        }
    }
}

Close メソッド

システムは、効果をシャットダウンする必要があるときに、クラスで Close Close メソッドを呼び出します。このメソッドを使って、作成したすべてのリソースを破棄する必要があります。このメソッドの MediaEffectClosedReason 引数により、効果が正常に終了されたかどうかがわかります。エラーが発生したり、必要なエンコード形式が効果でサポートされていないと、この引数で通知されます。

public void Close(MediaEffectClosedReason reason)
{
    // Dispose of effect resources
    echoBuffer = null;
}

DiscardQueuedFrames メソッド

DiscardQueuedFrames メソッドは、効果をリセットする必要があるときに呼び出されます。典型的なシナリオとしては、現在のフレームの処理で使うために前に処理したフレームを保存している場合などが挙げられます。このメソッドが呼び出されたときは、保存した一連のフレームを破棄する必要があります。このメソッドでは、蓄積されたオーディオフレームだけでなく、前のフレームに関連するすべての状態をリセットできます。

public void DiscardQueuedFrames()
{
    // Reset contents of the samples buffer
    Array.Clear(echoBuffer, 0, echoBuffer.Length - 1);
    currentActiveSampleIndex = 0;
}

TimeIndependent プロパティ

TimeIndependent TimeIndependent プロパティは、効果のタイミングを合わせる必要がないかどうかを示します。 true に設定すると、効果のパフォーマンスを高めるために最適化を使用できるようになります。

public bool TimeIndependent { get { return true; } }

UseInputFrameForOutput プロパティ

効果がその出力を ProcessFrame に渡される ProcessAudioFrameContext の OutputFrame ではなく、InputFrame のオーディオバッファーに書き込む場合には、UseInputFrameForOutput プロパティを true に設定します。

public bool UseInputFrameForOutput { get { return false; } }

アプリへのカスタム効果の追加

アプリからオーディオ特殊効果を使うには、効果のプロジェクトへの参照をアプリに追加する必要があります。

ソリューションエクスプローラーで、アプリのプロジェクトの下にある [参照設定] を右クリックし、[参照の追加] を選択します。
[プロジェクト] タブを展開し、[ソリューション] を選択して、効果のプロジェクトの名前に対応するチェックボックスをオンにします。この例では、AudioEffectComponent という名前です。
[OK]

オーディオ効果クラスが別の名前空間で宣言されている場合は、その名前空間をコードファイルに含めるようにします。

using AudioEffectComponent;

AudioGraph ノードにカスタム効果を追加する

オーディオグラフの使用に関する一般的な情報については、「オーディオグラフ」を参照してください。次のコードスニペットは、この記事で示すエコー効果の例をオーディオグラフノードに追加する方法を示しています。まず、PropertySet が作成され、効果によって定義された Mix プロパティの値が設定されます。次に、AudioEffectDefinition コンストラクターが呼び出され、カスタム効果の種類とプロパティセットの完全なクラス名が渡されます。最後に、既存の FileInputNode の EffectDefinitionsプロパティに効果の定義が追加され、カスタム効果によるオーディオの処理が行われます。

// Create a property set and add a property/value pair
PropertySet echoProperties = new PropertySet();
echoProperties.Add("Mix", 0.5f);

// Instantiate the custom effect defined in the 'AudioEffectComponent' project
AudioEffectDefinition echoEffectDefinition = new AudioEffectDefinition(typeof(ExampleAudioEffect).FullName, echoProperties);
fileInputNode.EffectDefinitions.Add(echoEffectDefinition);

カスタム効果がノードに追加された後では、DisableEffectsByDefinition を呼び出して、AudioEffectDefinition オブジェクトを渡すことにより無効化することができます。アプリでのオーディオグラフの使用について詳しくは、「AudioGraph」をご覧ください。

MediaComposition のクリップへのカスタム効果の追加

次のコードスニペットは、カスタムのオーディオ効果をメディアコンポジションのビデオクリップとバックグラウンドオーディオトラックに追加する方法を示しています。ビデオクリップからメディアコンポジションを作成してバックグラウンドオーディオトラックを追加する一般的なガイダンスについては、「メディアコンポジションと編集」をご覧ください。

// Create a property set and add a property/value pair
PropertySet echoProperties = new PropertySet();
echoProperties.Add("Mix", 0.5f);

// Instantiate the custom effect defined in the 'AudioEffectComponent' project
AudioEffectDefinition echoEffectDefinition = new AudioEffectDefinition(typeof(ExampleAudioEffect).FullName, echoProperties);

// Add custom audio effect to the current clip in the timeline
var currentClip = composition.Clips.FirstOrDefault(
    mc => mc.StartTimeInComposition <= mediaPlayerElement.MediaPlayer.PlaybackSession.Position &&
    mc.EndTimeInComposition >= mediaPlayerElement.MediaPlayer.PlaybackSession.Position);
currentClip.AudioEffectDefinitions.Add(echoEffectDefinition);

// Add custom audio effect to the first background audio track
if (composition.BackgroundAudioTracks.Count > 0)
{
    composition.BackgroundAudioTracks[0].AudioEffectDefinitions.Add(echoEffectDefinition);
}

次の方法で共有

カスタムのオーディオ特殊効果

アプリへのカスタム効果の追加

IBasicAudioEffect インターフェイスを実装する

SupportedEncodingProperties プロパティ

SetEncodingProperties メソッド

SetProperties メソッド

ProcessFrame メソッド

Close メソッド

DiscardQueuedFrames メソッド

TimeIndependent プロパティ

UseInputFrameForOutput プロパティ

アプリへのカスタム効果の追加

AudioGraph ノードにカスタム効果を追加する

MediaComposition のクリップへのカスタム効果の追加

フィードバック

その他のリソース

次の方法で共有

カスタムのオーディオ特殊効果

アプリへのカスタム効果の追加

IBasicAudioEffect インターフェイスを実装する

SupportedEncodingProperties プロパティ

SetEncodingProperties メソッド

SetProperties メソッド

ProcessFrame メソッド

Close メソッド

DiscardQueuedFrames メソッド

TimeIndependent プロパティ

UseInputFrameForOutput プロパティ

アプリへのカスタム効果の追加

AudioGraph ノードにカスタム効果を追加する

MediaComposition のクリップへのカスタム効果の追加

関連トピック

フィードバック

その他のリソース