ofSoundBuffer

class methods

variables

Documentation from code comments


/*!

@brief Buffer for audio samples and associated metadata.

ofSoundBuffer stores audio as an array of interleaved floating point samples, with a given sample rate for playback.

How sound recording works

Physically speaking, what we call sound is simply changes in air pressure perceived by a listener. These changes in sound pressure are converted by a microphone into changes in voltage that can be recorded, making a sound recording. A sound recording is therefore a recording of changes in air pressure at a particular point in space (ie where the microphone was positioned). When it is played back through a speaker, the speaker reproduces the same pattern of changes in air pressure as were recorded by the microphone, but this time at a different point in space (ie where the speaker is positioned).

In digital audio these changes in air pressure are recorded as a set of discrete numbers (samples), each number representing a snapshot of the air pressure at a particular point in time. For high quality audio there are typically 44,100 snapshots recorded every second. This is called the sample rate and is expressed in Hz (44100Hz) or kHz (44.1kHz).

Because humans have two ears, rather than one, sound is usually recorded in stereo. The simplest stereo sound recording is two channels of sound recorded by two microphones at two different points in space. More channels can also be recorded (eg with 5.1 surround sound systems or Ambisonics).

Frames, channels and samples

Data in an ofSoundBuffer is stored interleaved as an array of floats. Interleaved audio is analogous to how different color channels are stored side by side in an ofImage or ofPixels object.

The functions and function arguments in ofSoundBuffer that deal with this interleaved data are based on 3 key terms:

channels refers to the number of channels or individual streams of interleaved audio samples in the buffer. A mono recording has 1 channel, a stereo recording has 2 channels.

samples refers to the actual raw data. One sample is a single floating point number between -1 and 1, which represents a snapshot of sound pressure at a single moment in time. A 0.1 second long buffer at 44100Hz contains 4410 samples if it has 1 channel, 8820 samples if it has 2 channels, 13230 samples if it has 3 channels, and so on.

frames refers to the number of multi-channel sets of interleaved sample data there are in the buffer. A 0.1 second long buffer at 44100Hz always has 4410 frames, regardless of how many channels it has. To get the number of samples in a buffer you multiply the number of channels by the number of frames.

If I have an ofSoundBuffer with 8 frames of mono (1 channel) audio, the underlying array contains 8 samples (ie it is 8 floats long), and the samples are arranged like this:

L L L L L L L L

where L represents a single sample.

If I have an ofSoundBuffer with 8 frames of stereo (2 channel) audio, then the underlying array contains 16 samples ((getNumFrames()getNumChannels(), ie 82) arranged in an interleaved pattern:

L R L R L R L R L R L R L R L R

where L represents a single sample for the left channel, and R represents a single sample for the right channel. Grouping the frames together for clarity:

LR LR LR LR LR LR LR LR

If I have an ofSoundBuffer with 8 frames of 5.1 surround (6 channel) audio, then the underlying array of floats contains 48 samples (getNumFrames()getNumChannels(), ie 86) and is usually arranged in an interleaved pattern like this:

L C R Ls Rs Lfe L C R Ls Rs Lfe L C R Ls Rs Lfe L C R Ls Rs Lfe L C R Ls Rs Lfe L C R Ls Rs Lfe L C R Ls Rs Lfe L C R Ls Rs Lfe

where L represents a single sample for the left channel, C for centre, R for right, Ls for left surround, Rs for right surround and Lfe for the subwoofer. Grouping the frames together for clarity:

LCRLsRsLfe LCRLsRsLfe LCRLsRsLfe LCRLsRsLfe LCRLsRsLfe LCRLsRsLfe LCRLsRsLfe LCRLsRsLfe

*/

ofSoundBuffer()

ofSoundBuffer::ofSoundBuffer()

ofSoundBuffer(...)

ofSoundBuffer::ofSoundBuffer(short *shortBuffer, size_t numFrames, size_t numChannels, unsigned int sampleRate)

addTo(...)

void ofSoundBuffer::addTo(float *outBuffer, size_t outNumFrames, size_t outNumChannels, size_t fromFrame, bool loop=false)

Documentation from code comments


as copyTo but mixes source audio with audio in out by adding samples together (+), instead of overwriting

addTo(...)

void ofSoundBuffer::addTo(ofSoundBuffer &outBuffer, size_t fromFrame, bool loop=false)

Documentation from code comments


as addTo above but reads outNumFrames and outNumChannels from outBuffer

addTo(...)

void ofSoundBuffer::addTo(ofSoundBuffer &outBuffer, size_t outNumFrames, size_t outNumChannels, size_t fromFrame, bool loop=false)

Documentation from code comments


as copyTo but mixes source audio with audio in outBuffer by adding samples together (+), instead of overwriting.

allocate(...)

void ofSoundBuffer::allocate(size_t numSamples, size_t numChannels)

append(...)

void ofSoundBuffer::append(ofSoundBuffer &other)

clear()

void ofSoundBuffer::clear()

Documentation from code comments


remove all samples, preserving channel count and sample rate.

copyFrom(...)

void ofSoundBuffer::copyFrom(const float *floatBuffer, size_t numFrames, size_t numChannels, unsigned int sampleRate)

copyFrom(...)

void ofSoundBuffer::copyFrom(const short *shortBuffer, size_t numFrames, size_t numChannels, unsigned int sampleRate)

Documentation from code comments


copy length samples from shortBuffer and interpret as interleaved with the given number of channels at the given samplerate

copyFrom(...)

void ofSoundBuffer::copyFrom(const vector< float > &floatBuffer, size_t numChannels, unsigned int sampleRate)

copyFrom(...)

void ofSoundBuffer::copyFrom(const vector< short > &shortBuffer, size_t numChannels, unsigned int sampleRate)

copyTo(...)

void ofSoundBuffer::copyTo(float *outBuffer, size_t outNumFrames, size_t outNumChannels, size_t fromFrame, bool loop=false)

Documentation from code comments


copy sample data to out, where out is already allocated to match outNumFrames and outNumChannels (ie outNumFrames*outNumChannels samples). fromFrame is a frame offset. if we don't have enough source data, loop with fromFrame=0 until we have filled the out buffer. if out has fewer channels than our buffer, just copy the first outNumChannels of our data and skip the rest. if out has more channels than our buffer, loop through our channels repeatedly until done.

copyTo(...)

void ofSoundBuffer::copyTo(ofSoundBuffer &outBuffer, size_t frameFrame, bool loop=false)

Documentation from code comments


as copyTo above but reads outNumFrames and outNumChannels from outBuffer

copyTo(...)

void ofSoundBuffer::copyTo(ofSoundBuffer &outBuffer, size_t outNumFrames, size_t outNumChannels, size_t fromFrame, bool loop=false)

Documentation from code comments


resize outBuffer to outNumFrames with outNumChannels, and then copy outNumFrames of data from us to outBuffer. fromFrame is a frame offset. if we don't have enough source data, loop with fromFrame=0 until we have filled outBuffer. if outBuffer has fewer channels than our buffer, just copy the first outNumChannels of our data and skip the rest. if outBuffer has more channels than our buffer, loop through our channels repeatedly until done.

fillWithNoise(...)

void ofSoundBuffer::fillWithNoise(float amplitude=1.0f)

Documentation from code comments


fills the buffer with random noise between -amplitude and amplitude. useful for debugging.

fillWithTone(...)

float ofSoundBuffer::fillWithTone(float pitchHz=440.0f, float phase=0.0f)

Documentation from code comments


fills the buffer with a sine wave. useful for debugging.

getBuffer()

vector< float > & ofSoundBuffer::getBuffer()

Documentation from code comments


return the underlying buffer. careful!

getBuffer()

const vector< float > & ofSoundBuffer::getBuffer()

getChannel(...)

void ofSoundBuffer::getChannel(ofSoundBuffer &outBuffer, size_t sourceChannel)

Documentation from code comments


copy the requested channel of our data to outBuffer. resize outBuffer to fit.

getDeviceID()

int ofSoundBuffer::getDeviceID()

Documentation from code comments


return the ID of the device which generated this buffer

getDurationMS()

uint64_t ofSoundBuffer::getDurationMS()

Documentation from code comments


return the duration of audio in this buffer in milliseconds (==(getNumFrames()/getSampleRate())*1000)

getDurationMicros()

uint64_t ofSoundBuffer::getDurationMicros()

getDurationNanos()

uint64_t ofSoundBuffer::getDurationNanos()

getNumChannels()

size_t ofSoundBuffer::getNumChannels()

Documentation from code comments


the number of channels per frame

getNumFrames()

size_t ofSoundBuffer::getNumFrames()

Documentation from code comments


the number of frames, ie the number of sets of (getNumChannels()) samples

getRMSAmplitude()

float ofSoundBuffer::getRMSAmplitude()

getRMSAmplitudeChannel(...)

float ofSoundBuffer::getRMSAmplitudeChannel(size_t channel)

getSample(...)

float & ofSoundBuffer::getSample(size_t frameIndex, size_t channel)

Documentation from code comments


access the sample at frameIndex on a soecific channel

getSample(...)

const float & ofSoundBuffer::getSample(size_t frameIndex, size_t channel)

getSampleRate()

unsigned int ofSoundBuffer::getSampleRate()

Documentation from code comments


sample rate of the audio in this buffer

getTickCount()

uint64_t ofSoundBuffer::getTickCount()

Documentation from code comments


return the tickCount that was assigned by ofSoundStream (if this buffer originated from an ofSoundStream).

hermiteResampleTo(...)

void ofSoundBuffer::hermiteResampleTo(ofSoundBuffer &buffer, size_t fromFrame, size_t numFrames, float speed, bool loop)

linearResampleTo(...)

void ofSoundBuffer::linearResampleTo(ofSoundBuffer &buffer, size_t fromFrame, size_t numFrames, float speed, bool loop)

normalize(...)

void ofSoundBuffer::normalize(float level)

Documentation from code comments


amplifies samples so that the maximum amplitude is equal to 'level'

operator*(...)

ofSoundBuffer ofSoundBuffer::operator*(float value)

Documentation from code comments


return a new buffer containing the contents of this buffer multiplied by value.

operator*=(...)

ofSoundBuffer & ofSoundBuffer::operator*=(float value)

Documentation from code comments


multiply everything in this buffer by value, in-place.

operator[](...)

float & ofSoundBuffer::operator[](size_t samplePos)

Documentation from code comments


access the sample at the given position in the buffer. to retrieve the sample for channel channelIndex of frame frameIndex, do the following: ofSoundBuffer myBuffer; ... float sample = myBuffer[(frameIndex*myBuffer.getNumChannels()) + channelIndex];

operator[](...)

const float & ofSoundBuffer::operator[](size_t samplePos)

resample(...)

void ofSoundBuffer::resample(float speed, ofSoundBuffer::InterpolationAlgorithm algorithm)

Documentation from code comments


resample by changing the playback speed, keeping the same sampleRate

resampleTo(...)

void ofSoundBuffer::resampleTo(ofSoundBuffer &outBuffer, size_t fromFrame, size_t numFrames, float speed, bool loop=false, ofSoundBuffer::InterpolationAlgorithm algorithm)

Documentation from code comments


resample our data to outBuffer at the given target speed, starting at fromFrame and copying numFrames of data. resize outBuffer to fit. speed is relative to current speed (ie 1.0f == no change). lower speeds will give a larger outBuffer, higher speeds a smaller outBuffer.

resize(...)

void ofSoundBuffer::resize(size_t numSamples, float val)

Documentation from code comments


resize this buffer to exactly this many samples. it's up to you make sure samples matches the channel count.

set(...)

void ofSoundBuffer::set(float value)

Documentation from code comments


set everything in this buffer to value, preserving size, channel count and sample rate.

setChannel(...)

void ofSoundBuffer::setChannel(const ofSoundBuffer &inBuffer, size_t channel)

Documentation from code comments


copy data from inBuffer to the given channel. resize ourselves to match inBuffer's getNumFrames().

setDeviceID(...)

void ofSoundBuffer::setDeviceID(int id)

setNumChannels(...)

void ofSoundBuffer::setNumChannels(int channels)

Documentation from code comments


set the number of channels. does not change the underlying data, ie causes getNumFrames() to return a different result.

setSampleRate(...)

void ofSoundBuffer::setSampleRate(unsigned int rate)

setTickCount(...)

void ofSoundBuffer::setTickCount(uint64_t tick)

size()

size_t ofSoundBuffer::size()

Documentation from code comments


return the total number of samples in this buffer (==getNumFrames()*getNumChannels())

stereoPan(...)

void ofSoundBuffer::stereoPan(float left, float right)

Documentation from code comments


assuming a 2-channel buffer, apply a stereo pan by multiplying channel 0 by left and channel 1 by right.

swap(...)

void ofSoundBuffer::swap(ofSoundBuffer &otherBuffer)

Documentation from code comments


swap the contents of this buffer with otherBuffer

toShortPCM(...)

void ofSoundBuffer::toShortPCM(short *dst)

toShortPCM(...)

void ofSoundBuffer::toShortPCM(vector< short > &dst)

trimSilence(...)

bool ofSoundBuffer::trimSilence(float threshold=0.0001f, bool trimStart=true, bool trimEnd=true)

Documentation from code comments


removes initial / ending silence from the buffer

ofSoundBuffer::InterpolationAlgorithm defaultAlgorithm

ofSoundBuffer::InterpolationAlgorithm ofSoundBuffer::defaultAlgorithm

If you have any doubt about the usage of this module you can ask in the forum.

If you want to contribute better documentation or start documenting this section you can do so here

If you find anything wrong with this docs you can report any error by opening an issue