# Detecting tones

The tone detector runs a precise tone filter for a single or dual frequency tone. Each instance of the ADI service (for example, each context) has up to six programmable tone detectors. If the current telephony protocol employs an in-band cleardown tone detector, the first tone detector is not available. The tone detectors can generate the following events:

- ADIEVN_TONE_n_BEGIN

where n is the programmable tone ID (1-6)

- ADIEVN_TONE_n_END

where n is the programmable tone ID (1-6)

This topic presents:

- Starting tone detection

- Stopping tone detection

## Starting tone detection

In addition to the tone detector identifier that specifies a tone ID of 1 through 6, adiStartToneDetector takes four parameters that describe a single or dual frequency tone:

Parameter | Description
--- | ---
freq1 | Frequency 1. The center frequency in Hz of a single tone or the first of two frequencies in a dual tone.
bandw | Bandwidth 1. The bandwidth around Frequency 1 that is acceptable.
freq2 | Frequency 2. The center frequency in Hz of the second of two frequencies in a dual tone. Set this value to zero for single frequency tones.
bandw2 | Bandwidth 2. The bandwidth around Frequency 2 that is acceptable. Set this value to zero for single frequency tones.

The range of frequencies detected is the center frequency plus or minus one-half of the bandwidth. The following illustration describes the tone detection frequency parameters:

You can further modify the tone detector's default behavior by specifying the following parameters (which reside in the ADI_TONEDETECT_PARMS structure) when invoking adiStartToneDetector, or by modifying the system defaults:

Parameter | Description
--- | ---
qualampl | Qualification amplitude; the broadband qualification level in dBm required to further qualify any energy as tone.
qualtime | Qualification time; the time in milliseconds in which the tone must be present before reporting ADIEVN_TONE_n_BEGIN. After qualifying at tone, this parameter is used to qualify the absence of the tone to report ADIEVN_TONE_n_END.

The following illustration describes the tone detection qualification parameters:

Note: Do not modify the reflevel and reserved parameters in ADI_TONEDETECT_PARMS. These parameters apply to the DSP algorithms and are provided for diagnostic purposes when working with Dialogic Services and Support.

## Stopping tone detection

adiStopToneDetector immediately terminates a tone detector. The ADI service generates ADIEVN_TONE_n_DETECT_DONE with the value set to CTA_REASON_STOPPED.

The ADI service can also generate ADIEVN_TONE_n_DETECT_DONE with an error code, ADIERR_xxx or CTAERR_xxx, if the function is incorrectly started.