TechNote_BufferTerminology

Buffer Size, Capacity and Bursts

In AAudio and Oboe we try to use precise terms when referring to the size of buffers.

Sample

A single PCM value representing the amplitude of a signal at an instant of time.

Frame

A frame is a set of samples that are played or recorded at the same time. For example, a stereo stream has two samples in a frame.

Buffer Capacity

Buffer Capacity refers to the allocated size of the memory buffer in frames. It is determined when the stream is created and does not change.

Buffer Size

BufferSize refers to the maximum number of frames that are normally used by the app. Buffer Size can be less than the Buffer Capacity but cannot be larger. The Buffer Size determines the latency associated with the buffer. It can be modified at run-time by calling:

stream->setBufferSizeInFrames(size);

If the BufferSize is too low then glitches are more likely. The buffer size can be increased if the app detects glitches by calling getXRunCount().

Burst Size

This refers to the maximum number of frames that are processed at one time by the underlying mixer or HAL. It determines the maximum size of numFrames for a data callback from Oboe, unless you specify a different size using setFramesPerDataCallback().

The BufferSize is typically set to twice the burst size.

stream->setBufferSizeInFrames(2 * stream->getFramesPerBurst());

Confusing Terminology in Java AudioTrack API

The Java Audio APIs use these terms inconsistently.

This code actually queries the burst size that will probably be used by AudioTrack in low latency mode. The value can be used for the default burst size for OpenSL ES.

AudioManager.getProperty(AudioManager.PROPERTY_OUTPUT_FRAMES_PER_BUFFER); // actually the "burst size"

This sets the requested buffer capacity for an AudioTrack. I recommend not calling this method. It is often better to just let Android figure out the optimal capacity.

AudioTrack.Builder.setBufferSizeInBytes(int); // actually the "capacity"

AudioTrack.setBufferSizeInFrames() sets the actual dynamic Buffer Size in a way that is similar to AAudio and Oboe.

AudioTrack.setBufferSizeInFrames(int);