Inside Macintosh: Sound /

Chapter 2 - Sound Manager

Using the Sound Manager

The Sound Manager provides a wide variety of methods for creating sound and manipulating audio data on Macintosh computers. Usually, your application needs to use only a few of the many routines or sound commands that are available.

The Sound Manager routines can be divided into high-level routines and low-level routines. The high-level routines (like SndPlay and SysBeep) give you the ability to produce very complex audio output at very little programming expense. The majority of applications interact with the Sound Manager using these high-level routines, which allow you to play sounds without knowing anything about the structure of sound commands or sampled-sound data. You can let the high-level routines automatically allocate channels, or, for increased control, you can allocate your own sound channels.

Applications that have more sophisticated sound capabilities use the low-level routines (like SndDoCommand and SndDoImmediate) to send sound commands to sound channels. For example, your application might send a sound command to alter the amplitude of a sound that is playing (or is about to play).

Finally, a few very specialized applications use the Sound Manager's low-level sound playback routines, which allow fine-tuning of the algorithms the Sound Manager uses to manage the double buffering of sound for its play-from-disk routines.

In general, you should use the highest-level routines capable of producing the kind of sound you want. Many applications can simply play sounds stored in resources or files and do not need to customize the sounds or continue with other processing while those sounds are playing. In such cases, you can use the high-level Sound Manager routines, as illustrated in the chapter "Introduction to Sound on the Macintosh" in this book. If, however, you need to be able to exercise very fine control over sound output or to play sounds asynchronously, you must manage your own sound channels. See "Managing Sound Channels" on page 2-19 to learn how you can use the Sound Manager to

• allocate and dispose of sound channels manually by using the SndNewChannel and SndDisposeChannel functions
• manipulate sound that is playing (for example, by sending the ampCmd command to a sound channel to change the amplitude of sound playing)
• stop sounds and flush sound channels by using the quietCmd and flushCmd commands
• pause and restart sound channels by using the pauseCmd and resumeCmd commands
• synchronize sound channels by using the syncCmd command

As you've learned, the capabilities of the Sound Manager vary greatly from one Macintosh computer to another, depending on which version of the Sound Manager is available on a particular computer and on what audio hardware is available. To create sounds effectively on all computers, you might need to obtain information about the available sound features. "Obtaining Sound-Related Information" on page 2-32 explains how you can

• use the Gestalt function to determine which basic sound features are available
• find the version number of the available Sound Manager or of the MACE compression and expansion routines
• determine whether your application can take advantage of multichannel sound and the play-from-disk routines
• obtain information about a single sound channel

Some applications need to be able to play computer-generated tones at different pitches. In addition, some applications need to play waveforms or sampled sounds at different pitches. For example, if you are writing an application that converts musical notes to sound, you might record the sound of a violin playing middle C and then replay the sound at a variety of pitches to simulate a violinist's playing a concerto. The Sound Manager allows you to do this by allocating a sound channel and sending sound commands to it. "Playing Notes" on page 2-41 explains how you can

• play simple sequences of notes by using the freqCmd and freqDurationCmd commands
• install waveforms or sampled sounds into channels by using the soundCmd and waveTableCmd commands so that you can play them at different frequencies
• set a sound resource's loop points so that the sound repeats if a freqCmd or freqDurationCmd command lasts longer than the sound

Although some applications do not need to do other processing while sounds are playing, others do. If your application allocates sound channels itself, it can request that the Sound Manager play sounds asynchronously. By using callback procedures and completion routines, your application can arrange for a sound channel to be disposed when a sound finishes playing. "Playing Sounds Asynchronously" on page 2-46 explains how you can

• play a sound resource asynchronously by defining a callback procedure
• use callback procedures to synchronize sounds you play asynchronously with other actions
• play a sound file asynchronously and pause, restart, or stop such an asynchronous playback
• manage multiple channels of sound to play more than one sound asynchronously at the same time

The high-level Sound Manager routines automatically parse sound resources and sound files to determine the information the Sound Manager needs to play the sounds contained in the resources and files. However, you might need to obtain information about sound resources or sound files for some other reason. Or, you might need to locate a certain part of a sound resource or sound file. For example, to use the bufferCmd sound command to play a buffer of sampled sound, you must obtain a pointer to the sound header contained in that buffer. See the section "Parsing Sound Resources and Sound Files" on page 2-56 for information on how to

• parse sound resources containing sampled-sound data to obtain information from the sampled-sound data's sound header
• use the bufferCmd command to play sampled-sound data stored within a sound resource
• parse sound files to find a particular chunk and to extract the data from that chunk

High-level Sound Manager routines automatically expand sound data in real time when playing compressed sounds. However, you might need to manually compress or expand sound data at a time when you are not playing sounds. "Compressing and Expanding Sounds" on page 2-66 explains how you can use the Sound Manager's built-in sound compression and expansion routines to compress or expand sounds.

The Sound Manager's high-level play-from-disk routines use highly optimized algorithms to manage the double buffering of data so that the play from disk is continuous and without audible gaps. However, if you wish to bypass the high-level Sound Manager play-from-disk routines, you may define your own double-buffering routines. This might be useful if you need to change the sound data on disk before the Sound Manager can process it. The section "Using Double Buffers" on page 2-68 explains how you can set up your own double buffers and use a doubleback procedure to bypass the normal play-from-disk routines.

---

Subtopics

Managing Sound Channels

Managing Sound Volumes

Obtaining Sound-Related Information

Playing Notes

Playing Sounds Asynchronously

Parsing Sound Resources and Sound Files

Compressing and Expanding Sounds

Using Double Buffers