> ## 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

Provides methods for desktop apps and games to discover when their audio streams sound levels are modified by the system. This includes scenarios like the following:

* Knowing when a game media stream is muted because an audio app is playing in the background or
* Knowing when to stop a game chat audio stream because a VOIP call has started in the background.

Provides methods that allow desktop apps and games to determine the time their audio streams' sound levels are modified by the system. This includes scenarios in which a game or an app needs to determine the following:

* The time a game media stream is muted because an audio app is playing in the background
* The time to stop a game chat audio stream because a VoIP call has started in the background

The sound level can be checked and monitored for render as well as capture streams. Monitored streams can be selected by category, audio endpoint, or device role. The sound level that a new stream would have can be checked before the stream is created.

This API is equivalent to the [Windows.Media.Audio.AudiostateMonitor class](https://learn.microsoft.com/uwp/api/windows.media.audio.audiostatemonitor), which is available for UWP apps but not for desktop apps and games. This interface can't be used by UWP apps.

## Members

The **IAudioStateMonitor** interface inherits from the  [IUnknown](https://learn.microsoft.com/windows/desktop/api/unknwn/nn-unknwn-iunknown) interface but also has these types of members:

### Methods

The **IAudioStateMonitor** interface has these methods:

| Method                                                                                                    | Description                                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [GetSoundLevel](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-getsoundlevel)           | Gets the current sound level of the streams associated with  **IAudioStateMonitor**                                                                                          |
| [RegisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback)     | Registers a callback function that the system will call when there is a change in the audio level of the streams associated with  **IAudioStateMonitor**                     |
| [UnregisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback) | Unregisters a callback previously registered with  [IAudioStateMonitor::RegisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback) |

## Remarks

To get an instance of this interface, call one of these methods:

* [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)

The following example code demonstrates the scenario where a game registers for audio level notifications for its audio render streams in the [AudioCategory\_GameMedia](https://learn.microsoft.com/windows/desktop/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category) category.

If the sound level for this category is muted, the game will stop playback of its game media stream. If the sound level is set to any other value, the game media stream is played.

```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

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## See also

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


## Related topics

- [IAudioStateMonitor::RegisterCallback method](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback.md)
- [IAudioStateMonitor::UnregisterCallback method](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback.md)
- [IAudioStateMonitor::GetSoundLevel method](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-getsoundlevel.md)
- [AudioStateMonitor](/reference/audio/audiostatemonitor/audiostatemonitor_members.md)
- [CreateCaptureAudioStateMonitor](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitor.md)