DTMF
Table of Contents
0. DTMF digits
When writing an application, make sure to handle all valid DTMF tones (with sound clips; copied from the DTMF wikipedia page):
| 1209 Hz | 1336 Hz | 1477 Hz | 1633 Hz | |
|---|---|---|---|---|
| 697 Hz | 1 | 2 | 3 | A |
| 770 Hz | 4 | 5 | 6 | B |
| 852 Hz | 7 | 8 | 9 | C |
| 941 Hz | * | 0 | # | D |
The tones A , B , C , and D are very rare nowadays but they are still possible to send (e.g., someone has an old device with the extra ABCD column) and thus make sure that you handle them in your app, otherwise they may cause it to crash.
1. Mode overview
In the context of two bridged analog channels, we need to consider 5 possible approaches to DTMF handling per audio path (tx and rx).
DTMF behavior for a single audio path can be captured by a triple of booleans as follows:
Matrix
| Mode | Suppress | Detect | Regenerate |
|---|---|---|---|
| passthrough | . | . | . |
| passthrough | . | X | . |
| intercept | X | . | . |
| intercept | X | X | . |
| intercept | X | X | X |
Two such triples would be needed to fully describe the behavior of two bridged channels: one for the rx and one for tx audio path.
2. Mode descriptions
2.1 DTMF passthrough inband
Audio passes between the A and B legs without being inspected or modified.
2.2 DTMF passthrough inband w/ DTMF detection
Audio passes between the A and B legs without being modified. DTMF detection is done by running Goertzel on each 20ms buffer but NOT dropping frames in which DTMF is detected.
2.3 DTMF intercept w/ DTMF removal
DTMF is filtered out. In some implementations this could be a cheaper operation than detect and remove.
2.4 DTMF intercept w/ DTMF detection and removal
Detect DTMF using Goertzel and drop samples containing DTMF tones. The opposite leg will hear silence (with or without some bleeding).
2.5 DTMF intercept w/ DTMF detection, removal and regeneration
Detect DTMF using Goertzel and drop samples identified as containing DTMF tones. Regenerate the detected DTMF tones on the opposite leg. This AFAIK is the only DTMF intercept mode supported by FreeSWITCH ATM.
3. DTMF options
FreeSWITCH attempts to negotiate rfc2833 DTMF out-of-band transmission.
TODO RFC 2833 is obsoleted by RFC 4733.
An option to offer rfc2833 but accept INFO was added in GIT bc7cb400c0d576817b12836012899925dce61cca on June 23, 2011.
- As a SIP Profile option: Sofia Configuration Files#liberal-dtmf and set it to true
- As a gateway/user variable: sip_liberal_dtmf=true (I think, based on the GIT diff?) ~~
If you are receiving the DTMF inband and FreeSWITCH hasn't automatically started inband detection, use mod_dptools: start_dtmf
See more: section DTFM in Sofia Configuration Files.
4. DTMF Tools
You may want DTMF input to trigger certain actions. These tools will let you do that, e.g. start recording the call or initiate a transfer.
- Watch for digits: mod_dptools: bind_meta_app or the more flexible mod_dptools: bind_digit_action
- Play a prompt to enter digits: mod_dptools: play_and_get_digits