사용자 지정 오디오 효과

  • 아티클

이 문서에서는 오디오 스트림에 대한 사용자 지정 효과를 만들 수 있도록 IBasicAudioEffect 인터페이스를 구현하는 Windows 런타임 구성 요소를 만드는 방법을 설명합니다. 사용자 지정 효과는 디바이스의 카메라에 대한 액세스를 제공하는 MediaCapture, 미디어 클립에서 복잡한 컴퍼지션을 만들 수 있는 MediaComposition 및 다양한 오디오 입력, 출력 및 서브믹스 노드의 그래프를 신속하게 어셈블할 수 있는 AudioGraph를 비롯한 여러 Windows 런타임 API와 함께 사용할 수 있습니다.

앱에 사용자 지정 효과 추가

사용자 지정 오디오 효과는 IBasicAudioEffect 인터페이스를 구현하는 클래스에 정의됩니다. 이 클래스는 앱의 프로젝트에 직접 포함할 수 없습니다. 대신 Windows 런타임 구성 요소를 사용하여 오디오 효과 클래스를 호스트해야 합니다.

오디오 효과에 대한 Windows 런타임 구성 요소 추가

  1. Microsoft Visual Studio에서 솔루션이 열려 있는 상태에서 파일 메뉴로 이동하여 추가->새 프로젝트를 선택합니다.
  2. Windows 런타임 구성 요소(유니버설 Windows) 프로젝트 형식을 선택합니다.
  3. 이 예제에서는 프로젝트 이름을 AudioEffectComponent로 지정합니다. 이 이름은 나중에 코드에서 참조됩니다.
  4. 확인을 클릭합니다.
  5. 프로젝트 템플릿은 Class1.cs 클래스를 만듭니다. 솔루션 탐색기에서 Class1.cs 아이콘을 마우스 오른쪽 단추로 클릭하고 이름 바꾸기를 선택합니다.
  6. 파일의 이름을 ExampleAudioEffect.cs로 바꿉니다. Visual Studio는 모든 참조를 새 이름으로 업데이트할지 묻는 프롬프트를 표시합니다. 예를 클릭합니다.
  7. 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.1kHz 및 48kHz, 32비트 float, 모노 인코딩을 지원합니다.

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 메서드는 효과가 스트림의 오디오 데이터를 수정하는 위치입니다. 이 메서드는 프레임당 한 번씩 호출되며 ProcessAudioFrameContext 개체에 전달됩니다. 이 개체에는 처리할 들어오는 프레임과 오디오 파이프라인의 나머지 부분에 전달될 오디오 데이터를 쓰는 출력 AudioFrame 개체가 포함된 입력 AudioFrame 개체가 포함됩니다. 오디오 프레임은 짧은 오디오 데이터 조각을 나타내는 오디오 샘플의 버퍼입니다.

AudioFrame의 데이터 버퍼에 액세스하려면 COM interop가 필요하므로 효과 클래스 파일에 System.Runtime.InteropServices 네임스페이스를 포함하고 효과에 대한 다음 코드를 네임스페이스 내에 추가하여 오디오 버퍼에 액세스하기 위한 인터페이스를 가져와야 합니다.

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

참고 항목

이 기술은 관리되지 않는 네이티브 이미지 버퍼에 액세스하므로 안전하지 않은 코드를 허용하도록 프로젝트를 구성해야 합니다.

  1. 솔루션 탐색기에서 AudioEffectComponent 프로젝트를 마우스 오른쪽 단추로 클릭하고 속성을 선택합니다.
  2. 빌드 탭을 선택합니다.
  3. 안전하지 않은 코드 허용 확인란을 선택합니다.

 

이제 효과에 ProcessFrame 메서드 구현을 추가할 수 있습니다. 먼저 이 메서드는 입력 및 출력 오디오 프레임 모두에서 AudioBuffer 개체를 가져옵니다. 출력 프레임은 쓰기 및 읽기용 입력을 위해 열립니다. 다음으로, CreateReference를 호출하여 각 버퍼에 대해 IMemoryBufferReference를 가져옵니다. 그런 다음, IMemoryBufferReference 개체를 위에 정의된 COM interop 인터페이스인 IMemoryByteAccess로 캐스팅한 다음 GetBuffer를 호출하여 실제 데이터 버퍼를 가져옵니다.

이제 데이터 버퍼를 얻었으므로 입력 버퍼에서 읽고 출력 버퍼에 쓸 수 있습니다. 입력 버퍼의 각 샘플에 대해 값을 가져오고 1 - 혼합하여 효과의 건식 신호 값을 설정합니다. 다음으로, 샘플은 에코 버퍼의 현재 위치에서 검색되고 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 메서드

효과가 종료될 때 시스템에서 클래스에서 CloseClose 메서드를 호출합니다. 이 메서드를 사용하여 만든 모든 리소스를 삭제해야 합니다. 메서드에 대한 인수는 효과가 정상적으로 닫혔는지, 오류가 발생했는지 또는 효과가 필요한 인코딩 형식을 지원하지 않는지 여부를 알 수 있는 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 속성

UseInputFrameForOutput 속성을 true로 설정하여 OutputFrame에 쓰는 대신 ProcessFrame에 전달된 ProcessAudioFrameContext의 InputFrame 오디오 버퍼에 출력을 쓰도록 시스템에 알릴 수 있습니다.

public bool UseInputFrameForOutput { get { return false; } }

앱에 사용자 지정 효과 추가

앱에서 오디오 효과를 사용하려면 효과 프로젝트에 대한 참조를 앱에 추가해야 합니다.

  1. 앱 프로젝트 아래의 솔루션 탐색기에서 프로젝트 References 노드를 마우스 오른쪽 버튼으로 클릭하고 Add reference를 선택합니다.
  2. Projects 탭을 확장하고 Solution을 선택한 다음 효과 프로젝트 이름의 검사 상자를 선택합니다. 이 예제의 경우, 이름은 AudioEffectComponent입니다.
  3. 확인을 클릭합니다.

오디오 효과 클래스가 다른 네임스페이스로 선언된 경우 코드 파일에 해당 네임스페이스를 포함해야 합니다.

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);
}