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 Asterisk ZAP channels 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 the 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. There must be no spaces in 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 definition 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.
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 referring 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

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. Record some of the tones 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.

Log messages

If during a configuration reload you get the log message
indications.c:505 ast_unregister_indication_country: Removed default indication country ‘XX’
then you probably don’t have much to worry about since in indications.c source it says that one should notice once the default indications get removed. If you then do core set verbose 10 (something > 2), upon reload you’ll see that indication reload steps are working fine and this diagnostic message is a temporary (albeit very confusing) step during reload only.

Country-by-Country Tone References

http://www.cs.columbia.edu/sip/drafts/draft-roach-voip-ringtone-00.txt

References

ITU Recommendation VARIOUS TONES USED IN NATIONAL NETWORKS ITU-T RECOMMENDATION E.180

Asterisk config indications.conf