Definitions of audio functions. More...

Functions
Audio parameters
The parameters of the audio output device (sound card) can be set using the functions below. The audio gain (amplification factor) can be changed at any time. All other functions functions in this group have to be called before the audio subsystem is loaded (i.e. before the first sample is loaded and played) and their settings remain unchanged until the end of the program. The parameter functions also define the settings for samples that are created with ts5_alloc_sample().
unsigned int	ts5_set_audio_samplerate (unsigned int samplerate)
	Set the requested samplerate for the audio system. More...

unsigned int	ts5_get_audio_samplerate ()
	Get the sample rate of the audio system. More...

unsigned int	ts5_set_audio_channels (unsigned int channels)
	Set the requested number of channels for the audio system. More...

unsigned int	ts5_get_audio_channels ()
	Get the number of channels of the audio system. More...

int	ts5_set_audio_depth (int depth)
	Set the sample depth for the audio system. More...

int	ts5_get_audio_depth ()
	Get the sample depth of the audio system. More...

double	ts5_set_audio_gain (double gain)
	Set the gain (amplification factor) of the audio system. More...

double	ts5_get_audio_gain ()
	Get the gain of the audio system. More...

Loading samples
Samples can either be read from a file, or empty samples can be generated. Empty samples can be used for generating simple sounds or for recording vocal responses. Most samples (samples that contain less than 2^24 sample values) can be read completely into memory using ts5_read_sample(). Longer samples should be loaded with ts5_read_long_sample(). These will be streamed (i.e. they will be divided in parts that are read when necessary).
TS5_SAMPLE *	ts5_alloc_sample (double length)
	Create an empty sample. More...

TS5_SAMPLE *	ts5_read_sample (const char *file)
	Open a sample from a file. More...

TS5_SAMPLE *	ts5_read_long_sample (const char *file)
	Open a long sample from a file. More...

void	ts5_write_sample (const char file, TS5_SAMPLE sample)
	Write a sample. More...

void	ts5_free_sample (TS5_SAMPLE *sample)
	Free the memory used by a sample. More...

Playing samples
Audio samples can be played using the functions below. Playing a sample will not block the flow of your program. Once a sample starts playing the function call following ts5_play_sample() will be executed immediately.
void	ts5_play_sample (TS5_SAMPLE *sample)
	Start playing a sample. More...

void	ts5_pause_sample (TS5_SAMPLE *sample)
	Pause playing a sample. More...

void	ts5_stop_sample (TS5_SAMPLE *sample)
	Stop playing a sample. More...

int	ts5_get_sample_status (TS5_SAMPLE *sample)
	Query whether a sample is playing. More...

Manipulating sample data
The data of a sample can be accessed with the ts5_get_sample_data_pointer() function. This way, the user can generate simple sounds such as sine waves, white noise, etc. The process is as follows: Allocate a sample Get acces to the sample data Manipulate the sample data Play the sample See audio02.c for an example that shows how this works.
void *	ts5_get_sample_data_pointer (TS5_SAMPLE *sample)
	Get acces to a sample's data. More...

Recording samples
Audio samples can be recorded using the functions below. The user must explicilty start the recording system by calling ts5_start_audio_recorder(). During long breaks in the program (not intertrial intervals) the user can stop the audio recorder to save resources, then start the recorder again when the program continues. Recording is a two-step process: A call to ts5_record_sample() starts the recording of a sample. This generates a timestamp and then waits for the first fragment of audio from the driver. The part of the fragment that is older than the timestamp is discarded. The remainder is stored in the sample. Once the recording is started the user needs to repeatedly call ts5_get_sample_fragments() to append the available audio fragments to the sample. The audio buffer is about 10 seconds, so the recording loop does not need to be too tight. See audio03.c for an example that shows how this works.
void	ts5_start_audio_recorder ()
	Start the audio recorder. More...

void	ts5_stop_audio_recorder ()
	Stop the audio recorder. More...

void	ts5_flush_audio_recorder ()
	Flush the audio recorder buffer. More...

void	ts5_record_sample (TS5_SAMPLE *sample)
	Start recording a sample. More...

int	ts5_get_sample_fragments (TS5_SAMPLE *sample)
	Update the sample buffer when recording. More...

Software voice key
The audio recorder can be used as a software voice key. The user has to explicitly start an audio recording to start the voice key and update the sample buffer with ts5_get_sample_fragments(). The ts5_detect_voice_onsets() function will then detect voice onsets and offsets and notify the timer functions of each onset or offset that is detected. See timer.c for more information about response registration. See audio04.c for an example that shows how the software voice key works.
int	ts5_define_voicekey_button (int button)
	Define the software voice key as a response button. More...

void	ts5_detect_voice_onsets (TS5_SAMPLE *sample)
	Detect voice onsets in a sample. More...

double	ts5_set_voicekey_treshold (double treshold)
	Set the voice key treshold. More...

double	ts5_get_voicekey_treshold ()
	Get the voice key treshold. More...

double	ts5_set_voicekey_rise_delay (double rise_delay)
	Set the voice key rise delay. More...

double	ts5_get_voicekey_rise_delay ()
	Get the voice key rise delay. More...

double	ts5_set_voicekey_drop_delay (double drop_delay)
	Set the voice key drop delay. More...

double	ts5_get_voicekey_drop_delay ()
	Get the voice key drop delay. More...

Sample parameters
For each sample the parameters can be queried/set using the functions below: Sample position, speed, gain, pan and playmode can be adjusted at any time, even when the sample is playing. Samplerate, channels, depth and length are defined when the sample is read or allocated.
unsigned int	ts5_get_sample_samplerate (TS5_SAMPLE *sample)
	Get the sample rate of a sample. More...

unsigned int	ts5_get_sample_channels (TS5_SAMPLE *sample)
	Get the number of channels of a sample. More...

int	ts5_get_sample_depth (TS5_SAMPLE *sample)
	Get the sample depth of a sample. More...

double	ts5_get_sample_length (TS5_SAMPLE *sample)
	Get the length of a sample. More...

double	ts5_set_sample_position (TS5_SAMPLE *sample, double position)
	Set the playback position of a sample. More...

double	ts5_get_sample_position (TS5_SAMPLE *sample)
	Get the playback position of a sample. More...

double	ts5_set_sample_speed (TS5_SAMPLE *sample, double speed)
	Set the playback speed of a sample. More...

double	ts5_get_sample_speed (TS5_SAMPLE *sample)
	Get the playback speed of a sample. More...

double	ts5_set_sample_gain (TS5_SAMPLE *sample, double gain)
	Set the playback gain of a sample. More...

double	ts5_get_sample_gain (TS5_SAMPLE *sample)
	Get the playback gain of a sample. More...

double	ts5_set_sample_pan (TS5_SAMPLE *sample, double pan)
	Set the playback pan of a sample. More...

double	ts5_get_sample_pan (TS5_SAMPLE *sample)
	Get the playback pan of a sample. More...

int	ts5_set_sample_playmode (TS5_SAMPLE *sample, int playmode)
	Set the playmode of a sample. More...

int	ts5_get_sample_playmode (TS5_SAMPLE *sample)
	Get the playmode of a sample. More...

Detailed Description

Definitions of audio functions.

Definition in file audio.c.

Function Documentation

unsigned int ts5_set_audio_samplerate ( unsigned int samplerate )

Set the requested samplerate for the audio system.

Parameters

samplerate The samplerate. Can be TS5_11025, TS5_22050 or TS5_44100.

Returns: The previous requested samplerate.

This function has to be called before the (automatic) installation of the audio system.

Once the audio system is installed, the sample rate of the system cannot be changed.

This is only a request, the audio driver can choose non-matching values. Query the audio system after installation with ts5_get_audio_samplerate() for the actual sample rate.

This function also influences the sample rate of samples made by ts5_alloc_sample().

The default samplerate is TS5_44100.

Examples:: audio01.c, audio02.c, and audio03.c.

Definition at line 64 of file audio.c.

unsigned int ts5_get_audio_samplerate ( )

Get the sample rate of the audio system.

Returns: The sample rate of the audio system as an unsigned integer.

Examples:: audio02.c.

Definition at line 93 of file audio.c.

unsigned int ts5_set_audio_channels ( unsigned int channels )

Set the requested number of channels for the audio system.

Parameters

channels The number of channels. Can be TS5_MONO or TS5_STEREO.

Returns: The previous requested number of channels.

This function has to be called before the (automatic) installation of the audio system.

Once the audio system is installed, the number of channels of the system cannot be changed.

This is only a request, the audio driver can choose non-matching values. Query the audio system after installation with ts5_get_audio_channels() for the actual number of channels.

This function also influences the number of channels of samples made by ts5_alloc_sample().

The default number of channels is TS5_STEREO.

Examples:: audio01.c, audio02.c, and audio03.c.

Definition at line 124 of file audio.c.

unsigned int ts5_get_audio_channels ( )

Get the number of channels of the audio system.

Returns: The number of channels of the audio system.

Examples:: audio02.c.

Definition at line 155 of file audio.c.

int ts5_set_audio_depth ( int depth )

Set the sample depth for the audio system.

Parameters

depth The sample depth. Can be TS5_INTEGER or TS5_FLOAT.

Returns: The previous requested sample depth.

This function has to be called before the (automatic) installation of the audio system.

Once the audio system is installed, the sample depth of the system cannot be changed.

This is only a request, the audio driver can choose non-matching values. Query the audio system after installation with ts5_get_audio_depth() for the actual sample depth.

This function also influences the sample depth of samples made by ts5_alloc_sample().

The default sample depth is TS5_FLOAT.

Examples:: audio01.c.

Definition at line 206 of file audio.c.

int ts5_get_audio_depth ( )

Get the sample depth of the audio system.

Returns: The sample depth of the audio system.

Definition at line 235 of file audio.c.

double ts5_set_audio_gain ( double gain )

Set the gain (amplification factor) of the audio system.

Parameters

gain	The gain. 0.0 = silent, 0.5=half, 1.0 = untouched, 2.0 = double, ...

Returns: The previous setting.

The default gain is 1.0.

Definition at line 261 of file audio.c.

double ts5_get_audio_gain ( )

Get the gain of the audio system.

Returns: The gain of the audio system.

Definition at line 293 of file audio.c.

TS5_SAMPLE* ts5_alloc_sample ( double length )

Create an empty sample.

Parameters

length Length of the sample in seconds.

Returns: A pointer to the newly created sample.

A Sample's samplerate, channels and depth are set by ts5_set_audio_samplerate(), ts5_set_audio_channels() and ts5_set_audio_depth()

Examples:: audio02.c, audio03.c, and audio04.c.

Definition at line 334 of file audio.c.

TS5_SAMPLE* ts5_read_sample ( const char * file )

Open a sample from a file.

Parameters

file	Path to the sample file.

Returns: A pointer to the newly created sample.

Available sample types are: wav, flac, ogg, it, mod, s3m, xm.

The file is read from disk all at once.

Examples:: audio01.c.

Definition at line 440 of file audio.c.

TS5_SAMPLE* ts5_read_long_sample ( const char * file )

Open a long sample from a file.

Parameters

file	Path to the sample file.

Returns: A pointer to the newly created sample.

Available sample types are: wav, flac, ogg, it, mod, s3m, xm.

The file is read from disk as it is needed.

Definition at line 537 of file audio.c.

void ts5_write_sample	(	const char *	file,
		TS5_SAMPLE *	sample
	)

Write a sample.

Parameters

file	Path to the sample file.
sample	Pointer to the sample that will be written.

Only .wav is supported. The file extension should be .wav

Examples:: audio02.c, audio03.c, and audio04.c.

Definition at line 599 of file audio.c.

void ts5_free_sample ( TS5_SAMPLE * sample )

Free the memory used by a sample.

Parameters

sample Pointer to the sample that will be freed.

This function should be called at the end of the program for each sample allocated or read by the user.

Examples:: audio01.c, audio02.c, audio03.c, and audio04.c.

Definition at line 623 of file audio.c.

void ts5_play_sample ( TS5_SAMPLE * sample )

Start playing a sample.

Parameters

sample Pointer to the sample that will be played.

Examples:: audio01.c, and audio02.c.

Definition at line 671 of file audio.c.

void ts5_pause_sample ( TS5_SAMPLE * sample )

Pause playing a sample.

Parameters

sample Pointer to the sample that will be paused.

Definition at line 703 of file audio.c.

void ts5_stop_sample ( TS5_SAMPLE * sample )

Stop playing a sample.

Parameters

sample Pointer to the sample that will be stopped.

Examples:: audio02.c.

Definition at line 735 of file audio.c.

int ts5_get_sample_status ( TS5_SAMPLE * sample )

Query whether a sample is playing.

Parameters

sample Pointer to the sample that will queried.

Returns: 1 if the sample is playing, 0 if not.

Examples:: audio01.c.

Definition at line 775 of file audio.c.

void* ts5_get_sample_data_pointer ( TS5_SAMPLE * sample )

Get acces to a sample's data.

Parameters

sample Pointer to the sample that will queried.

Returns: a pointer to the sample data.

Examples:: audio02.c.

Definition at line 836 of file audio.c.

void ts5_start_audio_recorder ( )

Start the audio recorder.

This function has to be called explicitly by the user before samples can be recorded.

Examples:: audio03.c, and audio04.c.

Definition at line 902 of file audio.c.

void ts5_stop_audio_recorder ( )

Stop the audio recorder.

This function has to be called explicitly by the user at the end of the program.

Examples:: audio03.c, and audio04.c.

Definition at line 918 of file audio.c.

void ts5_flush_audio_recorder ( )

Flush the audio recorder buffer.

Definition at line 932 of file audio.c.

void ts5_record_sample ( TS5_SAMPLE * sample )

Start recording a sample.

Parameters

sample Pointer to the sample that will be recorded.

Examples:: audio03.c, and audio04.c.

Definition at line 944 of file audio.c.

int ts5_get_sample_fragments ( TS5_SAMPLE * sample )

Update the sample buffer when recording.

Parameters

sample Pointer to the sample that will be recorded.

Returns: 1 if the sample is full, 0 if not.

Examples:: audio03.c, and audio04.c.

Definition at line 1004 of file audio.c.

int ts5_define_voicekey_button ( int button )

Define the software voice key as a response button.

Parameters

button Number of the button (buttons are counted from 1).

Returns: The reponse number associated with the button.

Give a positive number for the button if you want to monitor button press events, a negative number if you want to monitor button release events.

Examples:: audio04.c.

Definition at line 1079 of file audio.c.

void ts5_detect_voice_onsets ( TS5_SAMPLE * sample )

Detect voice onsets in a sample.

Parameters

sample Pointer to the sample that will be processed.

Examples:: audio04.c.

Definition at line 1137 of file audio.c.

double ts5_set_voicekey_treshold ( double treshold )

Set the voice key treshold.

Parameters

treshold Treshold as a value beteen 0.0 (silence) and 1.0 (max).

Returns: The previous setting.

The default treshold is set to 0.5.

Examples:: audio04.c.

Definition at line 1242 of file audio.c.

double ts5_get_voicekey_treshold ( )

Get the voice key treshold.

Returns: The voice key treshold.

Definition at line 1277 of file audio.c.

double ts5_set_voicekey_rise_delay ( double rise_delay )

Set the voice key rise delay.

Parameters

rise_delay Rise delay in seconds.

Returns: The previous setting.

The default rise delay is set to 0.2 seconds.

Definition at line 1294 of file audio.c.

double ts5_get_voicekey_rise_delay ( )

Get the voice key rise delay.

Returns: The voice key rise delay.

Definition at line 1323 of file audio.c.

double ts5_set_voicekey_drop_delay ( double drop_delay )

Set the voice key drop delay.

Parameters

drop_delay Rise delay in seconds.

Returns: The previous setting.

The default drop delay is set to 0.2 seconds.

Definition at line 1341 of file audio.c.

double ts5_get_voicekey_drop_delay ( )

Get the voice key drop delay.

Returns: The voice key drop delay.

Definition at line 1370 of file audio.c.

unsigned int ts5_get_sample_samplerate ( TS5_SAMPLE * sample )

Get the sample rate of a sample.

Parameters

sample Pointer to the sample that will queried.

Returns: The sample rate of the sample.

Examples:: audio01.c.

Definition at line 1405 of file audio.c.

unsigned int ts5_get_sample_channels ( TS5_SAMPLE * sample )

Get the number of channels of a sample.

Parameters

sample Pointer to the sample that will queried.

Returns: The number of channels of the sample.

Definition at line 1438 of file audio.c.

int ts5_get_sample_depth ( TS5_SAMPLE * sample )

Get the sample depth of a sample.

Parameters

sample Pointer to the sample that will queried.

Returns: The sample depth of a sample.

Definition at line 1484 of file audio.c.

double ts5_get_sample_length ( TS5_SAMPLE * sample )

Get the length of a sample.

Parameters

sample Pointer to the sample that will queried.

Returns: The length of the sample.

Examples:: audio01.c.

Definition at line 1528 of file audio.c.

double ts5_set_sample_position	(	TS5_SAMPLE *	sample,
		double	position
	)

Set the playback position of a sample.

Parameters

sample	Pointer to the sample that will be adjusted.
position	The new playback position.

Returns: The old playback position.

Definition at line 1563 of file audio.c.

double ts5_get_sample_position ( TS5_SAMPLE * sample )

Get the playback position of a sample.

Parameters

sample Pointer to the sample that will be queried.

Returns: The current playback position.

Definition at line 1625 of file audio.c.

double ts5_set_sample_speed	(	TS5_SAMPLE *	sample,
		double	speed
	)

Set the playback speed of a sample.

Parameters

sample	Pointer to the sample that will be adjusted.
speed	The new playback speed (1.0 is normal speed).

Returns: The old playback speed.

Examples:: audio01.c.

Definition at line 1660 of file audio.c.

double ts5_get_sample_speed ( TS5_SAMPLE * sample )

Get the playback speed of a sample.

Parameters

sample Pointer to the sample that will be queried.

Returns: The current playback speed.

Definition at line 1709 of file audio.c.

double ts5_set_sample_gain	(	TS5_SAMPLE *	sample,
		double	gain
	)

Set the playback gain of a sample.

Parameters

sample	Pointer to the sample that will be adjusted.
gain	The new playback gain (1.0 is normal gain).

Returns: The old gain setting.

Examples:: audio01.c.

Definition at line 1742 of file audio.c.

double ts5_get_sample_gain ( TS5_SAMPLE * sample )

Get the playback gain of a sample.

Parameters

sample Pointer to the sample that will be queried.

Returns: The current playback gain.

Definition at line 1790 of file audio.c.

double ts5_set_sample_pan	(	TS5_SAMPLE *	sample,
		double	pan
	)

Set the playback pan of a sample.

Parameters

sample	Pointer to the sample that will be adjusted.
pan	The new playback pan (-1.0 is left, 0.0 is normal, 1.0 is right).

Returns: The old playback pan.

Examples:: audio01.c.

Definition at line 1824 of file audio.c.

double ts5_get_sample_pan ( TS5_SAMPLE * sample )

Get the playback pan of a sample.

Parameters

sample Pointer to the sample that will be queried.

Returns: The current playback pan.

Definition at line 1873 of file audio.c.

int ts5_set_sample_playmode	(	TS5_SAMPLE *	sample,
		int	playmode
	)

Set the playmode of a sample.

Parameters

sample	Pointer to the sample that will be adjusted.
playmode	The new playmode. Can be TS5_PLAY_ONCE or TS5_PLAY_LOOP.

Returns: The old playmode.

Definition at line 1906 of file audio.c.

int ts5_get_sample_playmode ( TS5_SAMPLE * sample )

Get the playmode of a sample.

Parameters

sample Pointer to the sample that will be queried.

Returns: The current playmode.

Definition at line 1957 of file audio.c.

Functions

Detailed Description

Function Documentation