etPlay Overview

The etPlay component can be used to play wave files through any available Windows Wave Audio device including voice modems, sophisticated telephony hardware and common sound cards.

After setting a property the etPlay.Error properties will contain error information if an error ocurrs. The etPlay.OnError will fire when an error occurs.

Each telephony device is different so don't be afraid to experiment!

Voice modems use the UnimodemV Telephony Service Provider (TSP) to interface with Microsoft's Telephony Application Programming Interface (TAPI). UnimodemV is limited to using the wave format "PCM 8000 Hz, 16 Bit, Mono". This is the default format for our etRecord control and all of the wave files supplied with TeleTools are in this format. Other sophisticated telephony devices support a wider range of wave formats.

The etPlay.Device.Delay property is set to a default value of 0 milliseconds for supporting most devices. However, some devices may require a delay to allow the device to function properly. Some indications that this setting may need to be changed include:

   - the etPlay.OnDone event is not triggered,
   - the application hangs,
   - the telephony device drivers may become unstable,
   - a prior wav file or portions of a prior file may be played instead of the intended file.
For sound quality issues check the file, the format, ensure the device driver supports that format and check the volume. etPlay.Device.Delay will not have an impact on sound quality issues. Some devices may have a limit on the size of the file that can be played.

Under normal operations etPlay saves the current device volume setting prior to playing a wave file then restores it when finished. When set to False the etPlay.Volume.Enabled property allows this process to be skipped. The default value is True. This is especially useful when working with a multi-line telephony board that offers a way to set the volume for all lines.

You can use as many etPlay controls as you need; you are limited only by your system's memory. Each control has around 10k of overhead plus the size of the buffer required to hold the wave file. Although it is important to remember that only one object can use an audio device at a time. Therefore, you cannot have two etPlay controls active at the same time using the same audio device.

Many audio devices use the same audio channel for wave play and wave record. With devices such as this, you cannot have an etPlay and etRecord control using the same audio device active at the same time.

Using etPlay along with etLine

This will allow you to play a wave file to be heard over the phone line.

The etLine.WavePlay properties are used to associate the etLine and etPlay controls. The etLine.Device.Active property must first be set to True. The etLine.WavePlay.Available indicates whether the telephony device has a wave play audio device associated with it. The etLine.WavePlay.ID holds the Windows ID of the wave play device associated with the TAPI line device. Set the etPlay.Device.ID property to the value in the etLine.WavePlay.ID to ensure that you are using the correct wave audio device.

When using etPlay and/or etRecord along with etLine it is import to remember to stop playing and recording any wave files prior to hanging up a call or when the etLine.OnDisconnected event is fired. An example of this can be found in the DialAnswer sample program, see the CommandHangup_Click and etLine1_OnDisconnected subroutines.

Using etPlay along with etPhone

This will allow you to play a wave file to be heard on the handset, headset or speakerphone.

The etPhone.WavePlay properties are used to associate the etPhone and etPlay controls. The etPhone.Device.Active property must first be set to True. The etPhone.WavePlay.Available indicates whether the telephony device has a wave play audio device associated with it. The etPhone.WavePlay.ID holds the Windows ID of the wave play device associated with the TAPI phone device. Set the etPlay.Device.ID property to the value in the etPhone.WavePlay.ID to ensure that you are using the correct wave audio device.

Debugging

Setting the property etPlay.Popup.OnError to True now causes the Windows messages to be logged in TeleScope. The allocation and deallocation of Windows handles is also logged.

Also see

Working with Wave Files and Buffers