Prerequisites

  1. If the music voice segment you use is specific to your state table, store the music data in a segment before you write your state table. This can be packaged to be imported and exported with the state table.
  2. Unless you want to define tunes dynamically in the state table, you can define your tunes in the configuration file. However, you should always define a default tune in the configuration file, so that if an application fails to dynamically configure a tune, there is always a tune configured and available to be played by the application.
  3. Ensure that a call has already been connected. The Juke_Box custom server rejects SendData requests unless a call is already established or connected.

State table

  1. Start: Use the OpenHostServerLink action to set up a link between the state table and the Juke_Box custom server. Check that the action succeeds. If it fails, let your application continue without using background music.
  2. If the tune you want to play is in the configuration file, go to step 5.
  3. Define a tune dynamically: Use the SendData action, specifying the juke_box_configure_music command. For details, see the Blueworx Voice Response for AIX: Application Development using State Tables.
  4. Use the ReceiveData action and then check the return code. If the Juke_Box custom server was unable to configure the tune, don't ask the Juke_Box custom server to play it. Instead, either use a tune that you know is available, or don't use background music for the rest of the call. Don't let your state table fail because it could not configure a tune. Make your application as robust and forgiving as you can.
  5. Start playing a tune: Use the SendData action, specifying the juke_box_start_music command to tell the Juke_Box custom server which tune to play. For details, see the Blueworx Voice Response for AIX: Application Development using State Tables information.
  6. Use ReceiveData to get the return code and check that the tune starts to play.
  7. If the tune doesn't start playing, set up alternative paths for your state table to follow. For example, if all the music channels are in use, you may want your state table to use a “music-of-the-day” default tune (if your system has this set up).
  8. Take appropriate action for all possible results from the SendData and ReceiveData actions.
  9. Fade the tune in: Use the ControlMusic action to increase the volume of the tune while it is playing. The initial volume is low: increase it so that the tune can be heard.
    Smooth Volume Change
    If you want the background music in your application to fade smoothly, use ControlMusic with a non-zero value for the Fade Time parameter . You can fade the music in two ways:
    • Wait for the fade action to complete before proceeding with the next action in the state table.
    • Proceed with the next action in the state table, while the music fades.
    Instant Volume Change
    To change the volume instantly, use ControlMusic with the Fade Time parameter set to 0. This is not recommended, as it can cause “clicks” on the line, which can be disconcerting to the caller.
  10. Take appropriate action for all possible results from the ControlMusic action.
  11. Change Smoothly from One Tune to Another: If you want to change from one tune to another smoothly, use two ControlMusic actions in your state table. In the first action, fade out the current tune by setting the fade option to wait until fade actions complete and set the volume to 80dBm (silence). In the second action fade in the new tune (use wait until fade actions complete or not, as you want).
  12. Take appropriate action for all possible results from the ControlMusic action.
  13. Perform normal application activities: Some actions work with background music playing to the caller, some fade out background music before the action starts, and fade in the music when it is complete. You can override the automatic fading using the system variables (see Table 1).
  14. Fade the tune out: When your state table has finished with the tune, use the ControlMusic action to fade the music to silence. Use a value of 80 dBm for silence.
  15. Stop playing a tune: If the tune plays successfully, make sure that your state table stops it playing (to release resources) before closing the host server link.
  16. Use the SendData action, specifying the juke_box_stop_music command to tell the Juke_Box custom server when you have finished using a tune, so that the resources can be released and reallocated. For details, see the Blueworx Voice Response for AIX: Application Development using State Tables information.
  17. Use ReceiveData to get the return code and check that juke_box_stop_music command was successful.
    Note: The tune does not stop if it is still playing on another channel. In this situation, it stops when a juke_box_stop_music command has been received by the custom server from each of the channels on which the tune is playing. (In effect, the custom server needs to receive a juke_box_stop_music command for every juke_box_start_music command that was issued.)
  18. Cleaning up: Use the CloseHostServerLink action, specifying the Juke_Box custom server.
  19. End the call, free any resources that the application used, and terminate.

Figure 1. Schematic overview of part of a state table using background music
The graphic here interprets the preceding text providing a schematic overview of part of a state table using background music.
Parent topic: Adding background music to a state table