reference

This documentation is automatically generated from the openFrameworks source code using doxygen and refers to the most recent release, version 0.12.0.

Buffer for audio samples and associated metadata. More...

#include <ofSoundBuffer.h>

Public Types

enum  InterpolationAlgorithm { Linear , Hermite }
 

Public Member Functions

 ofSoundBuffer ()
 
 ofSoundBuffer (short *shortBuffer, std::size_t numFrames, std::size_t numChannels, unsigned int sampleRate)
 
void allocate (size_t numSamples, size_t numChannels)
 
unsigned int getSampleRate () const
 sample rate of the audio in this buffer
 
void setSampleRate (unsigned int rate)
 
void resample (float speed, InterpolationAlgorithm algorithm=defaultAlgorithm)
 resample by changing the playback speed, keeping the same sampleRate
 
std::size_t getNumChannels () const
 the number of channels per frame
 
void setNumChannels (int channels)
 set the number of channels. does not change the underlying data, ie causes getNumFrames() to return a different result.
 
std::size_t getNumFrames () const
 the number of frames, ie the number of sets of (getNumChannels()) samples
 
uint64_t getTickCount () const
 return the tickCount that was assigned by ofSoundStream (if this buffer originated from an ofSoundStream).
 
void setTickCount (uint64_t tick)
 
uint64_t getDurationMS () const
 return the duration of audio in this buffer in milliseconds (==(getNumFrames()/getSampleRate())*1000)
 
uint64_t getDurationMicros () const
 
uint64_t getDurationNanos () const
 
int getDeviceID () const
 return the ID of the device which generated this buffer
 
void setDeviceID (int id)
 
float & operator[] (std::size_t samplePos)
 
const float & operator[] (std::size_t samplePos) const
 
float & getSample (std::size_t frameIndex, std::size_t channel)
 access the sample at frameIndex on a soecific channel
 
const float & getSample (std::size_t frameIndex, std::size_t channel) const
 
ofSoundBuffer operator* (float value)
 return a new buffer containing the contents of this buffer multiplied by value.
 
ofSoundBufferoperator*= (float value)
 multiply everything in this buffer by value, in-place.
 
void stereoPan (float left, float right)
 assuming a 2-channel buffer, apply a stereo pan by multiplying channel 0 by left and channel 1 by right.
 
void copyFrom (const short *shortBuffer, std::size_t numFrames, std::size_t numChannels, unsigned int sampleRate)
 copy length samples from shortBuffer and interpret as interleaved with the given number of channels at the given samplerate
 
void copyFrom (const float *floatBuffer, std::size_t numFrames, std::size_t numChannels, unsigned int sampleRate)
 
void copyFrom (const std::vector< short > &shortBuffer, std::size_t numChannels, unsigned int sampleRate)
 
void copyFrom (const std::vector< float > &floatBuffer, std::size_t numChannels, unsigned int sampleRate)
 
void toShortPCM (std::vector< short > &dst) const
 
void toShortPCM (short *dst) const
 
void copyTo (ofSoundBuffer &outBuffer, std::size_t outNumFrames, std::size_t outNumChannels, std::size_t fromFrame, bool loop=false) const
 
void addTo (ofSoundBuffer &outBuffer, std::size_t outNumFrames, std::size_t outNumChannels, std::size_t fromFrame, bool loop=false) const
 as copyTo but mixes source audio with audio in outBuffer by adding samples together (+), instead of overwriting.
 
void copyTo (ofSoundBuffer &outBuffer, std::size_t frameFrame=0, bool loop=false) const
 as copyTo above but reads outNumFrames and outNumChannels from outBuffer
 
void addTo (ofSoundBuffer &outBuffer, std::size_t fromFrame=0, bool loop=false) const
 as addTo above but reads outNumFrames and outNumChannels from outBuffer
 
void append (ofSoundBuffer &other)
 
void copyTo (float *outBuffer, std::size_t outNumFrames, std::size_t outNumChannels, std::size_t fromFrame, bool loop=false) const
 
void addTo (float *outBuffer, std::size_t outNumFrames, std::size_t outNumChannels, std::size_t fromFrame, bool loop=false) const
 as copyTo but mixes source audio with audio in out by adding samples together (+), instead of overwriting
 
void resampleTo (ofSoundBuffer &outBuffer, std::size_t fromFrame, std::size_t numFrames, float speed, bool loop=false, InterpolationAlgorithm algorithm=defaultAlgorithm) const
 
void getChannel (ofSoundBuffer &outBuffer, std::size_t sourceChannel) const
 copy the requested channel of our data to outBuffer. resize outBuffer to fit.
 
void setChannel (const ofSoundBuffer &inBuffer, std::size_t channel)
 copy data from inBuffer to the given channel. resize ourselves to match inBuffer's getNumFrames().
 
float getRMSAmplitude () const
 
float getRMSAmplitudeChannel (std::size_t channel) const
 
void linearResampleTo (ofSoundBuffer &buffer, std::size_t fromFrame, std::size_t numFrames, float speed, bool loop) const
 
void hermiteResampleTo (ofSoundBuffer &buffer, std::size_t fromFrame, std::size_t numFrames, float speed, bool loop) const
 
void fillWithNoise (float amplitude=1.0f)
 fills the buffer with random noise between -amplitude and amplitude. useful for debugging.
 
float fillWithTone (float pitchHz=440.0f, float phase=0.0f)
 fills the buffer with a sine wave. useful for debugging.
 
void normalize (float level=1)
 amplifies samples so that the maximum amplitude is equal to 'level'
 
bool trimSilence (float threshold=0.0001f, bool trimStart=true, bool trimEnd=true)
 removes initial / ending silence from the buffer
 
std::size_t size () const
 return the total number of samples in this buffer (==getNumFrames()*getNumChannels())
 
void resize (std::size_t numSamples, float val=float())
 resize this buffer to exactly this many samples. it's up to you make sure samples matches the channel count.
 
void clear ()
 remove all samples, preserving channel count and sample rate.
 
void swap (ofSoundBuffer &otherBuffer)
 swap the contents of this buffer with otherBuffer
 
void set (float value)
 set everything in this buffer to value, preserving size, channel count and sample rate.
 
std::vector< float > & getBuffer ()
 return the underlying buffer. careful!
 
const std::vector< float > & getBuffer () const
 

Static Public Attributes

static InterpolationAlgorithm defaultAlgorithm = ofSoundBuffer::Hermite
 

Protected Member Functions

bool checkSizeAndChannelsConsistency (const std::string &function="")
 

Protected Attributes

std::vector< float > buffer
 
std::size_t channels
 
unsigned int samplerate
 
uint64_t tickCount
 
int soundStreamDeviceID
 

Detailed Description

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 8*2) 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 8*6) 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 

Member Enumeration Documentation

◆ InterpolationAlgorithm

Enumerator
Linear 
Hermite 

Constructor & Destructor Documentation

◆ ofSoundBuffer() [1/2]

ofSoundBuffer::ofSoundBuffer ( )

◆ ofSoundBuffer() [2/2]

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

Member Function Documentation

◆ addTo() [1/3]

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

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

◆ addTo() [2/3]

void ofSoundBuffer::addTo ( ofSoundBuffer outBuffer,
std::size_t  fromFrame = 0,
bool  loop = false 
) const

as addTo above but reads outNumFrames and outNumChannels from outBuffer

◆ addTo() [3/3]

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

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)

◆ checkSizeAndChannelsConsistency()

bool ofSoundBuffer::checkSizeAndChannelsConsistency ( const std::string &  function = "")
protected

◆ clear()

void ofSoundBuffer::clear ( )

remove all samples, preserving channel count and sample rate.

◆ copyFrom() [1/4]

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

◆ copyFrom() [2/4]

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

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

◆ copyFrom() [3/4]

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

◆ copyFrom() [4/4]

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

◆ copyTo() [1/3]

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

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() [2/3]

void ofSoundBuffer::copyTo ( ofSoundBuffer outBuffer,
std::size_t  frameFrame = 0,
bool  loop = false 
) const

as copyTo above but reads outNumFrames and outNumChannels from outBuffer

◆ copyTo() [3/3]

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

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)

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 
)

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

◆ getBuffer() [1/2]

vector< float > & ofSoundBuffer::getBuffer ( )

return the underlying buffer. careful!

◆ getBuffer() [2/2]

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

◆ getChannel()

void ofSoundBuffer::getChannel ( ofSoundBuffer outBuffer,
std::size_t  sourceChannel 
) const

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

◆ getDeviceID()

int ofSoundBuffer::getDeviceID ( ) const
inline

return the ID of the device which generated this buffer

◆ getDurationMicros()

uint64_t ofSoundBuffer::getDurationMicros ( ) const

◆ getDurationMS()

uint64_t ofSoundBuffer::getDurationMS ( ) const

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

◆ getDurationNanos()

uint64_t ofSoundBuffer::getDurationNanos ( ) const

◆ getNumChannels()

std::size_t ofSoundBuffer::getNumChannels ( ) const
inline

the number of channels per frame

◆ getNumFrames()

std::size_t ofSoundBuffer::getNumFrames ( ) const
inline

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

◆ getRMSAmplitude()

float ofSoundBuffer::getRMSAmplitude ( ) const

◆ getRMSAmplitudeChannel()

float ofSoundBuffer::getRMSAmplitudeChannel ( std::size_t  channel) const

◆ getSample() [1/2]

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

access the sample at frameIndex on a soecific channel

◆ getSample() [2/2]

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

◆ getSampleRate()

unsigned int ofSoundBuffer::getSampleRate ( ) const
inline

sample rate of the audio in this buffer

◆ getTickCount()

uint64_t ofSoundBuffer::getTickCount ( ) const
inline

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

◆ hermiteResampleTo()

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

◆ linearResampleTo()

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

◆ normalize()

void ofSoundBuffer::normalize ( float  level = 1)

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

◆ operator*()

ofSoundBuffer ofSoundBuffer::operator* ( float  value)

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

◆ operator*=()

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

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

◆ operator[]() [1/2]

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

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[]() [2/2]

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

◆ resample()

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

resample by changing the playback speed, keeping the same sampleRate

◆ resampleTo()

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

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 ( std::size_t  numSamples,
float  val = float() 
)

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)

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

◆ setChannel()

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

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

◆ setDeviceID()

void ofSoundBuffer::setDeviceID ( int  id)
inline

◆ setNumChannels()

void ofSoundBuffer::setNumChannels ( int  channels)

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)
inline

◆ size()

std::size_t ofSoundBuffer::size ( ) const
inline

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

◆ stereoPan()

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

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)

swap the contents of this buffer with otherBuffer

◆ toShortPCM() [1/2]

void ofSoundBuffer::toShortPCM ( short *  dst) const

◆ toShortPCM() [2/2]

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

◆ trimSilence()

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

removes initial / ending silence from the buffer

Member Data Documentation

◆ buffer

std::vector<float> ofSoundBuffer::buffer
protected

◆ channels

std::size_t ofSoundBuffer::channels
protected

◆ defaultAlgorithm

ofSoundBuffer::InterpolationAlgorithm ofSoundBuffer::defaultAlgorithm = ofSoundBuffer::Hermite
static

◆ samplerate

unsigned int ofSoundBuffer::samplerate
protected

◆ soundStreamDeviceID

int ofSoundBuffer::soundStreamDeviceID
protected

◆ tickCount

uint64_t ofSoundBuffer::tickCount
protected

The documentation for this class was generated from the following files: