Inside Macintosh: Sound /

Chapter 2 - Sound Manager / About the Sound Manager

Sound Commands

The Sound Manager provides routines that allow you to create and dispose of sound channels. These routines allow you to manipulate sound channels, but they do not directly produce any sounds. To actually produce sounds, you need to issue sound commands. A sound command is an instruction to produce sound, modify sound, or otherwise assist in the overall process of sound production. For example, the ampCmd sound command changes the amplitude (or volume) of a sound.

You can issue sound commands in several ways. You can send sound commands one at a time into a sound channel by repeatedly calling the SndDoCommand function. The commands are held in a queue and processed in a first-in, first-out order. Alternatively, you can bypass a sound queue altogether by calling the SndDoImmediate function. You can also issue sound commands by calling the function SndPlay and specifying a sound resource of type 'snd ' that contains the sound commands you want to issue. A sound resource can contain any number of sound commands. As a result, you might be able to accomplish all sound-related activity simply by creating sound resources and calling SndPlay in your application. See "Sound Resources" on page 2-74 for details on the format of an 'snd ' resource.

Generally speaking, no matter how sound commands are issued, they are all eventually sent to the Sound Manager, which interprets the commands and plays the sound on the available audio hardware. The Sound Manager provides a rich set of sound commands. The structure of a sound command is defined by the SndCommand data type:

TYPE SndCommand =
PACKED RECORD
   cmd:        Integer;    {command number}
   param1:     Integer;    {first parameter}
   param2:     LongInt;    {second parameter}
END;

Commands are always 8 bytes in length. The first 2 bytes are the command number, and the next 6 make up the command's options. The format of the last 6 bytes depends on the command in use, although typically those 6 bytes are interpreted as an integer followed by a long integer. For example, an application can install a wave table into a sound channel by using SndDoCommand with a sound command whose cmd field is the waveTableCmd constant. In that case, the param1 field specifies the length of the wave table, and the param2 field is a pointer to the wave-table data itself. Other sound commands may interpret the 6 parameter bytes differently or may not use them at all.

The sound commands available to your application are defined by constants.

CONST
   nullCmd           = 0;     {do nothing}
   quietCmd          = 3;     {stop a sound that is playing}
   flushCmd          = 4;     {flush a sound channel}
   reInitCmd         = 5;     {reinitialize a sound channel}
   waitCmd           = 10;    {suspend processing in a channel}
   pauseCmd          = 11;    {pause processing in a channel}
   resumeCmd         = 12;    {resume processing in a channel}
   callBackCmd       = 13;    {execute a callback procedure}
   syncCmd           = 14;    {synchronize channels}
   availableCmd      = 24;    {see if initialization options are supported}
   versionCmd        = 25;    {determine version}
   totalLoadCmd      = 26;    {report total CPU load}
   loadCmd           = 27;    {report CPU load for a new channel}
   freqDurationCmd   = 40;    {play a note for a duration}
   restCmd           = 41;    {rest a channel for a duration}
   freqCmd           = 42;    {change the pitch of a sound}
   ampCmd            = 43;    {change the amplitude of a sound}
   timbreCmd         = 44;    {change the timbre of a sound}
   getAmpCmd         = 45;    {get the amplitude of a sound}
   volumeCmd         = 46;    {set volume}
   getVolumeCmd      = 47;    {get volume}
   waveTableCmd      = 60;    {install a wave table as a voice}
   soundCmd          = 80;    {install a sampled sound as a voice}
   bufferCmd         = 81;    {play a sampled sound}
   rateCmd           = 82;    {set the pitch of a sampled sound}
   getRateCmd        = 85;    {get the pitch of a sampled sound}

For details on individual sound commands, see the relevant sections in "Using the Sound Manager" beginning on page 2-17. Also see "Sound Command Numbers" beginning on page 2-92 for a complete summary of the available sound commands, their parameters, and their uses.