Installing and configuring UniMRCP modules

The preferred way to integrate with the Asterisk PBX is through the Asterisk modules provided by the UniMRCP Project. UniMRCP is an open-source implementation of the Media Resource Control Protocol (MRCP), fully supported by the Capacity Private Cloud Media Server. Its Asterisk modules let Asterisk act as an MRCP client, making automatic speech recognition (ASR) and text-to-speech (TTS) requests to the Media Server. The latest build of UniMRCP for Asterisk is available from the UniMRCP Project.

UniMRCP provides two Asterisk modules that work in different ways:

res_speech_unimrcp.so backs the Generic Speech API.
app_unimrcp.so (the res_unimrcp.so applications) provides the UniMRCP Applications — MRCPRecog(), MRCPSynth(), and SynthAndRecog().

We recommend building and loading both, so you can use either mechanism.

Tip: For a complete, worked example — installing Asterisk 13, UniMRCP 1.3.0, and the containerized platform on a fresh operating system, with an accompanying video series — see Configuring Asterisk 13.

Installing UniMRCP

Use asterisk-unimrcp 1.3.0. A known bug in asterisk-unimrcp 1.2.0 causes crashes when invoking MRCPRecog(), so 1.2.0 should not be used.

Download the latest UniMRCP-Asterisk package. (Be sure to obtain both UniMRCP and the UniMRCP-Asterisk module.)
Install the UniMRCP dependency package before installing the UniMRCP package.
Extract the downloaded tarball with tar -xzvf filename to an appropriate directory (for example, /usr/src/).
Follow the README included with the source code.
Build and install the base UniMRCP libraries (including the APR and Sofia-SIP dependencies).
Build and install the UniMRCP-Asterisk modules.

Configuring UniMRCP

The UniMRCP installation provides several configuration files:

mrcp.conf in /etc/asterisk/
res-speech-unimrcp.conf in /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 likely missed a step during installation — do not continue until the installation is complete. Which files you edit depends on which module you intend to use: res_speech_unimrcp.so or res_unimrcp.so.

Configuring res_unimrcp.so

The res_unimrcp.so module relies on /etc/asterisk/mrcp.conf. Below is a sample already configured to work with the platform over MRCPv1. Save it as /etc/asterisk/mrcp.conf:

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

Two changes must be made for your environment:

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

Reload Asterisk after making these changes, then move on to testing the installation.

Configuring res_speech_unimrcp.so

Configuring res_speech_unimrcp.so is more involved than res_unimrcp.so. First, edit /etc/asterisk/res-speech-unimrcp.conf. 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

Make sure the only profile left uncommented is lv1, so it is used as the default profile.

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

lumenvox.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- UniMRCP client document -->
<unimrcpclient xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../unimrcpclient.xsd" version="1.0">
  <settings>
    <!-- SIP MRCPv2 settings -->
    <sip-settings id="LumenVox-SIP-Settings">
      <!-- Server address should be explicitly specified, it defaults to "ip" address set in the properties. -->
      <server-ip>127.0.0.1</server-ip> 
      <server-port>5060</server-port>
      <!-- <force-destination>true</force-destination> -->
    </sip-settings>
    
    <!-- RTSP MRCPv1 settings -->
    <rtsp-settings id="LumenVox-RTSP-Settings">
      <!-- Set to value of the LV Media Server's IP address -->
      <server-ip>127.0.0.1</server-ip>
      <server-port>554</server-port>
      <!-- <force-destination>true</force-destination> -->
      <resource-location></resource-location>
      <resource-map>
        <param name="speechrecog" value="recognizer"/>
      </resource-map>
    </rtsp-settings>
  </settings>
  
  <profiles>
    <!-- LumenVox MRCPv2 profile -->
    <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>
    
    <!-- LumenVox MRCPv1 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>  

Change the server-ip value in the RTSP settings section to the IP address of the Media Server.

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

unimrcpclient.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- UniMRCP client document -->
<unimrcpclient xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="unimrcpclient.xsd" version="1.0" subfolder="client-profiles">
<properties>
<!-- By default, network interface (IP address) to bind to will be implicitly identified.
Alternatively, it can be explicitly set.
-->
<!-- <ip type="auto"/> -->

<!-- Set to the actual IP address of this machine. -->
<ip>127.0.0.1</ip>

<!-- <ext-ip>a.b.c.d</ext-ip> -->
<!-- <server-ip>a.b.c.d</server-ip> -->
</properties>

<components>
<!-- Factory of MRCP resources -->
<resource-factory>
<resource id="speechsynth" enable="true"/>
<resource id="speechrecog" enable="true"/>
<resource id="recorder" enable="true"/>
<resource id="speakverify" enable="true"/>
</resource-factory>

<!-- SofiaSIP MRCPv2 signaling agent -->
<sip-uac id="SIP-Agent-1" type="SofiaSIP">
<!-- By default, "ip" and "ext-ip" addresses set in the properties will be used.
They still can be explicitly specified (overriden) here.
-->
<!-- <sip-ip>10.10.0.1</sip-ip> -->
<!-- <sip-ext-ip>a.b.c.d</sip-ext-ip> -->
<sip-port>8062</sip-port>
<sip-transport>udp</sip-transport>
<ua-name>UniMRCP SofiaSIP</ua-name>
<sdp-origin>UniMRCPClient</sdp-origin>
<!-- <sip-t1>500</sip-t1> -->
<!-- <sip-t2>4000</sip-t2> -->
<!-- <sip-t4>4000</sip-t4> -->
<!-- <sip-t1x64>32000</sip-t1x64> -->
<!-- <sip-message-output>true</sip-message-output> -->
<!-- <sip-message-dump>/tmp/sofia-sip.log</sip-message-dump> -->
</sip-uac>

<!-- UniRTSP MRCPv1 signaling agent -->
<rtsp-uac id="RTSP-Agent-1" type="UniRTSP">
<max-connection-count>100</max-connection-count>
<!-- <request-timeout>5000</request-timeout> -->
<sdp-origin>UniMRCPClient</sdp-origin>
</rtsp-uac>

<!-- MRCPv2 connection agent -->
<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>
<!-- <request-timeout>5000</request-timeout> -->
</mrcpv2-uac>

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

<!-- Factory of RTP terminations -->
<rtp-factory id="RTP-Factory-1">
<!-- By default, "ip" and "ext-ip" addresses set in the properties will be used.
They still can be explicitly specified (overriden) here.
-->
<!-- <rtp-ip>10.10.0.1</rtp-ip> -->
<!-- <rtp-ext-ip>a.b.c.d</rtp-ext-ip> -->
<rtp-port-min>4000</rtp-port-min>
<rtp-port-max>5000</rtp-port-max>
</rtp-factory>
</components>

<settings>
<!-- common (default) RTP/RTCP 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>
<!-- <codecs>PCMU PCMA L16/96/8000 PCMU/97/16000 PCMA/98/16000 L16/99/16000</codecs> -->
<!-- enable/disable RTCP support -->
<rtcp enable="false">
<!-- RTCP BYE policies (RTCP must be enabled first)
0 - disable RTCP BYE
1 - send RTCP BYE at the end of session
2 - send RTCP BYE also at the end of each talkspurt (input)
-->
<rtcp-bye>1</rtcp-bye>
<!-- rtcp transmission interval in msec (set 0 to disable) -->
<tx-interval>5000</tx-interval>
<!-- period (timeout) to check for new rtcp messages in msec (set 0 to disable) -->
<rx-resolution>1000</rx-resolution>
</rtcp>
</rtp-settings>
</settings>
</unimrcpclient> 

The <ip> value in the first <properties> section must be set to the IP address of the machine running Asterisk. Also verify that the <codecs> setting in the RTP settings (RTP-Settings-1) section is set as shown above.