PLAY statement

Purpose

Play a sound under program control.

Syntax

PLAY WAVE ResourceID$ [,descriptors...] [TO ResultVar&]

PLAY WAVE END

Remarks

The PLAY statement allows you to play a previously created WAVE resource or WAVE file. It's generally advantageous to use the resource form. Access is typically faster and the need for extra files is reduced. The first form of PLAY WAVE starts the sound, while PLAY WAVE END stops any waveform sound which is currently playing.

ResourceID$ is a string expression which tells either the Resource ID of the waveform data, or the disk file where it can be found. If the resource ID is numeric, just precede the number with #, such as "#12345". If the Resource ID contains a period, it is presumed to be the name of a disk file. Otherwise, an attempt is made to load it from a resource -- if not found, it is then presumed to be a disk file. If the waveform data cannot be found, an error 53 (File Not Found) is generated.

If you include the optional TO clause, a success value is assigned to the ResultVar&. If the operation succeeds, the value True (non-zero) is assigned. If it fails, the value False (zero) is assigned.

The default method is to play the waveform data in the background. That is, the Play statement returns immediately so the application can execute other code while the sound is playing.

By default, the new sound takes precedence over any other sound currently playing. When PLAY WAVE is executed, any other sound playing is stopped immediately. The new sound is played to replace it. This default methodology can be altered with options described later.

The optional descriptor words (one or more) may be added to control the way in which the sound is played. The descriptors available are:

Loop	The sound is played repeatedly, in the background, until PLAY WAVE END is executed.
NoStop	If another sound is playing, the new sound is discarded and not played. The value False (zero) is returned to the ResultVar& to let you know that the operation failed. You can try again to play the new sound at your convenience.
Synch	The sound plays in synchronous mode, commonly known as the foreground. The application waits for the sound to complete before continuing execution of other code. The sound and the code are synchronized.
YieldMS(TimeOut&)	If another sound is playing, the new sound yields and allows the first sound to complete. The numeric expression TimeOut& tells the maximum number of milliseconds (approximate) to wait before giving up. If the Timeout period expires and the first sound is still playing, the new sound is aborted. If the Timeout period is zero (0), the program will wait an unlimited amount of time for the first sound to finish. The maximum TimeOut& permitted is one hour.