freeswitch spandsp

http://wiki.freeswitch.org/wiki/Mod_spandsp#Invoking_the_app_from_the_XML_dialplan

DTMF

Inband DTMF detectors in mod_spandsp can detect duration in addition to frequency. The mod_spandsp detector is more robust than the legacy teletone detector in the FreeSWITCH core.

Channel Variables

• min_dup_digit_spacing_ms - Duplicate inband DTMF that starts sooner than this time will be ignored. This is not set by default.

Dialplan Applications

spandsp_start_dtmf

Detect inband dtmf on the session

<action application="spandsp_start_dtmf"/>

spandsp_stop_dtmf

Stop detecting inband dtmf

<action application="spandsp_stop_dtmf"/>

Call Progress

mod_spandsp provides the tools to create a call progress tone detector. By accounting for cadence in addition to frequency, this call progress detector can distinguish between North American BUSY and REORDER, which only differ in cadence.

Configuration

conf/autoload_configs/spandsp.conf.xml defines the tone detector descriptors. Each descriptor defines a named grouping of tones to detect. When starting the tone detector, you specify the group of tones you wish to detect.

This is a sample configuration for detecting some call progress tones in North America:

  <configuration name="spandsp.conf" description="Tone detector descriptors">
   <descriptors>
     <!-- These tones are defined in Annex to ITU Operational Bulletin No. 781 - 1.II.2003 -->
     <!-- Various Tones Used in National Networks (According to ITU-T Recommendation E.180)(03/1998) -->

     <!-- North America -->
     <descriptor name="1">
       <tone name="CED_TONE">
         <element freq1="2100" freq2="0" min="500" max="0"/>
       </tone>
       <tone name="SIT">
         <element freq1="950" freq2="0" min="256" max="400"/>
         <element freq1="1400" freq2="0" min="256" max="400"/>
         <element freq1="1800" freq2="0" min="256" max="400"/>
       </tone>
       <tone name="REORDER_TONE">
         <element freq1="480" freq2="620" min="224" max="272"/>
         <element freq1="0" freq2="0" min="224" max="272"/>
       </tone>
       <tone name="BUSY_TONE">
         <element freq1="480" freq2="620" min="464" max="516"/>
         <element freq1="0" freq2="0" min="464" max="516"/>
       </tone>
     </descriptor>
   </descriptors>
  </configuration>

Each descriptor defines the tones to detect. Each tone is composed of elements defining the frequencies and cadence of the tone. The tone name will be reported in the DETECTED_TONE event. Each element can be composed of 0 (silence), 1, or 2 frequencies. min and max define the minimum and maximum element durations in milliseconds.

Tuning the detector

It takes much trial and error to figure out the tone configuration that works well without introducing talk-off. mod_spandsp_dsp.c can be edited to increase the logging level to report additional detection information to assist in this process. To get this additional information, change the globals.debug value in do_config() to 2. Recompile the module and re-install it.

The "Tone report" log will tell you when a tone was detected. The "Tone segment" log will tell you each segment that is detected. The f1 and f2 values identify which frequencies were matched in that segment.

Dialplan Applications

start_tone_detect

Start background tone detection with cadence

 <!-- start detection for North American call progress tones -->
 <action application="start_tone_detect" data="1"/>

stop_tone_detect

Stop background tone detection with cadence

<action application="stop_tone_detect"/>

Events

DETECTED_TONE

This event is fired when the tone detector detects a tone.

The following headers are set:

Detected-Tone
Unique-ID

The Detected-Tone header will contain the name of the tone, as specified in the configuration file. The Unique-ID will contain the session UUID.

http://wiki.freeswitch.org/wiki/Mod_spandsp#min_dup_digit_spacing_ms

============================================

Tone Detection

mod_spandsp offers better tone detection than what is provided by default in the FreeSWITCH core.

DTMF

Inband DTMF detectors in mod_spandsp can detect duration in addition to frequency. The mod_spandsp detector is more robust than the legacy teletone detector in the FreeSWITCH core.

Channel Variables

min_dup_digit_spacing_ms

Duplicate inband DTMF that starts sooner than this time will be ignored. That is, this is the minimum gap from the end of the first digit and the start of the repeated digit required for two digits to be detected. This value is 0 by default. Set this variable prior to executing spandsp_start_dtmf.

Usage:

<action application="set" data="min_dup_digit_spacing_ms=40"/>
<action application="spandsp_start_dtmf" />

spandsp_dtmf_rx_threshold

Sets the threshold parameter in the spandsp DTMF detector. Threshold is set to -42 dBm0 by default. Set this variable prior to executing spandsp_start_dtmf.

Usage:

<action application="set" data="spandsp_dtmf_rx_threshold=-42"/>
<action application="spandsp_start_dtmf" />

spandsp_dtmf_rx_twist

Sets the twist parameter in the spandsp DTMF detector. Twist is set to 8 dB by default. Set this variable prior to executing spandsp_start_dtmf.

Usage:

<action application="set" data="spandsp_dtmf_rx_twist=8"/>
<action application="spandsp_start_dtmf" />

spandsp_dtmf_rx_reverse_twist

Sets the reverse twist setting in the spandsp DTMF detector. Reverse twist is set to 4 dB by default. This value can be safely increased up to 6 or 7 without a significant increase in talk-off to allow DTMFs that exceed this threshold to be detected. Set this variable prior to executing spandsp_start_dtmf.

Usage:

<action application="set" data="spandsp_dtmf_rx_reverse_twist=6"/>
<action application="spandsp_start_dtmf" />

spandsp_dtmf_rx_filter_dialtone

Sets the filter dialtone parameter in the spandsp DTMF detector. Dialtone filtering is disabled by default. Set this variable prior to executing spandsp_start_dtmf.

Usage:

<action application="set" data="spandsp_dtmf_rx_filter_dialtone=true"/>
<action application="spandsp_start_dtmf" />

Dialplan Applications

spandsp_start_dtmf

Detect inband dtmf on the session

<action application="spandsp_start_dtmf"/>

spandsp_stop_dtmf

Stop detecting inband dtmf

<action application="spandsp_stop_dtmf"/>