The tone manager

The tone manager module is used to provide some tone management functionality for the ringback tone used during some types of call transfer. To use the tone manager module in an application import it as follows:

from prosody.uas import ToneManager

Create a tone manager and pass it a reference to the logger, for example:

tone_manager = ToneManager(my_log)

The ToneManager can be used to create new tones and add them to the list of known tones. It can also be used to set a new default tone.

To set a new default tone use the set_default function. It takes a pre-defined tone as the argument:

ToneManager.set_default(ToneManager.PredefinedTones.RINGBACK_EU)

The tone manager has two pre-defined tones RINGBACK_EU, RINGBACK_UK and RINGBACK (which is the US ringtone).

To add to the list of pre-defined tones use the creat_tone function. This function allows the user to create a custom tone sequence and add it to the tone manager. The function takes two arguments:

• tone_info

  a list of tone descriptions.

• tone_name

  a name to give the new tone sequence

The argument tone_info is a list of tones to play. Each tone in the list is actually a pair of tones that will be combined by either summation or mudulation. The pair of tones are described in a tuple that contains the definition for two tones, the duration and the way they are to be added together. And each tone definition is a dictionary containing the information for that tone. See below for an illustration of tone_info:

[
   (
     {
       'frequency' : value,  # frequency in Hz, 0 to 9999
       'amplitude' : value   # negative amplitude in dBm0, 0 to 99
     },
     {
       'frequency' : value,
       'amplitude' : value
     },
     {
       'duration'  : value,  # duration in milliseconds, 0 to 9999
       'add'       : method  # the method used to add the tones, 'summation' or 'modulation'
     }
   ),
   (
      .. next tone pair
   )
]

The following will play a single 400 Hz tone at -10 dBm0 for 1.65 seconds followed by silence for 3.35 seconds:

# create the tone
new_tone_sequence = [ ( { 'frequency' : 400,
                          'amplitude' : 10 },
                        { 'frequency' : 0,
                          'amplitude' : 0  },
                        { 'duration'  : 1650,
                          'add'       : 'summation' } ),
                      ( { 'frequency' : 0,
                          'amplitude' : 0 },
                        { 'frequency' : 0,
                          'amplitude' : 0 },
                        { 'duration'  : 3350,
                          'add'       : 'modulation' } ) ]

# add the tone to the list of known tones
ToneManager.create_tone(new_tone_sequence, 'MY_RINGBACK')

# set the new tone to be the default tone
ToneManager.set_default('MY_RINGBACK')

For a channel to be able to use the tones that are configured on the tone manager, it must create a tone player. The create_tone_player function on the call channel will take a reference to the tone manager and create a tone player.