SoundIoManager Class Reference
[Audio I/O and Signal Processing]

Streaming Audio Configuration Manager. More...

#include <soundio.h>

Collaboration diagram for SoundIoManager:

[legend]

List of all members.

Public Member Functions
	SoundIoManager (DispatchInterface *di)
	Standard constructor.
	~SoundIoManager ()
	Standard destructor.
bool	SetDriver (const char *drivername, const char *driveropts, ErrorInfo *error=0)
	Set the audio driver parameters.
SoundIo *	GetPrimary (void) const
	Query the primary endpoint.
bool	TestOpen (bool up=false, bool down=false, ErrorInfo *error=0)
	Test whether the primary endpoint can be opened.
SoundIo *	GetSecondary (void) const
	Query the secondary endpoint.
bool	SetSecondary (SoundIo *secp, ErrorInfo *error=0)
	Set the secondary endpoint.
bool	Loopback (ErrorInfo *error=0)
	Configure the secondary endpoint for loopback.
bool	GetHardMute (void) const
	Query whether the primary endpoint is disabled.
bool	SetHardMute (bool state, bool closepri=false, ErrorInfo *error=0)
	Temporarily disable and close the primary endpoint.
bool	GetMute (bool up=true) const
	Query soft mute feature state.
bool	SetMute (bool up, bool dn=false, ErrorInfo *error=0)
	Configure soft mute feature.
bool	SetDsp (SoundIoFilter *dspp, ErrorInfo *error=0)
	Set the signal processing filter object.
bool	SetDspEnabled (bool enabled=true, ErrorInfo *error=0)
	Enable/disable the DSP filter.
bool	IsDspEnabled (void)
	Query whether the DSP filter is enabled.
bool	Start (bool up=false, bool down=false, ErrorInfo *error=0)
	Request stream to start.
void	Stop (void)
	Request stream to stop.
bool	IsStarted (void) const
	Query operation state of audio stream.
SoundIoFilter *	GetTopFilter (void) const
	Query the topmost filter installed in the stack.
SoundIoFilter *	GetBottomFilter (void) const
	Query the bottommost filter installed in the stack.
bool	AddAbove (SoundIoFilter *fltp, SoundIoFilter *targp, ErrorInfo *error=0)
	Install a filter above an already installed filter.
bool	AddBelow (SoundIoFilter *fltp, SoundIoFilter *targp, ErrorInfo *error=0)
	Install a filter below an already installed filter.
void	RemoveFilter (SoundIoFilter *fltp)
	Remove a filter from the stack.
bool	AddTop (SoundIoFilter *fltp, ErrorInfo *error=0)
	Install a filter at the topmost position.
bool	AddBottom (SoundIoFilter *fltp, ErrorInfo *error=0)
	Install a filter at the bottommost position.
unsigned int	GetPacketInterval (void)
	Query the configured packet interval of the primary endpoint.
unsigned int	GetMinBufferFill (void)
	Query the active minimum output buffer fill level of the primary endpoint.
unsigned int	GetJitterWindow (void)
	Query the active acceptable output buffer fill level window size of the primary endpoint.
unsigned int	GetPacketIntervalHint (void) const
	Query the desired packet size for the primary endpoint.
void	SetPacketIntervalHint (unsigned int ms)
	Set the desired packet size for the primary endpoint.
unsigned int	GetMinBufferFillHint (void) const
	Query the desired minimum output buffer fill level.
void	SetMinBufferFillHint (unsigned int ms)
	Set the desired minimum output buffer fill level.
unsigned int	GetJitterWindowHint (void) const
	Set the desired window size on output buffers.
void	SetJitterWindowHint (unsigned int ms)
	Set the desired window size on output buffers.
Static Public Member Functions
static bool	GetDriverInfo (int index, const char **name, const char **desc, SoundIoDeviceList **devlist, ErrorInfo *error=0)
	Get descriptive information about a configured audio driver.
Public Attributes
Callback< void, SoundIoManager *, ErrorInfo & >	cb_NotifyAsyncState
	Notification of stream halting.
Callback< void, SoundIoManager *, sio_stream_skewinfo_t, double >	cb_NotifySkew
	Notification of clock skew.

---

Detailed Description

Streaming Audio Configuration Manager.

This object supports a local sound card usage model for SoundIoPump. It encapsulates SoundIoPump, which it uses to stream between its primary and secondary endpoints. Most configuration details other than those specific to the secondary endpoint are handled internally.

The primary endpoint can be configured by driver name and option strings. A default driver with default options will be used if no options are provided. Clients need not have any knowledge of available drivers, but can enumerate them, as well as probe for available local sound card devices, using GetDriverInfo().

The primary endpoint is automatically opened and closed, and has its format set to that of the secondary endpoint when the stream is to be started. Clients need not have any knowledge of sample formats or have any part in configuring packet sizes, although methods exist to set the packet size and buffer fill levels.

If no secondary endpoint is provided, the stream is configured for loopback mode. Loopback mode is useful for qualitatively evaluating latency.

This object also supports software mute mode. Software mute can be enabled at any time using SetMute(). When enabled, both endpoints will continue streaming, but the audio data in one or both directions will be replaced with silence.

---

Member Function Documentation

static bool GetDriverInfo	(	int	index,
		const char **	name,
		const char **	desc,
		SoundIoDeviceList **	devlist,
		ErrorInfo *	error = 0
	)			[static]

Get descriptive information about a configured audio driver.

Parameters:

[in]	index	Driver index number to retrieve information about.
[out]	name	Address of pointer to receive the name of the driver, or NULL if the name is not desired.
[out]	desc	Address of pointer to receive descriptive text about the driver, or NULL if descriptive text is not desired.
[out]	devlist	Address of pointer to receive the detected device list associated with the driver, or NULL of the detected device list is not desired.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Note:

If devlist is specified, and the returned pointer value is 0, this indicates a failed enumeration. A successful enumeration will return an empty SoundIoDeviceList object rather than a null pointer.

Return values:

	true	Driver info retrieved.
	false	Driver index is invalid, or enumerating devices failed. If error is not 0, error will be filled with the reason for the failure.

bool SetHardMute	(	bool	state,
		bool	closepri = false,
		ErrorInfo *	error = 0
	)

Temporarily disable and close the primary endpoint.

Hard streaming mute mode allows the secondary endpoint to continue streaming while the primary is removed. The primary endpoint may also be optionally closed.

This is not recommended for most use cases. Instead, use the soft mute feature, SetMute().

Parameters:

[in]	state	Set to true to enable streaming mute mode, false to turn it off.
[in]	closepri	Set to true when muting (state = true) to cause the primary endpoint to be closed, false otherwise. If the primary endpoint is closed, it will be reopened the next time the device is unmuted, or started after being stopped and unmuted.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	The streaming mute state has been changed.
	false	The streaming mute state could not be changed. If hard mute is being disabled, and the primary endpoint had been closed, this could indicate an error attempting to reopen it.

Note:

Stopping and restarting the primary endpoint, and frequently opening and closing the primary endpoint can be high latency operations. A simple ALSA configuration with the hda-intel driver underneath has been observed to block for 115ms in its open function, and as much as 40ms in its close function.

bool SetMute	(	bool	up,
		bool	dn = false,
		ErrorInfo *	error = 0
	)

Configure soft mute feature.

The soft mute feature replaces all audio packet data moving in one or both directions with silence made up of the first sample received. Soft mute can be instantly enabled/disabled as it requires no potential hardware operations, and incurs only minor CPU overhead.

Parameters:

[in]	up	Set to true to enable mute in the upward direction, i.e. microphone input from the sound card.
[in]	dn	Set to true to enable mute in the downward direction, i.e. speaker output to the sound card.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	Soft mute successfully configured
	false	Soft mute not configured. See error for the reason, but the expected reason is memory allocation failure.

See also:

GetMute(), SetHardMute()

bool SetDsp	(	SoundIoFilter *	dspp,
		ErrorInfo *	error = 0
	)

Set the signal processing filter object.

The SoundIoManager makes a special effort to support one digital signal processing filter object. The filter is always installed directly above the primary endpoint, which will be below any bottom-most filter that the client has installed. This supports the role of an acoustic echo canceler using an NLMS algorithm.

Besides being configured as the bottom-most filter, when the DSP filter is enabled, the pump is configured to be intolerant of loss on the primary endpoint using SoundIoPump::SetLossMode(). This way, samples will only be inserted or removed between the DSP filter and the primary endpoint if the primary endpoint exhibits a significant clock skew between its capture and playback halves.

The installed filter must also be enabled in order for it to be used. See SetDspEnabled() and IsDspEnabled().

Any configured DSP filter is automatically disabled when loopback mode is configured, and when hard mute mode is configured.

Parameters:

[in]	dspp	Signal processing filter to configure as the DSP object for this SoundIoManager. Any existing DSP filter will be cleared. Setting to 0 will configure the SoundIoManager to not use a DSP filter.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	DSP successfully installed. If streaming is in progress, the filter has been installed and is now operating.
	false	DSP filter could not be installed. This can be caused by streaming in progress with parameters that are rejected by the filter. If error is provided, it will be filled in with information about the failure.

bool SetDspEnabled	(	bool	enabled = true,
		ErrorInfo *	error = 0
	)

Enable/disable the DSP filter.

This method allows a configured DSP filter to be temporarily disabled and removed, or re-enabled if previously disabled.

Parameters:

[in]	enabled	Set to true to enable the DSP filter, false to disable the DSP filter. If streaming is in progress, the DSP filter will be inserted into or removed from the filter stack.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	DSP successfully enabled or disabled.
	false	DSP filter was being enabled, but could not be installed in the filter stack. This can be caused by streaming in progress with parameters that are rejected by the filter. If error is provided, it will be filled in with information about the failure.

bool IsDspEnabled

(

void

)

[inline]

Query whether the DSP filter is enabled.

Return values:

	true	DSP filter is enabled
	true	DSP filter is disabled

bool Start	(	bool	up = false,
		bool	down = false,
		ErrorInfo *	error = 0
	)

Request stream to start.

Attempts to start the audio stream. This function will perform a number of configuration steps prior to enabling the underlying SoundIoPump's streaming mechanism.

• If no primary endpoint has been configured via SetDriver(), one will be configured using default settings. If this step fails, the operation will fail.
• If no secondary endpoint has been configured via SetSecondary(), the loopback endpoint will be configured.
• The primary endpoint will be opened. If this step fails, the operation will fail.
• The format configured in the secondary endpoint will be configured on the primary endpoint. If the primary endpoint rejects the format, the operation will fail.

Then, SoundIoPump::Start() is called, which will:

• Configure buffer fill levels based on configuration set by SetPacketInterval(), SetMinBufferFill(), and SetJitterWindow().
• Prepare filters that have been configured.
• Enable asynchronous streaming on the endpoints.

Parameters:

[in]	up	Set to true to enable streaming from primary to secondary, false to disable.
[in]	down	Set to true to enable streaming from secondary to primary, false to disable.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Note:

If both up and down are set to false, the stream directions will be inferred from the capabilities of the secondary endpoint.

Return values:

	true	Streaming has been started
	false	Streaming start failed. If error is not 0, it will be filled out with information on the failure. Typical reasons include: A failure of any of the steps listed above The secondary endpoint not being open or properly configured Streaming mute mode enabled with an unclocked secondary endpoint Streaming already having been started

void Stop

(

void

)

Request stream to stop.

If the audio stream is running, this method will cause it to halt immediately and detach from its endpoints. The client may then close the endpoints if desired.

If a call to this method changes the pump from the operating state to halted, there will not be a corresponding callback to cb_NotifyAsyncState.

See also:

Start(), IsStarted()

bool IsStarted

(

void

)

const [inline]

Query operation state of audio stream.

Query operation state of pump.

Test whether the pump is actively handling sample data.

Return values:

	true	The pump is operating
	false	The pump is stopped

See also:

Start(), Stop()

bool AddAbove	(	SoundIoFilter *	fltp,
		SoundIoFilter *	targp,
		ErrorInfo *	error = 0
	)

Install a filter above an already installed filter.

Install a filter above an already installed filter.

Parameters:

[in]	fltp	Filter to be added to the stack.
[in]	targp	Filter already in the stack to sit directly below the given filter, or 0 to install the filter at the bottom of the stack.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	Filter successfully added to the stack
	false	Filter could not be added. This may only occur if the pump is currently active, and the filter rejects the active configuration of the pump.

bool AddBelow	(	SoundIoFilter *	fltp,
		SoundIoFilter *	targp,
		ErrorInfo *	error = 0
	)

Install a filter below an already installed filter.

Install a filter below an already installed filter.

Parameters:

[in]	fltp	Filter to be added to the stack.
[in]	targp	Filter already in the stack to sit directly above the given filter, or 0 to install the filter at the top of the stack.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	Filter successfully added to the stack
	false	Filter could not be added. This may only occur if the pump is currently active, and the filter rejects the active configuration of the pump.

void RemoveFilter

(

SoundIoFilter *

fltp

)

[inline]

Remove a filter from the stack.

Remove a filter from the stack.

This function will cause a filter installed in the stack to be removed. If the pump is active, the filter will be deconfigured.

unsigned int GetMinBufferFill

(

void

)

[inline]

Query the active minimum output buffer fill level of the primary endpoint.

Returns:

The minimum acceptable output buffer fill level of the primary endpoint. If the pump is active, the value in use will be returned, otherwise -1 will be returned.

unsigned int GetJitterWindow

(

void

)

[inline]

Query the active acceptable output buffer fill level window size of the primary endpoint.

Returns:

The acceptable output buffer fill level window size of the primary endpoint. If the pump is active, the value in use will be returned, otherwise -1 will be returned.

void SetPacketIntervalHint

(

unsigned int

ms

)

[inline]

Set the desired packet size for the primary endpoint.

This method provides the client some level of control over the packet size of the primary endpoint, i.e. the interrupt period length. This value has two consequences:

• If it is too small, the number of hardware interrupts serviced per second will become too large, and CPU time used in the overhead of context switches and interrupt handling will burden the system.
• Larger values can increase end-to-end latency, and potentially decrease the perceived quality of a voice telephony session.

The primary endpoint is the ultimate consumer of this value, and it is free to reject it or round it as required.

Parameters:

ms

Length, in milliseconds, of the desired packet interval. Setting this parameter to zero will cause the default packet interval selection logic to be used.

Note:

The packet interval will be applied the next time the pump is started with Start().

See also:

GetPacketInterval(), SetMinBufferFillHint(), SetJitterWindowHint()

unsigned int GetMinBufferFillHint

(

void

)

const [inline]

Query the desired minimum output buffer fill level.

Query the minimum buffer fill level hint value.

void SetMinBufferFillHint

(

unsigned int

ms

)

[inline]

Set the desired minimum output buffer fill level.

Set the desired minimum output buffer fill level.

This method provides the client some level of control over the minimum acceptable output buffer fill level. Choices of minimum output buffer fill level can have two consequences:

• If it is too small, inconsistent scheduling can cause underruns and stream interruptions. If the process running SoundIoPump is not allowed to run for longer than the time period represented by the input buffer fill level, an underrun will almost be guaranteed.
• Larger values increase end-to-end latency and decrease the perceived quality of a bidirectional stream used for telephony.

Some situations will cause a client-provided value to be ignored:

• The value is less than twice the packet size of a given endpoint. In this case it will be rounded up.
• The value is greater than the endpoint buffer size minus one packet size. In this case it will be rounded down.

This value is only applied to clocked endpoints. It does not apply to file writers.

Parameters:

ms

Length, in milliseconds, of the minimum buffer fill level to apply. Setting this parameter to zero will cause the default logic to be used.

Note:

The minimum buffer fill level will be applied the next time the pump is started with Start().

It is highly recommended that the minimum buffer fill level be set to at least twice the packet size.

See also:

GetMinBufferFillHint(), GetMinBufferFill(), SetJitterWindowHint()

unsigned int GetJitterWindowHint

(

void

)

const [inline]

Set the desired window size on output buffers.

Query the jitter window size hint value.

void SetJitterWindowHint

(

unsigned int

ms

)

[inline]

Set the desired window size on output buffers.

Set the desired window size on output buffers.

This method provides the client some level of control over the output window size, i.e. the limit of the fill level of output buffers above and beyond the minimum. This value has two consequences:

• If it is too small, transient inconsistencies in the rates of production and consumption between the two endpoints ("jitter") can cause samples to be dropped or silence to be inserted.
• Larger values can increase end-to-end latency, and potentially decrease the perceived quality of a voice telephony session.

Some situations will cause a client-provided value to be ignored:

• The value is less than the packet size of a given endpoint. In this case it will be rounded up.
• The value would cause the total buffering required to exceed the endpoint's output buffer size. In this case it will be rounded down.

This value is only applied to clocked endpoints. It does not apply to file writers.

Parameters:

ms

Length, in milliseconds, of the desired jitter window. Setting this parameter to zero will cause the default jitter window size selection logic to be used.

Note:

The jitter window size will be applied the next time the pump is started with Start().

It is highly recommended that the jitter window be set to larger than the packet size.

See also:

SetMinBufferFillHint()

---

Member Data Documentation

Callback<void, SoundIoManager*, ErrorInfo&> cb_NotifyAsyncState

Notification of stream halting.

When streaming halts for reasons other than the Stop() method being invoked -- usually due to a failure of one of the endpoints, this callback is invoked.

Parameters:

	SoundIoManager*	Pointer to the SoundIoManager object
	ErrorInfo&	ErrorInfo structure with information identifying the reason for the halt.

Callback<void, SoundIoManager*, sio_stream_skewinfo_t, double> cb_NotifySkew

Notification of clock skew.

SoundIoManager uses the statistics interface of SoundIoPump to monitor streaming activity. Specifically, it keeps track of clock divergences between the duplex sides of each endpoint, and between the two endpoints overall. If significant clock skew is detected, events will be generated through this callback method approximately every second.

Parameters:

	SoundIoManager*	SoundIoManager object originating the skew notification.
	sio_stream_skewinfo_t	Describes the type of skew that has been detected.
	double	Degree of the skew. For SIO_STREAM_SKEW_XRUN, this is the number of overruns and underruns that occurred since the last sample period. For SIO_STREAM_SKEW_PRI_DUPLEX and SIO_STREAM_SKEW_SEC_DUPLEX, the value is positive if the input clock is faster than the output clock, and negative if vice-versa. The magnitude of this value is the percentage difference of the sample rate of the slower clock relative to the faster clock. For SIO_STREAM_SKEW_ENDPOINT, the value is positive if the secondary endpoint clock is faster than the primary, and negative if vice-versa. The magnitude of this value is the percentage difference of the sample rate of the slower clock relative to the faster clock.

---

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

• include/libhfp/soundio.h

---