audio_capture_read :: Quanser C Functions

navigation bar

audio_capture_read

Reads audio samples from the audio capture session.

Description

The audio_capture_read function reads audio samples from the audio capture session. A "sample" consists of the data for all channels at one time instant. For example, for AUDIO_FORMAT_PCM (16-bits) where two channels are used, a sample consists of 2 * sizeof(t_int16) = 4 bytes. It is more efficient to read as many samples as possible at one time, such as a full audio buffer. This function returns immediately. If the requested samples are not available then it returns 0 to indicate it timed out. If any are available then the buffers are filled with the samples and the number of samples stored is returned.

An array of buffers is provided to the function, where the length of the array is the number of channels. Each buffer in the array should be large enough to contain max_samples values in the audio format specified in the audio_capture_open call.

Prototype

t_int
audio_capture_read(t_audio_capture capture, t_uint max_samples, t_audio_samples* buffers);

Parameters

t_audio_capture capture

A handle to the audio capture session, as returned by audio_capture_open

t_uint max_samples

The size of each buffer in number of samples.

t_audio_samples * buffers

An array of buffers in which the audio samples will be stored. The length of the array must be equal to the number of audio channels specified in the audio_capture_open call. Each buffer in the array must contain at least max_samples elements.

For example, for a two channel microphone using the AUDIO_FORMAT_FLOAT format, where max_samples is 4410, the buffers argument to the audio_capture_read function would be an array such as the following:

                
                t_single left_channel[4410];
                t_single right_channel[4410];
                t_audio_samples buffers[2] = { left_channel, right_channel };

Return value

The return value is equal to the number of samples actually read. If zero is returned then the operation timed out before any samples were read. Otherwise a negative error code is returned. Error codes are defined in quanser_errors.h A suitable error message may be retrieved using msg_get_error_message.

Error codes

QERR_INVALID_ARGUMENT

One of the arguments to the function is invalid.

QERR_OUT_OF_RANGE

The maximum number of samples specified is larger than the audio buffer size specified in the audio_capture_open call.

Requirements

Include Files	Libraries
quanser_audio.h	quanser_media.lib;quanser_runtime.lib;quanser_common.lib

Examples


/*
* Read 4800 samples from an audio capture session configured for a sample rate of 48000 Hz and two channels.
*/

t_single left_channel[4800];
t_single right_channel[4800];
t_audio_sample buffers[2] = { left_channel, right_channel };
t_error result = audio_capture_read(capture, 4800, buffers);

navigation bar