Tone Indications Configuration: indications.conf

The Playtones command can generate tones to indicate busy, ringing, congestion, dialtone, and similar. The indications.conf file defines the exact specifications of these tones. The sample indications.conf file installed with Asterisk has tone definitions for a variety of countries. You may use one of those, or edit the file with your own custom tones.

Note that the tone indications played to handsets connected to the Zap channel are NOT generated WITHIN Asterisk, but from the configurations of the Zaptel driver. You can configure the country in the zaptel driver's configuration file, zaptel.conf. To change the frequencies, you have to edit he source code in zonedata.c.

Tones played through other channels (SIP, IAX) are affected by indications.conf only if the tones are actually generated by Asterisk; for instance during the ringing interval of a SIP call, you may get ringback tone generated by your SIP phone or ATA, while if you had Asterisk dialtone due to using the DISA command you would get call progress tones generated by Asterisk.

In short, the settings in indications.conf affect only the tones generated by the Playtones command.

File Format of indications.conf

[general]

There is only one variable you can set in the [general] section: country. Possible values are any of the two-letter country codes defined in the remainder of this file. The setting of country determines which tone set is used by the Playtones command. There seems to be no Asterisk Command available to select a country setting from within the execution of a context's extension. Note that the SetLanguage command does not affect the country setting; country is different from language.

   [general]
   country=fr

Tone Definitions

You can probably just set the country code and ignore the rest of this configuration file. You need to proceed only if you wish to customize the indication tones used by the Playback command.

The rest of the indications.conf file is taken up by the definition of tone sets. Each tone set definition is in this format:

   [xx]
   description = description
   alias = aliases
   ringcadence = ringcadences
   dial = tonelist
   busy = tonelist
   ring = tonelist
   congestion = tonelist
   callwaiting = tonelist
   dialrecall = tonelist
   record = tonelist
   info = tonelist
   name = tonelist

• xx is the two-letter country code used to name this tone set
• description should be the full name of the country, in English
• aliases, if defined, is a list of additional 2-letter country codes which also use this same set of tones
• ringcadences is a comma-separated list of the durations the physical bell rings and pauses. There should be one or more pairs of durations listed; the first number in each pair is the ring time, and the second number is the pause time. "400,200" indicates to ring for 400 ms, then pause for 200 ms. "400,200,400,2000" indicates to ring for 400 ms, pause 200 ms, ring for 400 ms, pause for 2000 ms, and then the cycle is repeated as long as necessary. (:exclaim:) There must be no spaces in the this list of ring and pause durations.
• tonelist defines a sound sequence to be played. It is a comma-separated list of one or more sounds to play. The definition of a sound is a little complex:

   [!]frequency1[+frequency2][*modulation][/duration]

• Starting the sound definiton with an exclamation mark indicates that this sound should be played only once and omitted for the second and successive repeats of this sound sequence. If all the sounds in tonelist are so marked, then this tonelist has a fixed playing time. All other tonelists will repeat indefinitely.
• frequency1: The frequency, in Hz, of the sound to play.
• frequency2: You may optionally specify a second frequency to play simultaneously with the first. For example, "350+440" plays a 350 Hz sound and a 440 Hz sound simultaneously, generating the standard US dialtone.
• modulation: You may specify a modulation frequency, in Hz. For example, 425*25 means a tone of 425 Hz modulated by 25 Hz. Beware: Asterisk does not have a parameter to specify the modulation depth and uses 90% by default.
• duration: The duration, in ms, of the sound. The default duration is "infinite".
• If you want a pause in your tonelist, then specify a frequency of 0 Hz along with a duration. For example, 0/1000 generates one second of silence.
• (:exclaim:) There must be no spaces in the definition of tones in a tonelist.
• name = tonelist: You may specify your own custom tones with custom names. You can then play your custom tones by refering to them with Playtones(name).

Note that ringcadence is not a tone. It is the timing sequence (time on/time off) for the ringer of a phone when a call arrives. Consider that originally telephones simply had a mechanical bell that could be turned on or off. The specification of ringcadences is simply a specification of the amount of time to turn that "mechanical bell" on and off. You can not specify sound frequencies; it is up to the telephone handset to either physically ring a mechanical bell, or to make some other sound. All other tones can be specified in terms of frequencies because they are generated after a handset has been lifted. The ring tonelist is the sound you hear in the earpiece when you have dialed someone else; it is the signal to you that the other end of the connection is ringing.

These tone names are used by Asterisk, and a tone set should define a tonelist for each of these tones:

• ringcadence: how to ring the "mechanical bell" on a telephone handset
• dial: the dialtone you hear when you lift the telephone off the hook
• ring: the sound you hear when the telephone you have dialed is ringing
• busy: the sound you hear when the telephone you have dialed is offhook
• congestion: the sound you hear when your call could not be connected through to the destination you dialed (e.g. because all connections in part of the network are in use for other calls)
• callwaiting: the sound you hear when you are in a conversation, and the exchange wishes to indicate to you that someone is trying to dial you
• dialrecall: no precise definition of what this means, but many phone systems play a 'recall dial tone' after switch hook for call holding, conferencing, etc.
• record: This tone is played during a conversation to indicate that the conversation is being recorded. Typically it is a very short beep with long intervals between beeps.
• info: no definition of what this means, often used to mean 'Special Information Tone' (SIT)

Example

   [us]
   description = United States / North America
   ringcadance = 2000,4000
   dial = 350+440
   busy = 480+620/500,0/500
   ring = 440+480/2000,0/4000
   congestion = 480+620/250,0/250
   callwaiting = 440/300,0/10000
   dialrecall = !350+440/100,!0/100,!350+440/100,!0/100,!350+440/100,!0/100,350+440
   record = 1400/500,0/15000
   info = !950/330,!1400/330,!1800/330,0

More Examples

• John Todd, Loligo.com
• Asterisk indications default: The default configuration
• Asterisk indications Brazil: Indications for Brazil
• Asterisk indications Colombia: Indications for Colombia
• Asterisk indications Croatia: Indications for Croatia
• Asterisk indications Germany: Indications for Germany
• Asterisk indications Hungary: Indications for Hungary
• Asterisk indications Iceland: Indications for Iceland
• Asterisk indications New Zealand: Indications for New Zealand
• Asterisk indications Portugal:: Indications for Portugal
• Asterisk indications Poland: Indications for Poland
• Asterisk indications Spain: Indications for Spain
• Asterisk indications Sweden: Indications for Sweden
• Asterisk indications UK: Indications for UK
• Asterisk indications BE: Indications for Belgium
• Asterisk indications Turkey: Indications for Turkey

Generating a Tone Set

Matching the tones you hear on your country's telephone system isn't hard, if you have the right tools. Try the free sound editor you will find at http://www.speech.kth.se/wavesurfer/. Record some of the tone you are interested in. Then use wavesurfer to look at it. Choose the n-waveforms view. Left click over the waveform and mark out a chunk of the recording you are interested in. Then right click over the waveform and choose "spectrum section". This will show a spectrum analysis of the sound in the section you marked. This may not initially give enough resolution to pinpoint the exact frequency of the tones. Click on the "FFT points" box, and set the number of points to a higher value. You should then have the resolution you need.

Country-by-Country Tone References

• http://www.cs.columbia.edu/sip/drafts/draft-roach-voip-ringtone-00.txt
• http://www.cisco.com/univercd/cc/td/doc/product/tel_pswt/vco_prod/index.htm

References

• Teletone Telephone Line Emulator TLE-A User's Manual
• What are the frequencies of the telephone tones?

See also

• Playtones

---

Asterisk | Asterisk config files