audio.c

Go to the documentation of this file.

////////////////////////////////////////////////////////////////////////////////
//     
//    __                                ______
//   / /_______________  ____  ___     / ____/
//  / __/ ___/ ___/ __ \/ __ \/ _ \   /___ )  
// / /_(__  ) /__/ /_/ / /_/ /  __/  ____/ /  
// \__/____/\___/\____/ .___/\___/  /_____/   
//                   /_/                      
//     
/// \file audio.c 
/// Definitions of audio functions.
/// \example audio01.c
/// \example audio02.c
/// \example audio03.c
/// \example audio04.c
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name 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().
//@{
////////////////////////////////////////////////////////////////////////////////

#include "../include/tscope5/audio.h"
#include "../include/tscope5/audio_internal.h"
#include "../include/tscope5/system_internal.h"

#include <math.h>


////////////////////////////////////////////////////////////////////////////////
/// Set the requested samplerate for the audio system.
///
/// \param samplerate The samplerate. Can be TS5_11025, TS5_22050 or TS5_44100.
///
/// \return 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.
////////////////////////////////////////////////////////////////////////////////
unsigned int ts5_set_audio_samplerate(unsigned int samplerate)
{
    if (!_ts5_is_tscope5_installed) {
        ts5_install_tscope5("ts5_set_audio_samplerate");
    }

    ts5_log(TS5_LOGLEVEL_4, "ts5_set_audio_samplerate(%u)\n", samplerate);

    unsigned int retval = _ts5_status.audio.samplerate;

    if (samplerate!=TS5_11025 && samplerate!=TS5_22050 && samplerate!=TS5_44100) {
        ts5_fatal("ts5_set_audio_samplerate: unknown samplerate requested\n");
    }

    _ts5_status.audio.samplerate = samplerate;

    ts5_log(TS5_LOGLEVEL_4, 
                "ts5_set_audio_samplerate: set sample rate to %u (was %u)\n",
                _ts5_status.audio.samplerate, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the sample rate of the audio system.
///
/// \return The sample rate of the audio system as an unsigned integer.
////////////////////////////////////////////////////////////////////////////////
unsigned int ts5_get_audio_samplerate()
{
    ts5_check_audio("ts5_get_audio_samplerate");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_audio_samplerate()\n");

    return _ts5_status.audio.samplerate;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the requested number of channels for the audio system.
///
/// \param channels The number of channels. Can be TS5_MONO or TS5_STEREO.
///
/// \return 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.
////////////////////////////////////////////////////////////////////////////////
unsigned int ts5_set_audio_channels(unsigned int channels)
{
    if (!_ts5_is_tscope5_installed) {
        ts5_install_tscope5("ts5_set_audio_channels");
    }

    ts5_log(TS5_LOGLEVEL_4, "ts5_set_audio_channels(%d)\n", channels);

    unsigned int retval = _ts5_status.audio.channels;

    if (channels!=TS5_MONO && channels!=TS5_STEREO) {
        ts5_fatal("%s: %s\n", "ts5_set_audio_channels",
                    "unknown number of channels requested");
    }

    _ts5_status.audio.channels = channels;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %u (was %u)\n",
                "ts5_set_audio_channels",
                "set number of channels to", 
                _ts5_status.audio.channels, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the number of channels of the audio system.
///
/// \return The number of channels of the audio system.
////////////////////////////////////////////////////////////////////////////////
unsigned int ts5_get_audio_channels()
{
    ts5_check_audio("ts5_get_audio_channels");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_audio_channels()\n");

    ALLEGRO_CHANNEL_CONF channels = 
        al_get_voice_channels(_ts5_data.audio.voice);

    unsigned int retval;

    if (channels == ALLEGRO_CHANNEL_CONF_1) {
        retval =  TS5_MONO;
    }
    else if (channels == ALLEGRO_CHANNEL_CONF_2) {
        retval =  TS5_STEREO;
    }
    else {
        ts5_fatal("%s: %s\n", "ts5_get_audio_channels",
                    "got an unknown number of channels");
        retval =  0;
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the sample depth for the audio system.
///
/// \param depth The sample depth. Can be TS5_INTEGER or TS5_FLOAT.
///
/// \return 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.
///
/// \todo currently has no effect. 
/// The voice will be integer and the mixer floating point.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_audio_depth(int depth)
{
    if (!_ts5_is_tscope5_installed) {
        ts5_install_tscope5("ts5_set_audio_depth");
    }

    ts5_log(TS5_LOGLEVEL_4, "ts5_set_audio_depth(%d)\n", depth);

    int retval = _ts5_status.audio.depth;

    if (depth!=TS5_INTEGER && depth!=TS5_FLOAT) {
        ts5_fatal("ts5_set_audio_depth: unknown sample depth requested\n");
    }

    _ts5_status.audio.depth = depth;

    ts5_log(TS5_LOGLEVEL_4, "%s: %s %d (was %d)\n",
                "ts5_set_audio_depth", "set sample depth to",
                _ts5_status.audio.depth, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the sample depth of the audio system.
///
/// \return The sample depth of the audio system.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_audio_depth()
{
    ts5_check_audio("ts5_get_audio_depth");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_audio_depth()\n");

    ALLEGRO_AUDIO_DEPTH depth = 
        al_get_voice_depth(_ts5_data.audio.voice);

    if (depth != TS5_INTEGER && depth !=TS5_FLOAT) {
        ts5_fatal("ts5_get_audio_depth: got an unknown sample depth\n");
    }

    return depth;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the gain (amplification factor) of the audio system.
///
/// \param gain The gain. 
/// 0.0 = silent, 0.5=half, 1.0 = untouched, 2.0 = double, ...
///
/// \return The previous setting.
///
/// The default gain is 1.0.
////////////////////////////////////////////////////////////////////////////////
double ts5_set_audio_gain(double gain)
{
    if (!_ts5_is_tscope5_installed) {
        ts5_install_tscope5("ts5_set_audio_gain");
    }

    ts5_log(TS5_LOGLEVEL_4, "ts5_set_audio_gain(%f)\n", gain);

    double retval = _ts5_status.audio.gain;

    if (gain<0.0) {
        ts5_fatal("ts5_set_audio_gain: gain should be >= 0.0\n");
    }

    _ts5_status.audio.gain = gain;

    if (!al_set_mixer_gain(_ts5_data.audio.mixer, gain)) {
        ts5_fatal("ts5_set_audio_gain: could not change audio gain\n");
    }

    ts5_log(TS5_LOGLEVEL_4, "ts5_set_audio_gain: set gain to %f (was %f)\n",
                _ts5_status.audio.gain, retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the gain of the audio system.
///
/// \return The gain of the audio system.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_audio_gain()
{
    ts5_check_audio("ts5_get_audio_gain");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_audio_gain()\n");

    return _ts5_status.audio.gain;
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name 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).
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Create an empty sample.
///
/// \param length Length of the sample in seconds.
///
/// \return 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()
////////////////////////////////////////////////////////////////////////////////
TS5_SAMPLE *ts5_alloc_sample(double length)
{
    ts5_check_audio("ts5_alloc_sample");
    ts5_log(TS5_LOGLEVEL_2, "ts5_alloc_sample(%f)\n", length);

    // create the sample structure
    TS5_SAMPLE *sample = NULL;
    sample = (TS5_SAMPLE *)al_malloc(sizeof(TS5_SAMPLE));

    if (!sample) {
        ts5_fatal("ts5_alloc_sample: could not allocate sample\n");
    }

    sample->issample = 1;
    sample->isbuffer = 1;
    sample->isfilestream = 0;
    sample->ismemorystream = 0;
    sample->stream = NULL;
    
    // get the paramters for the sample
    unsigned int samples = length * _ts5_status.audio.samplerate;
    ALLEGRO_CHANNEL_CONF channels = 0;

    if (_ts5_status.audio.channels==TS5_MONO) {
        channels=ALLEGRO_CHANNEL_CONF_1;
    }
    else if (_ts5_status.audio.channels==TS5_STEREO) {
        channels=ALLEGRO_CHANNEL_CONF_2;
    }
    else {
        ts5_fatal("%s: %s\n", "ts5_alloc_sample",
                    "unknown channel configuration requested");
    }

    unsigned int sample_size = 
        al_get_channel_count(channels) *
        al_get_audio_depth_size(ALLEGRO_AUDIO_DEPTH_INT16);

    unsigned int bytes = samples * sample_size;

    sample->start_time = 0.0;
    
    // create the buffer
    sample->buffer = al_malloc(bytes);
    if (!sample->buffer) {
        ts5_fatal("ts5_alloc_sample: could not allocate sample buffer\n");
    }

    sample->buffer_end = sample->buffer + samples * _ts5_status.audio.channels;
    sample->buffer_recorder_position = sample->buffer;
    sample->buffer_voicekey_position = sample->buffer;

    // create the sample
    sample->sample = al_create_sample(sample->buffer, samples, 
                        _ts5_status.audio.samplerate,
                        ALLEGRO_AUDIO_DEPTH_INT16, channels, 1);

    if (!sample->sample) {
        ts5_fatal("ts5_alloc_sample: could not create sample\n");
    }


    // create the sample instance
    sample->instance = al_create_sample_instance(NULL);

    if (!sample->instance) {
        ts5_fatal("ts5_alloc_sample: could not create sample instance\n");
    }

    if (!al_set_sample(sample->instance, sample->sample)) {
        ts5_fatal("%s: %s\n", "ts5_alloc_sample",
                    "could not attach sample to sample instance");
    }

    if (!al_attach_sample_instance_to_mixer
        (sample->instance, _ts5_data.audio.mixer)) {
            ts5_fatal("%s: %s\n", "ts5_alloc_sample",
                        "could not attach sample instance to mixer");
    }

    al_set_sample_instance_playing(sample->instance, 0);

    // voice key
    int nslices = length * 1000;
    sample->voicekey = (double *)al_malloc(nslices * sizeof(double));
    sample->voicekey_position = sample->voicekey;
    sample->voicekey_end = sample->voicekey + nslices;
    sample->voicekey_num_samples = (int *)al_malloc(nslices * sizeof(int));
    sample->last_state_toggle_time = -1000;
    sample->previous_state = 0;
        
    return sample;
}


////////////////////////////////////////////////////////////////////////////////
/// Open a sample from a file.
///
/// \param file Path to the sample file.
///
/// \return 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.
////////////////////////////////////////////////////////////////////////////////
TS5_SAMPLE *ts5_read_sample(const char *file)
{
    ts5_check_audio("ts5_read_sample");
    ts5_log(TS5_LOGLEVEL_2, "ts5_read_sample(%s)\n", file);

    TS5_SAMPLE *sample = NULL;
    sample = (TS5_SAMPLE *)al_malloc(sizeof(TS5_SAMPLE));

    if (!sample) {
        ts5_fatal("ts5_read_sample: could not allocate sample\n");
    }

    sample->issample = 1;
    sample->isbuffer = 0;
    sample->isfilestream = 0;
    sample->ismemorystream = 0;

    sample->sample = NULL;
    sample->sample = al_load_sample(file);

    if (!sample->sample) {
        ts5_fatal("ts5_read_sample: could not read sample\n");
    }

    sample->instance = NULL;
    sample->instance = al_create_sample_instance(NULL);

    if (!sample->instance) {
        ts5_fatal("ts5_read_sample: could not create sample instance\n");
    }

    if (!al_set_sample(sample->instance, sample->sample)) {
        ts5_fatal("%s: %s\n", "ts5_read_sample",
                    "could not attach sample to sample instance");
    }

    if (!al_attach_sample_instance_to_mixer
        (sample->instance, _ts5_data.audio.mixer)) {
            ts5_fatal("%s: %s\n", "ts5_read_sample",
                        "could not attach sample instance to mixer");
    }

    al_set_sample_instance_playing(sample->instance, 0);

    sample->stream = NULL;

    sample->start_time = 0.0;
        
    sample->buffer = NULL;
    sample->buffer_end = NULL;
    sample->buffer_recorder_position = NULL;
    sample->buffer_voicekey_position = NULL;

    int nslices = 0;
    sample->voicekey = NULL;
    sample->voicekey_position = NULL;
    sample->voicekey_end = NULL;
    sample->voicekey_num_samples = NULL;

    // for 16 bit samples we have access tot the sample buffer
    // so we can run an offline voice key
    if (al_get_sample_depth(sample->sample) == ALLEGRO_AUDIO_DEPTH_INT16) {
    
        sample->isbuffer = 1;
        
        sample->buffer = (int16_t *)al_get_sample_data(sample->sample);
        sample->buffer_end = sample->buffer + 
            al_get_sample_length(sample->sample) * 
            ts5_get_sample_channels(sample);
        
        sample->buffer_recorder_position = sample->buffer_end;
        sample->buffer_voicekey_position = sample->buffer;
        
        nslices = al_get_sample_length(sample->sample) * 1000;
        sample->voicekey = (double *)al_malloc(nslices * sizeof(double));
        sample->voicekey_position = sample->voicekey;
        sample->voicekey_end = sample->voicekey + nslices;
        sample->voicekey_num_samples = (int *)al_malloc(nslices * sizeof(int));
        sample->last_state_toggle_time = -1000;
        sample->previous_state = 0;
    }

    return sample;
}


////////////////////////////////////////////////////////////////////////////////
/// Open a long sample from a file.
///
/// \param file Path to the sample file.
///
/// \return 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.
////////////////////////////////////////////////////////////////////////////////
TS5_SAMPLE *ts5_read_long_sample(const char *file)
{
    ts5_check_audio("ts5_read_long_sample");
    ts5_log(TS5_LOGLEVEL_2, "ts5_read_long_sample(%s)\n", file);

    TS5_SAMPLE *sample = NULL;
    sample = (TS5_SAMPLE *)al_malloc(sizeof(TS5_SAMPLE));

    if (!sample) {
        ts5_fatal("ts5_read_long_sample: could not allocate sample\n");
    }

    sample->issample = 0;
    sample->isbuffer = 0;
    sample->isfilestream = 1;
    sample->ismemorystream = 0;

    sample->sample = NULL;
    sample->instance = NULL;
    sample->stream = NULL;
    sample->stream = al_load_audio_stream(file, 4, 2048);

    if (!sample->stream) {
        ts5_fatal("ts5_read_long_sample: could not read sample\n");
    }

    if (!al_attach_audio_stream_to_mixer
        (sample->stream, _ts5_data.audio.mixer)) {
            ts5_fatal("%s: %s\n", "ts5_read_long_sample",
                        "could not attach sample stream to mixer");
    }

    al_set_audio_stream_playing(sample->stream, 0);
    al_set_audio_stream_playmode(sample->stream, ALLEGRO_PLAYMODE_ONCE);

    // no start time
    sample->start_time = 0.0;

    // no acces to the buffer for file streams
    sample->buffer = NULL;
    sample->buffer_end = NULL;
    sample->buffer_recorder_position = NULL;
    sample->buffer_voicekey_position = NULL;

    // no voice key for file streams
    sample->voicekey = NULL;
    sample->voicekey_position = NULL;
    sample->voicekey_end = NULL;
    sample->voicekey_num_samples = NULL;
    
    return sample;
}


////////////////////////////////////////////////////////////////////////////////
/// Write a sample.
///
/// \param file Path to the sample file.
/// \param sample Pointer to the sample that will be written.
///
/// Only .wav is supported. The file extension should be .wav
////////////////////////////////////////////////////////////////////////////////
void ts5_write_sample(const char *file, TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_write_sample");
    ts5_log(TS5_LOGLEVEL_2, "ts5_write_sample(%s,%p)\n", file, sample);

    if (!sample->issample) {
        ts5_fatal("%s: %s\n", "ts5_write_sample",
                    "writing of streams is not implemented yet\n");
    }

    if (!al_save_sample(file, sample->sample)) {
        ts5_fatal("ts5_write_sample: could not write sample\n");
    }
}


////////////////////////////////////////////////////////////////////////////////
/// Free the memory used by a sample.
///
/// \param 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.
////////////////////////////////////////////////////////////////////////////////
void ts5_free_sample(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_free_sample");
    ts5_log(TS5_LOGLEVEL_2, "ts5_free_sample(%p)\n", sample);

    if (sample->issample) {
        al_set_sample(sample->instance, NULL);
        al_destroy_sample(sample->sample);

        al_detach_sample_instance(sample->instance);
        al_destroy_sample_instance(sample->instance);
        
        al_free(sample->voicekey);
        al_free(sample->voicekey_num_samples);
    }
    else if (sample->isfilestream) {
        al_detach_audio_stream(sample->stream);
        al_destroy_audio_stream(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("ts5_free_sample: memory streams not implemented yet\n");
    }

    al_free(sample);
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name 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.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Start playing a sample.
///
/// \param sample Pointer to the sample that will be played.
////////////////////////////////////////////////////////////////////////////////
void ts5_play_sample(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_play_sample");
    ts5_log(TS5_LOGLEVEL_5, "ts5_play_sample(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_play_sample: sample pointer is null\n");
    }

    if (sample->issample) {

        if (!al_set_sample_instance_playing(sample->instance, 1)) {
            ts5_fatal("ts5_play_sample: could not play sample\n");
        }
    }
    else if (sample->isfilestream) {

        if (!al_set_audio_stream_playing(sample->stream, 1)) {
            ts5_fatal("ts5_play_sample: could not play sample\n");
        }
    }
    else if (sample->ismemorystream) {
        ts5_fatal("ts5_play_sample: memory streams not implemented yet\n");
    }
}


////////////////////////////////////////////////////////////////////////////////
/// Pause playing a sample.
///
/// \param sample Pointer to the sample that will be paused.
////////////////////////////////////////////////////////////////////////////////
void ts5_pause_sample(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_pause_sample");
    ts5_log(TS5_LOGLEVEL_5, "ts5_pause_sample(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_pause_sample: sample pointer is null\n");
    }

    if (sample->issample) {

        if (!al_set_sample_instance_playing(sample->instance, 0)) {
            ts5_fatal("ts5_pause_sample: could not pause sample\n");
        }
    }
    else if (sample->isfilestream) {

        if (!al_set_audio_stream_playing(sample->stream, 0)) {
            ts5_fatal("ts5_pause_sample: could not pause sample\n");
        }
    }
    else if (sample->ismemorystream) {
        ts5_fatal("memory streams not implemented yet\n");
    }
}


////////////////////////////////////////////////////////////////////////////////
/// Stop playing a sample.
///
/// \param sample Pointer to the sample that will be stopped.
////////////////////////////////////////////////////////////////////////////////
void ts5_stop_sample(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_stop_sample");
    ts5_log(TS5_LOGLEVEL_5, "ts5_stop_sample(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_stop_sample: sample pointer is null\n");
    }

    if (sample->issample) {

        if (!al_set_sample_instance_playing(sample->instance, 0)) {
            ts5_fatal("ts5_stop_sample: could not stop sample\n");
        }

        if (!al_set_sample_instance_position(sample->instance, 0)) {
            ts5_fatal("ts5_stop_sample: could not stop sample\n");
        }
    }
    else if (sample->isfilestream) {

        al_drain_audio_stream(sample->stream);

        if (!al_rewind_audio_stream(sample->stream)) {
            ts5_fatal("ts5_stop_sample: could not rewind sample\n");
        }
    }
    else if (sample->ismemorystream) {
        ts5_fatal("ts5_stop_sample: memory streams not implemented yet\n");
    }
}


////////////////////////////////////////////////////////////////////////////////
/// Query whether a sample is playing.
///
/// \param sample Pointer to the sample that will queried.
///
/// \return 1 if the sample is playing, 0 if not.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_sample_status(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_status");
    ts5_log(TS5_LOGLEVEL_5, "ts5_get_sample_status(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_status: sample pointer is null\n");
    }

    int retval = 0;

    if (sample->issample) {
        retval =  al_get_sample_instance_playing(sample->instance);
    }
    else if (sample->isfilestream) {
        retval =  al_get_audio_stream_playing(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("%s: %s\n", "ts5_get_sample_status",
                    "memory streams not implemented yet");
    }
    else {
        ts5_fatal("ts5_get_sample_status: sample type unknown\n");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name 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 <a href="audio02_8c-example.html">audio02.c</a> 
/// for an example that shows how this works.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Get acces to a sample's data.
///
/// \param sample Pointer to the sample that will queried.
///
/// \return a pointer to the sample data.
////////////////////////////////////////////////////////////////////////////////
void *ts5_get_sample_data_pointer(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_data_pointer");
    ts5_log(TS5_LOGLEVEL_5, "ts5_get_sample_data_pointer(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_data_pointer: sample pointer is null\n");
    }

    void *retval;
    retval = NULL;

    if (sample->issample) {
        retval = al_get_sample_data(sample->sample);
    }
    else if (sample->isfilestream) {
        ts5_fatal("ts5_get_sample_data_pointer: file streams not implemented yet\n");
    }
    else if (sample->ismemorystream) {
        ts5_fatal("ts5_get_sample_data_pointer: memory streams not implemented yet\n");
    }
    
    return retval;
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name 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 <a href="audio03_8c-example.html">audio03.c</a> 
/// for an example that shows how this works.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Start the audio recorder.
///
/// This function has to be called explicitly by the user
/// before samples can be recorded.
////////////////////////////////////////////////////////////////////////////////
void ts5_start_audio_recorder() 
{
    ts5_check_audio_recorder("ts5_start_audio_recorder");
    if (!al_start_audio_recorder(_ts5_data.audio.recorder)) {
        ts5_fatal("ts5_start_audio_recorder: could not start audio recorder\n"); 
    }
    _ts5_is_audio_recorder_recording = 1;
}


////////////////////////////////////////////////////////////////////////////////
/// Stop the audio recorder.
///
/// This function has to be called explicitly by the user
/// at the end of the program.
////////////////////////////////////////////////////////////////////////////////
void ts5_stop_audio_recorder() 
{
    ts5_check_audio_recorder("ts5_stop_audio_recorder");
    if (_ts5_is_audio_recorder_recording) {
        al_stop_audio_recorder(_ts5_data.audio.recorder);
        ts5_flush_audio_recorder();
        _ts5_is_audio_recorder_recording = 0;
    }
}


////////////////////////////////////////////////////////////////////////////////
/// Flush the audio recorder buffer.
////////////////////////////////////////////////////////////////////////////////
void ts5_flush_audio_recorder()
{
    ts5_check_audio_recorder("ts5_flush_audio_recorder");
    al_flush_event_queue(_ts5_data.audio.recorder_queue);
}


////////////////////////////////////////////////////////////////////////////////
/// Start recording a sample.
///
/// \param sample Pointer to the sample that will be recorded.
////////////////////////////////////////////////////////////////////////////////
void ts5_record_sample(TS5_SAMPLE *sample)
{
    ts5_check_audio_recorder2("ts5_record_sample");
    ts5_check_audio_recorder3("ts5_record_sample", sample);
    
    // get some parameters
    sample->start_time = al_get_time();
    int channels = ts5_get_audio_channels();
    int depth = al_get_audio_depth_size(ALLEGRO_AUDIO_DEPTH_INT16);
    double samplerate = ts5_get_audio_samplerate();
    
    // remove buffered audio fragments
    ts5_flush_audio_recorder();
    
    // set buffer pointer of the sample to the beginning
    sample->buffer_recorder_position = sample->buffer;
    
    // wait for the first recorder fragment
    ALLEGRO_EVENT event;
    do {
        al_wait_for_event(_ts5_data.audio.recorder_queue, &event);
    } while(event.type != ALLEGRO_EVENT_AUDIO_RECORDER_FRAGMENT);
    ALLEGRO_AUDIO_RECORDER_EVENT *recorder_event = 
        al_get_audio_recorder_event(&event);
        
    // compute fragment onset and n of samples to skip
    double fragment_onset = event.any.timestamp - recorder_event->samples / samplerate;
    int64_t samples_to_skip = (sample->start_time - fragment_onset) * samplerate;

    if (samples_to_skip < 0) {
        samples_to_skip = 0;
    }

    // compute n of samples to copy
    int64_t samples_to_copy = channels * (recorder_event->samples - samples_to_skip);

    if (samples_to_copy > sample->buffer_end - sample->buffer_recorder_position) {
        samples_to_copy = sample->buffer_end - sample->buffer_recorder_position;
    }
    
    if (samples_to_copy < 0) {
        samples_to_copy = 0;
    }
    
    // copy to the sample buffer
    memcpy(sample->buffer_recorder_position, recorder_event->buffer + samples_to_skip * channels, 
            (uint64_t)samples_to_copy * depth); 

    // update buffer counter
    sample->buffer_recorder_position += samples_to_copy;
}


////////////////////////////////////////////////////////////////////////////////
/// Update the sample buffer when recording.
///
/// \param sample Pointer to the sample that will be recorded.
///
/// \return 1 if the sample is full, 0 if not.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_sample_fragments(TS5_SAMPLE *sample)
{
    ts5_check_audio_recorder2("ts5_get_sample_fragments");
    ts5_check_audio_recorder3("ts5_get_sample_fragments", sample);
    
    if (sample->buffer_recorder_position == sample->buffer) {
        ts5_fatal("ts5_get_sample_fragments: audio recording not started yet\n");
    }
    
    int channels = ts5_get_audio_channels();
    int depth = al_get_audio_depth_size(ALLEGRO_AUDIO_DEPTH_INT16);
        
    // update until all events are processed or until the sample is full
    int full = 0;
    ALLEGRO_EVENT event;
    while (!full && al_get_next_event(_ts5_data.audio.recorder_queue, &event)) {
        
        if (event.type==ALLEGRO_EVENT_AUDIO_RECORDER_FRAGMENT) {
            
            ALLEGRO_AUDIO_RECORDER_EVENT *recorder_event = 
                al_get_audio_recorder_event(&event);
        
            // compute n of samples to copy
            int64_t samples_to_copy = channels * recorder_event->samples;
            if (samples_to_copy > sample->buffer_end - sample->buffer_recorder_position) {
                samples_to_copy = sample->buffer_end - sample->buffer_recorder_position;
                full = 1;
            }
            
            // write to the buffer
            memcpy(sample->buffer_recorder_position, recorder_event->buffer, 
                    (uint64_t)samples_to_copy * depth); 

            // update buffer counter
            sample->buffer_recorder_position += samples_to_copy;
            
        }       
    }
    return full;    
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// @name 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 <a href="audio04_8c-example.html">audio04.c</a> 
/// for an example that shows how the software voice key works.
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Define the software voice key as a response button.
///
/// \param button Number of the button (buttons are counted from 1).
///
/// \return 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.
////////////////////////////////////////////////////////////////////////////////
int ts5_define_voicekey_button(int button)
{
    ts5_check_voicekey("ts5_define_voicekey_button");
    ts5_log(TS5_LOGLEVEL_3, "ts5_define_voicekey_button(%d)\n", button);
    
    if (abs(button)>_ts5_status.timer.voicekey.num_buttons) {
        ts5_fatal("%s: %s %d, %s %d is %d\n", "ts5_define_voicekey_button",
                    "button argument is", button, 
                    "number of voicekey buttons", 
                    _ts5_status.timer.voicekey.num_buttons);
    }
    
    if (button>0 && _ts5_status.timer.voicekey
                    .button_press_defined[button-1]!=0) {
        ts5_fatal("%s: %s %d %s\n", "ts5_define_voicekey_button",
                    "button press", button, "is already defined");
    }

    if (button<0 && _ts5_status.timer.voicekey
                    .button_release_defined[-button-1]!=0) {
        ts5_fatal("%s: %s %d %s\n", "ts5_define_voicekey_button",
                    "button release", button, "is already defined");
    }

    _ts5_status.timer.voicekey_is_response_device = 1;
    _ts5_status.timer.num_defined_buttons++;
    _ts5_status.timer.num_active_buttons++;
    _ts5_status.timer.voicekey.num_defined_buttons++;
    _ts5_status.timer.voicekey.num_active_buttons++;

    if (button>0) {
        _ts5_status.timer.voicekey
            .button_press_defined[button-1] =
            _ts5_status.timer.num_defined_buttons;

        _ts5_status.timer.voicekey
            .button_press_active[button-1] =
            _ts5_status.timer.num_defined_buttons;
    }
    else {
        _ts5_status.timer.voicekey
            .button_release_defined[-button-1] =
            _ts5_status.timer.num_defined_buttons;

        _ts5_status.timer.voicekey
            .button_release_active[-button-1] =
            _ts5_status.timer.num_defined_buttons;
    }

    return _ts5_status.timer.num_defined_buttons;
}


////////////////////////////////////////////////////////////////////////////////
/// Detect voice onsets in a sample.
///
/// \param sample   Pointer to the sample that will be processed.
////////////////////////////////////////////////////////////////////////////////
void ts5_detect_voice_onsets(TS5_SAMPLE *sample)
{
    ts5_check_audio_recorder2("ts5_detect_voice_onsets");
    ts5_check_audio_recorder3("ts5_detect_voice_onsets", sample);
    ts5_check_voicekey("ts5_detect_voice_onsets");
    ts5_log(TS5_LOGLEVEL_4, "ts5_detect_voice_onsets(%p)\n", sample);
    
    int channels = ts5_get_sample_channels(sample);
    int samplerate = al_get_sample_frequency(sample->sample);
    
    int64_t sample_idx;
    int64_t start_sample = 
        sample->buffer_voicekey_position - sample->buffer;

    int64_t stop_sample = 
        sample->buffer_recorder_position - sample->buffer;

    int64_t slice_idx;
    int64_t start_slice = start_sample * 1000 / samplerate / channels;
    int64_t stop_slice = stop_sample * 1000 / samplerate / channels;
    
    // voicekey step 1: compute sum of squares per slice
    for(sample_idx = start_sample; sample_idx < stop_sample; sample_idx++) {

        slice_idx = sample_idx * 1000 / samplerate / channels;
        sample->voicekey_num_samples[slice_idx]++;
        sample->voicekey[slice_idx] += 
            (sample->buffer[sample_idx] * sample->buffer[sample_idx]);
    }
    
    // voicekey step 2: take root mean square per slice
    int max = 32767; // maximum value of 16-bit integers
    for(slice_idx = start_slice; slice_idx < stop_slice; slice_idx++) {
        sample->voicekey[slice_idx] = 
            sqrt(sample->voicekey[slice_idx]/sample->voicekey_num_samples[slice_idx]) / max;
    }
    
    // voicekey step 3: treshold
    for(slice_idx = start_slice; slice_idx < stop_slice; slice_idx++) {
        
        if(sample->voicekey[slice_idx] > _ts5_status.timer.voicekey.treshold) {
            sample->voicekey[slice_idx] = 1.0;          
        } 
        else {
            sample->voicekey[slice_idx] = 0.0;                      
        }
    }
    
    // step 4: detect state changes
    int current_state;
    
    for(slice_idx = start_slice; slice_idx < stop_slice; slice_idx++) {
    
        if(sample->voicekey[slice_idx] > _ts5_status.timer.voicekey.treshold) {
            current_state = 1;          
        } 
        else {
            current_state = 0;                      
        }

        if(current_state != sample->previous_state) {
            
            int64_t diff = slice_idx - sample->last_state_toggle_time;
            int rise = current_state && diff > _ts5_status.timer.voicekey.rise_delay * 1000;
            int drop  = (!current_state) && diff > _ts5_status.timer.voicekey.drop_delay * 1000;
                                
            if(rise || drop) {
                
                ALLEGRO_EVENT voicekey_event;
                if (rise) {
                    voicekey_event.user.type = TS5_EVENT_VOICEKEY_BUTTON_DOWN;
                }

                if (drop) {
                    voicekey_event.user.type = TS5_EVENT_VOICEKEY_BUTTON_UP;    
                }

                voicekey_event.user.data1 = 1;
                voicekey_event.user.data2 = 1;
                
                // make our own timestamp: time where onset/offset is detected
                // allegro timestamp: time where event is emitted
                voicekey_event.user.data3 =  
                    (intptr_t)(slice_idx*1000 + sample->start_time*1000000.0);
                
                sample->previous_state = current_state; 
                sample->last_state_toggle_time = slice_idx;
                
                al_emit_user_event(
                    &_ts5_data.timer.voicekey_response_event_source,
                    &voicekey_event, NULL);
            }
        }   
    }
}


////////////////////////////////////////////////////////////////////////////////
/// Set the voice key treshold.
///
/// \param treshold Treshold as a value beteen 0.0 (silence) and 1.0 (max).
/// \return The previous setting.
///
/// The default treshold is set to 0.5.
////////////////////////////////////////////////////////////////////////////////
double ts5_set_voicekey_treshold(double treshold)
{
    ts5_check_voicekey("ts5_set_voicekey_treshold");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_voicekey_treshold(%f)\n", treshold);

    if (treshold < 0.0) {
        ts5_fatal("%s: %s (is %f)\n", "ts5_set_voicekey_treshold",
            "treshold should be positive", treshold);
    }

    if (treshold > 1.0) {
        ts5_fatal("%s: %s (is %f)\n", "ts5_set_voicekey_treshold",
            "treshold should be smaller than 1.0", treshold);
    }

    double retval = 
        _ts5_status.timer.voicekey.treshold;

    _ts5_status.timer.voicekey.treshold = treshold;
    
    ts5_log(TS5_LOGLEVEL_4, "%s: %s to %f (was %f)\n", 
                "ts5_set_voicekey_treshold",
                "set voice key treshold", 
                _ts5_status.timer.voicekey.treshold, 
                retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the voice key treshold.
///
/// \return The voice key treshold.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_voicekey_treshold()
{
    ts5_check_voicekey("ts5_get_voicekey_treshold");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_voicekey_treshold\n");

    return _ts5_status.timer.voicekey.treshold;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the voice key rise delay.
///
/// \param rise_delay Rise delay in seconds.
/// \return The previous setting.
///
/// The default rise delay is set to 0.2 seconds.
////////////////////////////////////////////////////////////////////////////////
double ts5_set_voicekey_rise_delay(double rise_delay)
{
    ts5_check_voicekey("ts5_set_voicekey_rise_delay");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_voicekey_rise_delay(%f)\n", rise_delay);

    if (rise_delay < 0.0) {
        ts5_fatal("%s: %s (is %f)\n", "ts5_set_voicekey_rise_delay",
            "rise_delay should be positive", rise_delay);
    }

    double retval = _ts5_status.timer.voicekey.rise_delay;

    _ts5_status.timer.voicekey.rise_delay = rise_delay;
    
    ts5_log(TS5_LOGLEVEL_4, "%s: %s to %f (was %f)\n", 
                "ts5_set_voicekey_rise_delay",
                "set voice key rise_delay", 
                _ts5_status.timer.voicekey.rise_delay, 
                retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the voice key rise delay.
///
/// \return The voice key rise delay.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_voicekey_rise_delay()
{
    ts5_check_voicekey("ts5_get_voicekey_rise_delay");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_voicekey_rise_delay\n");

    return _ts5_status.timer.voicekey.rise_delay;
}



////////////////////////////////////////////////////////////////////////////////
/// Set the voice key drop delay.
///
/// \param drop_delay Rise delay in seconds.
/// \return The previous setting.
///
/// The default drop delay is set to 0.2 seconds.
////////////////////////////////////////////////////////////////////////////////
double ts5_set_voicekey_drop_delay(double drop_delay)
{
    ts5_check_voicekey("ts5_set_voicekey_drop_delay");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_voicekey_drop_delay(%f)\n", drop_delay);

    if (drop_delay < 0.0) {
        ts5_fatal("%s: %s (is %f)\n", "ts5_set_voicekey_drop_delay",
            "drop_delay should be positive", drop_delay);
    }

    double retval = _ts5_status.timer.voicekey.drop_delay;

    _ts5_status.timer.voicekey.drop_delay = drop_delay;
    
    ts5_log(TS5_LOGLEVEL_4, "%s: %s to %f (was %f)\n", 
                "ts5_set_voicekey_drop_delay",
                "set voice key drop_delay", 
                _ts5_status.timer.voicekey.drop_delay, 
                retval);

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the voice key drop delay.
///
/// \return The voice key drop delay.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_voicekey_drop_delay()
{
    ts5_check_voicekey("ts5_get_voicekey_drop_delay");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_voicekey_drop_delay\n");

    return _ts5_status.timer.voicekey.drop_delay;
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////



////////////////////////////////////////////////////////////////////////////////
/// @name 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.  
///
//@{
////////////////////////////////////////////////////////////////////////////////


////////////////////////////////////////////////////////////////////////////////
/// Get the sample rate of a sample.
///
/// \param sample Pointer to the sample that will queried.
///
/// \return The sample rate of the sample.
////////////////////////////////////////////////////////////////////////////////
unsigned int ts5_get_sample_samplerate(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_samplerate");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_sample_samplerate(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_samplerate: sample pointer is null\n");
    }

    unsigned int retval = 0;

    if (sample->issample) {
        retval =  al_get_sample_frequency(sample->sample);
    }
    else if (sample->isfilestream) {
        retval =  al_get_audio_stream_frequency(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("%s: %s\n", "ts5_get_sample_samplerate",
                    "memory streams not implemented yet");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the number of channels of a sample.
///
/// \param sample Pointer to the sample that will queried.
///
/// \return The number of channels of the sample.
////////////////////////////////////////////////////////////////////////////////
unsigned int ts5_get_sample_channels(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_channels");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_sample_channels(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_channels: sample pointer is null\n");
    }

    ALLEGRO_CHANNEL_CONF channels = 0;

    if (sample->issample) {
        channels = al_get_sample_channels(sample->sample);
    }
    else if (sample->isfilestream) {
        channels = al_get_audio_stream_channels(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("%s: %s\n", "ts5_get_sample_channels",
                    "memory streams not implemented yet");
    }

    unsigned int retval = 0;

    if (channels == ALLEGRO_CHANNEL_CONF_1) {
        retval =  TS5_MONO;
    }
    else if (channels == ALLEGRO_CHANNEL_CONF_2) {
        retval =  TS5_STEREO;
    }
    else {
        ts5_fatal("%s: %s\n", "ts5_get_sample_channels",
                    "got an unknown number of channels");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the sample depth of a sample.
///
/// \param sample Pointer to the sample that will queried.
///
/// \return The sample depth of a sample.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_sample_depth(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_depth");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_sample_depth(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_depth: sample pointer is null\n");
    }

    ALLEGRO_AUDIO_DEPTH depth = 0;

    if (sample->issample) {
        depth = al_get_sample_depth(sample->sample);
    }
    else if (sample->isfilestream) {
        depth = al_get_audio_stream_depth(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("ts5_get_sample_depth: memory streams not implemented yet\n");
    }

    int retval = 0;

    if (depth == ALLEGRO_AUDIO_DEPTH_INT16) {
        retval =  TS5_INTEGER;
    }
    else if (depth == ALLEGRO_AUDIO_DEPTH_FLOAT32) {
        retval =  TS5_FLOAT;
    }
    else {
        ts5_fatal("ts5_get_audio_depth: got an unknown sample depth\n");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the length of a sample.
///
/// \param sample Pointer to the sample that will queried.
///
/// \return The length of the sample.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_sample_length(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_length");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_sample_length(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_length: sample pointer is null\n");
    }

    double retval = 0.0;

    if (sample->issample) {
        double freq = al_get_sample_frequency(sample->sample);
        retval = (double)al_get_sample_length(sample->sample) / freq;                   
    }
    else if (sample->isfilestream) {
        retval =  al_get_audio_stream_length_secs(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("%s: %s\n", "ts5_get_sample_length",
                    "memory streams not implemented yet");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the playback position of a sample.
///
/// \param sample Pointer to the sample that will be adjusted.
/// \param position The new playback position.
///
/// \return The old playback position.
////////////////////////////////////////////////////////////////////////////////
double ts5_set_sample_position(TS5_SAMPLE *sample, double position)
{
    ts5_check_audio("ts5_set_sample_position");
    
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_sample_position(%p,%u)\n", 
                sample, position);

    if (!sample) {
        ts5_fatal("ts5_set_sample_position: sample pointer is null\n");
    }

    double retval = 0.0;

    if (sample->issample) {

        double freq = al_get_sample_frequency(sample->sample);
        double max = al_get_sample_length(sample->sample) / freq;

        if (position > max) {
            ts5_fatal("ts5_set_sample_position: position should be",
                        " <= the length of the sample (%f)\n", max);
        }

        retval = al_get_sample_instance_position(sample->instance) / freq;
        
        if (!(al_set_sample_instance_position(sample->instance, position*freq))) {
            ts5_fatal("%s: %s\n", "ts5_set_sample_position",
                        "could not change sample position");
        }
    }
    else if (sample->isfilestream) {

        unsigned int max = al_get_audio_stream_length_secs(sample->stream);

        if (position > max) {
            ts5_fatal("ts5_set_sample_position: position should be",
                        " <= the length of the sample (%f)\n", max);
        }

        retval =  al_get_audio_stream_position_secs(sample->stream);

        if (!(al_seek_audio_stream_secs(sample->stream, position))) {
            ts5_fatal("%s: %s\n", "ts5_set_sample_position",
                        "could not change sample position");
        }
    }
    else if (sample->ismemorystream) {
        ts5_fatal("%s: %s\n", "ts5_set_sample_position",
                    "memory streams not implemented yet");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the playback position of a sample.
///
/// \param sample Pointer to the sample that will be queried.
///
/// \return The current playback position.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_sample_position(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_position");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_sample_position(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_length: sample pointer is null\n");
    }

    double retval = 0.0;
    
    if (sample->issample) {
        double freq = al_get_sample_frequency(sample->sample);
        retval = al_get_sample_instance_position(sample->instance) / freq;
    }
    else if (sample->isfilestream) {
        retval =  al_get_audio_stream_position_secs(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("%s: %s\n", "ts5_get_sample_position",
                    "memory streams not implemented yet");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the playback speed of a sample.
///
/// \param sample Pointer to the sample that will be adjusted.
/// \param speed The new playback speed (1.0 is normal speed).
///
/// \return The old playback speed.
////////////////////////////////////////////////////////////////////////////////
double ts5_set_sample_speed(TS5_SAMPLE *sample, double speed)
{
    ts5_check_audio("ts5_set_sample_speed");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_sample_speed(%p,%f)\n", sample, speed);

    if (!sample) {
        ts5_fatal("ts5_set_sample_speed: sample pointer is null\n");
    }

    if (speed < 0) {
        ts5_fatal("ts5_set_sample_speed: speed should be >0 (is %f)\n", speed);
    }

    double retval =  0.0;

    if (sample->issample) {

        retval =  al_get_sample_instance_speed(sample->instance);

        if (!(al_set_sample_instance_speed(sample->instance, speed))) {
            ts5_fatal("%s: %s (%f)\n", "ts5_set_sample_speed",
                        "could not change sample speed", speed);
        }
    }
    else if (sample->isfilestream) {

        retval =  al_get_audio_stream_speed(sample->stream);

        if (!(al_set_audio_stream_speed(sample->stream, speed))) {
            ts5_fatal("%s: %s (%f)\n", "ts5_set_sample_speed",
                        "could not change sample speed", speed);
        }
    }
    else if (sample->ismemorystream) {
        ts5_fatal("%s: %s\n", "ts5_set_sample_speed",
                    "memory streams not implemented yet");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the playback speed of a sample.
///
/// \param sample Pointer to the sample that will be queried.
///
/// \return The current playback speed.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_sample_speed(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_speed");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_sample_speed(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_speed: sample pointer is null\n");
    }

    double retval =  0.0;

    if (sample->issample) {
        retval =  al_get_sample_instance_speed(sample->instance);
    }
    else if (sample->isfilestream) {
        retval =  al_get_audio_stream_speed(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("ts5_get_sample_speed: memory streams not implemented yet\n");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the playback gain of a sample.
///
/// \param sample Pointer to the sample that will be adjusted.
/// \param gain The new playback gain (1.0 is normal gain).
///
/// \return The old gain setting.
////////////////////////////////////////////////////////////////////////////////
double ts5_set_sample_gain(TS5_SAMPLE *sample, double gain)
{
    ts5_check_audio("ts5_set_sample_gain");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_sample_gain(%p,%f)\n", sample, gain);

    if (!sample) {
        ts5_fatal("ts5_set_sample_gain: sample pointer is null\n");
    }

    if (gain < 0) {
        ts5_fatal("ts5_set_sample_gain: gain should be >0 (is %f)\n", gain);
    }

    double retval =  0.0;

    if (sample->issample) {

        retval =  al_get_sample_instance_gain(sample->instance);

        if (!(al_set_sample_instance_gain(sample->instance, gain))) {
            ts5_fatal("%s: %s (%f)\n", "ts5_set_sample_gain",
                        "could not change sample gain", gain);
        }
    }
    else if (sample->isfilestream) {

        retval =  al_get_audio_stream_gain(sample->stream);

        if (!(al_set_audio_stream_gain(sample->stream, gain))) {
            ts5_fatal("%s: %s (%f)\n", "ts5_set_sample_gain",
                        "could not change sample gain", gain);
        }
    }
    else if (sample->ismemorystream) {
        ts5_fatal("ts5_set_sample_gain: memory streams not implemented yet\n");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the playback gain of a sample.
///
/// \param sample Pointer to the sample that will be queried.
///
/// \return The current playback gain.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_sample_gain(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_gain");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_sample_gain(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_gain: sample pointer is null\n");
    }

    double retval =  0.0;

    if (sample->issample) {
        retval =  al_get_sample_instance_gain(sample->instance);
    }
    else if (sample->isfilestream) {
        retval =  al_get_audio_stream_gain(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("ts5_get_sample_gain: memory streams not implemented yet\n");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the playback pan of a sample.
///
/// \param sample Pointer to the sample that will be adjusted.
/// \param pan The new playback pan 
/// (-1.0 is left, 0.0 is normal, 1.0 is right).
///
/// \return The old playback pan.
////////////////////////////////////////////////////////////////////////////////
double ts5_set_sample_pan(TS5_SAMPLE *sample, double pan)
{
    ts5_check_audio("ts5_set_sample_pan");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_sample_pan(%p,%f)\n", sample, pan);

    if (!sample) {
        ts5_fatal("ts5_set_sample_pan: sample pointer is null\n");
    }

    if (pan < -1.0 || pan > 1) {
        ts5_fatal("%s: %s (is %f)\n", "ts5_set_sample_pan",
                    "pan should be between -1.0 and 1.0", pan);
    }

    double retval =  0.0;

    if (sample->issample) {

        retval =  al_get_sample_instance_pan(sample->instance);

        if (!(al_set_sample_instance_pan(sample->instance, pan))) {
            ts5_fatal("%s: %s (%f)\n", "ts5_set_sample_pan",
                        "could not change sample pan", pan);
        }
    }
    else if (sample->isfilestream) {

        retval =  al_get_audio_stream_pan(sample->stream);

        if (!(al_set_audio_stream_pan(sample->stream, pan))) {
            ts5_fatal("%s: %s (%f)\n", "ts5_set_sample_pan",
                        "could not change sample pan", pan);
        }
    }
    else if (sample->ismemorystream) {
        ts5_fatal("ts5_set_sample_pan: memory streams not implemented yet\n");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the playback pan of a sample.
///
/// \param sample Pointer to the sample that will be queried.
///
/// \return The current playback pan.
////////////////////////////////////////////////////////////////////////////////
double ts5_get_sample_pan(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_pan");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_sample_pan(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_pan: sample pointer is null\n");
    }

    double retval =  0.0;

    if (sample->issample) {
        retval =  al_get_sample_instance_pan(sample->instance);
    }
    else if (sample->isfilestream) {
        retval =  al_get_audio_stream_pan(sample->stream);
    }
    else if (sample->ismemorystream) {
        ts5_fatal("memory streams not implemented yet\n");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Set the playmode of a sample.
///
/// \param sample Pointer to the sample that will be adjusted.
/// \param playmode The new playmode. Can be TS5_PLAY_ONCE or TS5_PLAY_LOOP.
///
/// \return The old playmode.
////////////////////////////////////////////////////////////////////////////////
int ts5_set_sample_playmode(TS5_SAMPLE *sample, int playmode)
{
    ts5_check_audio("ts5_set_sample_playmode");
    ts5_log(TS5_LOGLEVEL_4, "ts5_set_sample_playmode(%p,%d)\n", 
                sample, playmode);

    if (!sample) {
        ts5_fatal("ts5_set_sample_playmode: sample pointer is null\n");
    }

    if (playmode != TS5_PLAY_ONCE && playmode != TS5_PLAY_LOOP) {
        ts5_fatal("%s: %s\n", "ts5_set_sample_playmode",
                    "playmode should be TS5_PLAY_ONCE or TS5_PLAY_LOOP");
    }

    int retval = 0;

    if (sample->issample) {

        retval =  al_get_sample_instance_playmode(sample->instance);

        if (!(al_set_sample_instance_playmode(sample->instance, playmode))) {
            ts5_fatal("%s: %s\n", "ts5_set_sample_playmode",
                        "could not change sample playmode");
        }
    }
    else if (sample->isfilestream) {

        retval =  al_get_audio_stream_playmode(sample->stream) - 3;

        if (!(al_set_audio_stream_playmode(sample->stream, playmode))) {
            ts5_fatal("%s: %s\n", "ts5_set_sample_playmode",
                        "could not change sample playmode");
        }
    }
    else if (sample->ismemorystream) {
        ts5_fatal("%s: %s\n", "ts5_set_sample_playmode",
                    "memory streams not implemented yet");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
/// Get the playmode of a sample.
///
/// \param sample Pointer to the sample that will be queried.
///
/// \return The current playmode.
////////////////////////////////////////////////////////////////////////////////
int ts5_get_sample_playmode(TS5_SAMPLE *sample)
{
    ts5_check_audio("ts5_get_sample_playmode");
    ts5_log(TS5_LOGLEVEL_4, "ts5_get_sample_playmode(%p)\n", sample);

    if (!sample) {
        ts5_fatal("ts5_get_sample_playmode: sample pointer is null\n");
    }

    int retval = 0;

    if (sample->issample) {
        retval =  al_get_sample_instance_playmode(sample->instance);
    }
    else if (sample->isfilestream) {
        retval =  al_get_audio_stream_playmode(sample->stream) - 3;
    }
    else if (sample->ismemorystream) {
        ts5_fatal("%s: %s\n", "ts5_get_sample_playmode",
                    "memory streams not implemented yet");
    }

    return retval;
}


////////////////////////////////////////////////////////////////////////////////
//@}
////////////////////////////////////////////////////////////////////////////////