libhfp: Audio I/O and Signal Processing

anonymous enum

Error values for subsystem LIBHFP_ERROR_SUBSYS_SOUNDIO.

Enumerator:

LIBHFP_ERROR_SOUNDIO_SYSCALL	System call failure
LIBHFP_ERROR_SOUNDIO_INTERNAL	Error internal to audio module
LIBHFP_ERROR_SOUNDIO_NOT_SUPPORTED	Function not supported
LIBHFP_ERROR_SOUNDIO_ALREADY_OPEN	Device is already open
LIBHFP_ERROR_SOUNDIO_NO_CLOCK	Function not supported because endpoint does not have a clock
LIBHFP_ERROR_SOUNDIO_BAD_FILE	File format invalid
LIBHFP_ERROR_SOUNDIO_DUPLEX_MISMATCH	Inappropriate request for available duplexing
LIBHFP_ERROR_SOUNDIO_FORMAT_UNKNOWN	Unrecognized sample format
LIBHFP_ERROR_SOUNDIO_FORMAT_MISMATCH	Sample format does not match
LIBHFP_ERROR_SOUNDIO_BAD_PUMP_CONFIG	Invalid pump configuration
LIBHFP_ERROR_SOUNDIO_WATCHDOG_TIMEOUT	Endpoint is unresponsive
LIBHFP_ERROR_SOUNDIO_EXCESSIVE_SKEW	Skew threshold exceeded
LIBHFP_ERROR_SOUNDIO_DATA_EXHAUSTED	Data exhausted on static endpoint
LIBHFP_ERROR_SOUNDIO_NO_DRIVER	Driver is not present
LIBHFP_ERROR_SOUNDIO_CANNOT_CHANGE_WHILE_STREAMING	Cannot change parameters while streaming
LIBHFP_ERROR_SOUNDIO_SOUNDCARD_FAILED	Sound card failed

enum sio_sampletype_t

Known Sample Format Enumeration.

This enumeration contains common known sample formats for use with SoundIo derived classes, such as the ALSA and OSS driver frontends.

Enumerator:

SIO_PCM_U8	Unsigned 8-bit.
SIO_PCM_S16_LE	Signed 16-bit little endian.
SIO_PCM_A_LAW	A-Law.
SIO_PCM_MU_LAW	Mu-Law.

SoundIo* libhfp::SoundIoCreateAlsa	(	DispatchInterface *	dip,
		const char *	driveropts,
		ErrorInfo *	error
	)

Construct a SoundIo object backed by an ALSA driver.

This function constructs a SoundIo object that acts as a frontend to an ALSA driver. The device specifier must be specified at construction time to this function.

Parameters:

`[in]`	dip	Dispatcher interface object adapted to the environment in which the SoundIo object is to run.
`[in]`	driveropts	Driver options string for the ALSA driver. This can be empty, in which case the default devices will be selected. It can be a simple devspec, in which case that devspec will be used for both input and output. It can also be a concatenation of `name` `=` `value` pairs of the following form: name1=value1[&name2=value2[&...]] Recognized parameters for the ALSA driver include: `dev` `=` devspec (sets both input and output devices) `in` `=` devspec (sets input device) `out` `=` devspec (sets output device) `access` `=` proc\|thread\|mmap (sets the access mode -- default proc)
`[out]`	error	Error information structure. If this method fails and returns 0, and error is not 0, error will be filled out with information on the cause of the failure.

Returns:: A newly constructed SoundIo object interfacing with ALSA, or NULL on failure.

Some common ALSA device specifiers:

"default" -- the default PCM device.
"plughw:0" -- Card 0 with the rate autoconversion plugin attached.
"hw:0" -- Card 0 with no rate conversion plugin, unlikely to work.

An example driveropts string:

 out=default&in=plughw:0&access=mmap

SoundIo* libhfp::SoundIoCreateFileHandler	(	DispatchInterface *	ei,
		const char *	filename,
		bool	create,
		ErrorInfo *	error = `0`
	)

Construct a SoundIo object backed by a disk file.

This function constructs a SoundIo object that acts as a frontend to an uncompressed PCM audio file using the SGI AudioFile library.

The object can be directed to open the file for reading or writing depending on the parameters passed to SoundIo::SndOpen(). For writing, the sample format should be configured via SoundIo::SndSetFormat() prior to the call to SoundIo::SndOpen(). For reading, SoundIo::SndGetFormat() will only report meaningful results after the file has been opened.

Parameters:

`[in]`	ei	Pointer to dispatcher interface object for the environment. This is used for logging errors.
`[in]`	filename	Name of the audio file to associate the object with.
`[in]`	create	Set to true to allow the file to be created if it is opened for output and does not exist.
`[out]`	error	Error information structure. If this method fails and returns `0`, and error is not 0, error will be filled out with information on the cause of the failure.

Returns:: A newly constructed SoundIo disk file handler object associated with filename, or 0 on failure.

SoundIo* libhfp::SoundIoCreateMembuf	(	const SoundIoFormat *	fmt,
		sio_sampnum_t	nsamps
	)

Construct a SoundIo object backed by a fixed-size memory buffer.

This function constructs a SoundIo object that uses independent memory-only buffers for sample storage. The object uses separate buffers for "playback" and "capture", depending on the mode passed to SndOpen(). When requested to be opened for playback, it will initialize a new empty buffer to receive the playback samples. When requested to be opened for capture, if a prior playback buffer exists, it will become the capture buffer and samples will be read from it. The object can also operate in full-duplex mode, in which case it will present separate playback and capture buffers.

Parameters:

`[in]`	fmt	Initial format to set on the object.
`[in]`	nsamps	Buffer size to use when creating new buffers. To convert from seconds, multiply the number of seconds by SoundIoFormat::samplerate.

Returns:: A newly constructed SoundIo memory buffer handler object associated with filename, or 0 on memory allocation failure.

Note:: This object was created to aid in system testing, to observe the effects of filters and signal processing settings.

SoundIoFilter* libhfp::SoundIoCreateSnooper	(	SoundIo *	target,
		bool	up = `true`,
		bool	dn = `true`,
		ErrorInfo *	error = `0`
	)

Construct a stream snooping filter.

The stream snooper is an installable filter that outputs data passing through it to a slave SoundIo object. When the snooper is configured as an installed filter by SoundIoPump, the snooper will set the format of its slave to the configured streaming format and open the slave in sink mode. When the snooper is deconfigured, it will close the slave.

If bidirectional snooping mode is set -- both the up and dn parameters are true, and the stream is operating in bidirectional mode, the output to the slave endpoint will be a mix of the packet data from both directions. Otherwise the output will be the packet data from one direction, or if not streaming in any configured directions, no output data. In the latter case, the slave endpoint will not even be opened.

The intended use of the snooper object is for recording stream sessions to files. The intended slave endpoint is a file sink, e.g. one produced by SoundIoCreateFileHandler(). The use of a clocked endpoint as the slave is not recommended, as no rate matching is attempted by the snooper object.

Parameters:

`[in]`	target	Slave endpoint to receive snooped sample data.
`[in]`	up	Set to `true` to snoop audio data streaming upward, `false` to ignore data streaming upward.
`[in]`	dn	Set to `true` to snoop audio data streaming downward, `false` to ignore data streaming downward.
`[out]`	error	Error information structure. If this method fails and returns `0`, and error is not 0, error will be filled out with information on the cause of the failure. Currently, the only reason for failure of this function is a memory allocation failure.

Returns:: A newly constructed snoop filter configured with the target endpoint, or 0 on error

Note:: The snoop filter does not perform any life cycle management on the specified slave endpoint. Clients are responsible for managing the life cycle of the slave endpoint, and should take care to destroy the snoop filter before destroying the slave endpoint.

SoundIoFltSpeex* libhfp::SoundIoFltCreateSpeex	(	DispatchInterface *	ei,
		ErrorInfo *	error = `0`
	)

Instantiate a Speex signal processing filter object.

Constructs a new signal processing filter object employing the libspeexdsp library. This filter provides a number of signal processing features useful for telephony applications. Used in conjunction with SoundIoPump, this filter can clean up microphone inputs and remove acoustic echo.

Note:: This filter is not a data compressor and does not employ the Speex voice codec. It does employ the Speex signal processing accessory functions from libspeexdsp.

This filter operates on PCM data moving upward through the stack, i.e. from the bottom endpoint to the top endpoint. The acoustic echo canceler may also examine data moving downward to the bottom endpoint, in order to determine a signal to be removed from the input. In order for this filter to be effective, the sound card device must be the bottom endpoint. In order for the echo canceler to be effective, this filter should either be the bottom-most filter, or no filters placed below it should alter the data stream.

Parameters:

`[in]`	ei	Pointer to dispatcher interface object for the environment. This is used for logging errors.
`[out]`	error	Error information structure. If this method fails and returns `0`, and error is not 0, error will be filled out with information on the cause of the failure.

To use this filter:

Instantaite it with this function.
Configure it, SoundIoFltSpeex::Configure().
Insert it into the filter stack, SoundIoPump::AddBottom(). This filter functions best as the bottom-most filter in a stack where the sound card device is the bottom endpoint.
Start the data pump. SoundIoPump::Start().

For information on the options supported by the filter and how to configure it, see SoundIoSpeexProps and SoundIoFltSpeex::Configure().

Returns:: A newly constructed, unconfigured SoundIoFltSpeex object, or 0 on error.


Classes
class	SoundIo
	Audio Source/Sink Interface. More...
class	SoundIoFilter
	Audio Filtering and Signal Processing Interface. More...
class	SoundIoPump
	Audio Data Pump. More...
class	SoundIoManager
	Streaming Audio Configuration Manager. More...
Typedefs
typedef unsigned int	sio_sampnum_t
	Sample count value type.
Enumerations
enum	{ , LIBHFP_ERROR_SOUNDIO_SYSCALL, LIBHFP_ERROR_SOUNDIO_INTERNAL, LIBHFP_ERROR_SOUNDIO_NOT_SUPPORTED, LIBHFP_ERROR_SOUNDIO_ALREADY_OPEN, LIBHFP_ERROR_SOUNDIO_NO_CLOCK, LIBHFP_ERROR_SOUNDIO_BAD_FILE, LIBHFP_ERROR_SOUNDIO_DUPLEX_MISMATCH, LIBHFP_ERROR_SOUNDIO_FORMAT_UNKNOWN, LIBHFP_ERROR_SOUNDIO_FORMAT_MISMATCH, LIBHFP_ERROR_SOUNDIO_BAD_PUMP_CONFIG, LIBHFP_ERROR_SOUNDIO_WATCHDOG_TIMEOUT, LIBHFP_ERROR_SOUNDIO_EXCESSIVE_SKEW, LIBHFP_ERROR_SOUNDIO_DATA_EXHAUSTED, LIBHFP_ERROR_SOUNDIO_NO_DRIVER, LIBHFP_ERROR_SOUNDIO_CANNOT_CHANGE_WHILE_STREAMING, LIBHFP_ERROR_SOUNDIO_SOUNDCARD_FAILED }
	Error values for subsystem LIBHFP_ERROR_SUBSYS_SOUNDIO. More...
enum	sio_sampletype_t { , SIO_PCM_U8, SIO_PCM_S16_LE, SIO_PCM_A_LAW, SIO_PCM_MU_LAW }
	Known Sample Format Enumeration. More...
Functions
SoundIo *	SoundIoCreateOss (DispatchInterface dip, const char driveropts, ErrorInfo *error)
	Construct a SoundIo object backed by an OSS driver.
SoundIo *	SoundIoCreateAlsa (DispatchInterface dip, const char driveropts, ErrorInfo *error)
	Construct a SoundIo object backed by an ALSA driver.
SoundIo *	SoundIoCreateMembuf (const SoundIoFormat *fmt, sio_sampnum_t nsamps)
	Construct a SoundIo object backed by a fixed-size memory buffer.
SoundIo *	SoundIoCreateFileHandler (DispatchInterface ei, const char filename, bool create, ErrorInfo *error=0)
	Construct a SoundIo object backed by a disk file.
SoundIoFilter *	SoundIoCreateSnooper (SoundIo target, bool up=true, bool dn=true, ErrorInfo error=0)
	Construct a stream snooping filter.
SoundIoFltSpeex *	SoundIoFltCreateSpeex (DispatchInterface ei, ErrorInfo error=0)
	Instantiate a Speex signal processing filter object.

Audio I/O and Signal Processing

Classes

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation