ControlMusic

Purpose

Use ControlMusic to:

Start or stop playing a piece of musicIn this section, the term music refers to any uncompressed audio data.
Control the volume of the music for each telephony channel
Fade music in or out smoothly

Description

Before using ControlMusic:

The call must be connected using a MakeCall, Dial, or AnswerCall state table action.
A music channel (playing the specified Music Title) must be started using a SendData-ReceiveData pair. For information on how to define a tune to the Juke_Box custom server, see the Blueworx Voice Response for AIX: Designing and Managing State Table Applications ¹.

To specify the piece of music:

Select Const and type the name of the piece of music in the Music Title field, or select Var and then select the variable containing the name. The name must match the name passed by the music player custom server to Blueworx Voice Response.

To turn on background music:

In the Volume field, type the difference in decibels (dBm) between the background ceiling volume and the desired music volume.

To fade in the music gradually, specify a Fade Time greater than 100. The maximum is 10000 (10 seconds). To start the music abruptly, specify 100.

To ensure that the state table proceeds directly to the next action, do not select Wait for fade action to complete.

To change the volume:

When background music is already playing, fill in the Music Title, Volume, and Fade Time parameters, changing the value in the Volume field. If the value is numerically lower than the value in the previous ControlMusic action, the music will get louder. If the value is numerically higher than the value in the previous ControlMusic action, the music will get quieter.

To turn off background music:

To stop the music, fill in the Music Title, Volume, and Fade Time parameters, specifying 80 in the Volume field.

Parameters

Music Title

Identifies the piece of music. The Music Title must exactly match the title passed by the music player custom server to Blueworx Voice Response.

Volume

Specifies the difference, in decibels (dBm), between the music volume ceiling and the volume at which the music is to be played. The smaller the number, the louder the music will be played. 0 is the loudest.

To stop the music, specify 80, which is below the lowest possible absolute silence threshold. When the music volume falls below this threshold, the music channel is unlinked from the telephony channel.

Blueworx Voice Response ensures that the volume of the music does not exceed the maximum permissible volume on the line.

Fade Time

Specifies, in milliseconds, whether the music is abruptly started or stopped, or gradually faded in or out. Specify 100 for an abrupt start or stop. (If you specify 0, callers might hear a click.) The maximum is 10000 (10 seconds).

If the caller presses a DTMF key while music is being faded out or in, the DTMF keystroke is available for retrieval after completion of the fade.

Wait for fade action to complete

Specifies whether Blueworx Voice Response waits for the fade to be completed before proceeding with the next action.

When the Fade Time is very short, it does not matter whether you select Wait for fade action to complete.

When the Fade Time is longer, the application will appear to be waiting for the music to fade.

Possible results

ControlMusic can have one of the following results:

Succeeded: The music has started to fade in or out. If you did not select Wait for fade action to complete, the action has also finished.
Music not available: There is no music channel available playing the specified Music Title, or some other error has occurred. See the error log for details. For information on how to define a tune to the Juke_Box custom server, refer to the Blueworx Voice Response for AIX: Designing and Managing State Table Applications information.
Caller Hung Up: The caller hung up while the music was being faded. This result is returned when the ControlMusic action is used before setting up the call (MakeCall, Dial, or AnswerCall actions).

ASCII syntax

When using an ASCII editor, code this action with these parameters in the following order:

Music title
Volume
Value of fade time
Wait for fade action to complete, "WAIT" or "NO_WAIT".

For example:

label: "Fade-in noisy office sound-effects"
   ControlMusic("Fade-in noisy office sound-effects",0,fadetime, "WAIT")
      edge EDGE_CM_SUCCESSFUL:           succeeded_1
      edge EDGE_CM_MUSIC_NOT_PLAYING:    start_music_retry
      edge EDGE_CM_HUP:                  cleanup_app
   ;

The parameters and edges are described above under "Parameters" and "Possible results". For more information, see Testing a state table using the debugger.