Snd Class Reference
The Snd object encapsulates a sounds format parameters and it's sample data. It supports reading and writing to a soundfile, playback of sound, recording of sampled sound, conversion among various sampled formats, basic editing of the sound, and name and storage management for sounds. More...
#import <Snd.h>
Public Member Functions | |
| (id) | - initFromSoundfile: |
| Initializes the Snd instance, which must be newly allocated, from the sound file filename. | |
| (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. | |
| (id) | - initWithFormat:channelCount:frames:samplingRate: |
| Initialise a Snd instance with silence of given format and length. | |
| (id) | - initWithData: |
| Initialise a Snd instance using a NSData instance which holds audio data in Sun/NeXT .au format. | |
| (void) | - swapBigEndianToHostFormat |
| The swapBigEndianToHostFormat method swaps the byte order of the receiver if it is running on a little-endian (e.g Intel) architecture, and has no effect on a big-endian (e.g Motorola 68k, PPC) architecture. | |
| (void) | - swapHostToBigEndianFormat |
| The swapHostToBigEndianFormat method swaps the byte order of the receiver if it is running on a little-endian (e.g Intel) architecture, and has no effect on a big-endian (e.g Motorola 68k, PPC) architecture. | |
| (NSString *) | - name |
| Returns the Snd's name. | |
| (id) | - setName: |
| Sets the Snd's name to aName. | |
| (id) | - delegate |
| Returns the Snd's delegate. | |
| (void) | - setDelegate: |
| Sets the Snd's delegate to anObject. | |
| (double) | - samplingRate |
| Returns the Snd's sampling rate. | |
| (unsigned long) | - lengthInSampleFrames |
| Returns the number of sample frames, or channel count-independent samples, in the Snd. | |
| (double) | - duration |
| Returns the Snd's length in seconds. | |
| (int) | - channelCount |
| Returns the number of channels in the Snd. | |
| (NSString *) | - info |
| Returns the Snd's info string. | |
| (void) | - setInfo: |
| Assigns the Snd's info string. | |
| (BOOL) | - isEmpty |
| Returns YES if the Snd doesn't contain any sound data, otherwise returns NO. | |
| (BOOL) | - isEditable |
| Returns YES if the Snd's format indicates that it can be edited, otherwise returns NO. | |
| (BOOL) | - compatibleWithSound: |
| Returns YES if the format, sampling rate, and channel count of aSound's sound data is the same as that of the Snd receiving this message. | |
| (int) | - convertToSampleFormat:samplingRate:channelCount: |
| Convert the Snd's data to the given format, sampling rate, and number of channels. | |
| (int) | - convertToSampleFormat: |
| This is the same as convertToSampleFormat:samplingRate:channelCount:, except that only the format is changed. | |
| (int) | - convertToNativeFormat |
| The Snd is converted to the format (sampling rate, resolution and channels) that the hardware natively uses. | |
| (id) | - copyWithZone: |
| (NSData *) | - dataEncodedAsFormat: |
| Creates an NSData instance holding the Snd's name (if any), sample format, and sound data (if any). | |
| (void *) | - bytes |
| Returns a pointer to the Snd's sampled data. | |
| (long) | - dataSize |
| Return the size (in bytes) of the Snd's sample data. | |
| (SndSampleFormat) | - dataFormat |
| Returns the format of the Snd's data. | |
| (BOOL) | - hasSameFormatAsBuffer: |
| Returns YES if the Snd's dataFormat, channelCount and sampling rate match the given SndAudioBuffer instance. | |
| (SndFormat) | - format |
| Returns the format (number of frames, channels, dataFormat) of the audio buffer as a SndFormat structure. | |
| (NSString *) | - formatDescription |
| Returns a string describing the data format in a textual description. | |
| (int) | - processingError |
| Returns a constant that represents the last error that was generated. | |
| (Snd *) | - soundBeingProcessed |
| Returns the Snd object that's being performed. | |
| (void) | - tellDelegate: |
| Sends theMessage to the Snd's delegate (only sent if the delegate implements theMessage). | |
| (void) | - tellDelegate:duringPerformance: |
| Sends theMessage to the Snd's delegate (only sent if the delegate implements theMessage). | |
| (void) | - tellDelegateString:duringPerformance: |
| Sends theMessage to the Snd's delegate (only sent if the delegate implements theMessage). | |
| (void) | - setConversionQuality: |
| Sets the conversion quality performed by convertToSampleFormat:. | |
| (SndConversionQuality) | - conversionQuality |
| Returns the current conversion quality performed by convertToSampleFormat:. | |
| (id) | - initWithAudioBuffer: |
| Initialises a Snd instance from the provided SndAudioBuffer. | |
| (void) | - normalise |
| Normalises the amplitude of the entire sound. | |
| (double) | - maximumAmplitude |
| Returns the maximum amplitude of the format, that is, the maximum positive value of a sample. | |
Static Public Member Functions | |
| (id) | + findSoundFor: |
| Finds and returns the named Snd object. | |
| (id) | + addName:sound: |
| (id) | + addName:fromSoundfile: |
| (id) | + addName:fromSection: |
| (id) | + addName:fromBundle: |
| (void) | + removeSoundForName: |
| (void) | + removeAllSounds |
| Remove all named sounds in the name table. | |
| (SndFormat) | + nativeFormat |
| Returns the native format (sampling rate, resolution and channels) used by the sound playback hardware in streaming audio. | |
Public Attributes | |
| int | tag |
Protected Attributes | |
| NSMutableArray * | soundBuffers |
| SndFormat | soundFormat |
| NSString * | info |
| int | priority |
| id | delegate |
| NSString * | name |
| int | currentError |
| SndConversionQuality | conversionQuality |
| NSMutableArray * | performancesArray |
| NSLock * | performancesArrayLock |
| NSRecursiveLock * | editingLock |
| BOOL | loopWhenPlaying |
| long | loopStartIndex |
| long | loopEndIndex |
| SndAudioProcessorChain * | audioProcessorChain |
Detailed Description
The Snd object encapsulates a sounds format parameters and it's sample data. It supports reading and writing to a soundfile, playback of sound, recording of sampled sound, conversion among various sampled formats, basic editing of the sound, and name and storage management for sounds.Snd objects represent and manage sounds. A Snd object's sound can be recorded from a microphone, read from a sound file or NSBundle resource, retrieved from the pasteboard or from the sound segment in the application's executable file, or created algorithmically. The Snd class also provides an application-wide name table that lets you identify and locate sounds by name.
Playback and recording are performed by background threads, allowing your application to proceed in parallel. By using preemption of queueing, the latency between sending a play: or record: message and the start of the playback or recording, is no more than the duration of one hardware buffer. A Snd holds parameters that prime it's performance at the start of play including a SndAudioProcessor for effects processing, volume and panning.
You can also edit a Snd object by adding and removing samples. To minimize data movement (and thus save time), an edited Snd may become fragmented; in other words, its sound data might become discontiguous in memory. While playback of a fragmented Snd object is transparent, it does incur some overhead. If you perform a number of edits you may want to return the Snd to a contiguous state by sending it a compactSamples message before you play it. However, a large Snd may take a long time to compact, so a judicious and well-timed use of compactSamples is advised. Fragmented Snds are automatically compacted before they're copied to a pasteboard (through the writeToPasteboard: method). Also, when you write a Snd to a sound file, the data in the file will be compact regardless of the state of the object.
A Snd object contains an NSArray of SndAudioBuffers, the structure that describes and contains sound data. Most of the methods defined in the Snd class are implemented so that you needn't be aware of this structure.
Sound Conversion Features
The sample rate conversion routines (in particular) come from Julius Smith (resample-1.2), but have been modified to not require compacting of fragmented sound files. Additionally, they will accept 8 bit, float and double input, although the output is always 16 bit. So although you can convert sampling rates of float data, it has to go through an intermediate 16 bit stage for the rate conversion. Sorry.
There are 3 different qualities of sample rate conversion, described by SndConversionQuality. The fastest conversion is of the lowest quality. The Snd object uses the fastest one by default, but you can set the quality to be used with the -setConversionQuality: method.
The sound conversion routines (in general) basically convert from any sampling rate, any number of channels (<= 16), 8, 16 bit, float and double formats to any other combination of the above, in as few passes as possible. When changing numbers of channels, you can change from 1 to many, many to 1, or any power of 2 to any other power of 2 (eg 2 to 8, 4 to 2, 2 to 16 etc).
Member Function Documentation
| + (id) findSoundFor: | (NSString *) | aName |
Finds and returns the named Snd object.
- Parameters:
-
aName is a NSString instance.
- Returns:
- Returns an id. First the named Snd table is searched; if the sound isn't found, then the method looks for “aName.snd” in the sound segment of the application's executable file. Finally, the file is searched for in the following directories (in order):
- ~/Library/Sounds
- /LocalLibrary/Sounds
- /NextLibrary/Sounds
where ~ represents the user's home directory. If the Snd eludes the search, nil is returned.
| + (id) addName: | (NSString *) | name | ||
| sound: | (Snd *) | aSnd | ||
- Parameters:
-
name aSnd
- Returns:
| + (id) addName: | (NSString *) | name | ||
| fromSoundfile: | (NSString *) | filename | ||
- Parameters:
-
name filename
- Returns:
| + (id) addName: | (NSString *) | name | ||
| fromSection: | (NSString *) | sectionName | ||
- Parameters:
-
name sectionName
- Returns:
| + (id) addName: | (NSString *) | aName | ||
| fromBundle: | (NSBundle *) | aBundle | ||
- Parameters:
-
aName aBundle
- Returns:
| + (void) removeSoundForName: | (NSString *) | name |
- Parameters:
-
name
- Returns:
| - (id) initFromSoundfile: | (NSString *) | filename |
Initializes the Snd instance, which must be newly allocated, from the sound file filename.
- Parameters:
-
filename is a NSString instance.
- Returns:
- Returns self (an unnamed Snd) if the file was successfully read; otherwise, frees the newly allocated Snd and returns nil.
- See also:
- +alloc (NSObject), +allocWithZone: (NSObject)
| - (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:, +alloc (NSObject), +allocWithZone: (NSObject)
Reimplemented in SndMP3.
| - (id) initWithFormat: | (SndSampleFormat) | format | ||
| channelCount: | (int) | channels | ||
| frames: | (unsigned long) | frames | ||
| samplingRate: | (float) | samplingRate | ||
Initialise a Snd instance with silence of given format and length.
- Parameters:
-
format is an SndSampleFormat. channels specifies the number of channels (i.e 2 for stereo). frames specifies the number of frames (multiple channel samples) in the sound. samplingRate is a double.
- Returns:
- Returns self.
| - (id) initWithData: | (NSData *) | soundData |
Initialise a Snd instance using a NSData instance which holds audio data in Sun/NeXT .au format.
The data is held with format preceding the PCM audio data. If the sound in the NSData is named, the Snd gets the new name. Currently only reads Sun/NeXT .au format data.
- Parameters:
-
soundData An NSData instance containing preceding sound format data followed by PCM audio data, in Sun/NeXT .au format.
- Returns:
- Returns self if the sound was read successfully, nil otherwise.
| - (void) swapBigEndianToHostFormat |
The swapBigEndianToHostFormat method swaps the byte order of the receiver if it is running on a little-endian (e.g Intel) architecture, and has no effect on a big-endian (e.g Motorola 68k, PPC) architecture.
Note that no checks are done as to whether or not the receiver was already byte-swapped, so you have to keep track of the state of Snd objects yourself.
Always use the appropriate method to convert your Snd objects; either swapBigEndianToHostFormat to convert a Snd from the pasteboard or from a soundfile, or swapHostToBigEndianFormat to prepare a Snd which was in host order to be saved or put onto the pasteboard.
| - (void) swapHostToBigEndianFormat |
The swapHostToBigEndianFormat method swaps the byte order of the receiver if it is running on a little-endian (e.g Intel) architecture, and has no effect on a big-endian (e.g Motorola 68k, PPC) architecture.
Note that no checks are done as to whether or not the receiver was already byte-swapped, so you have to keep track of the state of Snd objects yourself.
Always use the appropriate method to convert your Snd objects; either swapBigEndianToHostFormat to convert a Snd from the pasteboard or from a soundfile, or swapHostToBigEndianFormat to prepare a Snd which was in host order to be saved or put onto the pasteboard.
| - (NSString *) name |
Returns the Snd's name.
- Returns:
- Returns a NSString instance.
| - (id) setName: | (NSString *) | theName |
Sets the Snd's name to aName.
If aName is already being used, then the Snd's name isn't set and NO is returned; otherwise returns YES.
- Parameters:
-
theName is a NSString instance.
- Returns:
- Returns a BOOL.
| - (id) delegate |
Returns the Snd's delegate.
- Returns:
- Returns an id.
| - (void) setDelegate: | (id) | anObject |
Sets the Snd's delegate to anObject.
- Parameters:
-
anObject is an id.
| - (double) samplingRate |
| - (unsigned long) lengthInSampleFrames |
| - (double) duration |
| - (int) channelCount |
| - (NSString *) info |
Returns the Snd's info string.
The Snd's info string is any text description the user of the object wishes to assign to it. It will however, endeavour to be written in an appropriate field to any sound file written from this Snd instance. It will be retrieved from an appropriate field when reading a sound file.
- Returns:
- Returns an NSString.
| - (void) setInfo: | (NSString *) | newInfoString |
Assigns the Snd's info string.
The Snd's info string is any text description the user of the object wishes to assign to it. It will however, endeavour to be written in an appropriate field to any sound file written from this Snd instance.
- Parameters:
-
newInfoString An NSString containing the new text.
| - (BOOL) isEmpty |
| - (BOOL) isEditable |
Returns YES if the Snd's format indicates that it can be edited, otherwise returns NO.
- Returns:
- Returns a BOOL.
| - (BOOL) compatibleWithSound: | (Snd *) | aSound |
Returns YES if the format, sampling rate, and channel count of aSound's sound data is the same as that of the Snd receiving this message.
- Parameters:
-
aSound is an id.
- Returns:
- Returns a BOOL. If one (or both) of the Snds doesn't contain a sound (its soundStruct is nil) then the objects are declared compatible and YES is returned.
| - (int) convertToSampleFormat: | (SndSampleFormat) | newFormat | ||
| samplingRate: | (double) | newRate | ||
| channelCount: | (int) | newChannelCount | ||
Convert the Snd's data to the given format, sampling rate, and number of channels.
- Parameters:
-
newFormat is an SndSampleFormat. newRate is a double. newChannelCount is an int.
- Returns:
- Returns an error code or SND_ERR_NONE if the conversion was performed correctly. The following conversions are possible:
- Arbitrary sampling rate conversion.
- Compression and decompression.
- Floating-point formats (including double-precision) to and from linear formats.
- Mono to stereo.
- CODEC mu-law to and from linear formats.
Reimplemented in SndMP3.
| - (int) convertToSampleFormat: | (SndSampleFormat) | newFormat |
This is the same as convertToSampleFormat:samplingRate:channelCount:, except that only the format is changed.
- Parameters:
-
newFormat is an SndSampleFormat.
- Returns:
- Returns an integer indicating any error or SND_ERR_NONE if the conversion worked. An error code is returned.
| + (SndFormat) nativeFormat |
Returns the native format (sampling rate, resolution and channels) used by the sound playback hardware in streaming audio.
The native format is the format sounds loaded and audio buffers created in which will incur the least processing overhead in order to play. Recording could be in a different format.
- Returns:
- Returns a SndFormat structure.
| - (int) convertToNativeFormat |
| - (id) copyWithZone: | (NSZone *) | zone |
- Parameters:
-
zone is an NSZone.
- Returns:
- Returns a new retained instance with duplicated data, or nil if unable to copy.
| - (NSData *) dataEncodedAsFormat: | (NSString *) | dataFormat |
Creates an NSData instance holding the Snd's name (if any), sample format, and sound data (if any).
- Parameters:
-
dataFormat is an NSString describing the data format.
- Returns:
- Returns an autoreleased NSData instance, or nil if unable to encode. The dataFormat parameter matches sound file extensions. Currently however, all data is encoded as .au format, dataFormat is ignored.
| - (void *) bytes |
Returns a pointer to the Snd's sampled data.
- Returns:
- Returns a void pointer. You can use the pointer to examine, create, and modify the sound data. To intelligently manipulate the data, you need to be aware of its size, format, sampling rate, and the number of channels that it contains (a query method for each of these attributes is provided by the Snd class). The size of the data, in particular, must be respected; it's set when the Snd is created or given a new sound (through readSoundfile:, for example) and can't be changed directly. To resize the data, you should invoke one of the editing methods such as insertSamples:at: or deleteSamplesInRange:.
| - (long) dataSize |
Return the size (in bytes) of the Snd's sample data.
If you modify the data (through the pointer returned by the data method) you must be careful not to exceed its length. If the sound is fragmented, the value returned by this method is still the total size of the Snd's data.
- Returns:
- Returns a long int.
Reimplemented in SndOnDisk.
| - (SndSampleFormat) dataFormat |
Returns the format of the Snd's data.
- Returns:
- Returns an SndSampleFormat. If the data is fragmented, the format of the samples is returned (in other words, SND_FORMAT_INDIRECT is never returned by this method).
Reimplemented in SndMP3.
| - (BOOL) hasSameFormatAsBuffer: | (SndAudioBuffer *) | buff |
Returns YES if the Snd's dataFormat, channelCount and sampling rate match the given SndAudioBuffer instance.
- Parameters:
-
buff The SndAudioBuffer instance to compare.
- Returns:
- Returns a BOOL. The number of frames are not compared.
| - (SndFormat) format |
| - (NSString *) formatDescription |
Returns a string describing the data format in a textual description.
Returns a NSString instance.
| - (int) processingError |
Returns a constant that represents the last error that was generated.
- Returns:
- Returns an int. The sound error codes are listed in “Types and Constants.”
| - (Snd *) soundBeingProcessed |
Returns the Snd object that's being performed.
- Returns:
- Returns an id. The default implementation always returns self.
| - (void) tellDelegate: | (SEL) | theMessage |
Sends theMessage to the Snd's delegate (only sent if the delegate implements theMessage).
- Parameters:
-
theMessage is a SEL. You never invoke this method directly; it's invoked automatically as the result of activities such as recording and playing. However, you can use it in designing a subclass of Snd.
| - (void) tellDelegate: | (SEL) | theMessage | ||
| duringPerformance: | (SndPerformance *) | performance | ||
Sends theMessage to the Snd's delegate (only sent if the delegate implements theMessage).
You never invoke this method directly; it's invoked automatically as the result of activities such as recording and playing. However, you can use it in designing a subclass of Snd.
- Parameters:
-
theMessage is a SEL. performance The performance playing when the message is sent.
| - (void) tellDelegateString: | (NSString *) | theMessage | ||
| duringPerformance: | (SndPerformance *) | performance | ||
Sends theMessage to the Snd's delegate (only sent if the delegate implements theMessage).
You never invoke this method directly; it's invoked automatically as the result of activities such as recording and playing. However, you can use it in designing a subclass of Snd.
- Parameters:
-
theMessage is an NSString, which will be converted to a SEL. performance The performance playing when the message is sent.
| - (void) setConversionQuality: | (SndConversionQuality) | quality |
Sets the conversion quality performed by convertToSampleFormat:.
Default is SndConvertLowQuality.
- Parameters:
-
quality Sets the conversion quality to a SndConversionQuality enumerated type.
| - (SndConversionQuality) conversionQuality |
Returns the current conversion quality performed by convertToSampleFormat:.
- Returns:
- Returns a SndConversionQuality enumerated type.
| - (id) initWithAudioBuffer: | (SndAudioBuffer *) | aBuffer |
Initialises a Snd instance from the provided SndAudioBuffer.
- Parameters:
-
aBuffer the SndAudioBuffer object from which to copy the data
- Returns:
- self
| - (void) normalise |
Normalises the amplitude of the entire sound.
The highest amplitude sample in the sound is scaled to be the maximum resolution.
| - (double) maximumAmplitude |
Returns the maximum amplitude of the format, that is, the maximum positive value of a sample.
- Returns:
- Returns the maximum value of a sample.
Member Data Documentation
- (NSMutableArray*) soundBuffers [protected] |
An array of SndAudioBuffers, the number of elements will depend on the fragmentation.
- (SndFormat) soundFormat [protected] |
The parameters defining the format of the sound.
- (NSString*) info [protected] |
A descriptive information string read from a sound file.
- (int) priority [protected] |
The priority of the sound - currently unused.
- (id) delegate [protected] |
The target of notification messages
- (NSString*) name [protected] |
The name of the sound, typically less verbose than the info string which can be descriptive.
- (int) currentError [protected] |
The code of the most recently occurring error. Zero if no error.
- (SndConversionQuality) conversionQuality [protected] |
Determines quality of sampling rate conversion - see quality defines
- (NSMutableArray*) performancesArray [protected] |
An array of all active AND pending performances of this Snd
- (NSLock*) performancesArrayLock [protected] |
An NSLock to protect the performancesArray when playing.
- (NSRecursiveLock*) editingLock [protected] |
An NSRecursiveLock to protect concurrent modifying of a sound.
- (BOOL) loopWhenPlaying [protected] |
Indicates whether the default behaviour is to loop when playing. This is set from reading the sound file.
- (long) loopStartIndex [protected] |
The sample the loop begins at. This is just the priming value for each performance.
- (long) loopEndIndex [protected] |
The sample the loop ends at. This is just the priming value for each performance.
- (SndAudioProcessorChain*) audioProcessorChain [protected] |
Typically used to prime a performance of this Snd with a chain of audio effects including volume and balance settings (via it's postFader).
The documentation for this class was generated from the following file:
