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

# CreateCaptureAudioStateMonitorForCategory

> CreateCaptureAudioStateMonitorForCategory

# CreateCaptureAudioStateMonitorForCategory

\[Some information relates to pre-released product which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.]

Creates a new instance of [IAudioStateMonitor](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor) that monitors the audio level of all audio capture streams in the specified category.

## Syntax

```cpp theme={null}
HRESULT WINAPI CreateCaptureAudioStateMonitorForCategory(
  AUDIO_STREAM_CATEGORY category,
  _Out_ IAudioStateMonitor **audioStateMonitor
);
```

### Parameters

*category*\
Type: AUDIO\_STREAM\_CATEGORY

A member of the <a href="https://learn.microsoft.com/en-us/windows/desktop/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category" target="_blank">AUDIO\_STREAM\_CATEGORY</a> enumeration that specifies the category of the audio capture streams to be monitored.

*audioStateMonitor* \[out]\
Type: IAudioStateMonitor\*\*

This output parameter is populated with the created `IAudioStateMonitor` object.

### Return value

Type: HRESULT

If the method succeeds, it returns `S\_OK`.

## Remarks

This is one of the functions that create and return an `AudioStateMonitor` instance.

There are four variants each for capture and render streams that determine
whether a process can do one of the following for a given role:

* Capture or render any audio of any category
* Capture or render audio of a specific category
* Capture or render audio of a specific category, to a specific endpoint.\
  The endpoint may be specified using the `MMDevice` ID (obtained using `IMMDevice::GetId()`), or by using its `SWD` ID (obtained using `Windows.Devices.Enumeration` or `Windows.Media.Devices.MediaDevice`)
* Capture or render audio of a specific category to the default endpoint

Consider the following scenario, where a game wants to engage its in-game GameChat functionality only when it knows that the audio will not be muted by the OS policies. To do this, the game registers for SoundLevel notifications for the [AudioCategory\_GameChat](https://learn.microsoft.com/windows/win32/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category) stream category on the default communications endpoint.

If the SoundLevel for this category is set to 'Muted', the game will stop its GameChat session. If the SoundLevel is set to anything else, the game chooses to enable its GameChat stream.

The following code example shows how the game can create an appropriate `IAudioStateMonitor` object for this scenario.

```cpp theme={null}
HRESULT RegisterForSoundLevelChanges() 
{ 
HRESULT hr = S_OK; 

// Create a new AudioStateMonitor for the GameChat category, if needed, and 
// register for callbacks. 
if (m_audioStateMonitor == nullptr) 
{ 
hr = CreateCaptureAudioStateMonitorForCategoryAndDeviceRole( 
AudioCategory_GameChat, ERole::eCommunications, 
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, &m_registration); 
} 
} 

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

## Requirements

**Header:** Audiostatemonitorapi.h

**Library:** Windows.Media.MediaControl.lib

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

## See also

[AUDIO\_STREAM\_CATEGORY](https://learn.microsoft.com/windows/win32/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category)

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

[WASAPI](/build/console-features/audio/overviews/wasapi-overview)


## Related topics

- [IAudioStateMonitor interface](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor.md)
- [AudioStateMonitor](/reference/audio/audiostatemonitor/audiostatemonitor_members.md)
- [CreateCaptureAudioStateMonitorForCategoryAndDeviceId](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategoryanddeviceid.md)
- [CreateCaptureAudioStateMonitorForCategoryAndDeviceRole](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategoryanddevicerole.md)
- [CreateCaptureAudioStateMonitor](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitor.md)