#include <sp/spDefs.h>
#include <sp/spOption.h>
#include <sp/spAudioDefs.h>

Include dependency graph for spAudio.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	SP_AUDIO_BLOCKING 0

#define	SP_AUDIO_NONBLOCKING 1

#define	SP_AUDIO_NO_CALLBACK 0

#define	SP_AUDIO_OUTPUT_POSITION_CALLBACK (1<<0)

#define	SP_AUDIO_OUTPUT_BUFFER_CALLBACK (1<<2)

#define	spFreeAudioDriver(audio) {_spFreeAudioDriver(audio); (audio) = NULL;}

Typedefs
typedef struct _spAudio *	spAudio

typedef unsigned long	spAudioCallbackType

typedef spBool(*	spAudioCallbackFunc) (spAudio audio, spAudioCallbackType call_type, void data1, void data2, void *user_data)

Functions
int	spGetNumAudioDriver (void)

char *	xspGetAudioDriverName (int index)

int	spGetNumAudioDriverDevice (const char *driver_name)

char *	xspGetAudioDriverDeviceName (const char *driver_name, int index)

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)

Function Documentation

◆ spInitAudioDriver()

spAudio spInitAudioDriver ( const char * driver_name )

extern

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

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

◆ spInitAudio()

spAudio spInitAudio ( void )

extern

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 )

extern

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 )

extern

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

Examples: driver.c.

◆ xspGetAudioDeviceName()

char * xspGetAudioDeviceName	(	spAudio	audio,
		int	device_index )

extern

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

Examples: driver.c.

◆ spSelectAudioDevice()

spBool spSelectAudioDevice	(	spAudio	audio,
		int	device_index )

extern

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

Examples: driver.c.

◆ spSetAudioSampleRate()

spBool spSetAudioSampleRate	(	spAudio	audio,
		double	samp_rate )

extern

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

Examples: iotest.c, playsin.c, and rec.c.

◆ spGetAudioSampleRate()

spBool spGetAudioSampleRate	(	spAudio	audio,
		double *	samp_rate )

extern

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

Examples: playsin.c, and rec.c.

◆ spSetAudioChannel()

spBool spSetAudioChannel	(	spAudio	audio,
		int	num_channel )

extern

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

Examples: iotest.c, playsin.c, and rec.c.

◆ spGetAudioChannel()

spBool spGetAudioChannel	(	spAudio	audio,
		int *	num_channel )

extern

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

Examples: iotest.c, and rec.c.

◆ spSetAudioBufferSize()

spBool spSetAudioBufferSize	(	spAudio	audio,
		int	buffer_size )

extern

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

Examples: iotest.c, playsin.c, and rec.c.

◆ spGetAudioBufferSize()

spBool spGetAudioBufferSize	(	spAudio	audio,
		int *	buffer_size )

extern

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 )

extern

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

Examples: iotest.c, playsin.c, and rec.c.

◆ spGetAudioNumBuffer()

spBool spGetAudioNumBuffer	(	spAudio	audio,
		int *	num_buffer )

extern

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 )

extern

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

Examples: rec.c.

◆ spGetAudioBlockingMode()

spBool spGetAudioBlockingMode	(	spAudio	audio,
		int *	block_mode )

extern

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 )

extern

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

Examples: iotest.c, playsin.c, and rec.c.

◆ spGetAudioSampleBit()

spBool spGetAudioSampleBit	(	spAudio	audio,
		int *	samp_bit )

extern

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 )

extern

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 )

extern

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); spAudio A class to handle audio I/O. spAudioCallbackType unsigned long spAudioCallbackType Definition* spAudio.h:63 spBool int spBool
[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.

Examples: playsin.c.

◆ spOpenAudioDevice()

spBool spOpenAudioDevice	(	spAudio	audio,
		const char *	mode )

extern

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

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

◆ spCloseAudioDevice()

spBool spCloseAudioDevice ( spAudio audio )

extern

Closes the current audio device.

Parameters

[in] audio spAudio type variable obtained by spInitAudioDriver() or spInitAudio() .

Return values

SP_TRUE	Success
SP_FALSE	Failure

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

◆ spReadAudio()

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

extern

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.

Examples: rec.c.

◆ spWriteAudio()

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

extern

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 )

extern

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 )

extern

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.

Examples: iotest.c.

◆ spWriteAudioDoubleWeighted()

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

extern

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 )

extern

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.

Examples: iotest.c, and playsin.c.

◆ spGetAudioOutputPosition()

spBool spGetAudioOutputPosition	(	spAudio	audio,
		spLong *	position )

extern

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 )

extern

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 )

extern

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

Macros

Typedefs

Functions

Function Documentation

◆ spInitAudioDriver()

◆ spInitAudio()

◆ _spFreeAudioDriver()

◆ spGetNumAudioDevice()

◆ xspGetAudioDeviceName()

◆ spSelectAudioDevice()

◆ spSetAudioSampleRate()

◆ spGetAudioSampleRate()

◆ spSetAudioChannel()

◆ spGetAudioChannel()

◆ spSetAudioBufferSize()

◆ spGetAudioBufferSize()

◆ spSetAudioNumBuffer()

◆ spGetAudioNumBuffer()

◆ spSetAudioBlockingMode()

◆ spGetAudioBlockingMode()

◆ spSetAudioSampleBit()

◆ spGetAudioSampleBit()

◆ spGetAudioSpecifiedSampleBit()

◆ spSetAudioCallbackFunc()

◆ spOpenAudioDevice()

◆ spCloseAudioDevice()

◆ spReadAudio()

◆ spWriteAudio()

◆ spReadAudioDoubleWeighted()

◆ spReadAudioDouble()

◆ spWriteAudioDoubleWeighted()

◆ spWriteAudioDouble()

◆ spGetAudioOutputPosition()

◆ spStopAudio()

◆ spSyncAudio()