Tools

Installing and Configuring UniMRCP Modules

Reference Number: AA-01129 Views: 46670

0 Rating/ Voters

The preferred method of communicating with the Asterisk PBX is via the use of Asterisk modules provided by the UniMRCP Project. UniMRCP is an open-source implementation of the Media Resource Control Protocol (MRCP) which is fully supported by the LumenVox Media Server. UniMRCP makes available a number of Asterisk modules that allow Asterisk to act as an MRCP client to make automatic speech recognition (ASR) and text-to-speech (TTS) requests to the LumenVox Media Server.

The latest build of UniMRCP for Asterisk can be obtained from the UniMRCP Project.

Note: Prior to LumenVox version 11, the recommend method of integration with Asterisk was via a closed-source "connector bridge" Asterisk module called res_speech_lumenvox.so (owned and maintained by Digium). The help documentation for this module is still available but it is not recommended for users. To clarify - the older "Asterisk Connector Bridge" is no longer supported. All users should adopt the newer and less problematic UniMRCP interface which allows Asterisk to connect to LumenVox ASR and TTS resources using the MRCP protocol.

UniMRCP provides two Asterisk modules: res_speech_unimrcp.so and app_unimrcp.so which work in different ways. We recommend both be built and loaded so you can use either mechanism.

TIP: We have provided a step-by-step guide to installing Asterisk 13 + UniMRCP 1.3.0 + LumenVox 13.1, along with an accompanying video series, which shows all of the steps required to install and configure these components on a fresh operating system, providing a completely functional speech-enabled Asterisk PBX system. See our Configuring Asterisk 13 article for more details.

Installing UniMRCP

NOTE: As of August 2014, there is a known bug in asterisk-unimrcp 1.2.0 that prevents it from functioning properly, resulting in crashes when attempting to invoke MRCPRecog(). We recommend upgrading to asterisk-unimrcp 1.3.0 instead.

Download the latest UniMRCP-Asterisk package. Unimrcp member may also use subversion to get the latest code from the trunk (be sure and get both UniMRCP and the UniMRCP-Asterisk module from the packages repository).
Make sure you have installed the UniMRCP Dependency package before installing UniMRCP package.
Extract the tarball you downloaded using tar -xzvf filename to an appropriate directory (e.g. /usr/src/). If you used subversion to checkout the code you can skip this step.
Follow the readme included with the source code.
Build and install the base UniMRCP libraries (including the dependencies ARP and sofia-sip).
Build and install the UniMRCP-Asterisk modules.

Configuring UniMRCP

UniMRCP has several configuration files that should have been installed:

The mrcp.conf file in /etc/asterisk/
The res-speech-unimrcp.conf file /etc/asterisk/
A set of XML config files in /usr/local/unimrcp/conf/ and /usr/local/unimrcp/conf/client-profiles

If you do not have all of these files, you have likely missed a step in the installation. Do not continue until you have finished the installation.

Depending on whether you are going to use the functionality in res_speech_unimrcp.so or res_unimrcp.so, you will need to change different configuration files.

Configuring res_unimrcp.so

The res_unimrcp.so module relies on the /etc/asterisk/mrcp.conf file. Here is a sample version of the file you can use that is already configured to work with LumenVox, with two important changes:

mrcp.conf

[general]
default-asr-profile = speech-lumenvox-mrcp1
default-tts-profile = speech-lumenvox-mrcp1

; UniMRCP logging level to appear in Asterisk logs. Options are:
; EMERGENCY|ALERT|CRITICAL|ERROR|WARNING|NOTICE|INFO|DEBUG -->
log-level = DEBUG
max-connection-count = 100
offer-new-connection = 1
; rx-buffer-size = 1024
; tx-buffer-size = 1024
; request-timeout = 60

[speech-lumenvox-mrcp1]
; +++ MRCP settings +++
version = 1
;
; +++ RTSP +++
; === RSTP settings ===
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Set this to the LumenVox Media Server's IP:
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
server-ip = 127.0.0.1
server-port = 554
; force-destination = 1
resource-location = media
speechsynth = speechsynthesizer
speechrecog = speechrecognizer
;
; +++ RTP +++
; === RTP factory ===

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; Set this to the local machine's IP:
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
rtp-ip = 127.0.0.1
; rtp-ext-ip = auto
rtp-port-min = 4000
rtp-port-max = 5000
; === RTP settings ===
; --- Jitter buffer settings ---
playout-delay = 50
; min-playout-delay = 20
max-playout-delay = 200
; --- RTP settings ---
ptime = 20
codecs = PCMU PCMA L16/96/8000 telephone-event/101/8000
; --- RTCP settings ---
rtcp = 1
rtcp-bye = 2
rtcp-tx-interval = 5000
rtcp-rx-resolution = 1000

The two changes that must be made:

Set the server-ip address to the IP address of the machine running the LumenVox Media Server.
Set the rtp-ip address to the IP address of the machine running Asterisk.

Reload Asterisk after making these changes, and you may move on to testing the installation.

Configuring res_speech_unimrcp.so

Configuring the res_speech_unimrcp.so module is a little more complex than res_unimrcp.so. First, you must edit the /etc/asterisk/res-speech-unimrcp.conf file. Here is a sample to use:

res-speech-unimrcp.conf

[general]
; UniMRCP named profile. Options are:
;unimrcp-profile = uni2 ; UniMRCP MRCPv2 Server
;unimrcp-profile = uni1 ; UniMRCP MRCPv1 Server
;unimrcp-profile = lv2 ; LumenVox MRCPv2 Server
unimrcp-profile = lv1 ; LumenVox MRCPv1 Server (uncomment this line)

; UniMRCP logging level. Options are:
; EMERGENCY|ALERT|CRITICAL|ERROR|WARNING|NOTICE|INFO|DEBUG -->
log-level = DEBUG

; Preloaded grammars
[grammars]
;grammar-name = path-to-grammar-file

; MRCPv2 properties (recognizer and generic header fields)
; http://tools.ietf.org/html/draft-ietf-speechsc-mrcpv2-20#section-9.4
[mrcpv2-properties]
Recognition-Timeout = 20000
No-Input-Timeout = 15000

; MRCPv1 properties (recognizer and generic header fields)
; http://tools.ietf.org/html/rfc4463#section-8.4
[mrcpv1-properties]
Recognition-Timeout = 20000
No-Input-Timeout = 15000

You will want to make sure that the only profile not commented out is lv1 so it is ensured of being the default profile.

The settings for lv1 are defined in /usr/local/unimrcp/conf/client-profiles/lumenvox.xml. Again, here is a sample to use:

lumenvox.xml

<?xml version="1.0" encoding="UTF-8"?>

<unimrcpclient xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../unimrcpclient.xsd" version="1.0">
<settings>

<sip-settings id="LumenVox-SIP-Settings">

<server-ip>127.0.0.1</server-ip>
<server-port>5060</server-port>

</sip-settings>


<rtsp-settings id="LumenVox-RTSP-Settings">

<server-ip>127.0.0.1</server-ip>
<server-port>554</server-port>

<resource-location></resource-location>
<resource-map>
<param name="speechrecog" value="recognizer"/>
</resource-map>
</rtsp-settings>
</settings>

<profiles>

<mrcpv2-profile id="lv2">
<sip-uac>SIP-Agent-1</sip-uac>
<mrcpv2-uac>MRCPv2-Agent-1</mrcpv2-uac>
<media-engine>Media-Engine-1</media-engine>
<rtp-factory>RTP-Factory-1</rtp-factory>
<sip-settings>LumenVox-SIP-Settings</sip-settings>
<rtp-settings>RTP-Settings-1</rtp-settings>
</mrcpv2-profile>


<mrcpv1-profile id="lv1">
<rtsp-uac>RTSP-Agent-1</rtsp-uac>
<media-engine>Media-Engine-1</media-engine>
<rtp-factory>RTP-Factory-1</rtp-factory>
<rtsp-settings>LumenVox-RTSP-Settings</rtsp-settings>
<rtp-settings>RTP-Settings-1</rtp-settings>
</mrcpv1-profile>

</profiles>
</unimrcpclient>

You must change the server-ip value in the RTSP-Settings section to the IP address of the LumenVox Media Server.

Finally, you must make one or two changes to /usr/local/unimrcp/conf/unimrcpclient.xml:

unimrcpclient.xml

<?xml version="1.0" encoding="UTF-8"?>

<unimrcpclient xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="unimrcpclient.xsd" version="1.0" subfolder="client-profiles">
<properties>




<ip>127.0.0.1</ip>



</properties>

<components>

<resource-factory>
<resource id="speechsynth" enable="true"/>
<resource id="speechrecog" enable="true"/>
<resource id="recorder" enable="true"/>
<resource id="speakverify" enable="true"/>
</resource-factory>


<sip-uac id="SIP-Agent-1" type="SofiaSIP">



<sip-port>8062</sip-port>
<sip-transport>udp</sip-transport>
<ua-name>UniMRCP SofiaSIP</ua-name>
<sdp-origin>UniMRCPClient</sdp-origin>






</sip-uac>


<rtsp-uac id="RTSP-Agent-1" type="UniRTSP">
<max-connection-count>100</max-connection-count>

<sdp-origin>UniMRCPClient</sdp-origin>
</rtsp-uac>


<mrcpv2-uac id="MRCPv2-Agent-1">
<max-connection-count>100</max-connection-count>
<offer-new-connection>false</offer-new-connection>
<rx-buffer-size>1024</rx-buffer-size>
<tx-buffer-size>1024</tx-buffer-size>

</mrcpv2-uac>


<media-engine id="Media-Engine-1">
<realtime-rate>1</realtime-rate>
</media-engine>


<rtp-factory id="RTP-Factory-1">



<rtp-port-min>4000</rtp-port-min>
<rtp-port-max>5000</rtp-port-max>
</rtp-factory>
</components>

<settings>

<rtp-settings id="RTP-Settings-1">
<jitter-buffer>
<adaptive>1</adaptive>
<playout-delay>50</playout-delay>
<max-playout-delay>600</max-playout-delay>
<time-skew-detection>1</time-skew-detection>
</jitter-buffer>
<ptime>20</ptime>
<codecs>PCMU PCMA L16/96/8000 telephone-event/101/8000</codecs>


<rtcp enable="false">

<rtcp-bye>1</rtcp-bye>

<tx-interval>5000</tx-interval>

<rx-resolution>1000</rx-resolution>
</rtcp>
</rtp-settings>
</settings>
</unimrcpclient>

It is important that the <ip> value in the first <properties> section be set to the IP address of the machine running Asterisk. Also verify that the <codecs> setting in the RTSP-Settings-1 section is correctly set as shown above.

Reload Asterisk after making these changes, and you may move on to testing the installation.