spAudio Class Reference

A class to handle audio I/O. More...

#include <sp/spAudio.h>

Collaboration diagram for spAudio:

Related Symbols
(Note that these are not member symbols.)
#define	spFreeAudio(audio)   spFreeAudioDriver(audio)
Initialization
spAudio	spInitAudioDriver (const char *driver_name)
spAudio	spInitAudio (void)
void	_spFreeAudioDriver (spAudio audio)
Device Selection
spBool	spGetNumAudioDevice (spAudio audio, int *num_device)
char *	xspGetAudioDeviceName (spAudio audio, int device_index)
spBool	spSelectAudioDevice (spAudio audio, int device_index)
Setter and Getter
spBool	spSetAudioSampleRate (spAudio audio, double samp_rate)
spBool	spGetAudioSampleRate (spAudio audio, double *samp_rate)
spBool	spSetAudioChannel (spAudio audio, int num_channel)
spBool	spGetAudioChannel (spAudio audio, int *num_channel)
spBool	spSetAudioBufferSize (spAudio audio, int buffer_size)
spBool	spGetAudioBufferSize (spAudio audio, int *buffer_size)
spBool	spSetAudioNumBuffer (spAudio audio, int num_buffer)
spBool	spGetAudioNumBuffer (spAudio audio, int *num_buffer)
spBool	spSetAudioBlockingMode (spAudio audio, int block_mode)
spBool	spGetAudioBlockingMode (spAudio audio, int *block_mode)
spBool	spSetAudioSampleBit (spAudio audio, int samp_bit)
spBool	spGetAudioSampleBit (spAudio audio, int *samp_bit)
spBool	spGetAudioSpecifiedSampleBit (spAudio audio, int *specified_samp_bit)
spAudioCallbackType	spSetAudioCallbackFunc (spAudio audio, spAudioCallbackType call_type, spAudioCallbackFunc call_func, void *call_data)
Open and Close
spBool	spOpenAudioDevice (spAudio audio, const char *mode)
spBool	spCloseAudioDevice (spAudio audio)
Read and Write
long	spReadAudio (spAudio audio, void *data, long length)
long	spWriteAudio (spAudio audio, void *data, long length)
long	spReadAudioDoubleWeighted (spAudio audio, double *data, long length, double weight)
long	spReadAudioDouble (spAudio audio, double *data, long length)
long	spWriteAudioDoubleWeighted (spAudio audio, double *data, long length, double weight)
long	spWriteAudioDouble (spAudio audio, double *data, long length)
Device Control
spBool	spGetAudioOutputPosition (spAudio audio, spLong *position)
spBool	spStopAudio (spAudio audio)
spBool	spSyncAudio (spAudio audio)

Detailed Description

A class to handle audio I/O.

Actually, spAudio is not a class, but a typedefed type by typedef struct _spAudio *spAudio;. You can use this class after initialization by spInitAudio() or spInitAudioDriver() , should free resources of this class after use by spFreeAudio() or spFreeAudioDriver() .

Normal audio I/O procedure is as follows.

1. Get spAudio by spInitAudio() or spInitAudioDriver() .
2. Select an audio device by spSelectAudioDevice() . If you don't call this function, the default device will be used.
3. Set information of the current device by spSetAudioXXX
4. Open the current device by spOpenAudioDevice()
5. Check the device information by spGetAudioXXX if necessary since the current information is sometimes not indentical to the information you set.
6. Call spReadAudio() for input or spWriteAudio() for output repeatedly.
7. Flush buffers by spSyncAudio() if you want to restart I/O.
8. Close the current device by spCloseAudioDevice()
9. Free resources of spAudio by spFreeAudio() or spFreeAudioDriver() .

See also

spInitAudio() , spInitAudioDriver() , spFreeAudio() , spFreeAudioDriver()

Examples

driver.c, iotest.c, playsin.c, and rec.c.

Friends And Related Symbol Documentation

spInitAudioDriver()

spAudio spInitAudioDriver ( const char * driver_name )

related

Initializes the audio driver (constructor).
All audio I/O functions do not work before you call this function (or spInitAudio() ). Multiple calls before spFreeAudioDriver() with one driver are not accepted. Some environments accept multiple calls of this function with different drivers.

Parameters

[in]

driver_name

The name of the driver.

See also

spFreeAudioDriver()

spInitAudio()

spAudio spInitAudio ( void )

related

Initializes the audio driver (constructor).
All audio I/O functions do not work before you call this function (or spInitAudioDriver() ). Multiple calls before spFreeAudio() are not accepted.

See also

spFreeAudio()

_spFreeAudioDriver()

void _spFreeAudioDriver ( spAudio audio )

related

Frees the audio driver's resources. Use spFreeAudioDriver() instead of this.

Parameters

[in]

audio

spAudio type variable obtained by spInitAudioDriver() .

spGetNumAudioDevice()

spBool spGetNumAudioDevice ( spAudio audio, int * num_device )

related

Gets the number of audio devices.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	num_device	The address of a variable to receive the number of devices.

Return values

SP_TRUE	Success
SP_FALSE	Failure

xspGetAudioDeviceName()

char * xspGetAudioDeviceName ( spAudio audio, int device_index )

related

Gets the name of the audio device. You have to deallocate the memory by calling xspFree() .

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	device_index	0-based device index. You can specify an index from 0 to ( spGetNumAudioDevice() - 1). The index 0 always corresponds to the default device.

Returns

A null-terminated string indicating the name of the device. You have to deallocate the memory by calling xspFree() .

spSelectAudioDevice()

spBool spSelectAudioDevice ( spAudio audio, int device_index )

related

Selects an audio device which has the index specified.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	device_index	0-based device index. You can specify an index from 0 to ( spGetNumAudioDevice() - 1). The index 0 always corresponds to the default device.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spSetAudioSampleRate()

spBool spSetAudioSampleRate ( spAudio audio, double samp_rate )

related

Sets sample rate of the current device. This function should be called before opening a device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	samp_rate	The value of sample rate in Hz.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spGetAudioSampleRate()

spBool spGetAudioSampleRate ( spAudio audio, double * samp_rate )

related

Gets sample rate of the current device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	samp_rate	The address of a variable to receive the sample rate in Hz.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spSetAudioChannel()

spBool spSetAudioChannel ( spAudio audio, int num_channel )

related

Sets the number of channels of the current device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	num_channel	The number of channels.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spGetAudioChannel()

spBool spGetAudioChannel ( spAudio audio, int * num_channel )

related

Gets the number of channels of the current device. This function should be called before opening a device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	num_channel	The address of a variable to receive the number of channels.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spSetAudioBufferSize()

spBool spSetAudioBufferSize ( spAudio audio, int buffer_size )

related

Sets the buffer size of the current device. This function should be called before opening a device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	buffer_size	The buffer size.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spGetAudioBufferSize()

spBool spGetAudioBufferSize ( spAudio audio, int * buffer_size )

related

Gets the buffer size of the current device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	buffer_size	The address of a variable to receive the buffer size.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spSetAudioNumBuffer()

spBool spSetAudioNumBuffer ( spAudio audio, int num_buffer )

related

Sets the number of buffers of the current device. This function should be called before opening a device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	num_buffer	The number of buffers.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spGetAudioNumBuffer()

spBool spGetAudioNumBuffer ( spAudio audio, int * num_buffer )

related

Gets the number of buffers of the current device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	num_buffer	The address of a variable to receive the number of buffers.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spSetAudioBlockingMode()

spBool spSetAudioBlockingMode ( spAudio audio, int block_mode )

related

Sets the blocking mode of the current device. This function should be called before opening a device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	block_mode	The blocking mode of SP_AUDIO_BLOCKING or SP_AUDIO_NONBLOCKING .

Return values

SP_TRUE	Success
SP_FALSE	Failure

spGetAudioBlockingMode()

spBool spGetAudioBlockingMode ( spAudio audio, int * block_mode )

related

Gets the blocking mode of the current device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	block_mode	The address of a variable to receive the blocking mode.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spSetAudioSampleBit()

spBool spSetAudioSampleBit ( spAudio audio, int samp_bit )

related

Sets bits/sample of the current device. This function should be called before opening a device. 16, 24 and 32 bits/sample are supported currently. For the device not supporting 24 and 32 bits/sample, the data is internally converted to 16 bits/sample data.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	samp_bit	The bits/sample.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spGetAudioSampleBit()

spBool spGetAudioSampleBit ( spAudio audio, int * samp_bit )

related

Gets bits/sample of the current device.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	samp_bit	The address of a variable to receive the bits/sample.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spGetAudioSpecifiedSampleBit()

spBool spGetAudioSpecifiedSampleBit ( spAudio audio, int * specified_samp_bit )

related

Gets the bits/sample specified.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	specified_samp_bit	The address of a variable to receive the bits/sample specified.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spSetAudioCallbackFunc()

spAudioCallbackType spSetAudioCallbackFunc ( spAudio audio, spAudioCallbackType call_type, spAudioCallbackFunc call_func, void * call_data )

related

Sets a callback function. This function should be called before opening a device. The callback types of SP_AUDIO_OUTPUT_POSITION_CALLBACK and SP_AUDIO_OUTPUT_BUFFER_CALLBACK are only supported currently.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	call_type	The callback type. Multiple types can be specified by using '|'.
[in]	call_func	The callback function which has the following signature ( spAudioCallbackFunc ): spBool func(spAudio audio, spAudioCallbackType call_type, void *data1, void *data2, void *user_data);
[in]	call_data	The user data for the callback function. You can obtain this address as the 5th argument of the callback function.

Returns

The callack type which can be set successfully. This value sometimes differs from call_type value on some environments.

spOpenAudioDevice()

spBool spOpenAudioDevice ( spAudio audio, const char * mode )

related

Opens the current audio device. If you want full-duplex I/O, open with read mode then do with write mode. The second open with write mode will fail if the device doesn't accept full-duplex I/O.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	mode	Device opening mode. 'r' means read mode, 'w' means write mode. 'ro' and 'wo' which mean read only and write only modes are also supported. Although these ‘only’ modes invalidate full-duplex I/O, sometimes improve sound quality especially for Linux OSS environment.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spCloseAudioDevice()

spBool spCloseAudioDevice ( spAudio audio )

related

Closes the current audio device.

Parameters

[in]

audio

spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .

Return values

SP_TRUE	Success
SP_FALSE	Failure

spReadAudio()

long spReadAudio ( spAudio audio, void * data, long length )

related

Reads raw data from the audio device. This function blocks processing until the read length reaches length unless the blocking mode is disabled by spSetAudioBlockingMode().

Warning

This function can be used when spOpenAudioDevice() is called with "r" mode.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	data	The address of a buffer to receive raw data from the audio device. The type of the buffer must be 'short' for up to 16 bits/sample, 'long' for up to 32 bits/sample.
[in]	length	The length of the buffer. This length is not the size in bytes of the buffer, but the number of elements of the buffer.

Returns

The read length for success, or -1 for failure.

spWriteAudio()

long spWriteAudio ( spAudio audio, void * data, long length )

related

Writes raw data to the audio device. Since writing data is performed asynchronously, the function call finishes before playing whole specified data. The timing of the finish depends on your environment.

Warning

This function can be used when spOpenAudioDevice() is called with "w" mode.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	data	The address of a buffer to send raw data to the audio device. The type of the buffer must be 'short' for up to 16 bits/sample, 'long' for up to 32 bits/sample.
[in]	length	The length of the buffer. This length is not the size in bytes of the buffer, but the number of elements of the buffer.

Returns

The written length for success, -1 for failure.

spReadAudioDoubleWeighted()

long spReadAudioDoubleWeighted ( spAudio audio, double * data, long length, double weight )

related

Reads data to a double array from the audio device. The weight is multiplied to the data after reading.

Warning

This function can be used when spOpenAudioDevice() is called with "r" mode.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	data	The address of a double array to receive data from the audio device.
[in]	length	The length of the buffer. This length is not the size in bytes of the buffer, but the number of elements of the buffer.
[in]	weight	a weighting factor multiplied to each element in data after reading.

Returns

The read length for success, -1 for failure.

spReadAudioDouble()

long spReadAudioDouble ( spAudio audio, double * data, long length )

related

Reads data to a double array from the audio device.

Warning

This function can be used when spOpenAudioDevice() is called with "r" mode.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	data	The address of a double array to receive data from the audio device.
[in]	length	The length of the buffer. This length is not the size in bytes of the buffer, but the number of elements of the buffer.

Returns

The read length for success, -1 for failure.

spWriteAudioDoubleWeighted()

long spWriteAudioDoubleWeighted ( spAudio audio, double * data, long length, double weight )

related

Writes a double array to the audio device. The weight is multiplied to the data before writing.

Warning

This function can be used when spOpenAudioDevice() is called with "w" mode.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	data	The address of a double array to send data to the audio device. The data range must be basically from -1 to 1 inclusive.
[in]	length	The length of the buffer. This length is not the size in bytes of the buffer, but the number of elements of the buffer.
[in]	weight	a weighting factor multiplied to each element in data before writing.

Returns

The written length for success, -1 for failure.

spWriteAudioDouble()

long spWriteAudioDouble ( spAudio audio, double * data, long length )

related

Writes a double array to the audio device.

Warning

This function can be used when spOpenAudioDevice() is called with "w" mode.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[in]	data	The address of a double array to send data to the audio device. The data range must be basically from -1 to 1 inclusive.
[in]	length	The length of the buffer. This length is not the size in bytes of the buffer, but the number of elements of the buffer.

Returns

The written length for success, -1 for failure.

spGetAudioOutputPosition()

spBool spGetAudioOutputPosition ( spAudio audio, spLong * position )

related

Gets the playback position.

Note

Since this function is not supported on some environments, the function call on those environments always fails.

Parameters

[in]	audio	spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .
[out]	position	The address of a variable to receive the playback position.

Return values

SP_TRUE	Success
SP_FALSE	Failure

spStopAudio()

spBool spStopAudio ( spAudio audio )

related

Stops audio I/O as soon as possible. Note that the behavior of this function has dependence on an environment. The function call on some environments will decrease a processing load starting to increase from beginning of audio I/O.

Parameters

[in]

audio

spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .

Return values

SP_TRUE	Success
SP_FALSE	Failure

spSyncAudio()

spBool spSyncAudio ( spAudio audio )

related

Synchronizes audio I/O. Note that the behavior of this function has dependence on an environment.

Parameters

[in]

audio

spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .

Return values

SP_TRUE	Success
SP_FALSE	Failure

spFreeAudio

#define spFreeAudio ( audio )    spFreeAudioDriver(audio)

related

Frees the default audio driver's resources (destructor).

Parameters

[in]

audio

spAudio type variable obtained by spInitAudio() .