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. | |
ofSoundBuffer & | operator*= (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
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()
|
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()
|
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()
|
inline |
the number of channels per frame
◆ getNumFrames()
|
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()
|
inline |
sample rate of the audio in this buffer
◆ getTickCount()
|
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()
|
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()
|
inline |
◆ size()
|
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
|
protected |
◆ channels
|
protected |
◆ defaultAlgorithm
|
static |
◆ samplerate
|
protected |
◆ soundStreamDeviceID
|
protected |
◆ tickCount
|
protected |
The documentation for this class was generated from the following files:
- /Users/icq4ever/Desktop/oF0120/libs/openFrameworks/sound/ofSoundBuffer.h
- /Users/icq4ever/Desktop/oF0120/libs/openFrameworks/sound/ofSoundBuffer.cpp