Asterisk generic speech API - overview
Asterisk's Generic Speech Recognition API lets you drive speech recognition directly from the dialplan, without writing a separate application against a lower-level interface. It exposes a compact set of dialplan applications and functions that create a speech resource, load and activate grammars, run a recognition against caller audio, and read the result back into channel variables. Capacity Private Cloud registers as the speech engine behind this API, so the same dialplan primitives drive the platform's ASR.
This article walks through the end-to-end recognition flow and the dialplan applications used at each stage.
Two ways to integrate Asterisk. The Generic Speech API described here drives recognition through Asterisk's native res_speech framework, with the platform registered as the speech engine. Alternatively, the UniMRCP / MRCPv2 path connects Asterisk to the Media Server over MRCP using applications such as MRCPRecog() and SynthAndRecog(). Use the Generic Speech API when you want recognition expressed natively in the dialplan; use UniMRCP when you need MRCP interoperability or text-to-speech alongside recognition. See the related articles below for the MRCP path.
The Recognition Lifecycle
A speech-enabled call flow follows six stages: create a resource, load and activate grammars, run the recognition, read the result, and release the resource.
1. Initialize the Connection
Call SpeechCreate() to open a connection between Asterisk and the speech engine. This allocates a speech resource on the channel, to which grammars and recognitions are subsequently bound. Each resource you create consumes one ASR license, so create a resource only when a recognition is needed and release it once the interaction is complete.
2. Load a Grammar
Load a grammar with SpeechLoadGrammar(), which takes two parameters separated by a pipe: a label you choose, and the path to the grammar. The label is how you reference the grammar in later steps:
SpeechLoadGrammar(yesno|/opt/lumenvox/engine/Lang/BuiltinGrammars/ABNFBoolean.gram)
3. Activate Grammars
Active grammars determine what the engine will recognize — at any moment, recognition is constrained to the words and phrases defined in the currently active grammars. Activate a loaded grammar by its label with SpeechActivateGrammar():
SpeechActivateGrammar(yesno)
4. Run the Recognition
Begin listening with SpeechBackground() or SpeechStart(). SpeechBackground() takes the name of a prompt to play while it listens, and supports barge-in — much like the standard Background() application — so the caller can answer before the prompt finishes. Recognition runs against the caller's audio until a result is returned or the recognition times out.
5. Examine the Results
Recognition results are exposed as dialplan functions. The most commonly used are:
${SPEECH(results)}— the number of results returned.${SPEECH_TEXT(n)}— the text the caller said for resultn, or its semantic interpretation when the grammar defines one.${SPEECH_SCORE(n)}— the confidence score for resultn.
Result indexes are zero-based, so the top result is ${SPEECH_TEXT(0)}.
6. Release Resources
When recognition is finished, deactivate and unload grammars with SpeechDeactivateGrammar(label) and SpeechUnloadGrammar(label), then release the speech resource with SpeechDestroy(). Destroying the resource frees the associated ASR license. Always release resources at the end of an interaction so licenses are not held longer than needed.
Putting It Together
The following dialplan extension shows the full lifecycle — create, load, activate, recognize, read the result, and clean up — for a simple yes/no prompt:
| exten => s,1,Answer() same => n,SpeechCreate() same => n,SpeechLoadGrammar(yesno|/opt/lumenvox/engine/Lang/BuiltinGrammars/ABNFBoolean.gram) same => n,SpeechActivateGrammar(yesno) same => n,SpeechBackground(please-say-yes-or-no) same => n,Verbose(1,Caller said: ${SPEECH_TEXT(0)} (score ${SPEECH_SCORE(0)})) same => n,SpeechDeactivateGrammar(yesno) same => n,SpeechUnloadGrammar(yesno) same => n,SpeechDestroy() same => n,Hangup() |
Related Articles
Developing speech applications on Asterisk:
- Developing Speech Applications on Asterisk
- Building Asterisk Speech Applications with AGI
- Asterisk PHP Generic Speech Interface
- Configuring Asterisk 13
- Testing the Installation on Asterisk
The MRCP integration path (UniMRCP / MRCPv2):
- Configuring UniMRCP Modules Using MRCPv2
- Installing and Configuring UniMRCP Modules
- Media Server Overview
Writing grammars and semantic interpretation:
For the complete reference on Asterisk's Generic Speech Recognition API applications and functions, see the Asterisk documentation.