Tscope5
audio.c File Reference

Definitions of audio functions. More...

Go to the source code of this file.

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_frequency (unsigned int frequency)
 Set the requested sample rate for the audio system.
unsigned int ts5_get_audio_frequency ()
 Get the sample rate of the audio system.
unsigned int ts5_set_audio_channels (unsigned int channels)
 Set the requested number of channels for the audio system.
unsigned int ts5_get_audio_channels ()
 Get the number of channels of the audio system.
int ts5_set_audio_depth (int depth)
 Set the sample depth for the audio system.
int ts5_get_audio_depth ()
 Get the sample depth of the audio system.
double ts5_set_audio_gain (double gain)
 Set the gain (amplification factor) of the audio system.
double ts5_get_audio_gain ()
 Get the gain of the audio system.
Loading samples

Samples can either be read from a file, or empty samples can be generated.

Empty samples can be used for recording vocal responses (tbd).

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.
TS5_SAMPLE * ts5_read_sample (const char *file)
 Open a sample from a file.
TS5_SAMPLE * ts5_read_long_sample (const char *file)
 Open a long sample from a file.
void ts5_write_sample (const char *file, TS5_SAMPLE *sample)
 Write a sample.
void ts5_free_sample (TS5_SAMPLE *sample)
 Free the memory used by a sample.
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.
void ts5_pause_sample (TS5_SAMPLE *sample)
 Pause playing a sample.
void ts5_stop_sample (TS5_SAMPLE *sample)
 Stop playing a sample.
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.
  • Sample frequency, channels, depth and length are defined when the sample is read or allocated.
int ts5_get_sample_status (TS5_SAMPLE *sample)
 Query whether a sample is playing.
unsigned int ts5_get_sample_frequency (TS5_SAMPLE *sample)
 Get the sample rate of a sample.
unsigned int ts5_get_sample_channels (TS5_SAMPLE *sample)
 Get the number of channels of a sample.
int ts5_get_sample_depth (TS5_SAMPLE *sample)
 Get the sample depth of a sample.
unsigned int ts5_get_sample_length (TS5_SAMPLE *sample)
 Get the length of a sample.
unsigned int ts5_set_sample_position (TS5_SAMPLE *sample, unsigned int position)
 Set the playback position of a sample.
unsigned int ts5_get_sample_position (TS5_SAMPLE *sample)
 Get the playback position of a sample.
double ts5_set_sample_speed (TS5_SAMPLE *sample, double speed)
 Set the playback speed of a sample.
double ts5_get_sample_speed (TS5_SAMPLE *sample)
 Get the playback speed of a sample.
double ts5_set_sample_gain (TS5_SAMPLE *sample, double gain)
 Set the playback gain of a sample.
double ts5_get_sample_gain (TS5_SAMPLE *sample)
 Get the playback gain of a sample.
double ts5_set_sample_pan (TS5_SAMPLE *sample, double pan)
 Set the playback pan of a sample.
double ts5_get_sample_pan (TS5_SAMPLE *sample)
 Get the playback pan of a sample.
int ts5_set_sample_playmode (TS5_SAMPLE *sample, int playmode)
 Set the playmode of a sample.
int ts5_get_sample_playmode (TS5_SAMPLE *sample)
 Get the playmode of a sample.

Detailed Description

Definitions of audio functions.

Definition in file audio.c.


Function Documentation

unsigned int ts5_set_audio_frequency ( unsigned int  frequency)

Set the requested sample rate for the audio system.

Parameters:
frequencyThe sample rate. Can be TS5_11025, TS5_22050 or TS5_44100.
Returns:
The previous requested sample rate.

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_frequency() for the actual sample rate.

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

The default frequency is TS5_44100.

Examples:
audio01.c.

Definition at line 59 of file audio.c.

unsigned int ts5_get_audio_frequency ( )

Get the sample rate of the audio system.

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

Definition at line 88 of file audio.c.

unsigned int ts5_set_audio_channels ( unsigned int  channels)

Set the requested number of channels for the audio system.

Parameters:
channelsThe 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.

Definition at line 119 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.

Definition at line 150 of file audio.c.

int ts5_set_audio_depth ( int  depth)

Set the sample depth for the audio system.

Parameters:
depthThe 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 201 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 230 of file audio.c.

double ts5_set_audio_gain ( double  gain)

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

Parameters:
gainThe gain. 0.0 = silent, 0.5=half, 1.0 = untouched, 2.0 = double, ...
Returns:
The previous gain.

The default gain is 1.0.

Definition at line 256 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 288 of file audio.c.

TS5_SAMPLE* ts5_alloc_sample ( double  length)

Create an empty sample.

Parameters:
lengthLength of the sample in seconds.
Returns:
A pointer to the newly created sample.

Sample frequency, channels and depth are set by ts5_set_audio_frequency(), ts5_set_audio_channels() and ts5_set_audio_depth()

Definition at line 327 of file audio.c.

TS5_SAMPLE* ts5_read_sample ( const char *  file)

Open a sample from a file.

Parameters:
filePath 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 414 of file audio.c.

TS5_SAMPLE* ts5_read_long_sample ( const char *  file)

Open a long sample from a file.

Parameters:
filePath 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 474 of file audio.c.

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

Write a sample.

Parameters:
filePath to the sample file.
samplePointer to the sample that will be written.

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

Definition at line 521 of file audio.c.

void ts5_free_sample ( TS5_SAMPLE *  sample)

Free the memory used by a sample.

Parameters:
samplePointer 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.

Definition at line 545 of file audio.c.

void ts5_play_sample ( TS5_SAMPLE *  sample)

Start playing a sample.

Parameters:
samplePointer to the sample that will be played.
Examples:
audio01.c.

Definition at line 590 of file audio.c.

void ts5_pause_sample ( TS5_SAMPLE *  sample)

Pause playing a sample.

Parameters:
samplePointer to the sample that will be paused.

Definition at line 622 of file audio.c.

void ts5_stop_sample ( TS5_SAMPLE *  sample)

Stop playing a sample.

Parameters:
samplePointer to the sample that will be stopped.

Definition at line 661 of file audio.c.

int ts5_get_sample_status ( TS5_SAMPLE *  sample)

Query whether a sample is playing.

Parameters:
samplePointer to the sample that will queried.
Returns:
1 if the sample is playing, 0 if not.
Examples:
audio01.c.

Definition at line 719 of file audio.c.

unsigned int ts5_get_sample_frequency ( TS5_SAMPLE *  sample)

Get the sample rate of a sample.

Parameters:
samplePointer to the sample that will queried.
Returns:
The sample rate of the sample.
Examples:
audio01.c.

Definition at line 755 of file audio.c.

unsigned int ts5_get_sample_channels ( TS5_SAMPLE *  sample)

Get the number of channels of a sample.

Parameters:
samplePointer to the sample that will queried.
Returns:
The number of channels of the sample.

Definition at line 788 of file audio.c.

int ts5_get_sample_depth ( TS5_SAMPLE *  sample)

Get the sample depth of a sample.

Parameters:
samplePointer to the sample that will queried.
Returns:
The sample depth of a sample.

Definition at line 834 of file audio.c.

unsigned int ts5_get_sample_length ( TS5_SAMPLE *  sample)

Get the length of a sample.

Parameters:
samplePointer to the sample that will queried.
Returns:
The length of the sample.
Examples:
audio01.c.

Definition at line 878 of file audio.c.

unsigned int ts5_set_sample_position ( TS5_SAMPLE *  sample,
unsigned int  position 
)

Set the playback position of a sample.

Parameters:
samplePointer to the sample that will be adjusted.
positionThe new playback position.
Returns:
The old playback position.

Definition at line 913 of file audio.c.

unsigned int ts5_get_sample_position ( TS5_SAMPLE *  sample)

Get the playback position of a sample.

Parameters:
samplePointer to the sample that will be queried.
Returns:
The current playback position.

Definition at line 977 of file audio.c.

double ts5_set_sample_speed ( TS5_SAMPLE *  sample,
double  speed 
)

Set the playback speed of a sample.

Parameters:
samplePointer to the sample that will be adjusted.
speedThe new playback speed (1.0 is normal speed).
Returns:
The old playback speed.
Examples:
audio01.c.

Definition at line 1012 of file audio.c.

double ts5_get_sample_speed ( TS5_SAMPLE *  sample)

Get the playback speed of a sample.

Parameters:
samplePointer to the sample that will be queried.
Returns:
The current playback speed.

Definition at line 1061 of file audio.c.

double ts5_set_sample_gain ( TS5_SAMPLE *  sample,
double  gain 
)

Set the playback gain of a sample.

Parameters:
samplePointer to the sample that will be adjusted.
gainThe new playback gain (1.0 is normal gain).
Returns:
The old gain position.
Examples:
audio01.c.

Definition at line 1094 of file audio.c.

double ts5_get_sample_gain ( TS5_SAMPLE *  sample)

Get the playback gain of a sample.

Parameters:
samplePointer to the sample that will be queried.
Returns:
The current playback gain.

Definition at line 1142 of file audio.c.

double ts5_set_sample_pan ( TS5_SAMPLE *  sample,
double  pan 
)

Set the playback pan of a sample.

Parameters:
samplePointer to the sample that will be adjusted.
panThe 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 1176 of file audio.c.

double ts5_get_sample_pan ( TS5_SAMPLE *  sample)

Get the playback pan of a sample.

Parameters:
samplePointer to the sample that will be queried.
Returns:
The current playback pan.

Definition at line 1225 of file audio.c.

int ts5_set_sample_playmode ( TS5_SAMPLE *  sample,
int  playmode 
)

Set the playmode of a sample.

Parameters:
samplePointer to the sample that will be adjusted.
playmodeThe new playmode. Can be TS5_PLAY_ONCE or TS5_PLAY_LOOP.
Returns:
The old playmode.

Definition at line 1258 of file audio.c.

int ts5_get_sample_playmode ( TS5_SAMPLE *  sample)

Get the playmode of a sample.

Parameters:
samplePointer to the sample that will be queried.
Returns:
The current playmode.

Definition at line 1309 of file audio.c.