Legacy Document
Important: Sound Input Manager is deprecated as of Mac OS X v10.5. For new audio development in Mac OS X, use Core Audio. See the Audio page in the ADC Reference Library.
Inside Macintosh: Sound
| Previous | Chapter contents | Chapter top | Section top | Next |
Important: Sound Input Manager is deprecated as of Mac OS X v10.5. For new audio development in Mac OS X, use Core Audio. See the Audio page in the ADC Reference Library.
You can use the SysBeep procedure to play the system alert sound, the SndPlay function to play the sound stored in any 'snd ' resource, and the SndStartFilePlay function to play a sound file.
You can use the SysBeep procedure to play the system alert sound.
PROCEDURE SysBeep (duration: Integer);
The duration (in ticks) of the resulting sound. This parameter is ignored except on a Macintosh Plus, Macintosh SE, or Macintosh Classic when the system alert sound is the Simple Beep. The recommended duration is 30 ticks, which equals one-half second.
The SysBeep procedure causes the Sound Manager to play the system alert sound at its current volume. If necessary, the Sound Manager loads into memory the sound resource containing the system alert sound and links it to a sound channel. The user selects a system alert sound in the Alert Sounds subpanel of the Sound control panel.
The volume of the sound produced depends on the current setting of the system alert sound volume, which the user can adjust in the Alert Sounds subpanel of the Sound control panel. The system alert sound volume can also be read and set by calling the GetSysBeepVolume and SetSysBeepVolume routines. If the volume is set to 0 (silent) and the system alert sound is enabled, calling SysBeep causes the menu bar to blink once.
You can use the SndPlay function to play a sound resource that your application has loaded into memory.
FUNCTION SndPlay (chan: SndChannelPtr; sndHdl: Handle;
async: Boolean): OSErr;
A pointer to a valid sound channel. You can pass NIL instead of a pointer to a sound channel if you want the Sound Manager to internally allocate a sound channel in your application's heap zone.
A handle to the sound resource to play.
A Boolean value that indicates whether the sound should be played asynchronously ( TRUE ) or synchronously ( FALSE ). This parameter is ignored (and the sound plays synchronously) if NIL is passed in the first parameter.
The SndPlay function attempts to play the sound located at sndHdl , which is expected to have the structure of a format 1 'snd ' resource. If the resource has not yet been loaded, the SndPlay function fails and returns the resProblem result code. The handle you pass in the sndHdl parameter must be locked for as long as the sound is playing asynchronously.
The chan parameter is a pointer to a sound channel. If chan is not NIL , it is used as a valid channel. If chan is NIL , an internally allocated sound channel is used. Commands and data contained in the sound handle are then sent to the channel. Note that you can pass SndPlay a handle to some data created by calling the Sound Input Manager's SndRecord function as well as a handle to an actual 'snd ' resource that you have loaded into memory.
Because the SndPlay function moves memory, you should not call it at interrupt time.
For an example of how to play a sound resource using the SndPlay function, see "Playing a Sound Resource" . For more information on the SndPlay function, see the chapter "Sound Manager" in this book.
You can call the SndStartFilePlay function to initiate a play from disk.
FUNCTION SndStartFilePlay (chan: SndChannelPtr; fRefNum: Integer;
resNum: Integer; bufferSize: LongInt;
theBuffer: Ptr;
theSelection: AudioSelectionPtr;
theCompletion: ProcPtr;
async: Boolean): OSErr;
A pointer to a valid sound channel. You can pass NIL instead of a pointer to a sound channel if you want the Sound Manager to internally allocate a sound channel in your application's heap zone.
The file reference number of the AIFF or AIFF-C file to play. To play a sound resource rather than a sound file, this field should be 0.
The resource ID number of a sound resource to play. To play a sound file rather than a sound resource, this field should be 0.
The number of bytes of memory that the Sound Manager is to use for input buffering while reading in sound data. For SndStartFilePlay to execute successfully on the slowest Macintosh computers, use a buffer of at least 20,480 bytes. You can pass the value 0 to instruct the Sound Manager to allocate a buffer of the default size.
A pointer to a buffer that the Sound Manager should use for input buffering while reading in sound data. If this parameter is NIL , the Sound Manager allocates two buffers, each half the size of the value specified in the bufferSize parameter. If this parameter is not NIL , the buffer should be a nonrelocatable block of size bufferSize .
A pointer to an audio selection record that specifies which portion of a sound should be played. You can pass NIL to specify that the Sound Manager should play the entire sound.
A pointer to a completion routine that the Sound Manager calls when the sound is finished playing. You can pass NIL to specify that the Sound Manager should not execute a completion routine. This field is useful only for asynchronous play.
A Boolean value that indicates whether the sound should be played asynchronously ( TRUE ) or synchronously ( FALSE ). You can play sound asynchronously only if you allocate your own sound channel (using SndNewChannel ). If you pass NIL in the chan parameter and TRUE for this parameter, the SndStartFilePlay function returns the badChannel result code.
The SndStartFilePlay function begins a continuous play from disk on a sound channel. The chan parameter is a pointer to the sound channel. If chan is not NIL , it is used as a valid channel. If chan is NIL , an internally allocated sound channel is used for play from disk. This internally allocated sound channel is not passed back to you. Because SndPauseFilePlay and SndStopFilePlay (described in the chapter "Sound Manager") require a sound-channel pointer, you must allocate your own channel if you wish to use those routines.
The sounds you wish to play can be stored either in a file or in an 'snd ' resource. If you are playing a file, then fRefNum should be the file reference number of the file to be played and the parameter resNum should be set to 0. If you are playing an 'snd ' resource, then fRefNum should be set to 0 and resNum should be the resource ID number (not the file reference number) of the resource to play.
Because the SndStartFilePlay function moves memory, you should not call it at interrupt time.
The trap macro and routine selector for the SndStartFilePlay function are
For an example of how to play a sound file using the SndStartFilePlay function, see "Playing a Sound File" . For information on completion routines, see the chapter "Sound Manager" in this book.
Inside Macintosh: Sound
| Previous | Chapter contents | Chapter top | Section top | Next |
Important: Sound Input Manager is deprecated as of Mac OS X v10.5. For new audio development in Mac OS X, use Core Audio. See the Audio page in the ADC Reference Library.