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

> IAudioStateMonitor 介面

# IAudioStateMonitor 介面

提供方法，讓桌面應用程式和遊戲探索其音訊串流的音量層級何時被系統修改。這包括下列案例：

* 得知遊戲媒體串流何時因為音訊應用程式正在背景中播放而被靜音，或
* 得知何時因為 VOIP 通話已在背景中開始而應停止遊戲聊天音訊串流。

提供方法，讓桌面應用程式和遊戲判斷其音訊串流的音量層級被系統修改的時間。這包括遊戲或應用程式需要判斷下列項目的案例：

* 遊戲媒體串流因為音訊應用程式正在背景中播放而被靜音的時間
* 因為 VoIP 通話已在背景中開始而應停止遊戲聊天音訊串流的時間

可以檢查並監視轉譯串流和擷取串流的音量層級。可依類別、音訊端點或裝置角色選取要監視的串流。在建立新串流之前，即可檢查該串流將會具有的音量層級。

此 API 相當於 [Windows.Media.Audio.AudiostateMonitor 類別](https://learn.microsoft.com/uwp/api/windows.media.audio.audiostatemonitor)，該類別可供 UWP 應用程式使用，但不適用於桌面應用程式和遊戲。UWP 應用程式無法使用此介面。

## 成員

**IAudioStateMonitor** 介面繼承自 [IUnknown](https://learn.microsoft.com/windows/desktop/api/unknwn/nn-unknwn-iunknown) 介面，但也具有下列類型的成員：

### 方法

**IAudioStateMonitor** 介面具有下列方法：

| 方法 | 描述 |
| - | - |
| [GetSoundLevel](/zh-TW/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-getsoundlevel) | 取得與 **IAudioStateMonitor** 相關聯之串流的目前音量層級 |
| [RegisterCallback](/zh-TW/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback) | 註冊回呼函式，當與 **IAudioStateMonitor** 相關聯之串流的音訊層級發生變更時，系統會呼叫此函式 |
| [UnregisterCallback](/zh-TW/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback) | 取消註冊先前透過 [IAudioStateMonitor::RegisterCallback](/zh-TW/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback) 註冊的回呼 |

## 備註

若要取得此介面的執行個體，請呼叫下列其中一個方法：

* [CreateCaptureAudioStateMonitor](/zh-TW/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitor)
* [CreateCaptureAudioStateMonitorForCategory](/zh-TW/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategory)
* [CreateCaptureAudioStateMonitorForCategoryAndDeviceId](/zh-TW/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategoryanddeviceid)
* [CreateCaptureAudioStateMonitorForCategoryAndDeviceRole](/zh-TW/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategoryanddevicerole)
* [CreateRenderAudioStateMonitor](/zh-TW/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitor)
* [CreateRenderAudioStateMonitorForCategory](/zh-TW/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitorforcategory)
* [CreateRenderAudioStateMonitorForCategoryAndDeviceId](/zh-TW/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitorforcategoryanddeviceid)
* [CreateRenderAudioStateMonitorForCategoryAndDeviceRole](/zh-TW/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.
}
```

## 需求

**標頭：** Audiostatemonitorapi.h

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

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


## Related topics

- [IAudioStateMonitor interface](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor.md)
- [Interfaz IAudioStateMonitor](/es/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor.md)
- [IAudioStateMonitor 接口](/zh-CN/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor.md)
- [AudioStateMonitor](/reference/audio/audiostatemonitor/audiostatemonitor_members.md)
- [IAudioStateMonitor::RegisterCallback method](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback.md)