Tscope5
audio.c File Reference

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)
unsigned int ts5_get_audio_frequency ()
unsigned int ts5_set_audio_channels (unsigned int channels)
unsigned int ts5_get_audio_channels ()
int ts5_set_audio_depth (int depth)
int ts5_get_audio_depth ()
double ts5_set_audio_gain (double gain)
double ts5_get_audio_gain ()
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)
TS5_SAMPLE * ts5_read_sample (const char *file)
TS5_SAMPLE * ts5_read_long_sample (const char *file)
void ts5_write_sample (const char *file, TS5_SAMPLE *sample)
void ts5_free_sample (TS5_SAMPLE *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)
void ts5_pause_sample (TS5_SAMPLE *sample)
void ts5_stop_sample (TS5_SAMPLE *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)
unsigned int ts5_get_sample_frequency (TS5_SAMPLE *sample)
unsigned int ts5_get_sample_channels (TS5_SAMPLE *sample)
int ts5_get_sample_depth (TS5_SAMPLE *sample)
unsigned int ts5_get_sample_length (TS5_SAMPLE *sample)
unsigned int ts5_set_sample_position (TS5_SAMPLE *sample, unsigned int position)
unsigned int ts5_get_sample_position (TS5_SAMPLE *sample)
double ts5_set_sample_speed (TS5_SAMPLE *sample, double speed)
double ts5_get_sample_speed (TS5_SAMPLE *sample)
double ts5_set_sample_gain (TS5_SAMPLE *sample, double gain)
double ts5_get_sample_gain (TS5_SAMPLE *sample)
double ts5_set_sample_pan (TS5_SAMPLE *sample, double pan)
double ts5_get_sample_pan (TS5_SAMPLE *sample)
int ts5_set_sample_playmode (TS5_SAMPLE *sample, int playmode)
int ts5_get_sample_playmode (TS5_SAMPLE *sample)

Detailed Description

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:
audio1.c.

Definition at line 46 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 74 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:
audio1.c.

Definition at line 101 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 129 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:
audio1.c.

Definition at line 173 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 201 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 225 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 257 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 295 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:
audio1.c.

Definition at line 376 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 433 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 478 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:
audio1.c.

Definition at line 501 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:
audio1.c.

Definition at line 546 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 578 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 616 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:
audio1.c.

Definition at line 674 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:
audio1.c.

Definition at line 709 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 741 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 785 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:
audio1.c.

Definition at line 829 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 863 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 920 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:
audio1.c.

Definition at line 954 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 1000 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:
audio1.c.

Definition at line 1033 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 1079 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:
audio1.c.

Definition at line 1112 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 1158 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 1191 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 1237 of file audio.c.