libhfp: SoundIoPump Class Reference

SoundIoPump handles exchanging sample data between two SoundIo derived source/sink endpoints. It can operate in unidirectional or bidirectional mode depending on the configured endpoints. SoundIoPump has no synchronous mode, operating exclusively asynchronously, using event notifications from its endpoint SoundIo objects to execute data transfers.

Specifically, SoundIoPump operates on buffer fill level constraints, and attempts to transfer as many samples as possible per availability event. Transfers are always done symmetrically -- the number of samples transferred between one source/sink pair is always the same as all others -- and must satisfy the fill level constraints of all sources and sinks in the system. When fill level constraints cannot be satisfied, silence-padding and sample dropping will occur. Sophisticated methods such as resampling are not employed. Fill level configuration is a closed process, but hints for fill level constraints can be provided via SetMinBufferFill() and SetJitterWindow().

Besides the fill level constraints and the packet sizes of each endpoint, the pump also chooses a "filter packet size" which is the basic transfer unit. The filter packet size is used for filters (described below) and all chosen transfer sizes are multiples of the filter packet size.

The two endpoints are referred to as the top and bottom endpoints. Both must be set in order to start the pump. Either can be changed at idle or while the pump is running. Removing an endpoint while the pump is running without specifying a replacement will stop the pump. If attempting to replace an endpoint while the pump is running, the replacement endpoint's buffer and packet sizes must support the filter packet size that was selected when the pump was started. If the replacement endpoint has a smaller packet size or output buffer size, it may not satisfy constraints.

The endpoints are required to implement the SoundIo::SndAsyncStart() and SoundIo::cb_NotifyPacket interfaces in order to work with SoundIoPump. Invocations of SoundIo::cb_NotifyPacket must occur on the packet interval with little divergence in order for SoudIoPump to maintain its fill levels and avoid a buffer underrun situation. SoundIoPump employs a watchdog timeout mechanism that attempts to verify that each clocked endpoint is making packet callbacks, and that the rate of sample processing is within some reasonable bound of the system clock.

Stackable signal processing filters can be configured into SoundIoPump. Filter objects must implement the SoundIoFilter interface. A list of filters is formed between the two endpoints, and filters can be added or removed from the ends using AddTop(), AddBottom(), RemoveTop(), and RemoveBottom(). For each data transfer, all attached filters are provided with symmetric fixed-size PCM data packets for inbound and outbound sample data.

When sample data is to be transferred, it is always done in top-to-bottom, then bottom-to-top order. In a bidirectional configuration, filters will always observe a single downward packet of the filter packet size, followed by a single upward packet of the filter packet size.

The primary goal of the filter interface is to support acoustic echo cancellation.

Operating in single-direction mode, a SoundIoPump instance can be used to play audio files and monitor the position of their playback. See SoundIoCreateFileHandler().

Constructor & Destructor Documentation

SoundIoPump	(	DispatchInterface *	eip,
		SoundIo *	bottom
	)

Standard constructor.

Parameters:

	eip	Loop interface object adapted to the environment in which SoundIoPump is to run.
	bottom	SoundIo object to reside at the bottom of the handling stack.

Note:: SoundIoPump does not perform any life cycle management of its endpoints. It is the responsibility of the client to ensure that the SoundIo objects set as endpoints to the pump remain valid as long as they are associated with the pump.

Member Function Documentation

SoundIo* GetBottom ( void ) const [inline]

Query the bottom endpoint.

Returns:: A pointer to the bottom endpoint of the pump, or NULL if no bottom endpoint is set.

bool SetBottom	(	SoundIo *	bottom,
		ErrorInfo *	error = `0`
	)

Set the bottom endpoint.

Configures a SoundIo object as the bottom endpoint of the pump.

Parameters:

`[in]`	bottom	SoundIo object to set as the bottom endpoint, or 0 to clear the bottom endpoint. If the pump is started, and the bottom endpoint is cleared, the pump will be stopped.
`[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	bottom was set as the bottom endpoint.
	false	bottom could not be set as the bottom endpoint. This will only happen if the pump was started when the call to SetBottom() was made, and the new endpoint could not be configured. In this case, the pump state will be unaltered.

Note:: SoundIoPump does not perform any life cycle management of its endpoints. It is the responsibility of the client to ensure that the SoundIo objects set as endpoints to the pump remain valid as long as they are associated with the pump.

SoundIo* GetTop ( void ) const [inline]

Query the top endpoint.

Returns:: A pointer to the top endpoint of the pump, or NULL if no top endpoint is set.

bool SetTop	(	SoundIo *	top,
		ErrorInfo *	error = `0`
	)

Set the top endpoint.

Configures a SoundIo object as the top endpoint of the pump.

Parameters:

`[in]`	top	SoundIo object to set as the top endpoint, or 0 to clear the top endpoint. If the pump is started, and the top endpoint is cleared, the pump will be stopped.
`[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	top was set as the top endpoint.
	false	top could not be set as the top endpoint. This will only happen if the pump was started when the call to SetTop() was made, and the new endpoint could not be configured. In this case, the pump state will be unaltered.

Note:: SoundIoPump does not perform any life cycle management of its endpoints. It is the responsibility of the client to ensure that the SoundIo objects set as endpoints to the pump remain valid as long as they are associated with the pump.

bool Start ( ErrorInfo * error = 0 )

Request pump to start.

After the top endpoint has been configured via SetTop(), and the filters have been installed via AddTop() and AddBottom(), a pump can be started.

Both the top and bottom endpoints must be opened and configured with compatible PCM data stream formats. They must agree on at least one transfer direction, i.e. if the top endpoint is configured for input only, the bottom endpoint must at least be configured for output.

Parameters:

[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	Pump has been prepared and asynchronous operation enabled at the endpoints.
	false	Pump could not be started. Possible reasons: No top endpoint configured Neither bottom nor top endpoint support asynchronous operation One or both of the endpoints has not been opened, see SoundIo::SndOpen() The endpoints do not agree on a transfer direction The endpoints are not configured with compatible PCM sample data formats One of the configured filters failed to prepare itself

void Stop ( void ) [inline]

Request pump to stop.

If a pump is operating, 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 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`
	)			`[inline]`

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.

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 )

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.

void SetLossMode	(	bool	loss_at_bottom,
		bool	loss_at_top
	)

Set the acceptable data loss mode.

When buffer fill level constraints cannot be fulfilled, some audio data must be lost, or padded with silence, in order to resolve the situation. Loss behavior can occur at either endpoint, before or after the filters are run on the data destined to and from the endpoint. Sometimes it is desirable to avoid loss behavior at one endpoint of the system, so that all data going to and coming from the endpoint is processed by the filters.

For example, an acoustic echo canceler based on a Normalized Least Mean Squares algorithm is intolerant of loss, and works best when all data from the target endpoint runs through the filters, and loss is isolated at the other endpoint.

Parameters:

	loss_at_bottom	Tolerate loss at the bottom endpoint
	loss_at_top	Tolerate loss at the top endpoint

By default, loss is tolerated at both endpoints.

Setting both loss_at_bottom and loss_at_top to false will cause an assertion failure.

Note:: This setting only attempts to isolate loss to one endpoint over another. Loss will still occur at an endpoint where it is not tolerated if there is a rate mismatch between the input and output sides of the endpoint.

unsigned int GetMinBufferFill ( bool top )

Query the active minimum output buffer fill level of the bottom or top endpoint.

Parameters:

top Set to true to retrieve information about the top endpoint, false for the bottom endpoint.

Returns:: The minimum acceptable output buffer fill level of the top or bottom endpoint, in milliseconds, depending on the top parameter. If the pump is inactive, -1 will be returned.

For information about minimum buffer fill levels, see SetMinBufferFillHint().

unsigned int GetJitterWindow ( bool top )

Query the active output buffer jitter window of the bottom or top endpoint.

Parameters:

top Set to true to retrieve information about the top endpoint, false for the bottom endpoint.

Returns:: The acceptable window size of the output buffer fill level, in milliseconds, of the top or bottom endpoint, depending on the top parameter. If the pump is inactive, -1 will be returned.

For information about jitter windows, see SetJitterWindowHint().

void SetMinBufferFillHint ( unsigned int ms ) [inline]

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:

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()

void SetJitterWindowHint ( unsigned int ms ) [inline]

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:

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, SoundIoPump*, SoundIo*, ErrorInfo&> cb_NotifyAsyncState

Notification of halted asynchronous processing.

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

Parameters:

	SoundIoPump*	Pointer to the SoundIoPump object
	SoundIo*	Pointer to the SoundIo object that caused the pump to stop, if known.
	ErrorInfo&	ErrorInfo structure with information identifying the reason for the halt.

Callback<void, SoundIoPump*, SoundIoPumpStatistics&, bool> cb_NotifyStatistics

Notification of updated pump statistics.

This notification informs the client of SoundIoPump of an update to its registered statistics structure. The information is raw, but can be used to diagnose specific problems.

Parameters:

	SoundIoPump*	The subject pump object
	SoundIoPumpStatistics&	The SoundIoPumpStatistics structure that was registered with SoundIoPump, and has been updated to reflect the result of a recent data transfer.
	bool	Set to `true` if any data losses (or padding) occurred.

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

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation


Public Member Functions
virtual	~SoundIoPump ()
	Standard destructor.
	SoundIoPump (DispatchInterface eip, SoundIo bottom)
	Standard constructor.
SoundIo *	GetBottom (void) const
	Query the bottom endpoint.
bool	SetBottom (SoundIo bottom, ErrorInfo error=0)
	Set the bottom endpoint.
SoundIo *	GetTop (void) const
	Query the top endpoint.
bool	SetTop (SoundIo top, ErrorInfo error=0)
	Set the top endpoint.
bool	Start (ErrorInfo *error=0)
	Request pump to start.
void	Stop (void)
	Request pump to stop.
bool	IsStarted (void) const
	Query operation state of pump.
void	SetStatistics (SoundIoPumpStatistics *statp)
	Set the structure to receive pump statistics.
SoundIoFilter *	GetTopFilter (void) const
	Query the topmost filter installed in the stack.
SoundIoFilter *	GetBottomFilter (void) const
	Query the bottommost filter installed in the stack.
SoundIoFilter *	GetBelowFilter (SoundIoFilter *fltp) const
	Query the filter immediately below another installed in the stack.
SoundIoFilter *	GetAboveFilter (SoundIoFilter *fltp) const
	Query the filter immediately above another 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.
SoundIoFilter *	RemoveTop (void)
	Remove the topmost filter.
SoundIoFilter *	RemoveBottom (void)
	Remove the bottommost filter.
void	SetLossMode (bool loss_at_bottom, bool loss_at_top)
	Set the acceptable data loss mode.
unsigned int	GetMinBufferFill (bool top)
	Query the active minimum output buffer fill level of the bottom or top endpoint.
unsigned int	GetJitterWindow (bool top)
	Query the active output buffer jitter window of the bottom or top endpoint.
unsigned int	GetMinBufferFillHint (void) const
	Query the minimum buffer fill level hint value.
void	SetMinBufferFillHint (unsigned int ms)
	Set the desired minimum output buffer fill level.
unsigned int	GetJitterWindowHint (void) const
	Query the jitter window size hint value.
void	SetJitterWindowHint (unsigned int ms)
	Set the desired window size on output buffers.
Public Attributes
Callback< void, SoundIoPump , SoundIo , ErrorInfo & >	cb_NotifyAsyncState
	Notification of halted asynchronous processing.
Callback< void, SoundIoPump *, SoundIoPumpStatistics &, bool >	cb_NotifyStatistics
	Notification of updated pump statistics.

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

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

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