> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IAudioStateMonitor interface

> IAudioStateMonitor interface

# IAudioStateMonitor interface

데스크톱 앱 및 게임이 시스템에 의해 오디오 스트림의 사운드 레벨이 수정되는 시점을 발견할 수 있도록 메서드를 제공합니다. 여기에는 다음과 같은 시나리오가 포함됩니다:

* 오디오 앱이 백그라운드에서 재생되어 게임 미디어 스트림이 음소거되는 시점을 파악
* VoIP 통화가 백그라운드에서 시작되어 게임 채팅 오디오 스트림을 중지해야 하는 시점을 파악

데스크톱 앱 및 게임이 시스템에 의해 오디오 스트림의 사운드 레벨이 수정되는 시점을 결정할 수 있는 메서드를 제공합니다. 여기에는 게임이나 앱이 다음을 결정해야 하는 시나리오가 포함됩니다:

* 오디오 앱이 백그라운드에서 재생되어 게임 미디어 스트림이 음소거되는 시점
* VoIP 통화가 백그라운드에서 시작되어 게임 채팅 오디오 스트림을 중지해야 하는 시점

렌더링 스트림뿐만 아니라 캡처 스트림에 대해서도 사운드 레벨을 확인하고 모니터링할 수 있습니다. 모니터링되는 스트림은 카테고리, 오디오 엔드포인트 또는 장치 역할에 따라 선택할 수 있습니다. 새 스트림이 갖게 될 사운드 레벨은 스트림이 생성되기 전에 확인할 수 있습니다.

이 API는 UWP 앱에서 사용할 수 있지만 데스크톱 앱과 게임에서는 사용할 수 없는 [Windows.Media.Audio.AudiostateMonitor 클래스](https://learn.microsoft.com/uwp/api/windows.media.audio.audiostatemonitor)와 동등합니다. 이 인터페이스는 UWP 앱에서는 사용할 수 없습니다.

## Members

**IAudioStateMonitor** 인터페이스는 [IUnknown](https://learn.microsoft.com/windows/desktop/api/unknwn/nn-unknwn-iunknown) 인터페이스를 상속하지만 다음과 같은 유형의 멤버도 갖습니다:

### Methods

**IAudioStateMonitor** 인터페이스에는 다음 메서드가 있습니다:

| 메서드                                                                                                       | 설명                                                                                                                                               |
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [GetSoundLevel](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-getsoundlevel)           | **IAudioStateMonitor**와 연결된 스트림의 현재 사운드 레벨을 가져옵니다.                                                                                               |
| [RegisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback)     | **IAudioStateMonitor**와 연결된 스트림의 오디오 레벨이 변경될 때 시스템이 호출할 콜백 함수를 등록합니다.                                                                            |
| [UnregisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback) | 이전에 [IAudioStateMonitor::RegisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback)로 등록된 콜백을 등록 해제합니다. |

## Remarks

이 인터페이스의 인스턴스를 얻으려면 다음 메서드 중 하나를 호출하세요:

* [CreateCaptureAudioStateMonitor](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitor)
* [CreateCaptureAudioStateMonitorForCategory](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategory)
* [CreateCaptureAudioStateMonitorForCategoryAndDeviceId](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategoryanddeviceid)
* [CreateCaptureAudioStateMonitorForCategoryAndDeviceRole](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategoryanddevicerole)
* [CreateRenderAudioStateMonitor](/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitor)
* [CreateRenderAudioStateMonitorForCategory](/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitorforcategory)
* [CreateRenderAudioStateMonitorForCategoryAndDeviceId](/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitorforcategoryanddeviceid)
* [CreateRenderAudioStateMonitorForCategoryAndDeviceRole](/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitorforcategoryanddevicerole)

다음 예제 코드는 게임이 [AudioCategory\_GameMedia](https://learn.microsoft.com/windows/desktop/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category) 카테고리의 오디오 렌더링 스트림에 대한 오디오 레벨 알림에 등록하는 시나리오를 보여줍니다.

이 카테고리의 사운드 레벨이 음소거되면 게임은 게임 미디어 스트림의 재생을 중지합니다. 사운드 레벨이 다른 값으로 설정되면 게임 미디어 스트림이 재생됩니다.

```cpp theme={null}
// Global variables
winrt::com_ptr<IAudioStateMonitor> g_audioStateMonitor;
AudioStateMonitorRegistrationHandle g_registration = 0;

// Returns true if the GameMedia stream is to be disabled, false if it's to be enabled.
bool IsSoundLevelMuted(_In_ IAudioStateMonitor* audioStateMonitor)
{
    return (audioStateMonitor->GetSoundLevel() == AudioStateMonitorSoundLevel::Muted);
}

HRESULT StartTrackingSoundLevel()
{
    // Create an AudioStateMonitor, and register for callbacks from it.
    HRESULT hr = RegisterForSoundLevelChanges();
    if (SUCCEEDED(hr))
    {
        // Check the current sound level, and determine whether the GameMedia stream is to be enabled.
        bool disableGameMediaStream = IsSoundLevelMuted(g_audioStateMonitor.get());

        // Here, add code that enables or disables the GameMedia stream 
        // according to the value of the Boolean.
    }
    return hr;
}

HRESULT RegisterForSoundLevelChanges()
{
    HRESULT hr = S_OK;

    // Create a new AudioStateMonitor for the GameMedia category, if needed, and register for callbacks.
    if (m_audioStateMonitor == nullptr)
    {
        hr = CreateRenderAudioStateMonitorForCategoryAndDeviceRole(
                 AudioCategory_GameMedia, ERole::eConsole, g_audioStateMonitor.put());
        if (SUCCEEDED(hr))
        {
            // Optional "context" parameter is not used in this example
            // and is set to nullptr.
            hr = g_audioStateMonitor->RegisterCallback(OnAudioStateMonitorCallback, nullptr, &amp;g_registration);
        }
    }

    if (FAILED(hr))
    {
        // g_audioStateMonitor is a smart pointer, so if an IAudioStateMonitor 
        // was allocated, then setting the smart pointer to null invokes the
        // Release method, which will decrement its usage count and ensure that 
        // the object is destroyed properly.
        g_audioStateMonitor = nullptr;
    }
    return hr;
}

// Unregister callbacks on program shutdown
void UnregisterForSoundLevelChanges()
{
    if (g_audioStateMonitor != nullptr)
    {
        if (g_registration)
        {
            g_audioStateMonitor->UnregisterCallback(g_registration);
        }

        // g_audioStateMonitor is a smart pointer, so setting it to null
        // will invoke the Release method to decrement its usage count.
        g_audioStateMonitor = nullptr;
    }
}

void OnAudioStateMonitorCallback(_In_ IAudioStateMonitor* audioStateMonitor, _In_opt_ void* context)
{
    bool disableGameMediaStream = IsSoundLevelMuted(audioStateMonitor);

    // Add code here that enables or disables the GameMedia stream 
    // according to the value of the Boolean.
}
```

## Requirements

**Header:** Audiostatemonitorapi.h

**지원 플랫폼:** Windows, XBOX One 제품군 콘솔 및 XBOX Series 콘솔

## See also

[WASAPI 소개](https://learn.microsoft.com/en-us/windows/desktop/CoreAudio/wasapi)


## Related topics

- [IAudioStateMonitor::RegisterCallback method](/ko/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback.md)
- [IAudioStateMonitor::UnregisterCallback method](/ko/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback.md)
- [IAudioStateMonitor::GetSoundLevel method](/ko/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-getsoundlevel.md)
- [AudioStateMonitor](/ko/reference/audio/audiostatemonitor/audiostatemonitor_members.md)
- [AudioStateMonitorRegistrationHandle](/ko/reference/audio/audiostatemonitor/types/audiostatemonitorregistrationhandle.md)