audio_capture_open :: Quanser C Functions

navigation bar

audio_capture_open

Opens an audio capture device, such as a microphone, or an audio file or URL.

Description

The audio_capture_open function opens an audio capture device, such as a microphone. It can also read audio samples from a file, such as an MP3 file. The handle to the capture session returned by this function is used by the other functions in the Multimedia API to refer to the session. This handle must be closed using the audio_capture_close function when the session is no longer in use.

Prototype

t_error
audio_capture_open(const char * url, t_double sample_rate, t_uint num_channels, t_audio_format format, t_uint buffer_size, t_audio_capture_mode mode, t_audio_capture * capture);

Parameters

const char * url

A string identifying the audio capture device to be opened, as a URL. For a microphone device, the URL takes the form:

audio://localhost:<port>

where <port> is the number of the capture device. For instance, to open first microphone enumerated on the system, the URL would be:

audio://localhost:0

To read audio samples from a file, such as an MP3 file, use a URL of the form:

"file:<path>" or "file:///<path>" or simply "<path>"

where <path> is the path to the audio file. Use forward slashes to separate folders.

To read audio from a web site, use the URL of the audio stream from the website. Note that this option is not available on all platforms.

t_double sample_rate

A real number specifying the sample rate at which audio input will be captured in Hertz. A value such as 44100 Hz or 48000 Hz is typical.

t_uint num_channels

The number of audio channels to capture. For example, a stereo microphone would have two channels. Typical values are 1 or 2.

t_audio_format format

The format in which to provide audio data. Valid audio formats are listed in the table below. The recommended format is AUDIO_FORMAT_FLOAT.

Format	Description
AUDIO_FORMAT_PCM	Audio data is encoded as signed 16-bit values (`t_int16`), where each value is the quantized amplitude of the time-domain signal collected at the specified sample rate.
AUDIO_FORMAT_FLOAT	Audio data is encoded as signed single-precision floating-point values (`t_single`), where each value is the quantized amplitude of the time-domain signal collected at the specified sample rate.

t_uint buffer_size

The size of the audio buffer in samples (where one sample includes all channels). A buffer large enough for at least 0.1 seconds of audio is recommended i.e. sample_rate * 0.1.

t_audio_capture_mode mode

The mode to use when the url parameter is a seekable file or URL. The different modes are enumerated in the table below:

Capture Mode	Description
AUDIO_CAPTURE_MODE_ONCE_AT_OPEN	Read audio samples from the URL to the end of stream once as soon as audio capture session is opened. Once the end of the stream is reached, no more audio data is captured.
AUDIO_CAPTURE_MODE_REPEAT_AT_OPEN	Read audio samples from the URL to the end of stream as soon as audio capture session is opened. Once the end of the stream is reached, the stream is rewound and samples are provided from the beginning again. The audio stream is replayed continually.
AUDIO_CAPTURE_MODE_ON_TRIGGER	Read audio samples from the URL to the end of stream each time a trigger occurs. A trigger occurs whenever the audio_capture_trigger function is called.

t_audio_capture * capture

The address of a t_audio_capture variable in which the handle to the capture session will be stored. This handle is then passed to the other audio capture functions to identify the capture session.

Return value

The return value is 0 if the audio capture session is opened successfully. 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 is invalid.

QERR_OUT_OF_MEMORY

There is not enough memory to complete the operation.

Requirements

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

Examples

t_audio_capture capture;
t_error result = audio_capture_open("audio://localhost:0", 44100, NUM_CHANNELS, AUDIO_FORMAT_FLOAT, 4410, AUDIO_CAPTURE_MODE_ONCE_AT_OPEN, &capture);
if (result >= 0) {
    ...
    audio_capture_close(capture);
} else {
    TCHAR message[512];
    msg_get_error_message(NULL, result, message, sizeof(message));
    _tprintf(_T("Failed to open audio capture session. %s (error %d)\n"), message, -result);
}