MusicKit
0.0.0
|
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. | |
(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. | |
(void) | - lockEditing |
Used to lock Snd instance against editing. | |
(void) | - lockEditing |
Used to lock Snd instance against editing. | |
(void) | - unlockEditing |
Used to unlock Snd instance for editing. | |
(void) | - unlockEditing |
Used to unlock Snd instance for editing. | |
(int) | - deleteSamples |
Deletes all the samples in the Snd's data. | |
(int) | - deleteSamples |
Deletes all the samples in the Snd's data. | |
(int) | - deleteSamplesInRange: |
Deletes a range of samples from the sound: the length of frameRange sample frames are deleted starting with the location of the frameRange (zero-based). | |
(int) | - deleteSamplesInRange: |
Deletes a range of samples from the sound: the length of frameRange sample frames are deleted starting with the location of the frameRange (zero-based). | |
(int) | - insertSamples:at: |
Pastes the sound data in aSound into the Snd receiving this message, starting at the receiving Snd's startSample'th sample (zero-based). | |
(int) | - insertSamples:at: |
Pastes the sound data in aSound into the Snd receiving this message, starting at the receiving Snd's startSample'th sample (zero-based). | |
(Snd *) | - soundFromSamplesInRange: |
Returns a new Snd instance of the same format with a copy of a portion of receivers sound data. | |
(Snd *) | - soundFromSamplesInRange: |
Returns a new Snd instance of the same format with a copy of a portion of receivers sound data. | |
(int) | - compactSamples |
The Snd's sampled data is compacted into a contiguous block, undoing the fragmentation that can occur during editing. | |
(int) | - compactSamples |
The Snd's sampled data is compacted into a contiguous block, undoing the fragmentation that can occur during editing. | |
(BOOL) | - needsCompacting |
Returns YES if the Snd's data is fragmented. Otherwise returns NO. | |
(BOOL) | - needsCompacting |
Returns YES if the Snd's data is fragmented. Otherwise returns NO. | |
(void *) | - fragmentOfFrame:indexInFragment:fragmentLength:dataFormat: |
Get data address and statistics for fragmented or non-fragmented Snds. | |
(void *) | - fragmentOfFrame:indexInFragment:fragmentLength:dataFormat: |
Get data address and statistics for fragmented or non-fragmented Snds. | |
(long) | - fillAudioBuffer:toLength:samplesInRange: |
Copies samples from self into the provided SndAudioBuffer. | |
(long) | - fillAudioBuffer:toLength:samplesInRange: |
Copies samples from self into the provided SndAudioBuffer. | |
(long) | - insertIntoAudioBuffer:intoFrameRange:samplesInRange: |
Copies samples from self into a sub region of the provided SndAudioBuffer. | |
(long) | - insertIntoAudioBuffer:intoFrameRange:samplesInRange: |
Copies samples from self into a sub region of the provided SndAudioBuffer. | |
(long) | - insertAudioBuffer:intoFrameRange: |
Copies in the given SndAudioBuffer into the Snd instance. | |
(long) | - insertAudioBuffer:intoFrameRange: |
Copies in the given SndAudioBuffer into the Snd instance. | |
(long) | - appendAudioBuffer: |
Appends the given SndAudioBuffer to the end of the Snd instance. | |
(long) | - appendAudioBuffer: |
Appends the given SndAudioBuffer to the end of the Snd instance. | |
(SndAudioBuffer *) | - audioBufferForSamplesInRange:looping: |
Returns a SndAudioBuffer containing a range of samples in the Snd. | |
(SndAudioBuffer *) | - audioBufferForSamplesInRange:looping: |
Returns a SndAudioBuffer containing a range of samples in the Snd. | |
(SndAudioBuffer *) | - audioBufferForSamplesInRange: |
Returns a SndAudioBuffer containing a range of samples in the Snd. | |
(SndAudioBuffer *) | - audioBufferForSamplesInRange: |
Returns a SndAudioBuffer containing a range of samples in the Snd. | |
(NSArray *) | - audioBuffers |
Returns an NSArray of SndAudioBuffers comprising the Snd. The array is stored in temporal order. | |
(NSArray *) | - audioBuffers |
Returns an NSArray of SndAudioBuffers comprising the Snd. The array is stored in temporal order. | |
(SndFormat) | - soundFormatOfFilename: |
Returns the format of the data in the named sound file. | |
(SndFormat) | - soundFormatOfFilename: |
Returns the format of the data in the named sound file. | |
(int) | - readSoundfile:startFrame:frameCount: |
Replaces the Snd's contents with a nominated subrange of those of the sound file filename. | |
(int) | - readSoundfile:startFrame:frameCount: |
Replaces the Snd's contents with a nominated subrange of those of the sound file filename. | |
(int) | - readSoundfile: |
Replaces the Snd's contents with those of the sound file filename. | |
(int) | - readSoundfile: |
Replaces the Snd's contents with those of the sound file filename. | |
(int) | - writeSoundfile:fileFormat:dataFormat: |
Writes the Snd's contents (its sample format and sound data) to the sound file filename in the given file format and data encoding. | |
(int) | - writeSoundfile:fileFormat:dataFormat: |
Writes the Snd's contents (its sample format and sound data) to the sound file filename in the given file format and data encoding. | |
(int) | - writeSoundfile: |
Writes the Snd's contents (its sample format and sound data) to the sound file filename. | |
(int) | - writeSoundfile: |
Writes the Snd's contents (its sample format and sound data) to the sound file filename. | |
(id) | - initFromPasteboard: |
Initializes the Snd instance, which must be newly allocated, by copying the sound data from the Pasteboard object thePboard. | |
(id) | - initFromPasteboard: |
Initializes the Snd instance, which must be newly allocated, by copying the sound data from the Pasteboard object thePboard. | |
(void) | - writeToPasteboard: |
Puts a copy of the Snd's contents (its sample format and sound data) on the pasteboard maintained by the NSPasteboard object thePboard. | |
(void) | - writeToPasteboard: |
Puts a copy of the Snd's contents (its sample format and sound data) on the pasteboard maintained by the NSPasteboard object thePboard. | |
(int) | - waitUntilStopped |
If the Snd is currently playing or recording, waits until the sound has finished playing or recording, at which time it returns the result of the SNDWait() function. | |
(int) | - waitUntilStopped |
If the Snd is currently playing or recording, waits until the sound has finished playing or recording, at which time it returns the result of the SNDWait() function. | |
(void) | - stop: |
Action method that stops the Snd's playback or recording. | |
(void) | - stop: |
Action method that stops the Snd's playback or recording. | |
(int) | - stop |
Terminates the Snd's playback or recording. | |
(int) | - stop |
Terminates the Snd's playback or recording. | |
(id) | - pause: |
Action method that pauses the Snd. | |
(id) | - pause: |
Action method that pauses the Snd. | |
(int) | - pause |
Pauses the Snd during recording or playback. | |
(int) | - pause |
Pauses the Snd during recording or playback. | |
(id) | - resume: |
Action method that resumes the paused Snd. | |
(id) | - resume: |
Action method that resumes the paused Snd. | |
(int) | - resume |
Resumes the paused Snd's activity. | |
(int) | - resume |
Resumes the paused Snd's activity. | |
(BOOL) | - isPlayable |
Returns YES if the Snd can be played, otherwise returns NO. | |
(BOOL) | - isPlayable |
Returns YES if the Snd can be played, otherwise returns NO. | |
(BOOL) | - isPlaying |
Returns YES if the Snd is currently playing one or more performances, otherwise returns NO. | |
(BOOL) | - isPlaying |
Returns YES if the Snd is currently playing one or more performances, otherwise returns NO. | |
(SndPerformance *) | - play |
Play the entire sound now. | |
(SndPerformance *) | - play |
Play the entire sound now. | |
(SndPerformance *) | - play: |
Play the entire sound now, for use as an action method. | |
(SndPerformance *) | - play: |
Play the entire sound now, for use as an action method. | |
(SndPerformance *) | - playInFuture:beginSample:sampleCount: |
Begin playback at some time in the future, over a region of the sound. | |
(SndPerformance *) | - playInFuture:beginSample:sampleCount: |
Begin playback at some time in the future, over a region of the sound. | |
(SndPerformance *) | - playInFuture:startPositionInSeconds:durationInSeconds: |
Begin playback at some time in the future, over a region of the sound. | |
(SndPerformance *) | - playInFuture:startPositionInSeconds:durationInSeconds: |
Begin playback at some time in the future, over a region of the sound. | |
(SndPerformance *) | - playAtTimeInSeconds:withDurationInSeconds: |
Begin playback at a certain absolute stream time, for a certain duration. | |
(SndPerformance *) | - playAtTimeInSeconds:withDurationInSeconds: |
Begin playback at a certain absolute stream time, for a certain duration. | |
(SndPerformance *) | - play:beginSample:sampleCount: |
Begin playback now, over a region of the sound. | |
(SndPerformance *) | - play:beginSample:sampleCount: |
Begin playback now, over a region of the sound. | |
(SndPerformance *) | - playInFuture: |
Begin the playback of the sound at some future time, specified in seconds. | |
(SndPerformance *) | - playInFuture: |
Begin the playback of the sound at some future time, specified in seconds. | |
(SndPerformance *) | - playAtDate: |
Begin the playback of the sound at a specified date. | |
(SndPerformance *) | - playAtDate: |
Begin the playback of the sound at a specified date. | |
(id) | - record: |
(id) | - record: |
(int) | - record |
Initiate recording into the Snd. | |
(int) | - record |
Initiate recording into the Snd. | |
(BOOL) | - isRecording |
Returns whether the Snd instance is currently recording audio into the sound. | |
(BOOL) | - isRecording |
Returns whether the Snd instance is currently recording audio into the sound. | |
(int) | - samplesPerformedOfPerformance: |
If the Snd is currently playing or recording, this returns the number of sample frames that have been played or recorded so far. | |
(int) | - samplesPerformedOfPerformance: |
If the Snd is currently playing or recording, this returns the number of sample frames that have been played or recorded so far. | |
(NSArray *) | - performances |
Performance array accessor. | |
(NSArray *) | - performances |
Performance array accessor. | |
(id) | - addPerformance: |
Adds a performance to the performance array. | |
(id) | - addPerformance: |
Adds a performance to the performance array. | |
(id) | - removePerformance: |
Removes a performance from the performance array. | |
(id) | - removePerformance: |
Removes a performance from the performance array. | |
(int) | - performanceCount |
Returns the number of active AND pending performances. | |
(int) | - performanceCount |
Returns the number of active AND pending performances. | |
(void) | - setLoopWhenPlaying: |
Sets the default behaviour whether to loop during play. | |
(void) | - setLoopWhenPlaying: |
Sets the default behaviour whether to loop during play. | |
(void) | - setLoopStartIndex: |
Sets the sample to stop playing at. | |
(void) | - setLoopStartIndex: |
Sets the sample to stop playing at. | |
(void) | - setLoopEndIndex: |
Sets the sample at which the performance loops back to the start index (set using setLoopStartIndex:). | |
(void) | - setLoopEndIndex: |
Sets the sample at which the performance loops back to the start index (set using setLoopStartIndex:). | |
(void) | - setAudioProcessorChain: |
Assigns the audioProcessorChain to this Snd instance. | |
(void) | - setAudioProcessorChain: |
Assigns the audioProcessorChain to this Snd instance. | |
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. | |
(SndFormat) | + nativeFormatForOutput: |
Returns the native format (sampling rate, resolution and channels) used by the sound playback or input hardware in streaming audio. | |
(SndFormat) | + nativeInputFormat |
Returns the native format (sampling rate, resolution and channels) used by the sound input hardware in streaming audio. | |
(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. | |
(SndFormat) | + nativeFormatForOutput: |
Returns the native format (sampling rate, resolution and channels) used by the sound playback or input hardware in streaming audio. | |
(SndFormat) | + nativeInputFormat |
Returns the native format (sampling rate, resolution and channels) used by the sound input hardware in streaming audio. | |
(NSArray *) | + soundFileExtensions |
Returns an array of valid file extensions available for reading and writing. | |
(NSArray *) | + soundFileExtensions |
Returns an array of valid file extensions available for reading and writing. | |
(BOOL) | + isPathForSoundFile: |
(BOOL) | + isPathForSoundFile: |
(NSString *) | + defaultFileExtension |
Returns the extension of the standard file format. This may differ between platforms. | |
(NSString *) | + defaultFileExtension |
Returns the extension of the standard file format. This may differ between platforms. | |
(BOOL) | + isMuted |
Returns YES if the sound output of all playing sounds is currently muted. | |
(BOOL) | + isMuted |
Returns YES if the sound output of all playing sounds is currently muted. | |
(id) | + setMute: |
Mutes and unmutes the sound output level of all playing sounds if aFlag is YES or NO, respectively. | |
(id) | + setMute: |
Mutes and unmutes the sound output level of all playing sounds if aFlag is YES or NO, respectively. | |
(void) | + stopPerformance:inFuture: |
Stop the given playback of the sound at some future time, specified in seconds. | |
(void) | + stopPerformance:inFuture: |
Stop the given playback of the sound at some future time, specified in seconds. | |
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 |
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.
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).
+ (id) addName: | (NSString *) | aName | |
fromBundle: | (NSBundle *) | aBundle | |
aName | |
aBundle |
+ (id) addName: | (NSString *) | aName | |
fromBundle: | (NSBundle *) | aBundle | |
aName | |
aBundle |
+ (id) addName: | (NSString *) | name | |
fromSection: | (NSString *) | sectionName | |
name | |
sectionName |
+ (id) addName: | (NSString *) | name | |
fromSection: | (NSString *) | sectionName | |
name | |
sectionName |
+ (id) addName: | (NSString *) | name | |
fromSoundfile: | (NSString *) | filename | |
name | |
filename |
+ (id) addName: | (NSString *) | name | |
fromSoundfile: | (NSString *) | filename | |
name | |
filename |
+ (id) addName: | (NSString *) | name | |
sound: | (Snd *) | aSnd | |
name | |
aSnd |
+ (id) addName: | (NSString *) | name | |
sound: | (Snd *) | aSnd | |
name | |
aSnd |
- (id) addPerformance: | (SndPerformance *) | p |
Adds a performance to the performance array.
Mainly for use by SndPlayer.
p | A performance |
- (id) addPerformance: | (SndPerformance *) | p |
Adds a performance to the performance array.
Mainly for use by SndPlayer.
p | A performance |
- (long) appendAudioBuffer: | (SndAudioBuffer *) | buffer |
Appends the given SndAudioBuffer to the end of the Snd instance.
buffer | The SndAudioBuffer to copy sound from. |
- (long) appendAudioBuffer: | (SndAudioBuffer *) | buffer |
Appends the given SndAudioBuffer to the end of the Snd instance.
buffer | The SndAudioBuffer to copy sound from. |
- (SndAudioBuffer *) audioBufferForSamplesInRange: | (NSRange) | r |
Returns a SndAudioBuffer containing a range of samples in the Snd.
r | Range of sample frames (as opposed to individual single channel samples) to stick into the audioBuffer |
- (SndAudioBuffer *) audioBufferForSamplesInRange: | (NSRange) | r |
Returns a SndAudioBuffer containing a range of samples in the Snd.
r | Range of sample frames (as opposed to individual single channel samples) to stick into the audioBuffer |
- (SndAudioBuffer *) audioBufferForSamplesInRange: | (NSRange) | sndFrameRange | |
looping: | (BOOL) | isLooping | |
Returns a SndAudioBuffer containing a range of samples in the Snd.
sndFrameRange | Range of sample frames (as opposed to individual single channel samples) to stick into the audioBuffer. |
isLooping | Indicates whether to read from the loop start if the length of the sndFrameRange exceeds the length of the Snd instance. |
- (SndAudioBuffer *) audioBufferForSamplesInRange: | (NSRange) | sndFrameRange | |
looping: | (BOOL) | isLooping | |
Returns a SndAudioBuffer containing a range of samples in the Snd.
sndFrameRange | Range of sample frames (as opposed to individual single channel samples) to stick into the audioBuffer. |
isLooping | Indicates whether to read from the loop start if the length of the sndFrameRange exceeds the length of the Snd instance. |
- (NSArray *) audioBuffers |
Returns an NSArray of SndAudioBuffers comprising the Snd. The array is stored in temporal order.
- (NSArray *) audioBuffers |
Returns an NSArray of SndAudioBuffers comprising the Snd. The array is stored in temporal order.
- (void *) bytes |
Returns a pointer to the Snd's sampled data.
To start with a new, unfragmented sound with a determinate length, invoke the initWithFormat:channelCount:frames:samplingRate: method. Keep in mind that the sound data in a fragmented sound is an NSArray of SndAudioBuffers, one for each fragment. To examine or manipulate the samples in a fragmented sound, you should retrieve the audio buffers array using audioBuffers.
- (void *) bytes |
Returns a pointer to the Snd's sampled data.
To start with a new, unfragmented sound with a determinate length, invoke the initWithFormat:channelCount:frames:samplingRate: method. Keep in mind that the sound data in a fragmented sound is an NSArray of SndAudioBuffers, one for each fragment. To examine or manipulate the samples in a fragmented sound, you should retrieve the audio buffers array using audioBuffers.
- (int) channelCount |
- (int) channelCount |
- (int) compactSamples |
The Snd's sampled data is compacted into a contiguous block, undoing the fragmentation that can occur during editing.
- (int) compactSamples |
The Snd's sampled data is compacted into a contiguous block, undoing the fragmentation that can occur during editing.
- (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.
aSound | is an id. |
- (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.
aSound | is an id. |
- (SndConversionQuality) conversionQuality |
Returns the current conversion quality performed by convertToSampleFormat:
- (SndConversionQuality) conversionQuality |
Returns the current conversion quality performed by convertToSampleFormat:
- (int) convertToNativeFormat |
- (int) convertToNativeFormat |
- (int) convertToSampleFormat: | (SndSampleFormat) | newFormat |
This is the same as convertToSampleFormat:samplingRate:channelCount:, except that only the format is changed.
newFormat | is an SndSampleFormat. |
- (int) convertToSampleFormat: | (SndSampleFormat) | newFormat |
This is the same as convertToSampleFormat:samplingRate:channelCount:, except that only the format is changed.
newFormat | is an SndSampleFormat. |
- (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.
newFormat | is an SndSampleFormat. |
newRate | is a double. |
newChannelCount | is an int. |
- (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.
newFormat | is an SndSampleFormat. |
newRate | is a double. |
newChannelCount | is an int. |
- (id) copyWithZone: | (NSZone *) | zone |
zone | is an NSZone. |
- (id) copyWithZone: | (NSZone *) | zone |
zone | is an NSZone. |
- (NSData *) dataEncodedAsFormat: | (NSString *) | dataFormat |
Creates an NSData instance holding the Snd's name (if any), sample format, and sound data (if any).
dataFormat | is an NSString describing the data format. |
- (NSData *) dataEncodedAsFormat: | (NSString *) | dataFormat |
Creates an NSData instance holding the Snd's name (if any), sample format, and sound data (if any).
dataFormat | is an NSString describing the data format. |
- (SndSampleFormat) dataFormat |
- (SndSampleFormat) dataFormat |
- (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.
- (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.
- (int) deleteSamples |
- (int) deleteSamples |
- (int) deleteSamplesInRange: | (NSRange) | frameRange |
Deletes a range of samples from the sound: the length of frameRange sample frames are deleted starting with the location of the frameRange (zero-based).
frameRange | is an NSRange giving the range of frames to delete. |
- (int) deleteSamplesInRange: | (NSRange) | frameRange |
Deletes a range of samples from the sound: the length of frameRange sample frames are deleted starting with the location of the frameRange (zero-based).
frameRange | is an NSRange giving the range of frames to delete. |
- (double) duration |
- (double) duration |
- (long) fillAudioBuffer: | (SndAudioBuffer *) | buff | |
toLength: | (long) | fillLength | |
samplesInRange: | (NSRange) | sndReadingRange | |
Copies samples from self into the provided SndAudioBuffer.
The SndAudioBuffer's data object's size is decreased if less than fillLength number of samples can be read. The buffer is not expanded.
buff | The SndAudioBuffer object into which to copy the data. |
fillLength | The number of sample frames in the buffer to copy into. |
sndReadingRange | The sample frame in the Snd to start reading from and maximum length of samples readable. |
- (long) fillAudioBuffer: | (SndAudioBuffer *) | buff | |
toLength: | (long) | fillLength | |
samplesInRange: | (NSRange) | sndReadingRange | |
Copies samples from self into the provided SndAudioBuffer.
The SndAudioBuffer's data object's size is decreased if less than fillLength number of samples can be read. The buffer is not expanded.
buff | The SndAudioBuffer object into which to copy the data. |
fillLength | The number of sample frames in the buffer to copy into. |
sndReadingRange | The sample frame in the Snd to start reading from and maximum length of samples readable. |
+ (id) findSoundFor: | (NSString *) | aName |
Finds and returns the named Snd object.
aName | is a NSString instance. |
where ~ represents the user's home directory. If the Snd eludes the search, nil is returned.
+ (id) findSoundFor: | (NSString *) | aName |
Finds and returns the named Snd object.
aName | is a NSString instance. |
where ~ represents the user's home directory. If the Snd eludes the search, nil is returned.
- (NSString *) formatDescription |
Returns a string describing the data format in a textual description.
Returns a NSString instance.
- (NSString *) formatDescription |
Returns a string describing the data format in a textual description.
Returns a NSString instance.
- (void *) fragmentOfFrame: | (unsigned long) | frame | |
indexInFragment: | (unsigned long *) | currentFrame | |
fragmentLength: | (unsigned long *) | fragmentLength | |
dataFormat: | (SndSampleFormat *) | dataFormat | |
Get data address and statistics for fragmented or non-fragmented Snds.
fragmentOfFrame:indexInFragment:fragmentLength:dataFormat: For fragmented sounds, you often need to be able to find the SndAudioBuffer of data that a certain frame resides in. You then often need to know which is the last frame in that fragment (audio buffer), indexed from the start of the block.
frame | The index of the sample you wish to find the block for, indexed from the beginning of the sound |
currentFrame | Returns by reference the index of the frame supplied, indexed from the start of the block |
fragmentLength | Returns by reference the length the block, indexed from the start of the block |
dataFormat | Returns by reference the format of the data. This will normally be the same as the Snd's dataFormat, but can differ if the format is encoded with compression. |
- (void *) fragmentOfFrame: | (unsigned long) | frame | |
indexInFragment: | (unsigned long *) | currentFrame | |
fragmentLength: | (unsigned long *) | fragmentLength | |
dataFormat: | (SndSampleFormat *) | dataFormat | |
Get data address and statistics for fragmented or non-fragmented Snds.
fragmentOfFrame:indexInFragment:fragmentLength:dataFormat: For fragmented sounds, you often need to be able to find the SndAudioBuffer of data that a certain frame resides in. You then often need to know which is the last frame in that fragment (audio buffer), indexed from the start of the block.
frame | The index of the sample you wish to find the block for, indexed from the beginning of the sound |
currentFrame | Returns by reference the index of the frame supplied, indexed from the start of the block |
fragmentLength | Returns by reference the length the block, indexed from the start of the block |
dataFormat | Returns by reference the format of the data. This will normally be the same as the Snd's dataFormat, but can differ if the format is encoded with compression. |
- (BOOL) hasSameFormatAsBuffer: | (SndAudioBuffer *) | buff |
Returns YES if the Snd's dataFormat, channelCount and sampling rate match the given SndAudioBuffer instance.
buff | The SndAudioBuffer instance to compare. |
- (BOOL) hasSameFormatAsBuffer: | (SndAudioBuffer *) | buff |
Returns YES if the Snd's dataFormat, channelCount and sampling rate match the given SndAudioBuffer instance.
buff | The SndAudioBuffer instance to compare. |
- (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.
- (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.
- (id) initFromPasteboard: | (NSPasteboard *) | thePboard |
Initializes the Snd instance, which must be newly allocated, by copying the sound data from the Pasteboard object thePboard.
thePboard | is a NSPasteboard *. |
- (id) initFromPasteboard: | (NSPasteboard *) | thePboard |
Initializes the Snd instance, which must be newly allocated, by copying the sound data from the Pasteboard object thePboard.
thePboard | is a NSPasteboard *. |
- (id) initFromSoundfile: | (NSString *) | filename |
Initializes the Snd instance, which must be newly allocated, from the sound file filename.
filename | is a NSString instance. |
- (id) initFromSoundfile: | (NSString *) | filename |
Initializes the Snd instance, which must be newly allocated, from the sound file filename.
filename | is a NSString instance. |
- (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.
url | is a NSURL instance. |
- (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.
url | is a NSURL instance. |
- (id) initWithAudioBuffer: | (SndAudioBuffer *) | aBuffer |
Initialises a Snd instance from the provided SndAudioBuffer.
aBuffer | the SndAudioBuffer object from which to copy the data |
- (id) initWithAudioBuffer: | (SndAudioBuffer *) | aBuffer |
Initialises a Snd instance from the provided SndAudioBuffer.
aBuffer | the SndAudioBuffer object from which to copy the data |
- (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.
soundData | An NSData instance containing preceding sound format data followed by PCM audio data, in Sun/NeXT .au format. |
- (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.
soundData | An NSData instance containing preceding sound format data followed by PCM audio data, in Sun/NeXT .au format. |
- (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.
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. |
- (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.
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. |
- (long) insertAudioBuffer: | (SndAudioBuffer *) | buffer | |
intoFrameRange: | (NSRange) | writeIntoSndFrameRange | |
Copies in the given SndAudioBuffer into the Snd instance.
buffer | The SndAudioBuffer to copy sound from. |
writeIntoSndFrameRange | The range of frames to copy. Can not be longer than the buffer. |
- (long) insertAudioBuffer: | (SndAudioBuffer *) | buffer | |
intoFrameRange: | (NSRange) | writeIntoSndFrameRange | |
Copies in the given SndAudioBuffer into the Snd instance.
buffer | The SndAudioBuffer to copy sound from. |
writeIntoSndFrameRange | The range of frames to copy. Can not be longer than the buffer. |
- (long) insertIntoAudioBuffer: | (SndAudioBuffer *) | buff | |
intoFrameRange: | (NSRange) | bufferFrameRange | |
samplesInRange: | (NSRange) | sndFrameRange | |
Copies samples from self into a sub region of the provided SndAudioBuffer.
If the buffer and the Snd instance have different formats, a format conversion will be performed to the buffers format, including resampling if necessary.
The Snd 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 Snd 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.
buff | 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. |
sndFrameRange | 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. |
- (long) insertIntoAudioBuffer: | (SndAudioBuffer *) | buff | |
intoFrameRange: | (NSRange) | bufferFrameRange | |
samplesInRange: | (NSRange) | sndFrameRange | |
Copies samples from self into a sub region of the provided SndAudioBuffer.
If the buffer and the Snd instance have different formats, a format conversion will be performed to the buffers format, including resampling if necessary.
The Snd 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 Snd 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.
buff | 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. |
sndFrameRange | 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. |
- (int) insertSamples: | (Snd *) | aSnd | |
at: | (int) | startSample | |
Pastes the sound data in aSound into the Snd receiving this message, starting at the receiving Snd's startSample'th sample (zero-based).
aSound | is an id. |
startSample | is an int. |
- (int) insertSamples: | (Snd *) | aSnd | |
at: | (int) | startSample | |
Pastes the sound data in aSound into the Snd receiving this message, starting at the receiving Snd's startSample'th sample (zero-based).
aSound | is an id. |
startSample | is an int. |
- (BOOL) isEditable |
Returns YES if the Snd's format indicates that it can be edited, otherwise returns NO.
- (BOOL) isEditable |
Returns YES if the Snd's format indicates that it can be edited, otherwise returns NO.
- (BOOL) isEmpty |
- (BOOL) isEmpty |
+ (BOOL) isMuted |
Returns YES if the sound output of all playing sounds is currently muted.
+ (BOOL) isMuted |
Returns YES if the sound output of all playing sounds is currently muted.
+ (BOOL) isPathForSoundFile: | (NSString *) | path |
path | A file path |
+ (BOOL) isPathForSoundFile: | (NSString *) | path |
path | A file path |
- (BOOL) isPlayable |
Returns YES if the Snd can be played, otherwise returns NO.
- (BOOL) isPlayable |
Returns YES if the Snd can be played, otherwise returns NO.
- (BOOL) isPlaying |
Returns YES if the Snd is currently playing one or more performances, otherwise returns NO.
- (BOOL) isPlaying |
Returns YES if the Snd is currently playing one or more performances, otherwise returns NO.
- (BOOL) isRecording |
Returns whether the Snd instance is currently recording audio into the sound.
- (BOOL) isRecording |
Returns whether the Snd instance is currently recording audio into the sound.
- (unsigned long) lengthInSampleFrames |
- (unsigned long) lengthInSampleFrames |
- (void) lockEditing |
Used to lock Snd instance against editing.
See also -unlockEditing for the complementary method to match with.
- (void) lockEditing |
Used to lock Snd instance against editing.
See also -unlockEditing for the complementary method to match with.
- (double) maximumAmplitude |
Returns the maximum amplitude of the format, that is, the maximum positive value of a sample.
- (double) maximumAmplitude |
Returns the maximum amplitude of the format, that is, the maximum positive value of a sample.
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 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.
+ (SndFormat) nativeFormatForOutput: | (BOOL) | forOutputDevices |
Returns the native format (sampling rate, resolution and channels) used by the sound playback or input 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 or record. Playback and recording can be in a different format, the direction is determined by the forOutputDevices boolean parameter.
forOutputDevices | YES to return the native format of playback hardware, NO to return the native format of input hardware. |
+ (SndFormat) nativeFormatForOutput: | (BOOL) | forOutputDevices |
Returns the native format (sampling rate, resolution and channels) used by the sound playback or input 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 or record. Playback and recording can be in a different format, the direction is determined by the forOutputDevices boolean parameter.
forOutputDevices | YES to return the native format of playback hardware, NO to return the native format of input hardware. |
Returns the native format (sampling rate, resolution and channels) used by the sound input 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 record. Playback could be in a different format.
Returns the native format (sampling rate, resolution and channels) used by the sound input 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 record. Playback could be in a different format.
- (BOOL) needsCompacting |
Returns YES if the Snd's data is fragmented. Otherwise returns NO.
- (BOOL) needsCompacting |
Returns YES if the Snd's data is fragmented. Otherwise returns NO.
- (void) normalise |
Normalises the amplitude of the entire sound.
The highest amplitude sample in the sound is scaled to be the maximum resolution.
- (void) normalise |
Normalises the amplitude of the entire sound.
The highest amplitude sample in the sound is scaled to be the maximum resolution.
- (id) pause: | (id) | sender |
Action method that pauses the Snd.
sender | is an id. Other than the argument and the return type, this is the same as the pause method. |
- (id) pause: | (id) | sender |
Action method that pauses the Snd.
sender | is an id. Other than the argument and the return type, this is the same as the pause method. |
- (int) performanceCount |
- (int) performanceCount |
- (NSArray*) performances |
- (NSArray*) performances |
- (SndPerformance *) play |
Play the entire sound now.
The method returns immediately while the playback continues asynchronously in the background. The playback ends when the Snd receives the stop message, or when its data is exhausted.
When playback starts, willPlay: is sent to the Snd's delegate; when it stops, didPlay: is sent.
Warning: For this method to work properly, the main event loop must not be blocked.
- (SndPerformance *) play |
Play the entire sound now.
The method returns immediately while the playback continues asynchronously in the background. The playback ends when the Snd receives the stop message, or when its data is exhausted.
When playback starts, willPlay: is sent to the Snd's delegate; when it stops, didPlay: is sent.
Warning: For this method to work properly, the main event loop must not be blocked.
- (SndPerformance *) play: | (id) | sender |
Play the entire sound now, for use as an action method.
sender | The sending object. |
- (SndPerformance *) play: | (id) | sender |
Play the entire sound now, for use as an action method.
sender | The sending object. |
- (SndPerformance *) play: | (id) | sender | |
beginSample: | (int) | begin | |
sampleCount: | (int) | count | |
Begin playback now, over a region of the sound.
This is a deprecated method for SoundKit compatability. You should use playInFuture:beginSample:sampleCount: instead.
begin | The sample number to begin playing from. Use 0 to play from the start of the sound. |
count | The number of samples to play. Use sampleCount to play the entire sound. |
- (SndPerformance *) play: | (id) | sender | |
beginSample: | (int) | begin | |
sampleCount: | (int) | count | |
Begin playback now, over a region of the sound.
This is a deprecated method for SoundKit compatability. You should use playInFuture:beginSample:sampleCount: instead.
begin | The sample number to begin playing from. Use 0 to play from the start of the sound. |
count | The number of samples to play. Use sampleCount to play the entire sound. |
- (SndPerformance *) playAtDate: | (NSDate *) | date |
Begin the playback of the sound at a specified date.
date | The date to begin playback. |
- (SndPerformance *) playAtDate: | (NSDate *) | date |
Begin the playback of the sound at a specified date.
date | The date to begin playback. |
- (SndPerformance *) playAtTimeInSeconds: | (double) | t | |
withDurationInSeconds: | (double) | d | |
Begin playback at a certain absolute stream time, for a certain duration.
t | Start time in seconds |
d | Duration in seconds |
- (SndPerformance *) playAtTimeInSeconds: | (double) | t | |
withDurationInSeconds: | (double) | d | |
Begin playback at a certain absolute stream time, for a certain duration.
t | Start time in seconds |
d | Duration in seconds |
- (SndPerformance *) playInFuture: | (double) | inSeconds |
Begin the playback of the sound at some future time, specified in seconds.
inSeconds | The number of seconds beyond the current time point to begin playback. |
- (SndPerformance *) playInFuture: | (double) | inSeconds |
Begin the playback of the sound at some future time, specified in seconds.
inSeconds | The number of seconds beyond the current time point to begin playback. |
- (SndPerformance *) playInFuture: | (double) | inSeconds | |
beginSample: | (unsigned long) | begin | |
sampleCount: | (unsigned long) | count | |
Begin playback at some time in the future, over a region of the sound.
inSeconds | The number of seconds beyond the current time point to begin playback. |
begin | The sample number to begin playing from. Use 0 to play from the start of the sound. |
count | The number of samples to play. Use sampleCount to play the entire sound. |
- (SndPerformance *) playInFuture: | (double) | inSeconds | |
beginSample: | (unsigned long) | begin | |
sampleCount: | (unsigned long) | count | |
Begin playback at some time in the future, over a region of the sound.
inSeconds | The number of seconds beyond the current time point to begin playback. |
begin | The sample number to begin playing from. Use 0 to play from the start of the sound. |
count | The number of samples to play. Use sampleCount to play the entire sound. |
- (SndPerformance *) playInFuture: | (double) | inSeconds | |
startPositionInSeconds: | (double) | startPosition | |
durationInSeconds: | (double) | duration | |
Begin playback at some time in the future, over a region of the sound.
inSeconds | The number of seconds beyond the current time point to begin playback. |
startPosition | The time in seconds in the Snd to begin playing from. Use 0.0 to play from the start of the sound. |
duration | The duration of the Snd to play in seconds. Use -[Snd duration] to play the entire sound. |
- (SndPerformance *) playInFuture: | (double) | inSeconds | |
startPositionInSeconds: | (double) | startPosition | |
durationInSeconds: | (double) | duration | |
Begin playback at some time in the future, over a region of the sound.
inSeconds | The number of seconds beyond the current time point to begin playback. |
startPosition | The time in seconds in the Snd to begin playing from. Use 0.0 to play from the start of the sound. |
duration | The duration of the Snd to play in seconds. Use -[Snd duration] to play the entire sound. |
- (int) processingError |
Returns a constant that represents the last error that was generated.
- (int) processingError |
Returns a constant that represents the last error that was generated.
- (int) readSoundfile: | (NSString *) | filename |
- (int) readSoundfile: | (NSString *) | filename |
- (int) readSoundfile: | (NSString *) | filename | |
startFrame: | (unsigned long) | startFrame | |
frameCount: | (long) | frameCount | |
Replaces the Snd's contents with a nominated subrange of those of the sound file filename.
filename | is a NSString instance. |
startFrame | The frame in the file to read from. |
frameCount | Number of frames to read, -1 = read to EOF marker. |
- (int) readSoundfile: | (NSString *) | filename | |
startFrame: | (unsigned long) | startFrame | |
frameCount: | (long) | frameCount | |
Replaces the Snd's contents with a nominated subrange of those of the sound file filename.
filename | is a NSString instance. |
startFrame | The frame in the file to read from. |
frameCount | Number of frames to read, -1 = read to EOF marker. |
- (int) record |
Initiate recording into the Snd.
The method returns immediately while the recording continues asynchronously in the background. The recording stops when the Snd receives the stop message or when the recording has gone on for the duration of the original sound data. The default CODEC recording lasts precisely ten minutes if not stopped. To record for a longer time, first increase the size of the sound data with initWithFormat:channelCount:frames:samplingRate:.
When the recording begins, willRecord: is sent to the Snd's delegate; when the recording stops, didRecord: is sent.
Warning: For this method to work properly, the main event loop must not be blocked.
- (int) record |
Initiate recording into the Snd.
The method returns immediately while the recording continues asynchronously in the background. The recording stops when the Snd receives the stop message or when the recording has gone on for the duration of the original sound data. The default CODEC recording lasts precisely ten minutes if not stopped. To record for a longer time, first increase the size of the sound data with initWithFormat:channelCount:frames:samplingRate:.
When the recording begins, willRecord: is sent to the Snd's delegate; when the recording stops, didRecord: is sent.
Warning: For this method to work properly, the main event loop must not be blocked.
- (id) record: | (id) | sender |
sender |
- (id) record: | (id) | sender |
sender |
- (id) removePerformance: | (SndPerformance *) | p |
Removes a performance from the performance array.
Mainly for use by SndPlayer.
p | A performance to be removed. |
- (id) removePerformance: | (SndPerformance *) | p |
Removes a performance from the performance array.
Mainly for use by SndPlayer.
p | A performance to be removed. |
+ (void) removeSoundForName: | (NSString *) | name |
name |
+ (void) removeSoundForName: | (NSString *) | name |
name |
- (int) samplesPerformedOfPerformance: | (SndPerformance *) | performance |
If the Snd is currently playing or recording, this returns the number of sample frames that have been played or recorded so far.
performance | The SndPerformance of which to enquire. |
- (int) samplesPerformedOfPerformance: | (SndPerformance *) | performance |
If the Snd is currently playing or recording, this returns the number of sample frames that have been played or recorded so far.
performance | The SndPerformance of which to enquire. |
- (double) samplingRate |
- (double) samplingRate |
- (void) setAudioProcessorChain: | (SndAudioProcessorChain *) | newAudioProcessorChain |
Assigns the audioProcessorChain to this Snd instance.
This is typically used during playback of the Snd, but could be used for any other (i.e offline processing of the Snd).
newAudioProcessorChain | A SndAudioProcessorChain instance. |
- (void) setAudioProcessorChain: | (SndAudioProcessorChain *) | newAudioProcessorChain |
Assigns the audioProcessorChain to this Snd instance.
This is typically used during playback of the Snd, but could be used for any other (i.e offline processing of the Snd).
newAudioProcessorChain | A SndAudioProcessorChain instance. |
- (void) setConversionQuality: | (SndConversionQuality) | quality |
Sets the conversion quality performed by convertToSampleFormat:
Default is SndConvertLowQuality.
quality | Sets the conversion quality to a SndConversionQuality enumerated type. |
- (void) setConversionQuality: | (SndConversionQuality) | quality |
Sets the conversion quality performed by convertToSampleFormat:
Default is SndConvertLowQuality.
quality | Sets the conversion quality to a SndConversionQuality enumerated type. |
- (void) setDelegate: | (id) | anObject |
Sets the Snd's delegate to anObject.
anObject | is an id. |
- (void) setDelegate: | (id) | anObject |
Sets the Snd's delegate to anObject.
anObject | is an id. |
- (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.
newInfoString | An NSString containing the new text. |
- (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.
newInfoString | An NSString containing the new text. |
- (void) setLoopEndIndex: | (long) | newLoopEndIndex |
Sets the sample at which the performance loops back to the start index (set using setLoopStartIndex:).
This sample index is the last sample of the loop, i.e. it is the last sample heard before the performance loops, the next sample heard will be that returned by -loopStartIndex. The loop end index may be changed while the sound is being performed and regardless of whether the performance is looping.
newLoopEndIndex | The sample index at the end of the loop. |
- (void) setLoopEndIndex: | (long) | newLoopEndIndex |
Sets the sample at which the performance loops back to the start index (set using setLoopStartIndex:).
This sample index is the last sample of the loop, i.e. it is the last sample heard before the performance loops, the next sample heard will be that returned by -loopStartIndex. The loop end index may be changed while the sound is being performed and regardless of whether the performance is looping.
newLoopEndIndex | The sample index at the end of the loop. |
- (void) setLoopStartIndex: | (long) | loopStartIndex |
Sets the sample to stop playing at.
The loop start index may be changed while the sound is being performed and regardless of whether the performance is looping.
newEndAtIndex | The sample index that playing should stop after. |
- (void) setLoopStartIndex: | (long) | loopStartIndex |
Sets the sample to stop playing at.
The loop start index may be changed while the sound is being performed and regardless of whether the performance is looping.
newEndAtIndex | The sample index that playing should stop after. |
- (void) setLoopWhenPlaying: | (BOOL) | yesOrNo |
Sets the default behaviour whether to loop during play.
yesOrNo | Sets the default behaviour whether to loop during play. |
- (void) setLoopWhenPlaying: | (BOOL) | yesOrNo |
Sets the default behaviour whether to loop during play.
yesOrNo | Sets the default behaviour whether to loop during play. |
+ (id) setMute: | (BOOL) | aFlag |
Mutes and unmutes the sound output level of all playing sounds if aFlag is YES or NO, respectively.
aFlag | is a BOOL. |
+ (id) setMute: | (BOOL) | aFlag |
Mutes and unmutes the sound output level of all playing sounds if aFlag is YES or NO, respectively.
aFlag | is a BOOL. |
- (id) setName: | (NSString *) | theName |
- (id) setName: | (NSString *) | theName |
- (Snd *) soundBeingProcessed |
Returns the Snd object that's being performed.
- (Snd *) soundBeingProcessed |
Returns the Snd object that's being performed.
+ (NSArray *) soundFileExtensions |
Returns an array of valid file extensions available for reading and writing.
Returns an array of file extensions indicating the file format (and file extension) that audio files may be read from or written to. This list may be used for limiting NSOpenPanel to those formats supported. The list can be expected to vary between platforms, but is ultimately derived from those formats supported by the underlying libsndfile library.
+ (NSArray *) soundFileExtensions |
Returns an array of valid file extensions available for reading and writing.
Returns an array of file extensions indicating the file format (and file extension) that audio files may be read from or written to. This list may be used for limiting NSOpenPanel to those formats supported. The list can be expected to vary between platforms, but is ultimately derived from those formats supported by the underlying libsndfile library.
- (SndFormat) soundFormatOfFilename: | (NSString *) | filename |
- (SndFormat) soundFormatOfFilename: | (NSString *) | filename |
- (Snd *) soundFromSamplesInRange: | (NSRange) | frameRange |
Returns a new Snd instance of the same format with a copy of a portion of receivers sound data.
frameRange | is an NSRange of sample frames. |
- (Snd *) soundFromSamplesInRange: | (NSRange) | frameRange |
Returns a new Snd instance of the same format with a copy of a portion of receivers sound data.
frameRange | is an NSRange of sample frames. |
- (int) stop |
- (int) stop |
- (void) stop: | (id) | sender |
Action method that stops the Snd's playback or recording.
sender | is an id. Other than the argument and the return type, this is the same as the stop method. |
- (void) stop: | (id) | sender |
Action method that stops the Snd's playback or recording.
sender | is an id. Other than the argument and the return type, this is the same as the stop method. |
+ (void) stopPerformance: | (SndPerformance *) | performance | |
inFuture: | (double) | inSeconds | |
Stop the given playback of the sound at some future time, specified in seconds.
inSeconds | The number of seconds beyond the current time point to begin playback. |
performance | The performance that represents the sound playing. |
+ (void) stopPerformance: | (SndPerformance *) | performance | |
inFuture: | (double) | inSeconds | |
Stop the given playback of the sound at some future time, specified in seconds.
inSeconds | The number of seconds beyond the current time point to begin playback. |
performance | The performance that represents the sound playing. |
- (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) 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.
- (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.
- (void) tellDelegate: | (SEL) | theMessage |
Sends theMessage to the Snd's delegate (only sent if the delegate implements theMessage).
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 |
Sends theMessage to the Snd's delegate (only sent if the delegate implements theMessage).
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.
theMessage | is a SEL. |
performance | The performance playing when the message is sent. |
- (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.
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.
theMessage | is an NSString, which will be converted to 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.
theMessage | is an NSString, which will be converted to a SEL. |
performance | The performance playing when the message is sent. |
- (void) unlockEditing |
Used to unlock Snd instance for editing.
See also -lockEditing for the complementary method to match with.
- (void) unlockEditing |
Used to unlock Snd instance for editing.
See also -lockEditing for the complementary method to match with.
- (int) waitUntilStopped |
- (int) waitUntilStopped |
- (int) writeSoundfile: | (NSString *) | filename |
Writes the Snd's contents (its sample format and sound data) to the sound file filename.
filename | is a NSString instance. |
- (int) writeSoundfile: | (NSString *) | filename |
Writes the Snd's contents (its sample format and sound data) to the sound file filename.
filename | is a NSString instance. |
- (int) writeSoundfile: | (NSString *) | filename | |
fileFormat: | (NSString *) | fileFormat | |
dataFormat: | (SndSampleFormat) | fileDataFormat | |
Writes the Snd's contents (its sample format and sound data) to the sound file filename in the given file format and data encoding.
Expects the sound to not be fragmented, and to be in host endian order.
filename | is a NSString instance. |
fileFormat | An NSString giving the extension format name (.au, .wav, .aiff etc) to write out the sound which matches one of the encodings returned by +soundFileExtensions. |
fileDataFormat | a SndSampleFormat allowing the sound to be written out in a different format (e.g SND_FORMAT_LINEAR_16) than it is held in (e.g SND_FORMAT_FLOAT). |
- (int) writeSoundfile: | (NSString *) | filename | |
fileFormat: | (NSString *) | fileFormat | |
dataFormat: | (SndSampleFormat) | fileDataFormat | |
Writes the Snd's contents (its sample format and sound data) to the sound file filename in the given file format and data encoding.
Expects the sound to not be fragmented, and to be in host endian order.
filename | is a NSString instance. |
fileFormat | An NSString giving the extension format name (.au, .wav, .aiff etc) to write out the sound which matches one of the encodings returned by +soundFileExtensions. |
fileDataFormat | a SndSampleFormat allowing the sound to be written out in a different format (e.g SND_FORMAT_LINEAR_16) than it is held in (e.g SND_FORMAT_FLOAT). |
- (void) writeToPasteboard: | (NSPasteboard *) | thePboard |
- (void) writeToPasteboard: | (NSPasteboard *) | thePboard |
- (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).
- (SndConversionQuality) conversionQuality [protected] |
Determines quality of sampling rate conversion - see quality defines
- (int) currentError [protected] |
The code of the most recently occurring error. Zero if no error.
- (id) delegate [protected] |
The target of notification messages
- (NSRecursiveLock *) editingLock [protected] |
An NSRecursiveLock to protect concurrent modifying of a sound.
- (NSString *) info [protected] |
A descriptive information string read from a sound file.
- (long) loopEndIndex [protected] |
The sample the loop ends at. This is just the priming value for each performance.
- (long) loopStartIndex [protected] |
The sample the loop begins at. This is just the priming value for each performance.
- (BOOL) loopWhenPlaying [protected] |
Indicates whether the default behaviour is to loop when playing. This is set from reading the sound file.
- (NSString *) name [protected] |
The name of the sound, typically less verbose than the info string which can be descriptive.
- (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.
- (int) priority [protected] |
The priority of the sound - currently unused.
- (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.