Inside Macintosh: Sound /

Chapter 2 - Sound Manager / Using the Sound Manager

Managing Sound Volumes

Versions of the Sound Manager prior to 3.0 allow you to set only one volume level, which applies to all sounds produced by the audio hardware. The Sound Manager versions 3.0 and later provide greatly improved control over the volumes of the sounds you ask it to create. You can use new facilities to

• set the volumes of the left and right channels of sound independently of each other
• set the volume of the system alert sound
• set the default volume of a particular sound output device

You can set the system alert sound volume to a different level than that of any other sounds you produce. For example, you can set the system alert sound to play at a lower volume than other sounds. This would allow a user to hear QuickTime movies at full volume and to hear system alert sounds at a lower volume.

You can use the volumeCmd and getVolumeCmd sound commands to set and get the right and left volumes of sound. You specify a channel's volume with 16-bit value, where 0 represents no volume and hexadecimal $0100 represents full volume. The Sound Manager defines constants for silence and full volume.

CONST
   kFullVolume                   = $0100;
   kNoVolume                     = 0;

The volumeCmd sound command expects the right and left volumes to be encoded as the high word and low word, respectively, of param2. For example, to set the left channel to half volume and the right channel to full volume, you pass the value $01000080 in param2, as illustrated in Listing 2-8.

Listing 2-8 Setting left and right volumes

FUNCTION MySetVolume (chan: SndChannelPtr): OSErr;
VAR
   mySndCmd:      SndCommand;
   myRightVol:    Integer;
   myLeftVol:     Integer;
   myErr:         OSErr;
BEGIN
   myRightVol := kFullVolume;
   myLeftVol := kFullVolume DIV 2;
   mySndCmd.cmd := volumeCmd;
   mySndCmd .param1 := 0;              {unused with volumeCmd}
   mySndCmd.param2 := BSL(myRightVol, 16) + myLeftVol;
   myErr := SndDoImmediate(chan, mySndCmd);
   MySetVolume := myErr;
END;

You can also use the volumeCmd sound command to pan a sound from one side to another. For example, to send the output signal entirely to the right channel, pass the value $01000000 in param2. To send the output signal entirely to the left channel, pass the value $00000100 in param2. You can overdrive a channel's volume by passing volume levels greater than $0100. For example, to play the left channel of a stereo sound at twice full volume while playing the right channel at full volume, pass the value $01000200.

You can use the GetSysBeepVolume and SetSysBeepVolume functions to get and set the output volume level of the system alert sound. Any calls to the SysBeep procedure use the volume set by the previous call to SetSysBeepVolume. As you've learned, this allows you to set a lower volume for the system alert sound than for your other sound output.

You can use the GetDefaultOutputVolume and SetDefaultOutputVolume functions to set the default output volumes for a particular output device. Each output device has its own current volume setting and its own default setting. If the user changes the output device (using the Sound control panel), the newly selected device will use its own default volume level.