Inside Macintosh: Sound /

Chapter 1 - Introduction to Sound on the Macintosh / Using Sound on Macintosh Computers

Playing a Sound File

You can initiate and control a playback of sampled sounds stored in a file using the SndStartFilePlay, SndPauseFilePlay, and SndStopFilePlay functions. You use SndStartFilePlay to initiate the playing of a sound file. If you allocate your own sound channel and specify that play be asynchronous, you can then use the SndPauseFilePlay and SndStopFilePlay functions to pause, resume, and stop sound files that are playing. The chapter "Sound Manager" in this book describes these two functions in detail.

To play a sampled sound that is contained in a file, you pass SndStartFilePlay the file reference number of the file to play. The sample should be stored in either AIFF or AIFF-C format. If the sample is compressed, it is automatically expanded during playback. If you specify NIL as the sound channel, then SndStartFilePlay allocates memory for a channel internally. Listing 1-2 defines a function that plays a file specified by its file reference number.

Listing 1-2 Playing a sound file with SndStartFilePlay

FUNCTION MyPlaySoundFile (myFileRefNum: Integer): OSErr;
CONST
   kAsync = TRUE;             {for asynchronous play}
   kBufferSize = 20480;       {20K play buffer}
VAR
   myErr:   OSErr;
BEGIN
   myErr := SndStartFilePlay(NIL, myFileRefNum, 0, kBufferSize,
                              NIL, NIL, NIL, NOT kAsync);
   MyPlaySoundFile := myErr;
END;

To allow the Sound Manager to handle all memory allocation automatically, you should pass NIL as the first and fifth parameters to SndStartFilePlay, as done in Listing 1-2. The first NIL specifies that you want SndStartFilePlay to allocate a sound channel itself. The NIL passed as the fifth parameter specifies that SndStartFilePlay should automatically allocate buffers to play the sound. The SndStartFilePlay function then allocates two buffers, each half the size specified in the fourth parameter; if the fourth parameter is 0, the Sound Manager chooses a default size for the buffers.

The third parameter passed to SndStartFilePlay here is set to 0. That parameter is used only when playing sound resources from disk.

The seventh parameter to SndStartFilePlay allows you to specify a routine to be executed when the sound finishes playing. This is useful only for asynchronous play. In Listing 1-2, the value NOT kAsync (that is, FALSE) is passed as the eighth parameter to SndStartFilePlay to request synchronous playback. SndStartFilePlay would return a badChannel result code if you request asynchronous playback because MyPlaySoundFile does not allocate a sound channel.