Tkwav

NAME

Tkwav - Asynchronous playback of WAV files.

SYNOPSYS

package require tkwav ?1.0?

::tkwav::load ?object? ?filename?
?object? play
?object? loop
?object? pause
?object? isPlaying
::tkwav::destroy object ?object...?
::tkwav::cooperate ?level? ?window?

Description

The Tkwav package provides Tcl/Tk scripts with the ability to play audio samples in WAV format using DirectX on Windows. Multiple sounds can be played simultaneously and playback of each sound can be started and stopped independantly.

Sounds are loaded using the command ::tkwav::load. This command loads an audio sample onto the sound card and creates a sound object that provides operations to start, loop, pause and stop playback of the sample. Sound playback occurs concurrently with the execution of Tcl scripts, so multiple sounds can be played at the same time - DirectX mixes the playback of all these sounds into a single output channel. Sound objects are destroyed by the ::tkwav::destroy command which frees any system resources used to hold the sound's data and removes the object's command from the Tcl interpreter.

The ::tkwav::cooperate command controls how the Tcl application shares the audio device with other applications. By default, Tkwav is in normal cooperative mode, meaning that the system hands it the audio device whenever it's main window is activated and takes it away when the main window is deactivated. The window used to control access to the device can be changed via the ::tkwav::cooperate command. Changing the cooperative level to a higher priority has not been fully tested in this release of Tkwav and is not guaranteed to work.

Commands

::tkwav::load ?object? ?filename?

Loads an audio sample from the WAV file named filename onto the sound card and creates a sound object named object to control playback of the sample. A new command called object is created to control the sound object from the Tcl interpreter.

If the same sample is loaded more than once, all sound objects initialised from the same file share the same sample data on the sound-card, thereby conserving memory on the card. Sound objects sharing a sample can all be started and stopped independantly.

?object? play

If the sample is not paused, this command starts playback of the sound object. If the sample is paused, this command unpauses playback. When the end of the sample is reached, playback will stop.

?object? loop

If the sample is not paused, this command starts looped playback of the sound object. If the sample is paused, this command unpauses playback. When the end of the sample is reached, playback will begin again from the start of the sample.

?object? pause

Pauses playback of this sample.

?object? isPlaying

Returns a boolean value that describes whether this sound object is currently being played back. Returns 1 if the sound is being played and 0 if playback has stopped.

::tkwav::destroy object ?object...?

Destroys the named sound objects. Memory on the sound card is released and the object commands are removed from the Tcl interpreter.  Sound card memory that is shared beetween commands is released when the last sound using the memory is destroyed.

::tkwav::cooperate ?level? ?window?

Controls how the Tcl application shares the audio device with other applications. By default, Tkwav is in normal cooperative mode, meaning that it has control of the audio device whenever it's main window is activated and loses control of the audio device when its main window is deactivated. The window used to control access to the device can be specified by giving the pathname of a Tk toplevel widget as the window parameter. The only cooperative level supported at the moment is normal. Changing the cooperative level to a higher priority has not been fully tested in this release of Tkwav and is not guaranteed to work.