#import <SndAudioBuffer.h>
Public Member Functions | |
| (id) | - initWithFormat:data: |
| Initialization method from a SndFormat and the data it describes. | |
| (id) | - initWithBuffer: |
| Initialize a buffer with a matching format to the supplied buffer. | |
| (id) | - initWithBuffer:range: |
| Initialize a buffer with a matching format to the supplied buffer, for a subset range of that audio buffer. | |
| (id) | - initWithDataFormat:channelCount:samplingRate:frameCount: |
| Initializes the instance to the given format. | |
| (id) | - initWithDataFormat:channelCount:samplingRate:duration: |
| Initializes this audio buffer with sound data of the given format, channels, sample rate and duration. | |
| (long) | - mixWithBuffer:fromStart:toEnd:canExpand: |
| Mixes supplied SndAudioBuffer instance with the receiving instance, modifying it. | |
| (long) | - mixWithBuffer: |
| Mixes supplied SndAudioBuffer instance with the receiving instance, modifying it. | |
| (id) | - copyWithZone: |
| SndAudioBuffer object copying. | |
| (id) | - copyDataFromBuffer: |
| Copies the audio buffer NSData instance from the given buffer to the receiver. | |
| (id) | - copyBytes:count:format: |
| Copies bytes from the void * array given. | |
| (id) | - copyBytes:intoRange:format: |
| Copies bytes from the void * array given into a sub region of the buffer. | |
| (id) | - copyFromBuffer:intoRange: |
| Copies from the start of the given buffer into a sub region of the receiving buffer. | |
| (long) | - copyFromBuffer:intoFrameRange:fromFrameRange: |
| Copies from the given region of the given buffer into a sub region of the receiving buffer. | |
| (void) | - fillSNDStreamBuffer: |
| Fills the given stream buffer from the receiving audio buffer. | |
| (SndAudioBuffer *) | - audioBufferOfChannel: |
| Returns a mono SndAudioBuffer instance extracting out the given audio channel of the receiving buffer. | |
| (unsigned long) | - lengthInSampleFrames |
| Returns the number of sample frames in the audio buffer. | |
| (id) | - setLengthInSampleFrames: |
| Changes the length of the buffer to newSampleFrameCount sample frames. | |
| (long) | - lengthInBytes |
| Returns the length of the buffer's sample data in bytes. | |
| (double) | - duration |
| Returns the length of the audio buffer in seconds. | |
| (double) | - samplingRate |
| Returns the sampling rate of the audio buffer in Hertz. | |
| (int) | - channelCount |
| Returns the number of channels in the audio buffer. | |
| (SndSampleFormat) | - dataFormat |
| Returns the format of the sample data as a SndSampleFormat enumerated type. | |
| (SndFormat) | - format |
| Returns the format (number of frames, channels, dataFormat) of the audio buffer as a SndFormat structure. | |
| (void *) | - bytes |
| Returns a C pointer to the sample data. | |
| (BOOL) | - hasSameFormatAsBuffer: |
| compares the data format and length of this buffer to a second buffer. | |
| (id) | - zero |
| Sets buffer data to zero. Silence. | |
| (id) | - zeroFrameRange: |
| Zeros (silences) a given range of frames. | |
| (int) | - frameSizeInBytes |
| Returns the size of a sample frame in bytes. | |
| (NSString *) | - description |
| Returns a description of the instance as an NSString. | |
| (void) | - findMin:max: |
| Finds the maximum and minimum sample values in the audio buffer and returns them as floats. | |
| (double) | - maximumAmplitude |
| Returns the maximum amplitude of the format, that is, the maximum positive value of a sample. | |
| (void) | - normalise |
| Scale signal to maximum dynamic range of data format. | |
| (void) | - scaleBy: |
| Scale signal by a given factor. | |
| (float) | - sampleAtFrameIndex:channel: |
| Retrieves a normalised sample given the frame number (time position) and channel number. | |
| (void) | - stereoChannels: |
| Retrieve the channels used for stereo presentation (left and right). | |
Static Public Member Functions | |
| (id) | + audioBufferWithDataFormat:channelCount:samplingRate:duration: |
| Factory method creating an instance from a set of parameters individually specified. | |
| (id) | + audioBufferWithDataFormat:channelCount:samplingRate:frameCount: |
| Factory method creating an instance from a set of parameters individually specified. | |
| (id) | + audioBufferWithFormat: |
| Factory method creating a zeroed buffer of the given format and length. | |
| (id) | + audioBufferWithFormat:data: |
| Factory method creating an audio buffer in the given format with the audio data. | |
| (id) | + audioBufferWithSNDStreamBuffer: |
| Factory method creating an SndAudioBuffer instance from a SNDStreamBuffer. | |
| (id) | + audioBufferWithSnd:inRange: |
| Factory method creating audioBuffers from a region of the given Snd. | |
Protected Attributes | |
| SndFormat | format |
| NSMutableData * | data |
| signed char * | speakerConfiguration |
A SndAudioBuffer represents sound data in contiguous memory. As distinct from a Snd class, it holds typically small chunks of sound data ready for signal processing or performance. Using classes such as SndAudioBufferQueue enables a fragmented arrangement of buffers across memory, typically for processing constraints. SndAudioBuffers are the closest SndKit match to the underlying audio hardware buffer. In addition to holding the sample data, SndAudioBuffer encapsulates sampling rate, number of channels, number of frames and the format of the sample data. A SndAudioBuffer is guaranteed to be uncompressed, therefore it can be processed as a linear buffer of memory.
| + (id) audioBufferWithDataFormat: | (SndSampleFormat) | dataFormat | ||
| channelCount: | (int) | channelCount | ||
| samplingRate: | (double) | sampleRate | ||
| duration: | (double) | timeInSeconds | ||
Factory method creating an instance from a set of parameters individually specified.
| dataFormat | A SndSampleFormat. | |
| channelCount | The number of sound channels per frame. | |
| sampleRate | The sampling rate specified in Hertz (Hz). | |
| timeInSeconds | Duration is specified in seconds. |
| + (id) audioBufferWithDataFormat: | (SndSampleFormat) | newDataFormat | ||
| channelCount: | (int) | newChannelCount | ||
| samplingRate: | (double) | newSamplingRate | ||
| frameCount: | (long) | newFrameCount | ||
Factory method creating an instance from a set of parameters individually specified.
| newDataFormat | A SndSampleFormat. | |
| newChannelCount | The number of sound channels per frame. | |
| newSamplingRate | The sampling rate specified in Hertz (Hz). | |
| newFrameCount | Duration is specified in frames. |
| + (id) audioBufferWithFormat: | (SndFormat) | format |
Factory method creating a zeroed buffer of the given format and length.
| format | A SndFormat describing the format of the buffer to be created. |
| + (id) audioBufferWithFormat: | (SndFormat *) | format | ||
| data: | (void *) | dataPointer | ||
Factory method creating an audio buffer in the given format with the audio data.
The frameCount member of format MUST match the length of d (in bytes)!
| format | A pointer to a SndFormat. | |
| dataPointer |
| + (id) audioBufferWithSNDStreamBuffer: | (SNDStreamBuffer *) | streamBuffer |
Factory method creating an SndAudioBuffer instance from a SNDStreamBuffer.
| streamBuffer | A fully populated SNDStreamBuffer structure. |
| + (id) audioBufferWithSnd: | (Snd *) | snd | ||
| inRange: | (NSRange) | rangeInFrames | ||
Factory method creating audioBuffers from a region of the given Snd.
| snd | ||
| rangeInFrames | An NSRange structure indicating the start and end of the region in samples. |
| - (id) initWithFormat: | (SndFormat *) | format | ||
| data: | (void *) | sampleData | ||
Initialization method from a SndFormat and the data it describes.
Can be used to initialize an instance with a buffer of data or with empty (i.e zeroed) data of the length given by format.frameCount if sampleData is NULL.
| format | A SndFormat. All fields must be valid before calling this method. | |
| sampleData | A pointer to the memory holding the sample data in the format described by format. |
| - (id) initWithBuffer: | (SndAudioBuffer *) | sndBuffer |
Initialize a buffer with a matching format to the supplied buffer.
Creates a duplicated buffer (with a shallow copy, the data is referenced)
| sndBuffer | An existing initialised SndAudioBuffer. |
| - (id) initWithBuffer: | (SndAudioBuffer *) | sndBuffer | ||
| range: | (NSRange) | rangeInFrames | ||
Initialize a buffer with a matching format to the supplied buffer, for a subset range of that audio buffer.
| sndBuffer | An existing initialised SndAudioBuffer. | |
| rangeInFrames | The NSRange of the supplied sndBuffer to initialise the new instance with. |
| - (id) initWithDataFormat: | (SndSampleFormat) | dataFormat | ||
| channelCount: | (int) | channelCount | ||
| samplingRate: | (double) | samplingRate | ||
| frameCount: | (long) | newFrameCount | ||
Initializes the instance to the given format.
Initializes the instance to the given sample data format, number of sound channels, sample rate, and frames (channel independent samples).
| dataFormat | A SndSampleFormat. | |
| channelCount | The number of sound channels. | |
| samplingRate | Sample rate in Hertz. | |
| newFrameCount | The number of frames, each frame consists of channelCount number of samples. |
| - (id) initWithDataFormat: | (SndSampleFormat) | dataFormat | ||
| channelCount: | (int) | channelCount | ||
| samplingRate: | (double) | samplingRate | ||
| duration: | (double) | timeInSeconds | ||
Initializes this audio buffer with sound data of the given format, channels, sample rate and duration.
The samples are all silence.
| dataFormat | A SndSampleFormat. | |
| channelCount | Number of audio channels, 1 for mono, 2 for stereo, 4 for quad etc.. | |
| samplingRate | Sample rate in Hertz. | |
| timeInSeconds | The size of the buffer in seconds. |
| - (long) mixWithBuffer: | (SndAudioBuffer *) | buff | ||
| fromStart: | (unsigned long) | start | ||
| toEnd: | (unsigned long) | end | ||
| canExpand: | (BOOL) | expand | ||
Mixes supplied SndAudioBuffer instance with the receiving instance, modifying it.
Mixes over the given range of the buffer.
| buff | The SndAudioBuffer instance to mix. | |
| start | The sample frame to begin mixing from. | |
| end | The sample frame to end mixing at. | |
| expand | If TRUE, receiver is allowed to expand buff in place if required to change data format before mixing, (not sample rate). |
| - (long) mixWithBuffer: | (SndAudioBuffer *) | buff |
Mixes supplied SndAudioBuffer instance with the receiving instance, modifying it.
Mixes the entire buffer onto the original buffer.
| buff | The SndAudioBuffer instance to mix. |
| - (id) copyWithZone: | (NSZone *) | zone |
| - (id) copyDataFromBuffer: | (SndAudioBuffer *) | audioBufferToCopyFrom |
Copies the audio buffer NSData instance from the given buffer to the receiver.
Audio buffers must be the same format.
| audioBufferToCopyFrom | The audio buffer instance to copy the data from. |
| - (id) copyBytes: | (void *) | bytes | ||
| count: | (unsigned int) | count | ||
| format: | (SndFormat) | format | ||
Copies bytes from the void * array given.
Grows the internal NSMutableData object as necessary
| bytes | The void * array to copy from. | |
| count | The number of bytes to copy from the array. | |
| format | A SndFormat containing valid channelCount, samplingRate and dataFormat variables. |
| - (id) copyBytes: | (void *) | bytes | ||
| intoRange: | (NSRange) | range | ||
| format: | (SndFormat) | format | ||
Copies bytes from the void * array given into a sub region of the buffer.
Grows the internal NSMutableData object as necessary
| bytes | The void * array to copy from. | |
| range | The start location and number of bytes to copy from the array. | |
| format | A SndFormat containing valid channelCount, samplingRate and dataFormat variables. |
| - (id) copyFromBuffer: | (SndAudioBuffer *) | sourceBuffer | ||
| intoRange: | (NSRange) | rangeInSamples | ||
Copies from the start of the given buffer into a sub region of the receiving buffer.
Grows the internal NSMutableData object as necessary
| sourceBuffer | The audio buffer to copy from. | |
| rangeInSamples | The start location and number of samples to copy to the receiving buffer. |
| - (long) copyFromBuffer: | (SndAudioBuffer *) | fromBuffer | ||
| intoFrameRange: | (NSRange) | bufferRange | ||
| fromFrameRange: | (NSRange) | fromFrameRange | ||
Copies from the given region of the given buffer into a sub region of the receiving buffer.
Grows the internal NSMutableData object as necessary
| fromBuffer | The audio buffer to copy from. | |
| bufferRange | The range of fromBuffer in sample frames to copy into. | |
| fromFrameRange | The start location and number of samples to copy to the receiving buffer. |
| - (void) fillSNDStreamBuffer: | (SNDStreamBuffer *) | streamBuffer |
Fills the given stream buffer from the receiving audio buffer.
Manages any conversion from interleaved SndAudioBuffer format to possibly non-interleaved SNDStreamBuffers.
| streamBuffer | Pointer to the structure that describes the underlying audio API format. |
| - (SndAudioBuffer *) audioBufferOfChannel: | (int) | channel |
Returns a mono SndAudioBuffer instance extracting out the given audio channel of the receiving buffer.
Use this to retrieve a single buffer from a multichannel buffer. Sending this to a mono buffer returns the buffer verbatim.
| channel | The channel to extract. Must be in the range {0..[self channelCount] - 1}. |
| - (unsigned long) lengthInSampleFrames |
Returns the number of sample frames in the audio buffer.
A sample frame is a channel independent time position duration, it's duration is the reciprocal of the sample rate.
| - (id) setLengthInSampleFrames: | (unsigned long) | newSampleFrameCount |
Changes the length of the buffer to newSampleFrameCount sample frames.
TODO Need to explain the consequences of setting the length longer or shorter than current. See the source code.
| - (long) lengthInBytes |
Returns the length of the buffer's sample data in bytes.
| - (double) duration |
Returns the length of the audio buffer in seconds.
| - (double) samplingRate |
Returns the sampling rate of the audio buffer in Hertz.
| - (int) channelCount |
Returns the number of channels in the audio buffer.
| - (SndSampleFormat) dataFormat |
Returns the format of the sample data as a SndSampleFormat enumerated type.
| - (void *) bytes |
Returns a C pointer to the sample data.
The user of this method will need to have determined the format of the data in order to correctly traverse it.
| - (BOOL) hasSameFormatAsBuffer: | (SndAudioBuffer *) | buff |
compares the data format and length of this buffer to a second buffer.
The number of frames (frameCount) are compared.
| buff | The SndAudioBuffer to compare to. |
| - (id) zero |
Sets buffer data to zero. Silence.
| - (id) zeroFrameRange: | (NSRange) | frameRange |
Zeros (silences) a given range of frames.
The range must be between 0 and the buffers frame length.
| - (int) frameSizeInBytes |
Returns the size of a sample frame in bytes.
| - (NSString *) description |
Returns a description of the instance as an NSString.
| - (void) findMin: | (float *) | pMin | ||
| max: | (float *) | pMax | ||
Finds the maximum and minimum sample values in the audio buffer and returns them as floats.
| pMin | Points to a float to store the minimum sample value (between -1.0 and 1.0). | |
| pMax | Points to a float to store the maximum sample value (between -1.0 and 1.0). |
| - (double) maximumAmplitude |
Returns the maximum amplitude of the format, that is, the maximum positive value of a sample.
| - (void) normalise |
Scale signal to maximum dynamic range of data format.
Manages both signals below the dynamic range and in the case of floating point format, exceeding the normalised dynamic range (-1.0 to 1.0). Scales such that no D.C shift occurs across all channels.
| - (void) scaleBy: | (float) | scaleFactor |
Scale signal by a given factor.
Scales the sample values in the buffer by the given multiplier across all channels.
| - (float) sampleAtFrameIndex: | (unsigned long) | frameIndex | ||
| channel: | (int) | channel | ||
Retrieves a normalised sample given the frame number (time position) and channel number.
| frameIndex | The frame index, between 0 and the value returned by lengthInSampleFrames less one, inclusive. | |
| channel | The channel index, between 0 and the number of channels in the buffer (channelCount - 1) to retrieve a single channel, channelCount to average all channels to a single value. |
| - (void) stereoChannels: | (int *) | leftAndRightChannels |
Retrieve the channels used for stereo presentation (left and right).
This allows multichannel sound buffers to have a stereo version.
| leftAndRightChannels | An array of at least two integers which will be assigned the channel number of the left speaker in the zeroth element of the array, the channel number of the right speaker in the first element of the array. |
Holds sound parameters (sample rate, data format, channel count, frame count).
- (NSMutableData*) data [protected] |
The audio sample data.
- (signed char*) speakerConfiguration [protected] |
Holds the association of channels to speakers. Each element holds a channel number (0 - format.channelCount), -1 for unused and silent. Elements are arranged as described by SndSpeakerPosition above.
1.5.6