Управление сеансом аудио

Статья
07/19/2024

[Функция, связанная с этой страницей MFPlay, является устаревшей функцией. Он был заменен MediaPlayer и МВФMediaEngine. Эти функции оптимизированы для Windows 10 и Windows 11. Корпорация Майкрософт настоятельно рекомендует использовать новый код MediaPlayer и IMFMediaEngine вместо DirectShow, когда это возможно. Корпорация Майкрософт предлагает, что существующий код, использующий устаревшие API, будет перезаписан для использования новых API, если это возможно.]

В этом разделе описывается, как управлять громкость звука при использовании MFPlay для воспроизведения звука и видео.

MFPlay предоставляет следующие методы для управления громкости звука во время воспроизведения.

Метод	Description
IMFPMediaPlayer::SetBalance	Задает баланс между левыми и правыми каналами.
IMFPMediaPlayer::SetMute	Отключает или отменяет звук.
IMFPMediaPlayer::SetVolume	Задает уровень тома.

Чтобы понять поведение этих методов, необходимо знать некоторые терминологии из API сеанса аудио windows (WASAPI), которая реализует низкоуровневую функциональность звука, используемую MFPlay.

В WASAPI каждый аудиопоток принадлежит ровно одному звуковому сеансу, который является группой связанных аудиопотоков. Как правило, приложение поддерживает один звуковой сеанс, хотя приложения могут создавать несколько сеансов. Программа управления томами (Sndvol) отображает элемент управления громкости для каждого звукового сеанса. С помощью Sndvol пользователь может настроить громкость звукового сеанса за пределами приложения. На следующем рисунке показан этот процесс.

схема, показывающая аудиопотоки, проходящие через элемент управления громкости на пути к динамикам; application and sndvol point to volume control

В MFPlay элемент мультимедиа может иметь один или несколько активных звуковых потоков (как правило, только один). Во внутреннем режиме MFPlay использует средство рендеринга потокового звука (SAR) для отрисовки звуковых потоков. Если вы не настроите его в противном случае, SAR присоединяется к звуковому сеансу по умолчанию приложения.

Методы звука MFPlay управляют только потоками, принадлежащими текущему элементу мультимедиа. Они не влияют на громкость для любых других потоков, принадлежащих к тому же звуковому сеансу. С точки зрения WASAPI методы MFPlay управляют уровнями томов для каждого канала , а не главным уровнем тома. На следующем рисунке показан этот процесс.

схема, аналогичная предыдущей, но второй поток начинается с элемента мультимедиа, а приложение указывает на второй поток и управление томом

Важно понимать некоторые последствия этой функции MFPlay. Во-первых, приложение может настроить громкость воспроизведения, не затрагивая другие звуковые потоки. Эту функцию можно использовать, если MFPlay реализует перекрестное отображение звука, создав два экземпляра объекта MFPlay и изменив громкость отдельно.

Если вы используете методы MFPlay для изменения состояния тома или отключения звука, изменения не отображаются в Sndvol. Например, можно вызвать SetMute , чтобы отключить звук, но Sndvol не будет отображать сеанс как отключенный. И наоборот, если SndVol используется для корректировки объема сеанса, изменения не отражаются в значениях, возвращаемых МВФPMediaPlayer::GetVolume или МВФPMediaPlayer::GetMute.

Для каждого экземпляра объекта проигрывателя MFPlay эффективный уровень тома равен fPlayerVolume × fSessionVolume, где fPlayerVolume — это значение, возвращаемое GetVolume, и fSessionVolume является главным томом для сеанса.

Для простых сценариев воспроизведения может быть предпочтительнее использовать WASAPI для управления громкость звука для всего сеанса, а не использовать методы MFPlay.

Пример кода

Ниже приведен класс C++, который обрабатывает основные задачи в WASAPI:

Управление томом и отключением состояния сеанса.
Получение уведомлений при изменении состояния тома или выключения.

Объявление класса

Объявление 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 использует два основных интерфейса WASAPI:

IAudioSessionControl управляет звуковым сеансом.
ISimpleAudioVolume управляет уровнем тома и состоянием отключения сеанса.

Чтобы получить эти интерфейсы, необходимо перечислить конечную точку звука, используемую SAR. Конечная точка звука — это аппаратное устройство, которое записывает или использует звуковые данные. Для воспроизведения звука конечная точка — это просто динамик или другие выходные данные звука. По умолчанию SAR использует конечную точку по умолчанию для роли устройства eConsole . Роль устройства — это назначенная роль для конечной точки. Роли устройства задаются перечислением ERole, который задокументирован в API Core Audio.

В следующем коде показано, как перечислить конечную точку и получить интерфейсы 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

Требования

См. также

Обратная связь

Дополнительные ресурсы