Browse
 
Tools
Rss Categories

Using the SimpleMRCPClient

Reference Number: AA-01633 Views: 22233 0 Rating/ Voters

LumenVox provides a very useful application called the SimpleMRCPClient to get you quickly started using the Media Server (MRCP) and to act as a sanity check that everything is working as expected after the installation.

Versions 11.0 and 11.1
The SimpleMRCPClient utility was introduced in LumenVox version 11.0.  Starting in version 11.1, SIP over TCP connectivity was added in conjunction with changes to the Media Server to support this protocol.

This utility is installed with the LumenVox Engine Installer (Windows) in the installed directory (by default C:\Program Files\LumenVox\Engine\ ) and with the LumenVoxClient RPM(Linux) 

The SimpleMRCPClient will perform decodes against the LumenVox Media Server, who internally gets them from the LumenVox ASR Server, or can perform synthesis requests against the LumenVox Media Server, who internally gets them from the LumenVox TTS Server.  This utility can be helpful in determining connectivity between MRCP and those resources. If you encounter problems when running the SimpleMRCPClient utility, you can independently verify functionality of the ASR using SimpleASRClient, or the TTS using SimpleTTSClient.  The SimpleMRCPClient utility in conjunction with the other utilities can be used to determine the cause of any simple configuration issues.

The usage for SimpleMRCPClient is: SimpleMRCPClient <options>

Communicates with LumenVox Media Server using MRCP to send ASR/TTS requests

== ASR OPTIONS ==

 -g, -grammar <grammar-file>

URI or file reference of the source grammar to be used for the ASR recognition. This can be a file system reference local to the ASR Server, a builtin grammar, an HTTP URI,  or reference a precompiled grammar.

 -a, -audio <ulaw-audio-file>

Headerless ulaw audio file. Note that if a WAV format file is specified, the RIFF header will be ignored.

== TTS OPTIONS ==

 -t, -text <plain-text>

Plain text for TTS. This should be contained in quotes, for example "Hello World"

 -s, -ssml <ssml-uri>

SSML URI or file for TTS

 -o, -output <output-file>

Output Wave File path
(default=SimpleMRCPClient_TTS_output.wav)

== OTHER OPTIONS ==

 -ip <ip-address>

LumenVox Media Server ip-address. Loop back address may not work.
(default=127.0.0.1)

 -v, -version <version>

MRCP protocol version i.e 1 for RTSP and 2 for SIP
(default=1).

 -rtsp_port <port>

MRCPv1 Server RTSP port to connect to
(default=554).

 -sip_port <port>

MRCPv2 Server SIP port to connect to
(default=5060).

 -sips_port <port>

MRCPv2 Server SIPS port to connect to
(default=5061).

 -secure_context

Set secure context i.e. mask sensitive information in logs
(default=0).

 -enable_srtp <true/false>

Enable or disable the use of SRTP in MRCPv2 connections
(default for TCP/UDP = false).
(default for TLS = true)

 -timeout <secs>

Amount of time to wait for recognition or synthesis before timing out
(default=30).

 -synth_res <resource-url>

URL path specified for recognizer resources
(default=/media/synthesizer)

 -recog_res <resource-url>

URL path specified for recognizer resources
(default=/media/speechrecognizer)

 -transport <UDP/TCP/TLS>

Transport used with SIP. Can be TCP, UDP or TLS
(default=UDP)

 -local_ip <ip-address>

Local host ip-address. Auto detected address may not work with hosts with more than one network interface
(default is auto detected)

 -vsp <Custom Parameters>

Vendor Specific Parameters. Adds additional Vendor Specific Parameters to the Vendor-Specific-Parameters header.
(There are no default Vendor-Specific-Parameters)

============================================================================


Examples:

----------------------------------------------------------------------------

* ASR Example *

SimpleMRCPClient -grammar http://192.168.1.1/gram/Test.grxml -audio Speech.raw

This will perform an ASR decode using 'Test.grxml' grammar and the headerless
ULAW audio file 'Speech.raw'. The media server at 127.0.0.1(default) is
used in MRCPv1(default) protocol at port 554(default).
----------------------------------------------------------------------------

* TTS Example : SSML *

SimpleMRCPClient -ssml http://192.168.10.10/ssml/Test.ssml -ip 192.168.15.15

This will perform a TTS synthesis using 'Test.ssml' and write the output
to 'SimpleMRCPClient_TTS_output.wav' (default). The media server at
192.168.15.15 is used in MRCPv1 (default) protocol at port 554 (default).
----------------------------------------------------------------------------

* TTS Example : Plain Text with secure context and MRCPv2 *

SimpleMRCPClient -text "Hello World" -secure_context 1 -v 2

This will perform a TTS synthesis using the provided text of "Hello World"
and the output is written to 'SimpleMRCPClient_TTS_output.wav' (default).
Logs are suppressed since secure_context was active. The media server at
127.0.0.1 (default) is used in MRCPv2 protocol at port 5060 (default).
----------------------------------------------------------------------------

* TTS Example : Plain Text with custom synthesis resource url and port *

SimpleMRCPClient -text "Hello World" -synth_res "/media/synth" -rtsp_port 560

This will perform a TTS synthesis using the provided text of "Hello World"
and the output is written to 'SimpleMRCPClient_TTS_output.wav' (default).
A custom synthesis url of /media/synth is used. The media server at
127.0.0.1 (default) is used in MRCPv1 (default) protocol at port 560.
============================================================================


RECOGNIZE

When performing a simple decode (RECOGNIZE request) with an audio and grammar file, you can provide your own or you can use sample files supplied by LumenVox. The supplied audio and grammar provided are also in the installed directory (Windows) or /usr/share/lumenvox/client/data (Linux) and they are named 1234.ulaw and ABNFDigits.gram.

Note: If a file path (and not a URI) is specified for the grammar, it is relative to the Media Server node, NOT the client. Therefore; you must provide the complete path.
Note: If no path is specified for the audio file, the Linux client will first look in the local directory and then in /usr/share/lumenvox/client/data. The Windows client only looks in the local folder.

Sample use on Windows:

C:\Program Files\Lumenvox\Engine>SimpleMRCPClient.exe -grammar builtin:grammar/digits -audio 1234.ulaw
C:\Program Files\Lumenvox\Engine>SimpleMRCPClient.exe -grammar "c:/Program Files/LumenVox/Engine/ABNFDigits.gram" -audio 1234.ulaw

Sample use on Linux:

[root@mynode ~]# SimpleMRCPClient -grammar builtin:grammar/digits -audio 1234.ulaw
[root@mynode ~]# SimpleMRCPClient -grammar /usr/share/lumenvox/client/data/ABNFDigits.gram -audio 1234.ulaw

The RECOGNIZE request follows the same pattern that any application would use in order to perform a speech recognition when using MRCP

  1. It reads the audio file into a buffer
  2. It creates an MRCP recognizer client connection to the Media Server
  3. It loads the grammar into the MRCP client session
  4. It issues a RECOGNIZE request to the Media Server
  5. It streams the audio to the Media Server (via RTP)
  6. The Media Server processes RECOGNIZE request
  7. It receives a Media Server signal for RECOGNITION-COMPLETE with the result when complete
  8. It prints out the results

Sample output (Windows):

C:\Program Files\Lumenvox\Engine>SimpleMRCPClient.exe -grammar builtin:grammar/digits -audio 1234.ulaw

Processing ASR decode request with timeout of 30 seconds
Using audio file: 1234.ulaw

Connected to server. Sending RECOGNIZE request...
Staring audio stream...
Waiting for result...
********************************************************************
    Input Sentence       : ONE TWO THREE FOUR
    Interpretation String: 1234
    Interpretation Score : 990
********************************************************************

Sample output (Linux):

[root@mynode ~]# SimpleMRCPClient -grammar builtin:grammar/digits -audio 1234.ulaw

Processing ASR decode request with timeout of 30 seconds
Using audio file: /usr/share/lumenvox/client/data/1234.ulaw

Connected to server. Sending RECOGNIZE request...
Staring audio stream...
Waiting for result...
********************************************************************
    Input Sentence       : ONE TWO THREE FOUR
    Interpretation String: 1234
    Interpretation Score : 990
********************************************************************


SPEAK

When performing a TTS synthesis (SPEAK request), you should supply either an SSML document reference,  a SSML file path, or plain text and you may optionally supply other parameters as needed. We provide a sample SSML file, named SimpleTTSClient.ssml, which is available in the installed directory (Windows) or /usr/share/lumenvox/client/data (Linux).

Note: If no path is specified for the ssml file, the Linux client will first look in the local directory and then in /usr/share/lumenvox/client/data. The Windows client only looks in the local folder.

The SPEAK request follows the same pattern that any application would use in order to perform speech synthesis using MRCP

  1. It reads the text or SSML to be synthesized into a buffer
  2. It creates an MRCP synthesizer client connection to the Media Server
  3. It issues a SPEAK request to the Media Server, specifying the text buffered earlier
  4. It receives a stream of audio from the Media Server (via RTP) containing the synthesized speech
  5. Received audio is saved to disk as a WAV file
  6. It receives a Media Server signal for SPEAK-COMPLETE with the result when complete
  7. It prints out the results

Sample outputs (Windows):

C:\Program Files\Lumenvox\Engine>SimpleMRCPClient.exe -text "Hello World" -output HelloWorld.wav
Processing TTS synthesis request with timeout of 30 seconds
Saving output to file: HelloWorld.wav

Resulting audio was stored in ULAW format with a WAVE-RIFF header at HelloWorld.wav
The TTS Synthesis completed successfully
C:\Program Files\Lumenvox\Engine>SimpleMRCPClient.exe  -s SimpleTTSClient.ssml -output SimpleSSMLTest.wav
Processing TTS synthesis request with timeout of 30 seconds
Saving output to file: SimpleSSMLTest.wav

Resulting audio was stored in ULAW format with a WAVE-RIFF header at SimpleSSMLTest.wav
The TTS Synthesis completed successfully

Sample outputs (Linux):

[root@mynode ~]# SimpleMRCPClient -text "Hello World" -output HelloWorld.wav
Processing TTS synthesis request with timeout of 30 seconds
Saving output to file: HelloWorld.wav

Resulting audio was stored in ULAW format with a WAVE-RIFF header at HelloWorld.wav
The TTS Synthesis completed successfully
[root@mynode ~]# SimpleMRCPClient -s SimpleTTSClient.ssml -output SimpleSSMLTest.wav
Processing TTS synthesis request with timeout of 30 seconds
Saving output to file: SimpleSSMLTest.wav

Resulting audio was stored in ULAW format with a WAVE-RIFF header at SimpleSSMLTest.wav
The TTS Synthesis completed successfully


Working with Vendor-Specific-Parameters

See our Vendor-Specific-Parameters article for more details of how these custom setting extensions can be used to influence MRCP requests when performing either MRCPv1 or MRCPv2 interactions with the LumenVox Media Server.

These settings can also be optionally applied when using the SimpleMRCPClient to emulate requests to the Media Server by specifying the -vsp parameter as shown here:

Windows example using Vendor Specific Parameters

C:\Program Files\Lumenvox\Engine>SimpleMRCPClient.exe -vsp "com.lumenvox.callsre-prefix=testing;com.lumenvox.secure_context=1" -grammar builtin:grammar/digits -audio 1234.ulaw

Linux example using Vendor Specific Parameters

[root@mynode ~]# SimpleMRCPClient -vsp "com.lumenvox.callsre-prefix=testing;com.lumenvox.secure_context=1" -grammar builtin:grammar/digits -audio 1234.ulaw

In both of these examples, there are 2 Vendor Specific Parameters specified, showing that a number of different parameters can used used at once with a semicolon separator between them.

Specifically in these examples, the string prefix for any generated response filename will be "testing" and the secure_context setting will be enabled (suppressing potentially sensitive data from logs). Note that these settings are only used for each SimpleMRCPClient request and have no long-term effects on other sessions or requests. See the Vendor-Specific-Parameters article for more details of using these within sessions, in a non-testing scenario.


Diagnosing network problems

Media Server Configuration:

If you have problems successfully getting the SimpleMRCPClient or the mrcp_test of the lv_show_config to pass, please make sure that you have properly set the media_server.conf's mrcp_server_ip parameter and restarted the Media Server. This is required for proper functionality.

Network Interface Loopback:

SimpleMRCPClient will issue a warning if you try to connect to a remote Media Server but the detected default network interface is the loopback. 

[root@mynode ~]# SimpleMRCPClient -text " hello="" world"="" -output="" helloworld.wav
WARNING: 127.0.0.1 (i.e. localhost) detected as default network interface
         Some MRCP functionality may not work.
Processing TTS synthesis request with timeout of 30 seconds

If you see this message, please follow the instructions in the Linux Installation page.

Note:

See the  -local_ip  optional parameter when using SimpleMRCPClient (described above), which allows you to specify the local IP address rather than using the default auto-detected address. This may be helpful if you have more than one network interfaces