Configuring Asterisk 13
Many customers run the Asterisk PBX against Capacity Private Cloud speech services, and the two work well together — but the friction is often in installing and configuring Asterisk and UniMRCP before the speech services even enter the picture. This guide walks through a complete, worked example: installing and configuring Asterisk 13, UniMRCP 1.3.0, and the Capacity Private Cloud speech services on CentOS 6 64-bit, with test calls at each layer to confirm progress.
An accompanying video walkthrough is available in the Installation Video Training Series — Asterisk 13.
Before starting, a few assumptions about the approach:
- We start from a fresh installation of CentOS 6 64-bit. The process is virtually identical for CentOS or RHEL 5 or 7.
- We follow Justin Hester's blog post on installing Asterisk 13 and PJSIP on CentOS 6 for the Asterisk and PJSIP portions.
- Asterisk 13 uses a library called PJSIP — the channel driver that replaces the older DAHDI and LIBPRI drivers — so PJSIP must be installed before Asterisk.
- We install UniMRCP 1.3.0.
- We install the speech services (this example was built on version 13.1; the steps are essentially the same across releases). You will need valid licenses to configure the services. This example uses both ASR and TTS and therefore requires both license types; an ASR-only or TTS-only setup follows the same process without the missing portion.
- You will need a SIP phone or softphone to place test calls. This example uses X-Lite, but any SIP phone works.
Important — version pinning. This walkthrough uses explicit versions, but the same approach works for platform versions newer than the 13.1 shown here. The same is not guaranteed for Asterisk and UniMRCP, which are not maintained by Capacity — exercise caution with different version combinations, and note that only certain Asterisk/UniMRCP combinations are supported. See Before You Begin: Asterisk Installation.
The Big Picture
UniMRCP sits between Asterisk and the Media Server. The Media Server lets external software — such as UniMRCP — communicate over MRCP and request ASR and TTS resources as needed. Asterisk cannot do this on its own; UniMRCP provides that capability, making Asterisk applications speech-enabled. The diagram shows all components on a single server, but the speech services can run on their own host if preferred.
The preferred way to integrate with Asterisk is through the Asterisk modules provided by the UniMRCP Project — an open-source implementation of the Media Resource Control Protocol (MRCP) that the Media Server fully supports. These modules let Asterisk act as an MRCP client, making ASR and TTS requests to the Media Server.
Starting From a Fresh Instance
You don't have to start with a new operating system, but it is cleaner to do so. This example uses a fresh CentOS 6 64-bit installation. There is nothing special about that OS; the process is virtually identical on any other supported OS, such as CentOS/RHEL 5 or 7.
Set Up the Environment
Before installing anything, bring the machine up to date so you have the latest versions installed:
# yum update
Next, install the packages required by PJSIP, Asterisk, and UniMRCP (several of these steps are based on Justin Hester's blog):
# yum install -y epel-release dmidecode gcc-c++ ncurses-devel libxml2-devel make wget openssl-devel newt-devel kernel-devel sqlite-devel libuuid-devel gtk2-devel jansson-devel binutils-devel libtool jansson-devel
You may encounter other required packages along the way, but these cover most of what you will need.
Installing PJSIP
Move to /usr/src, download the PJSIP source, and unpack it:
# cd /usr/src # wget http://www.pjsip.org/release/2.3/pjproject-2.3.tar.bz2 # tar -jxvf pjproject-2.3.tar.bz2
Move into the new source folder and run the configure script:
# cd pjproject-2.3 # ./configure CFLAGS="-DNDEBUG -DPJ_HAS_IPV6=1" --prefix=/usr --libdir=/usr/lib64 --enable-shared --disable-video --disable-sound --disable-opencore-amr
The next four commands build, install, and link the PJSIP libraries:
# make dep # make # make install # ldconfig
Verify that the PJSIP libraries have been dynamically linked:
# ldconfig -p | grep pj
You should see output like this:
Installing Asterisk 13
To build and install Asterisk 13 from source, change to /usr/src:
# cd /usr/src
Download the tarball from downloads.asterisk.org:
# wget http://downloads.asterisk.org/pub/telephony/asterisk/asterisk-13-current.tar.gz
Unpack the source into its new directory (named asterisk-13.4.0) and change into it:
# tar -zxvf asterisk-13-current.tar.gz # cd asterisk-13.4.0
Run the configure script:
# ./configure --libdir=/usr/lib64
If you get errors here, a tool or dependency is usually missing; the error typically indicates what it needs. Install the missing components, re-run ./configure, and continue once it succeeds. A successful configuration looks like this:
Run make menuselect to verify the PJSIP channel driver dependencies installed correctly:
# make menuselect
Use the arrow keys to navigate to Resource Modules in the left column (about halfway down). Press the right arrow, then scroll to the modules beginning with res_pjsip_. If these modules show [XXX] beside their name, the dependencies have not been met — return to the /usr/src/pjproject directory, run make distclean, and start over, watching carefully for error messages. If you see [*] instead, the res_pjsip dependencies are met and you can proceed. A correct menuselect screen looks like this:
After exiting menuselect, build and install Asterisk along with the sample configuration files:
# make && make install # make samples
Set Asterisk to start at boot:
# make config
Start the Asterisk service without rebooting:
# service asterisk start
Connect to Asterisk:
# asterisk -rvvvvvvvvvvvvvvv
You should see something like this, confirming Asterisk is running:
Quit the Asterisk console before moving on:
*CLI> quit
A Simple Dialplan to Test the Asterisk Configuration
Edit /etc/hosts and add a line for your server's IP address and hostname (your IP will almost certainly differ from the one shown):
172.18.2.111 EL6-VBOX
Tip: Back up /etc/asterisk/pjsip.conf before modifying it, so you always have the original for reference. A sample copy is also attached to this article.
# cp /etc/asterisk/pjsip.conf /etc/asterisk/pjsip.orig
Edit /etc/asterisk/pjsip.conf with the following settings:
| [transport-udp] type=transport protocol=udp bind=0.0.0.0 [6001] type=endpoint context=public disallow=all allow=ulaw auth=6001 aors=6001 [6001] type=auth auth_type=userpass password=password username=6001 [6001] type=aor max_contacts=1 |
Tip: Likewise, back up /etc/asterisk/extensions.conf before modifying it. A sample copy is attached to this article.
# cp /etc/asterisk/extensions.conf /etc/asterisk/extensions.conf.orig
Edit /etc/asterisk/extensions.conf with the following dialplan (from the Testing the Installation on Asterisk article):
| [public] exten = 100,1,Goto(hello-world,s,1) exten = 101,1,Goto(lumenvox-mrcp-tts-test,s,1) exten = 102,1,Goto(lumenvox-mrcp-asr-test,s,1) exten = 103,1,Goto(lumenvox-test,s,1) [default] [hello-world] exten = s,1,Answer() same = n,Wait(1) same = n,Playback(hello-world) same = n,Hangup() [lumenvox-mrcp-tts-test] exten = s,1,Answer same = n,Wait(1) same = n,MRCPSynth(Welcome to LumenVox) same = n,Verbose(1, ${SYNTHSTATUS}) [lumenvox-mrcp-asr-test] exten = s,1,Answer() same = n,Wait(1) same = n,MRCPRecog(builtin:grammar/boolean,&f=beep) same = n,Verbose(1,Status is: ${RECOGSTATUS} and Result is: ${RECOG_RESULT}) [lumenvox-test] exten = s,1,Answer same = n,Wait(1) same = n,SpeechCreate same = n,SpeechLoadGrammar(yesno,builtin:grammar/boolean) same = n,SpeechActivateGrammar(yesno) same = n,SpeechBackground(beep) same = n,Verbose(1,Result was ${SPEECH_TEXT(0)}) same = n,Verbose(1,Confidence was ${SPEECH_SCORE(0)}) |
Restart Asterisk so the changes take effect:
CLI> core restart now
Configure the SIP Phone and Test Hello World Playback
This example uses an X-Lite SIP phone, but use whichever SIP phone or softphone you prefer.
Set the Domain to the IP address of the Asterisk server, the User ID to 6001, and the Password to password (both configured in the PJSIP settings above). Open an Asterisk console with some verbosity:
# asterisk -rvvvvvvvvvvvvvvv
Dial extension 100. You should hear a female voice saying "Hello World," and the Asterisk console should look similar to this:
Installing UniMRCP Dependencies (1.3.0)
Navigate to /usr/src:
# cd /usr/src
Download the dependency tarball from unimrcp.org:
# wget http://www.unimrcp.org/project/component-view/unimrcp-deps-1-3-0-tar-gz/download –O unimrcp-deps-1.3.0.tar.gz
Unpack it into the unimrcp-deps-1.3.0 directory and change into it:
# tar -zxvf unimrcp-deps-1.3.0.tar.gz # cd unimrcp-deps-1.3.0
Run the dependency build script and follow the prompts:
# ./build-dep-libs.sh
Note the installation directory and type y to continue installing the APR and Sofia-SIP libraries.
Confirm installation of the APR and Sofia-SIP libraries when prompted — both are required by UniMRCP. This completes the dependency requirements, and UniMRCP can be installed next.
Installing UniMRCP
# cd /usr/src # wget http://www.unimrcp.org/project/component-view/unimrcp-1-3-0-tar-gz/download -O unimrcp-1.3.0.tar.gz # tar -zxvf unimrcp-1.3.0.tar.gz # cd unimrcp-1.3.0 # ./bootstrap
If you see errors about missing components or tools, install them and re-run ./bootstrap before running configure:
# ./configure --with-apr=/usr/local/apr --with-apr-util=/usr/local/apr
You should see a summary report similar to this:
****************************** REPORT ****************************** UniMRCP version............... : 1.3.0 APR version................... : 1.5.1 APR-util version.............. : 1.5.4 Sofia-SIP version............. : 1.12.11-225-g94cb919 Compiler...................... : gcc Compiler flags................ : -g -O2 -pthread Preprocessor definitions...... : -DLINUX -D_REENTRANT -D_GNU_SOURCE Linker flags.................. : UniMRCP client lib............ : yes Sample UniMRCP client app..... : yes Sample UMC C++ client app..... : yes Misc ASR client lib and app... : yes UniMRCP server lib............ : yes UniMRCP server app............ : yes Demo synthesizer plugin....... : yes Demo recognizer plugin........ : yes Demo verifier plugin.......... : yes Recorder plugin............... : yes Installation layout........... : classic Installation directory........ : /usr/local/unimrcp ********************************************************************
Assuming this succeeded, build and install the modules:
# make # make install
Once complete, proceed to the asterisk-unimrcp modules.
Installing the asterisk-unimrcp Modules
Change into /usr/src again and download/unpack the asterisk-unimrcp package:
# cd /usr/src # wget http://www.unimrcp.org/project/component-view/asterisk-unimrcp-1-3-0-tar-gz/download -O asterisk-unimrcp-1.3.0.tar.gz # tar -zxvf asterisk-unimrcp-1.3.0.tar.gz
Move into the folder and run the bootstrap and configure scripts:
# cd asterisk-unimrcp-1.3.0 # ./bootstrap # ./configure --prefix=/usr/lib64/asterisk/modules
If successful, you should see the following report:
Build and install the asterisk-unimrcp modules:
# make # make install
Confirm the following files exist:
# ls /etc/asterisk/mrcp.conf # ls /etc/asterisk/res-speech-unimrcp.conf # ls /usr/local/unimrcp/conf/client-profiles/lumenvox.xml # ls /usr/local/unimrcp/conf/unimrcpclient.xml
All of these should exist in the locations shown. If any is missing, recheck the recent steps — in particular, verify that make install ran correctly, since it generates these sample configuration files. Follow the Installing and Configuring UniMRCP Modules article to copy in the contents of these files, making backup copies of the originals first.
Note: Make sure the RTSP port of the MRCP server, server-port = 554, is correct in /etc/asterisk/mrcp.conf. A sample copy of this file is attached to this article.
Start Asterisk with the -c (console) option if it is not already running:
# asterisk -cvvvvvvvvvvvvvvvvvvvv
If Asterisk is already running, use the -r (remote) option to connect to the console:
# asterisk -rvvvvvvvvvvvvvvvvvvvv
Confirm the UniMRCP modules are loaded:
CLI> module show like mrcp
You should see something like this:
If you do not see the modules, restart Asterisk and try again:
CLI> core restart now CLI> module show like mrcp
Installing the Speech Services
Install Capacity Private Cloud following the platform installation guide. The legacy package-based install involves creating or updating /etc/yum.repos.d/LumenVox.repo for your Linux OS. For the CentOS 6 64-bit system used here, the file looks like this:
################################################### [LumenVox] name=LumenVox Products x86_64 baseurl=https://www.lumenvox.com/packages/EL6/x86_64/ enabled=1 gpgcheck=0 ###################################################
Edit the media_server.conf settings file and set sip_port = 0 to disable the SIP interface, since UniMRCP communicates with the platform using MRCPv1 (RTSP). Run a basic sanity check to confirm the services are configured and working:
# lv_show-config -a
The MRCPv2 (SIP) tests are expected to fail here, because we disabled sip_port in media_server.conf above.
Testing the Full Installation
Use the same X-Lite softphone you configured earlier to place test calls and verify that everything is installed and working. Each extension exercises a specific layer, progressing from basic Asterisk playback up to full speech integration.
Dial extension 100
Tests basic Asterisk playback of the "Hello World" prompt. You should hear a female voice saying "Hello World." This verifies that Asterisk and PJSIP are installed and configured correctly, without using UniMRCP or the speech services.
Dial extension 101
Tests MRCPSynth(Welcome to LumenVox). You should hear the synthesized "Welcome to LumenVox" audio. This confirms that Asterisk, UniMRCP (MRCPSynth), and the TTS service are all working and configured correctly.
Dial extension 102
Tests MRCPRecog(builtin:grammar/boolean,&f=beep). Say either "yes" or "no" after the beep. A successful result confirms that Asterisk, UniMRCP (MRCPRecog), and the ASR service are all working and configured correctly.
Dial extension 103
Tests ASR through the Generic Speech API. A successful result confirms that Asterisk, UniMRCP (Generic Speech API), and the ASR service are all working and configured correctly.
Success
If you reach this point, you have successfully installed and configured Asterisk 13, UniMRCP 1.3.0, and the Capacity Private Cloud speech services. From here, you can build your own Asterisk applications — see Developing Speech Applications on Asterisk and the Asterisk Generic Speech API overview for examples and tips.
Sample Configuration Files
The following sample files were used while producing this guide and are attached to this article for reference. Any IP addresses in these files may need to be updated to match your machine:
extensions.conflumenvox.xmlmrcp.confpjsip.confres-speech-unimrcp.confunimrcpclient.xml