オーディオセッションの管理

[アーティクル]
06/13/2023

[MFPlay は、[要件] セクションで指定したオペレーティングシステムで使用できます。今後のバージョンでは変更されるか、利用できなくなる場合もあります。 ]

このトピックでは、MFPlay を使用してオーディオ/ビデオを再生するときにオーディオボリュームを制御する方法について説明します。

MFPlay には、再生中にオーディオボリュームを制御する次のメソッドが用意されています。

メソッド	説明
IMFPMediaPlayer::SetBalance	左右のチャネル間のバランスを設定します。
IMFPMediaPlayer::SetMute	オーディオをミュートまたはミュート解除します。
IMFPMediaPlayer::SetVolume	ボリュームレベルを設定します。

これらのメソッドの動作を理解するには、MFPlay で使用される低レベルのオーディオ機能を実装する Windows Audio Session API (WASAPI) からいくつかの用語を知っている必要があります。

WASAPI では、すべてのオーディオストリームは、関連するオーディオストリームのグループである 1 つの オーディオセッションに属します。通常、アプリケーションは 1 つのオーディオセッションを維持しますが、アプリケーションでは複数のセッションを作成できます。システムボリューム制御プログラム (Sndvol) には、各オーディオセッションのボリュームコントロールが表示されます。 Sndvol を使用すると、ユーザーはアプリケーションの外部からオーディオセッションのボリュームを調整できます。次の図は、このプロセスを示しています。

スピーカーに向かう途中でボリュームコントロールを通過するオーディオストリームを示す図。アプリケーションと sndvol がボリューム制御を指す

MFPlay では、メディア項目に 1 つ以上のアクティブなオーディオストリームを含めることができます (通常は 1 つだけ)。内部的には、MFPlay はストリーミングオーディオレンダラー (SAR) を使用してオーディオストリームをレンダリングします。特に構成しない限り、SAR はアプリケーションの既定のオーディオセッションに参加します。

MFPlay オーディオメソッドは、現在のメディア項目に属するストリームのみを制御します。同じオーディオセッションに属する他のストリームのボリュームには影響しません。 WASAPI の観点からは、MFPlay メソッドはマスターボリュームレベルではなく 、チャネルごとの ボリュームレベルを制御します。次の図は、このプロセスを示しています。

図は前のストリームと似ていますが、2 番目のストリームはメディア項目から始まり、アプリケーションは 2 番目のストリームとボリューム制御を指します

MFPlay のこの機能の影響を理解することが重要です。まず、アプリケーションは、他のオーディオストリームに影響を与えることなく、再生ボリュームを調整できます。この機能は、MFPlay オブジェクトの 2 つのインスタンスを作成し、ボリュームを個別に調整することで、MFPlay がオーディオクロスフェードを実装する場合に使用できます。

MFPlay メソッドを使用してボリュームまたはミュートの状態を変更した場合、変更は Sndvol に表示されません。たとえば、 SetMute を呼び出してオーディオをミュートできますが、Sndvol ではセッションがミュートとして表示されません。逆に、SndVol を使用してセッションボリュームを調整する場合、変更は IMFPMediaPlayer::GetVolume または IMFPMediaPlayer::GetMute によって返される値には反映されません。

MFPlay プレーヤーオブジェクトの各インスタンスについて、有効ボリュームレベルは fPlayerVolume × fSessionVolume と等しくなります。 ここで、fPlayerVolume は GetVolume によって返される値、 fSessionVolume はセッションのマスターボリュームです。

単純な再生シナリオでは、MFPlay メソッドを使用するのではなく、WASAPI を使用してセッション全体のオーディオボリュームを制御することをお勧めします。

コード例

WASAPI の基本的なタスクを処理する C++ クラスを次に示します。

セッションのボリュームとミュートの状態を制御する。
ボリュームまたはミュートの状態が変化するたびに通知を受け取ります。

クラス宣言

クラス宣言は CAudioSessionVolume 、オーディオセッションイベントのコールバックインターフェイスである IAudioSessionEvents インターフェイスを実装します。

class CAudioSessionVolume : public IAudioSessionEvents
{
public:
    // Static method to create an instance of the object.
    static HRESULT CreateInstance(
        UINT uNotificationMessage,
        HWND hwndNotification,
        CAudioSessionVolume **ppAudioSessionVolume
    );

    // IUnknown methods.
    STDMETHODIMP QueryInterface(REFIID iid, void** ppv);
    STDMETHODIMP_(ULONG) AddRef();
    STDMETHODIMP_(ULONG) Release();

    // IAudioSessionEvents methods.

    STDMETHODIMP OnSimpleVolumeChanged(
        float NewVolume,
        BOOL NewMute,
        LPCGUID EventContext
        );

    // The remaining audio session events do not require any action.
    STDMETHODIMP OnDisplayNameChanged(LPCWSTR,LPCGUID)
    {
        return S_OK;
    }

    STDMETHODIMP OnIconPathChanged(LPCWSTR,LPCGUID)
    {
        return S_OK;
    }

    STDMETHODIMP OnChannelVolumeChanged(DWORD,float[],DWORD,LPCGUID)
    {
        return S_OK;
    }

    STDMETHODIMP OnGroupingParamChanged(LPCGUID,LPCGUID)
    {
        return S_OK;
    }

    STDMETHODIMP OnStateChanged(AudioSessionState)
    {
        return S_OK;
    }

    STDMETHODIMP OnSessionDisconnected(AudioSessionDisconnectReason)
    {
        return S_OK;
    }

    // Other methods
    HRESULT EnableNotifications(BOOL bEnable);
    HRESULT GetVolume(float *pflVolume);
    HRESULT SetVolume(float flVolume);
    HRESULT GetMute(BOOL *pbMute);
    HRESULT SetMute(BOOL bMute);
    HRESULT SetDisplayName(const WCHAR *wszName);

protected:
    CAudioSessionVolume(UINT uNotificationMessage, HWND hwndNotification);
    ~CAudioSessionVolume();

    HRESULT Initialize();

protected:
    LONG m_cRef;                        // Reference count.
    UINT m_uNotificationMessage;        // Window message to send when an audio event occurs.
    HWND m_hwndNotification;            // Window to receives messages.
    BOOL m_bNotificationsEnabled;       // Are audio notifications enabled?

    IAudioSessionControl    *m_pAudioSession;
    ISimpleAudioVolume      *m_pSimpleAudioVolume;
};

オブジェクトは CAudioSessionVolume 、オーディオセッションイベントを受信すると、プライベートウィンドウメッセージをアプリケーションに投稿します。ウィンドウハンドルとウィンドウメッセージは、静的 CAudioSessionVolume::CreateInstance メソッドのパラメーターとして指定されます。

WASAPI インターフェイスポインターの取得

CAudioSessionVolumeでは、次の 2 つのメイン WASAPI インターフェイスが使用されます。

IAudioSessionControl は 、オーディオセッションを管理します。
ISimpleAudioVolume は、セッションのボリュームレベルとミュート状態を制御します。

これらのインターフェイスを取得するには、SAR によって使用されるオーディオエンドポイントを列挙する必要があります。 オーディオエンドポイントは、オーディオデータをキャプチャまたは使用するハードウェアデバイスです。オーディオ再生の場合、エンドポイントは単にスピーカーまたはその他のオーディオ出力です。既定では、SAR は eConsole デバイスロールの既定のエンドポイントを使用します。 デバイスロールは、エンドポイントに割り当てられたロールです。デバイスロールは ERole 列挙によって指定されます。これは、 Core Audio API に記載されています。

次のコードは、エンドポイントを列挙し、WASAPI インターフェイスを取得する方法を示しています。

HRESULT CAudioSessionVolume::Initialize()
{
    HRESULT hr = S_OK;

    IMMDeviceEnumerator *pDeviceEnumerator = NULL;
    IMMDevice *pDevice = NULL;
    IAudioSessionManager *pAudioSessionManager = NULL;

    // Get the enumerator for the audio endpoint devices.
    hr = CoCreateInstance(
        __uuidof(MMDeviceEnumerator),
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_PPV_ARGS(&pDeviceEnumerator)
        );

    if (FAILED(hr))
    {
        goto done;
    }

    // Get the default audio endpoint that the SAR will use.
    hr = pDeviceEnumerator->GetDefaultAudioEndpoint(
        eRender,
        eConsole,   // The SAR uses 'eConsole' by default.
        &pDevice
        );

    if (FAILED(hr))
    {
        goto done;
    }

    // Get the session manager for this device.
    hr = pDevice->Activate(
        __uuidof(IAudioSessionManager),
        CLSCTX_INPROC_SERVER,
        NULL,
        (void**) &pAudioSessionManager
        );

    if (FAILED(hr))
    {
        goto done;
    }

    // Get the audio session.
    hr = pAudioSessionManager->GetAudioSessionControl(
        &GUID_NULL,     // Get the default audio session.
        FALSE,          // The session is not cross-process.
        &m_pAudioSession
        );


    if (FAILED(hr))
    {
        goto done;
    }

    hr = pAudioSessionManager->GetSimpleAudioVolume(
        &GUID_NULL, 0, &m_pSimpleAudioVolume
        );

done:
    SafeRelease(&pDeviceEnumerator);
    SafeRelease(&pDevice);
    SafeRelease(&pAudioSessionManager);
    return hr;
}

ボリュームの制御

オーディオボリュームを制御するメソッドは CAudioSessionVolume 、同等の ISimpleAudioVolume メソッドを 呼び出します。たとえば、 CAudioSessionVolume::SetVolume 次のコードに示すように、 ISimpleAudioVolume::SetMasterVolume を呼び出します。

HRESULT CAudioSessionVolume::SetVolume(float flVolume)
{
    if (m_pSimpleAudioVolume == NULL)
    {
        return E_FAIL;
    }
    else
    {
        return m_pSimpleAudioVolume->SetMasterVolume(
            flVolume,
            &AudioSessionVolumeCtx  // Event context.
            );
    }
}

完全な CAudioSessionVolume コード

クラスのメソッドの完全な一覧を次に CAudioSessionVolume 示します。

static const GUID AudioSessionVolumeCtx =
{ 0x2715279f, 0x4139, 0x4ba0, { 0x9c, 0xb1, 0xb3, 0x51, 0xf1, 0xb5, 0x8a, 0x4a } };


CAudioSessionVolume::CAudioSessionVolume(
    UINT uNotificationMessage,
    HWND hwndNotification
    )
    : m_cRef(1),
      m_uNotificationMessage(uNotificationMessage),
      m_hwndNotification(hwndNotification),
      m_bNotificationsEnabled(FALSE),
      m_pAudioSession(NULL),
      m_pSimpleAudioVolume(NULL)
{
}

CAudioSessionVolume::~CAudioSessionVolume()
{
    EnableNotifications(FALSE);

    SafeRelease(&m_pAudioSession);
    SafeRelease(&m_pSimpleAudioVolume);
};


//  Creates an instance of the CAudioSessionVolume object.

/* static */
HRESULT CAudioSessionVolume::CreateInstance(
    UINT uNotificationMessage,
    HWND hwndNotification,
    CAudioSessionVolume **ppAudioSessionVolume
    )
{

    CAudioSessionVolume *pAudioSessionVolume = new (std::nothrow)
        CAudioSessionVolume(uNotificationMessage, hwndNotification);

    if (pAudioSessionVolume == NULL)
    {
        return E_OUTOFMEMORY;
    }

    HRESULT hr = pAudioSessionVolume->Initialize();
    if (SUCCEEDED(hr))
    {
        *ppAudioSessionVolume = pAudioSessionVolume;
    }
    else
    {
        pAudioSessionVolume->Release();
    }

    return hr;
}


//  Initializes the CAudioSessionVolume object.

HRESULT CAudioSessionVolume::Initialize()
{
    HRESULT hr = S_OK;

    IMMDeviceEnumerator *pDeviceEnumerator = NULL;
    IMMDevice *pDevice = NULL;
    IAudioSessionManager *pAudioSessionManager = NULL;

    // Get the enumerator for the audio endpoint devices.
    hr = CoCreateInstance(
        __uuidof(MMDeviceEnumerator),
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_PPV_ARGS(&pDeviceEnumerator)
        );

    if (FAILED(hr))
    {
        goto done;
    }

    // Get the default audio endpoint that the SAR will use.
    hr = pDeviceEnumerator->GetDefaultAudioEndpoint(
        eRender,
        eConsole,   // The SAR uses 'eConsole' by default.
        &pDevice
        );

    if (FAILED(hr))
    {
        goto done;
    }

    // Get the session manager for this device.
    hr = pDevice->Activate(
        __uuidof(IAudioSessionManager),
        CLSCTX_INPROC_SERVER,
        NULL,
        (void**) &pAudioSessionManager
        );

    if (FAILED(hr))
    {
        goto done;
    }

    // Get the audio session.
    hr = pAudioSessionManager->GetAudioSessionControl(
        &GUID_NULL,     // Get the default audio session.
        FALSE,          // The session is not cross-process.
        &m_pAudioSession
        );


    if (FAILED(hr))
    {
        goto done;
    }

    hr = pAudioSessionManager->GetSimpleAudioVolume(
        &GUID_NULL, 0, &m_pSimpleAudioVolume
        );

done:
    SafeRelease(&pDeviceEnumerator);
    SafeRelease(&pDevice);
    SafeRelease(&pAudioSessionManager);
    return hr;
}

STDMETHODIMP CAudioSessionVolume::QueryInterface(REFIID riid, void **ppv)
{
    static const QITAB qit[] =
    {
        QITABENT(CAudioSessionVolume, IAudioSessionEvents),
        { 0 },
    };
    return QISearch(this, qit, riid, ppv);
}

STDMETHODIMP_(ULONG) CAudioSessionVolume::AddRef()
{
    return InterlockedIncrement(&m_cRef);
}

STDMETHODIMP_(ULONG) CAudioSessionVolume::Release()
{
    LONG cRef = InterlockedDecrement( &m_cRef );
    if (cRef == 0)
    {
        delete this;
    }
    return cRef;
}


// Enables or disables notifications from the audio session. For example, the
// application is notified if the user mutes the audio through the system
// volume-control program (Sndvol).

HRESULT CAudioSessionVolume::EnableNotifications(BOOL bEnable)
{
    HRESULT hr = S_OK;

    if (m_hwndNotification == NULL || m_pAudioSession == NULL)
    {
        return E_FAIL;
    }

    if (m_bNotificationsEnabled == bEnable)
    {
        // No change.
        return S_OK;
    }

    if (bEnable)
    {
        hr = m_pAudioSession->RegisterAudioSessionNotification(this);
    }
    else
    {
        hr = m_pAudioSession->UnregisterAudioSessionNotification(this);
    }

    if (SUCCEEDED(hr))
    {
        m_bNotificationsEnabled = bEnable;
    }

    return hr;
}


// Gets the session volume level.

HRESULT CAudioSessionVolume::GetVolume(float *pflVolume)
{
    if ( m_pSimpleAudioVolume == NULL)
    {
        return E_FAIL;
    }
    else
    {
        return m_pSimpleAudioVolume->GetMasterVolume(pflVolume);
    }
}

//  Sets the session volume level.
//
//  flVolume: Ranges from 0 (silent) to 1 (full volume)

HRESULT CAudioSessionVolume::SetVolume(float flVolume)
{
    if (m_pSimpleAudioVolume == NULL)
    {
        return E_FAIL;
    }
    else
    {
        return m_pSimpleAudioVolume->SetMasterVolume(
            flVolume,
            &AudioSessionVolumeCtx  // Event context.
            );
    }
}


//  Gets the muting state of the session.

HRESULT CAudioSessionVolume::GetMute(BOOL *pbMute)
{
    if (m_pSimpleAudioVolume == NULL)
    {
        return E_FAIL;
    }
    else
    {
        return m_pSimpleAudioVolume->GetMute(pbMute);
    }
}

//  Mutes or unmutes the session audio.

HRESULT CAudioSessionVolume::SetMute(BOOL bMute)
{
    if (m_pSimpleAudioVolume == NULL)
    {
        return E_FAIL;
    }
    else
    {
        return m_pSimpleAudioVolume->SetMute(
            bMute,
            &AudioSessionVolumeCtx  // Event context.
            );
    }
}

//  Sets the display name for the session audio.

HRESULT CAudioSessionVolume::SetDisplayName(const WCHAR *wszName)
{
    if (m_pAudioSession == NULL)
    {
        return E_FAIL;
    }
    else
    {
        return m_pAudioSession->SetDisplayName(wszName, NULL);
    }
}


//  Called when the session volume level or muting state changes.
//  (Implements IAudioSessionEvents::OnSimpleVolumeChanged.)

HRESULT CAudioSessionVolume::OnSimpleVolumeChanged(
    float NewVolume,
    BOOL NewMute,
    LPCGUID EventContext
    )
{
    // Check if we should post a message to the application.

    if ( m_bNotificationsEnabled &&
        (*EventContext != AudioSessionVolumeCtx) &&
        (m_hwndNotification != NULL)
        )
    {
        // Notifications are enabled, AND
        // We did not trigger the event ourselves, AND
        // We have a valid window handle.

        // Post the message.
        ::PostMessage(
            m_hwndNotification,
            m_uNotificationMessage,
            *((WPARAM*)(&NewVolume)),  // Coerce the float.
            (LPARAM)NewMute
            );
    }
    return S_OK;
}

要件

MFPlay には Windows 7 が必要です。

オーディオ/ビデオ再生に MFPlay を使用する

次の方法で共有

オーディオセッションの管理

コード例

クラス宣言

WASAPI インターフェイスポインターの取得

ボリュームの制御

完全な CAudioSessionVolume コード

要件

フィードバック

フィードバック

その他のリソース

次の方法で共有

オーディオ セッションの管理

コード例

クラス宣言

WASAPI インターフェイス ポインターの取得

ボリュームの制御

完全な CAudioSessionVolume コード

要件

関連トピック

フィードバック

フィードバック

その他のリソース

オーディオセッションの管理

WASAPI インターフェイスポインターの取得