Tone Recognizer
Tone Recognizer
The Tone Recognizer listens to call audio and recognises the tones in it - the DTMF digits a phone sends, and the tone-based alarm protocols some panels use - turning them into data SBN can act on.
Overview
Some information arrives as sound rather than data: the digits of a touch-tone phone, or the tone bursts an older alarm panel sends down a line. The Tone Recognizer decodes these from the audio of a call and emits what it hears - the digit pressed, or the bytes of a tone protocol.
It recognises:
- DTMF - the touch-tone digits
0-9,*,#, andA-D. - Tone protocols - FSK, OOK, pulse, Robofon, and SIA DC-03.
- Voice activity - whether someone is speaking, used to tell speech from silence.
It is attached to a call's audio while the call is up and detaches when it ends. Which decoder a line uses is chosen in the line configuration.
There is also a simpler inband recogniser built directly into the media streams for straightforward DTMF; the Tone Recognizer is the fuller service used when a line needs a specific tone protocol.
- Runs: When configured. Attached per call as needed.
- Required: Needed where digits or tone-based alarm protocols must be read from call audio. Not needed for data-only signalling.
- Depends on: NATS and the line configuration (which selects the decoder per line).
Configuration
The Tone Recognizer is configured under the toneRecognizer namespace for the host defaults; the decoder a given line uses is set per line in the line configuration (toneRecognizer, with an optional digitTimeout). View the defaults with ./sbn-media config eject and set overrides in sbn-media.local.yaml.
| Setting | Default | Description |
|---|---|---|
toneRecognizer.timeout | 10 | Seconds to wait for the next digit before the sequence is considered finished. |
toneRecognizer.dtmf.minAudioLevel | 0.1 | Minimum loudness before a tone is considered. |
toneRecognizer.dtmf.minToneCount | 4 | How long a tone must hold before it is accepted as a digit. |
toneRecognizer.dtmf.minSilenceCount | 20 | How much silence marks the gap after a digit. |
toneRecognizer.dtmf.minDigitSpaceCount | 2 | The minimum gap required between two digits. |
toneRecognizer.vad.mode | 3 | Voice-activity sensitivity (0-3); higher rejects more noise but may miss quiet speech. |
toneRecognizer.captureToneStream | false | Record the raw tone audio to disk for diagnosis. Off in normal use. |
toneRecognizer.captureLocation | ./recordings | Where captured tone audio is written when capture is on. |
To use a specific decoder on a line, set its toneRecognizer in the line configuration to one of dtmf, fsk, ook, pulse, robofon, dc03, or vad.
After changing these in sbn-media.local.yaml, apply them with ./sbn-media config reload.
FAQ
Which decoder does a line use?
The one set as toneRecognizer on that line in the line configuration. Use dtmf for touch-tone digits, or the matching protocol name (fsk, ook, pulse, robofon, dc03) for a tone-based alarm panel.
Digits are being missed or run together.
Adjust the DTMF timing: minToneCount controls how long a tone must hold to count, minSilenceCount and minDigitSpaceCount control the gaps between digits, and minAudioLevel sets how loud a tone must be.
How is this different from the inband recogniser?
The inband recogniser is built into the media streams and handles straightforward DTMF as audio passes through. The Tone Recognizer is the fuller service attached to a line when it needs a particular tone protocol.
Can I capture the audio to debug a problem line?
Yes - turn on toneRecognizer.captureToneStream to write the raw tone audio to captureLocation. Leave it off in normal operation.
Related pages
- SBN Media Overview (
SBN-Media/overview) - Installing and Configuring SBN Media (
SBN-Media/installation) - Line Configuration (
SBN-Media/Configuration/line-configuration) - Alarm Receiver (
SBN-Media/Alarms/alarm-receiver)