AudioPlayer implementation backed by the Windows Audio Session API (WASAPI). More...

#include <WasapiAudioPlayer.h>

Inheritance diagram for Ship::WasapiAudioPlayer:

Collaboration diagram for Ship::WasapiAudioPlayer:

Public Member Functions
	WasapiAudioPlayer (AudioSettings settings)
	Constructs a WasapiAudioPlayer with the given audio settings.

	~WasapiAudioPlayer ()
	Closes the stream and unregisters the endpoint notification callback.

int	Buffered () override
	Returns the number of frames currently queued in the WASAPI render buffer.

Public Member Functions inherited from Ship::AudioPlayer
	AudioPlayer (AudioSettings settings)
	Constructs an AudioPlayer with the given configuration.

virtual	~AudioPlayer ()

bool	Init ()
	Calls DoInit() and sets the initialised flag on success.

void	Play (const uint8_t *buf, size_t len)
	Submits a frame of PCM audio to the output device.

bool	IsInitialized ()
	Returns true if Init() has been called and succeeded.

int32_t	GetSampleRate () const
	Returns the configured output sample rate in Hz.

int32_t	GetSampleLength () const
	Returns the configured number of samples per audio frame.

int32_t	GetDesiredBuffered () const
	Returns the target number of frames to keep buffered.

AudioChannelsSetting	GetAudioChannels () const
	Returns the current channel-output mode.

void	SetSampleRate (int32_t rate)
	Sets the output sample rate.

void	SetSampleLength (int32_t length)
	Sets the number of samples per audio frame.

void	SetDesiredBuffered (int32_t size)
	Sets the target number of buffered frames.

bool	SetAudioChannels (AudioChannelsSetting channels)
	Changes the channel mode and reinitialises the audio device.

int32_t	GetNumOutputChannels () const
	Returns the number of output channels implied by the current channel setting.

Protected Member Functions
bool	DoInit () override
	Opens the WASAPI shared-mode audio client and registers device notifications.

void	DoClose () override
	Stops playback and releases the stream's COM objects.

void	DoPlay (const uint8_t *buf, size_t len) override
	Writes interleaved PCM samples to the WASAPI render buffer.

virtual HRESULT STDMETHODCALLTYPE	OnDeviceStateChanged (LPCWSTR pwstrDeviceId, DWORD dwNewState)
	Called when the state of an audio endpoint device changes.

virtual HRESULT STDMETHODCALLTYPE	OnDeviceAdded (LPCWSTR pwstrDeviceId)
	Called when a new audio endpoint device is added to the system.

virtual HRESULT STDMETHODCALLTYPE	OnDeviceRemoved (LPCWSTR pwstrDeviceId)
	Called when an audio endpoint device is removed from the system.

virtual HRESULT STDMETHODCALLTYPE	OnDefaultDeviceChanged (EDataFlow flow, ERole role, LPCWSTR pwstrDefaultDeviceId)
	Called when the default audio endpoint for a given data-flow or role changes.

virtual HRESULT STDMETHODCALLTYPE	OnPropertyValueChanged (LPCWSTR pwstrDeviceId, const PROPERTYKEY key)
	Called when a property value of an audio endpoint device changes.

virtual ULONG STDMETHODCALLTYPE	AddRef ()
	Increments the IUnknown reference count.

virtual ULONG STDMETHODCALLTYPE	Release ()
	Decrements the IUnknown reference count.

virtual HRESULT STDMETHODCALLTYPE	QueryInterface (REFIID riid, VOID **ppvInterface)
	Returns the requested interface if supported; otherwise E_NOINTERFACE.

void	ThrowIfFailed (HRESULT res)
	Throws a Ship::HResultException if `res` is a failed HRESULT.

bool	SetupStream ()
	(Re-)opens the WASAPI audio stream on the current default device.

Detailed Description

AudioPlayer implementation backed by the Windows Audio Session API (WASAPI).

WasapiAudioPlayer opens a shared-mode WASAPI audio client and also implements IMMNotificationClient so it can detect when the default audio device changes at runtime and seamlessly switch to the new device without requiring a restart.

This backend is only compiled on Windows (#ifdef _WIN32).

Constructor & Destructor Documentation

◆ WasapiAudioPlayer()

Ship::WasapiAudioPlayer::WasapiAudioPlayer ( AudioSettings settings )

inline

Constructs a WasapiAudioPlayer with the given audio settings.

Parameters

settings Sample rate, buffer size, desired buffered frames, and channel mode.

◆ ~WasapiAudioPlayer()

Ship::WasapiAudioPlayer::~WasapiAudioPlayer ( )

Closes the stream and unregisters the endpoint notification callback.

Member Function Documentation

◆ AddRef()

virtual ULONG STDMETHODCALLTYPE Ship::WasapiAudioPlayer::AddRef ( )

protectedvirtual

Increments the IUnknown reference count.

◆ Buffered()

int Ship::WasapiAudioPlayer::Buffered ( )

overridevirtual

Returns the number of frames currently queued in the WASAPI render buffer.

Used by the audio subsystem to pace audio production. While the device cannot be opened, reports the buffer as full so the producer backs off.

Implements Ship::AudioPlayer.

◆ DoClose()

void Ship::WasapiAudioPlayer::DoClose ( )

overrideprotectedvirtual

Stops playback and releases the stream's COM objects.

Implements Ship::AudioPlayer.

◆ DoInit()

bool Ship::WasapiAudioPlayer::DoInit ( )

overrideprotectedvirtual

Opens the WASAPI shared-mode audio client and registers device notifications.

Returns: true if the device was initialised successfully.

Implements Ship::AudioPlayer.

◆ DoPlay()

void Ship::WasapiAudioPlayer::DoPlay	(	const uint8_t *	buf,
		size_t	len
	)

overrideprotectedvirtual

Writes interleaved PCM samples to the WASAPI render buffer.

Parameters

buf	Sample data (stereo or surround, depending on channel setting).
len	Length of `buf` in bytes.

Implements Ship::AudioPlayer.

◆ OnDefaultDeviceChanged()

virtual HRESULT STDMETHODCALLTYPE Ship::WasapiAudioPlayer::OnDefaultDeviceChanged	(	EDataFlow	flow,
		ERole	role,
		LPCWSTR	pwstrDefaultDeviceId
	)

protectedvirtual

Called when the default audio endpoint for a given data-flow or role changes.

WasapiAudioPlayer uses this callback to tear down the current stream and reopen it on the new default device.

◆ OnDeviceAdded()

virtual HRESULT STDMETHODCALLTYPE Ship::WasapiAudioPlayer::OnDeviceAdded ( LPCWSTR pwstrDeviceId )

protectedvirtual

Called when a new audio endpoint device is added to the system.

◆ OnDeviceRemoved()

virtual HRESULT STDMETHODCALLTYPE Ship::WasapiAudioPlayer::OnDeviceRemoved ( LPCWSTR pwstrDeviceId )

protectedvirtual

Called when an audio endpoint device is removed from the system.

◆ OnDeviceStateChanged()

virtual HRESULT STDMETHODCALLTYPE Ship::WasapiAudioPlayer::OnDeviceStateChanged	(	LPCWSTR	pwstrDeviceId,
		DWORD	dwNewState
	)

protectedvirtual

Called when the state of an audio endpoint device changes.

◆ OnPropertyValueChanged()

virtual HRESULT STDMETHODCALLTYPE Ship::WasapiAudioPlayer::OnPropertyValueChanged	(	LPCWSTR	pwstrDeviceId,
		const PROPERTYKEY	key
	)

protectedvirtual

Called when a property value of an audio endpoint device changes.

◆ QueryInterface()

virtual HRESULT STDMETHODCALLTYPE Ship::WasapiAudioPlayer::QueryInterface	(	REFIID	riid,
		VOID **	ppvInterface
	)

protectedvirtual

Returns the requested interface if supported; otherwise E_NOINTERFACE.

◆ Release()

virtual ULONG STDMETHODCALLTYPE Ship::WasapiAudioPlayer::Release ( )

protectedvirtual

Decrements the IUnknown reference count.

◆ SetupStream()

bool Ship::WasapiAudioPlayer::SetupStream ( )

protected

(Re-)opens the WASAPI audio stream on the current default device.

Returns: true on success.

◆ ThrowIfFailed()

void Ship::WasapiAudioPlayer::ThrowIfFailed ( HRESULT res )

protected

Throws a Ship::HResultException if res is a failed HRESULT.

Parameters

res	HRESULT to check.

The documentation for this class was generated from the following file:

include/ship/audio/WasapiAudioPlayer.h

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ WasapiAudioPlayer()

◆ ~WasapiAudioPlayer()

Member Function Documentation

◆ AddRef()

◆ Buffered()

◆ DoClose()

◆ DoInit()

◆ DoPlay()

◆ OnDefaultDeviceChanged()

◆ OnDeviceAdded()

◆ OnDeviceRemoved()

◆ OnDeviceStateChanged()

◆ OnPropertyValueChanged()

◆ QueryInterface()

◆ Release()

◆ SetupStream()

◆ ThrowIfFailed()