MTB Statements

(Play Sound)

Mnemonic:

(Play Sound=WavFileName,Flags)

Discussion:

The (Play Sound) mnemonic plays a sound file.

The WavFileName parameter is specified using the full path name, such as c:\comet\dlg.tada.wav. If this parameter is null, any currently playing waveform sound is stopped.

Notes
The sound file must fit into available physical memory and be playable by an installed waveform-audio device driver. (Play Sound) searches the following directories for sound files: the current directory; the Windows directory; the Windows system directory; directories listed in the PATH environment variable; and the list of directories mapped in a network.

If the audio driver cannot find the specified sound, (Play Sound) uses the default system event sound entry instead. If the driver can find neither the system default entry nor the default sound, it makes no sound.

The second parameter, Flags, is a numeric value that describes how the sound file is to be played. This parameter is the sum of the numeric values listed in the following chart. For example, if Flags is equal to 3, the driver interprets this as:

1 (play sound file asynchronously) plus 2 (silence if the sound file is not found)

The following chart includes 3 columns. The left column contains the numeric values for the Flag parameter. The middle column contains a reference name for each value (which is used in some of the sample code below). The right column contains a description of the value.

Flag Reference name Description

0 SND.SYNCH The sound is played synchronously (default). The next program instruction is not executed until the sound file has finished playing.

1 SND.ASYNC The sound is played asynchronously and the next progam instruction is executed immediately after the sound file has started playing. To terminate an asynchronously played waveform sound, use (Play Sound) with WavFileName set to null.

2 SND.NODEFAULT No default sound event is used. If the specified sound cannot be found, (Play Sound) returns silently without playing the default sound.

8 SND.LOOP The sound plays repeatedly until (Play Sound) is called again with WavFileName set to null. You must also specify the SND.ASYNC flag to indicate an asynchronous sound event.

16 SND.NOSTOP The specified sound event will yield to another sound event that is already playing. If a sound cannot be played because the resource needed to generate that sound is busy playing another sound, the mnemonic immediately returns without playing the requested sound.
If this flag is not specified, (Play Sound) attempts to stop the currently playing sound so that the audio device can be used to play the new sound.

64 SND.PURGE Sounds are to be stopped for the calling task. If WavFileName is not null, all instances of the specified sound are stopped. If WavFileName is null, all sounds that are playing on behalf of the calling task are stopped.

8192 SND.NOWAIT If the driver is busy, return immediately without playing the sound.

131072 SND.FILENAME This value specifies that the WavFileName is an actual file name, as opposed to an alias for a system event or a resource identifier.

Example 1:

Print (PlaySound = "c:\comet\dlg\tada.wav",3)

In this example, the WAV file named c:\comet\dlg\tada.wav is played. The flag is equal to 3, which indicates that the sound is to be played asynchronously (1) and that there will be silence if the WAV file is not found (2).

Example 2:

SET SND.ASYNC=1
SET SND.NODEFAULT=2

Length 10.0 & Local SoundFlags

SoundFlags = SND.ASYNC + SND.NODEFAULT

Print (PlaySound = "c:\comet\dlg\tada.wav", SoundFlags)

Example 3:

SET SND.ASYNC=1
SET SND.NODEFAULT=2

Length 10.0 & Local SoundFlags

IF OPTION$ = "QUIT" THEN
  SoundFile$ = "c:\sound files\goodbye.wav"
  SoundFlags = SND.ASYNC + SND.NODEFAULT
  Print (PlaySound = SoundFile$, SoundFlags)
  STOP
ENDIF

This code segment shows how to play a WAV file named c:\sound files\goodbye.wav when the user chooses the QUIT option.