SndMP3 Class Reference
SndMP3 is a subclass of Snd for reading MP3 files. More...
#import <SndMP3.h>
Public Member Functions | |
| (id) | - initFromSoundURL: |
| Initializes the Snd instance, which must be newly allocated, by copying the sound data from the possibly remote sound file located using url. | |
| (double) | - duration |
| Returns the duration of the sound in seconds. | |
| (long) | - lengthInSampleFrames |
| Returns the duration of the sound in sample frames. | |
| (int) | - channelCount |
| Returns the number of channels of the sound. | |
| (double) | - samplingRate |
| Returns the sampling rate of the sound in Hz. | |
| (SndSampleFormat) | - dataFormat |
| Returns the sample data format the sound samples. | |
| (int) | - convertToSampleFormat:samplingRate:channelCount: |
| Actually all this does is check the MP3 is the same as the native format, if not it flags an error. | |
| (int) | - convertToNativeFormat |
| Actually all this does is check the MP3 is the same as the native format, if not it flags an error. | |
| (long) | - insertIntoAudioBuffer:intoFrameRange:samplesInRange: |
| Copies samples from self into a sub region of the provided SndAudioBuffer. | |
| (void *) | - fragmentOfFrame:indexInFragment:fragmentLength:dataFormat: |
| Returns a pointer to memory containing a decompressed region of sound samples containing the given sample frame. | |
| (Snd *) | - soundFromSamplesInRange: |
| Return an uncompressed Snd instance of a range of frames. | |
Static Public Member Functions | |
| (void) | + setPreDecode: |
| Sets whether to do background predecoding when reading an MP3 file or whether decoding is done on the fly. | |
| (BOOL) | + preDecode |
| Returns the current state of background predecoding. | |
| (NSArray *) | + soundFileExtensions |
| Returns an array of file extensions indicating the file format (and file extension) that audio files may be read from or written to. | |
Protected Attributes | |
| long * | encodedFrameLocations |
| long | encodedFrameLocationsCount |
| NSMutableDictionary * | decodedBufferCache |
| SndAudioBuffer * | pcmBufferToAccess |
| double | duration |
| NSLock * | pcmDataLock |
| NSMutableData * | pcmData |
| long | decodedSampleCount |
| BOOL | bDecoding |
Detailed Description
SndMP3 is a subclass of Snd for reading MP3 files.Decoding of MP3 sound files can be done in a background thread during reading (predecoding), or on-the-fly during playback, allowing selection of memory consumption versus processor load. Decoding on the fly has the advantage of memory conservation, but is more processor intensive. The factory methods +preDecode and +setPreDecode: are used to control the use of on-the-fly MP3 sound file decoding or to use the pre-decoding approach.
The current on-the-fly version has the limitation that it only works with CBR (constant bit rate) MP3 streams.
Support is only for 44.1KHz stereo MP3s at the moment.
Member Function Documentation
| + (void) setPreDecode: | (BOOL) | yesOrNo |
Sets whether to do background predecoding when reading an MP3 file or whether decoding is done on the fly.
When an MP3 file is read, predecoding of the MP3 bitstream to linear PCM can be done in the background. This is significantly more memory hungry than decoding the MP3 stream on the fly, but less processor intensive, moving the decoding processing before playback or other signal processing.
Decoding on the fly currently has the limitation that only one MP3 stream can play at any time. This limitation is being worked on.
The default is to decode on the fly.
- Parameters:
-
yesOrNo YES to enable background predecoding, NO to decode on the fly.
| + (BOOL) preDecode |
Returns the current state of background predecoding.
- Returns:
- Returns YES if background predecoding will occur on reading an MP3 file, NO if decoding will be done on the fly.
| - (id) initFromSoundURL: | (NSURL *) | url |
Initializes the Snd instance, which must be newly allocated, by copying the sound data from the possibly remote sound file located using url.
- Parameters:
-
url is a NSURL instance.
- Returns:
- Returns an id. Returns self (an unnamed Snd) if url can retrieve a sound file; otherwise, frees the newly allocated Snd and returns nil.
- See also:
- - initFromSoundfile: (Snd), +alloc (NSObject), +allocWithZone: (NSObject)
Reimplemented from Snd.
| - (long) insertIntoAudioBuffer: | (SndAudioBuffer *) | anAudioBuffer | ||
| intoFrameRange: | (NSRange) | bufferRange | ||
| samplesInRange: | (NSRange) | sndReadingRange | ||
Copies samples from self into a sub region of the provided SndAudioBuffer.
If the buffer and the SndMP3 instance have different formats (after decoding the MP3 bitstream), a format conversion will be performed to the buffers format, including resampling if necessary. The SndMP3 audio data will be read enough to fill the range of samples specified according to the sample rate of the buffer compared to the sample rate of the SndMP3 instance. In the case where there are less than the needed number of samples left in the sndFrameRange to completely insert into the specified buffer region, the number of samples inserted will be returned less than bufferRange.length.
Caching is performed so repeatedly retrieving the same frame successively incurs no decoding overhead.
- Parameters:
-
anAudioBuffer The SndAudioBuffer object into which to copy the data. bufferRange An NSRange of sample frames (i.e channel independent time position specified in samples) in the buffer to copy into. sndReadingRange An NSRange of sample frames (i.e channel independent time position specified in samples) within the Snd to start reading data from and the last permissible index to read from.
- Returns:
- Returns the number of samples actually inserted. This may be less than the length specified in the bufferRange if sndStartIndex is less than the number samples needed to convert to insert in the specified buffer region.
| + (NSArray *) soundFileExtensions |
Returns an array of file extensions indicating the file format (and file extension) that audio files may be read from or written to.
- Returns:
- Returns an array of file extensions available for reading and writing. Includes all of Snd's formats and "mp3".
| - (void *) fragmentOfFrame: | (int) | frame | ||
| indexInFragment: | (unsigned int *) | currentFrame | ||
| fragmentLength: | (unsigned int *) | lastFrameInBlock | ||
| dataFormat: | (SndSampleFormat *) | dataFormat | ||
Returns a pointer to memory containing a decompressed region of sound samples containing the given sample frame.
- Parameters:
-
frame The sample frame to find. currentFrame lastFrameInBlock dataFormat
- Returns:
- Returns a void * pointer to memory holding the region of sound samples.
| - (Snd *) soundFromSamplesInRange: | (NSRange) | frameRange |
Member Data Documentation
- (currentMP3FrameID The most recently decoded bitstream frame index into) encodedFrameLocations [protected] |
An array of longs which give the locations in the MP3 bitstream data of the start of each MP3 frame.
Keeps track of the which MP3 frame ID HIP is expecting next to identify when to backtrack decoding.
- (long) encodedFrameLocationsCount [protected] |
The number of frame locations in encodedFrameLocations.
- (NSMutableDictionary*) decodedBufferCache [protected] |
Caches the n most recently decoded bitstream frames, when we are simultaneously accessing the same SndMP3. Each key is the MP3 frame ID, each object is a SndAudioBuffer in 16 bit PCM data (left and right channels) format.
- (SndAudioBuffer*) pcmBufferToAccess [protected] |
The decoded audio buffer ready for access.
- (double) duration [protected] |
The duration of the sound (when decoded) in seconds. In principle we could use the soundFormat.frameCount instead.
- (NSLock*) pcmDataLock [protected] |
Locks the decoding of a bitstream frame (and any preceding frames necessary to backtrack).
- (NSMutableData*) pcmData [protected] |
the decoded linear sample data.
- (long) decodedSampleCount [protected] |
Number of samples decoded so far.
- (BOOL) bDecoding [protected] |
Indicates we are decoding.
The documentation for this class was generated from the following file:
