omni::audio::experimental::CaptureDataCallback

Defined in omni/audio/experimental/IAudioCapture.h

using omni::audio::experimental::CaptureDataCallback = void (*)(ICaptureStream *stream, const void *buffer, size_t frames, void *context)

A callback that’s used to receive audio data from an audio capture stream.

Note

If the stream was not created with fCaptureStreamFlagLowLatency, data returned from this function is considered locked. For data to become unlocked, the caller needs to call ICaptureStream::unlock() with the number of frames that have been locked by this call. If the data is not unlocked, that portion of the buffer cannot be overwritten. It is not required to release the buffer before the callback ends, but the data needs to be unlocked eventually otherwise you will stop receiving data and an overrun may occur.

Note

This callback executes from its own thread, so thread safety will need to be considered. This is called on the same thread as CaptureInfoCallback, so these two calls can access the same data without concurrency issues.

Note

This callback must return as fast as possible, since this is called directly from the audio capture thread (e.g. under 1ms). A callback that takes too long could cause capture overruns. Doing anything that could involve substantial waits (e.g. calling into python) should be avoided; in those cases you should copy the buffer somewhere else or use a omni::extras::DataStreamer for a series of asynchronous data packets.

Note

It is safe to call any ICaptureStream function from within this callback, but it is not safe to destroy the ICaptureStream object from within it.

Param stream

[inout] The stream that this callback was fired from.

Param buffer

[in] The audio data that’s been captured. The data in the buffer will be in the format specified by ICaptureStream::getSoundFormat(). If the stream was created with fCaptureStreamFlagLowLatency, this buffer will not be valid once the callback returns; otherwise, the buffer will be invalidated once ICaptureStream::unlock() is called for this portion of the buffer. See the note on unlocking the buffer for more detail on this.

Param frames

[in] The length of audio in buffer, in frames. If the stream was created with fCaptureStreamFlagLowLatency, the frame count passed to each callback may differ; otherwise, the frame count will be exactly one fragment long. If you need to convert to bytes, you can use carb::audio::convertUnits() or carb::audio::framesToBytes().

Param context

[inout] The user-specified callback data.