The SndKit

Soundfiles

Soundfiles are files on a disk that contain sound data. By convention, soundfile names are given a “.snd” extension. To read a soundfile into a Snd object, simply create the object and send it the readSoundfile: message:

#import <SndKit/SndKit.h>               /* you must import this file */

. . .

Snd  *aSound = [[Snd alloc] init];     /* create a Snd object */
int result = [aSound readSoundfile: @"KneeSqueak.snd"];   /* read a file */

The data in the named soundfile is read into the Snd object. The given file name is a complete UNIX pathname and must include the extension; in the example, the soundfile is searched for in the current working directory. Like many of the Snd methods, readSoundfile: returns an error code; the complete list of errors codes is given in the description of the SNDSoundError() C function in SndKit Function References. Success is indicated by the code SND_ERR_NONE.

These two operations, initializing a Snd object and reading a soundfile, are combined in the initFromSoundfile: method:

Snd *aSound = [[Snd alloc] initFromSoundfile: @"KneeSqueak.snd"];

The method returns nil if the soundfile isn't found or if it can't be read. You can read a new soundfile into an existing Snd object at any time; the object's old sound is discarded.

Apple provides a number of short sound effects (useful as system beeps) that are stored in the directory /System/Library/Sounds. You can audition a soundfile by running the sndplay program from a Terminal shell window. For example:

sndplay /System/Library/Sounds/Frog.aiff

Writing a soundfile from the data in a sound object is done by invoking the writeSoundfile: method:

[mySound writeSoundfile: @"FleaSigh.snd"];

Even if the Snd object contains fragmented data, the data in the soundfile will be compact. However, the Snd object's data will remain fragmented.

The Pasteboard

Placing a Snd object on the pasteboard lets you copy its data between running applications. To place a Snd on the pasteboard, invoke the writeToPasteboard method:

[mySound writeToPasteboard];

The object's data is compacted (if it's fragmented) and copied. The copy is then placed on the pasteboard.

To read data from the pasteboard into a Snd, invoke the initFromPasteboard: method:

id  mySound = [[Snd alloc] initFromPasteboard];

The sound data currently on the pasteboard is copied into the receiver of the message. Since the pasteboard can contain only one sound at a time, the method doesn't require an argument to further identify the sound. If there isn't a sound on the pasteboard, initFromPasteboard returns nil.

The Named Sound List

The Snd class maintains an application-wide list of named Snd objects called the named Sound list. The addName:Sound: class method lets you name a Snd object and add it to the named Sound list:

/* Add a Snd to the named Sound list. */
id namedSound = [Snd addName: @"PopTop" sound: mySound];

/* Check for failure. */
if (namedSound == nil)
    . . .

The names in the named Sound list are unique; if you try to add a Snd by a name that's already in use, the effort is denied and nil is returned.

You can also name a Snd and place it on the named Sound list by sending setName: to the object:

id  namedSound = [mySound setName: @"RedRover"];

setName: can be used to change the name of a Snd that's already on the named Sound list.

The name method retrieves a Snd object's name, whether given in a setName: message or through the addName:sound: method.

Named Snds are visible to your entire application. To retrieve a named Snd and load a copy of its data into a new Snd object, invoke the findSoundFor:method:

id  newRedButton = [Snd findSoundFor: @"RedButton"];

If findSoundFor: fails to find the Snd in the named Sound list, it gives its argument (the Snd name) a “.snd” suffix and looks for a soundfile in these directories (in order):

• ~/Library/Sounds/

• /LocalLibrary/Sounds/ (on NeXTStep)

• /NextLibrary/Sounds/ (on NeXTStep)

• /Library/Sounds/ (on MacOS X)

• /System/Library/Sounds/ (on MacOS X)

(~ represents the user's home directory.)

A Snd found through findSoundFor: is automatically added to the named Sound list.

To remove a named Snd from the named Sound list, invoke removeSoundForName:, passing the name of the object that you want to remove. Removing a named Snd neither frees the Snd nor changes the object's notion of its name (which it stores as an instance variable).

Identifying and locating Snds through the named Sound list is generally the most efficient way to access sound data. The data in a named Snd is shared by all the objects that retrieve it.

Action Methods

The Snd class methods record:, play:, pause:, resume:, and stop: are designed to be used as part of the target/action mechanism described in the Openstep/Cocoa Concepts manual. Briefly, this mechanism lets you assign a selected message (the action) and an object id (the target) to a NSControl object such that when the user acts on the NSControl, the action message is sent to the target object. In the following example, the three methods are assigned as action messages to three different NSControl objects―in this case, NSButtons. The same Snd object is assigned as the NSButton's target:

/* Create a Snd object ... */
id  mySound = [[Snd alloc] init];

/* ...  and three NSButtons.  */
id  recordButton = [[NSButton alloc] init],
    playButton = [[NSButton alloc] init],
    stopButton = [[NSButton alloc] init];

/* Set the action messages.  */
[recordButton setAction: @selector(record:)];
[playButton setAction: @selector(play:)];
[stopButton setAction: @selector(stop:)];

/* Set the targets.  */
[recordButton setTarget: mySound];
[playButton setTarget: mySound];
[stopButton setTarget: mySound];

In response to the user's clicking the different NSButtons, the Snd object starts recording, starts playing, or stops one of these operations.

The Delegate

A Snd can have a delegate object. A Snd's delegate receives, asynchronously, the following messages as the Snd records or plays:

• willPlay: is sent just before the Snd begins playing.

• didPlay: is sent when the Snd finishes playing.

• willRecord: is sent just before recording.

• didRecord: is sent after recording.

• hadError: is sent if playback or recording generates an error.

To set a Snd's delegate object, invoke the setDelegate: method:

[mySound setDelegate:SoundDelegate];

A message is sent to the delegate only if the delegate implements the method that the message invokes.

Delete

Deleting a portion of a Snd's data is direct; you simply invoke deleteSamplesAt:count:. For example:

/* Delete the beginning of mySound. */
int eCode = [mySound deleteSamplesAt:0 count:1000];

The first 1000 samples are deleted from the receiver of the message. The first argument specifies the beginning of the deletion in samples from the beginning of the data (counting from sample 0); the second argument is the number of samples to delete.

Copy and Paste

Copying a portion of one Snd and pasting it into another―or into itself, for that matter―requires the use of both copySamples:at:count and insertSamples:at:. In the following example, the beginning of mySound is repeated:

/* Create a stutter at the beginning of mySound. */
id tmpSound = [[Snd alloc] init];
int errorCode = [tmpSound copySamples: mySound at: 0 count: 1000];

if (errorCode == SND_ERROR_NONE)
    errorCode = [mySound insertSamples: tmpSound at: 0];
[tmpSound free];

First, the data in tmpSound is completely replaced by a copy of the first 1000 samples in mySound. Note that the copySamples:at:count method doesn't remove any data from its first argument, it simply copies the specified range of samples from the first argument into the receiver. Next, tmpSound is prepended to mySound, creating a repetition of the first 1000 samples in mySound. The insertSamples: method inserts a copy of the argument into the receiver. Thus, the argument can be freed after inserting.

The two Snd objects involved in the insertSamples:at: method (the receiver and the first argument) must be compatible: They must have the same format, sampling rate, and channel count. If possible, the data that's inserted into the receiver of insertSamples:at: is automatically converted to be compatible with the data already in the receiver (see the description of the SNDConvertSound() C function in SndKit Function References for a list of the conversions that are supported). An error code indicating that the insertion failed is returned if the two Snds aren't compatible or if the inserted data can't be converted.

Replace

Replacing is like copying and pasting, except that a region of the pasted-into Snd is destroyed to accommodate the new data. In the following example, the beginning of oneSound is replaced with a copy of the beginning of twoSound:

/* Replace the beginning of oneSound with that of twoSound.  */
int tmpCode = [tmpSound copySamples:twoSound at:0 count:1000];
int inCode;

if (tmpCode == SND_ERROR_NONE) {
    int oneCode = [oneSound deleteSamplesAt:0 count:1000];
    if (oneCode == SND_ERROR_NONE)
        inCode = [oneSound insertSamples:tmpSound at:0]; }
[tmpSound free];

/* Check inCode before performing further manipulations. */
. . .

Utility Methods

The editing methods described above only work on Snds that contain sampled data. The isEditable method is provided to quickly determine whether a Snd object can be edited. The method returns YES if the object can be edited, NO if it can't.

The compatibleWith: method takes a Snd object as its argument and returns YES if the argument and the receiver are compatible. (The method also returns YES if one of the objects is empty; in other words, it's OK to insert samples into an empty object.) This method is useful prior to invoking the insertSound:at: method.

Another handy method is sampleCount, which returns the number of sample frames contained in the receiver. A sample frame is a channel-independent count of the samples in a Snd. For example, sending sampleCount to a two-channel Snd that contains three seconds worth of data returns the same value as sending it to a one-channel Snd that also contains three seconds of data (given that the two Snds have the same sampling rate), even though the two-channel Snd actually contains twice as much data.

Other Editing Methods

The Snd class defines three more editing methods:

• copy returns a new Snd object that's a copy of the receiver.

• copySound: takes a Snd object as an argument and replaces the data in the receiver with the data in its argument. Since the entire range of data in the receiver is replaced, it needn't be editable, nor must the two Snds be compatible.

• deleteSamples can only be sent to an editable Snd. It deletes the receiver's sound data.

Fragmentation

A Snd's data is normally contiguous in memory. However, when you edit a Snd object, its data can become fragmented, or discontiguous. Fragmentation is explained in the description of the SndSoundStruct, earlier in this chapter. Briefly, fragmentation lets you edit Snds without incurring the cost of moving large sections of data in memory. However, fragmented Snds can be less efficient to play. The needsCompacting and compactSamples methods are provided to determine if a Snd is fragmented and to compact it. Note that compacting a large Snd that has been mercilessly fragmented can take a noticeably long time.