Powered by Universal Speech Solutions LLC
Client Integration Manual
Last updated: March 19, 2017
Created by: Arsen Chaloyan
Table of Contents
1.2 Installation and Configuration
3.1 Creating an Instance of the Client Stack
3.2 Creating an Instance of the Application Object
3.3 Starting the Message Processing Loop
4.1 Creating an Instance of the MRCP Session
4.2 Creating an Instance of the MRCP Resource Channel
4.3 Adding the Resource Channel to the Session
5.2 Receiving an MRCP Response or Event
6 MRCP Session De-initialization
6.1 Removing an MRCP Resource Channel
6.2 Terminating an MRCP Session
6.3 Destroying an MRCP Session
7 Client Stack De-initialization
7.1 Shutting down Client Stack
This guide describes how to use the UniMRCP client library in a user application. The document provides basic steps only and is not a complete reference.
The intended audience is speech application developers familiar with the C/C++ programming languages.
Unless explicitly stated, instructions provided in this guide are applicable to the following versions.
UniMRCP 1.0.0 and above
For the installation and configuration of the library, see the Installation Guide and the Client Configuration Guide.
The UniMRCP client library provides a unified, MRCP version consistent interface for integration in IVRs, Call Centers, IP PBXs and other speech applications. The UniMRCP client stack is a multi-threaded library implemented in the C language and built on top of a number of internal and external components. The library uses the asynchronous event-driven model with a fixed number of threads (tasks) launched upon initialization. Memory pools are used throughout the library in order to avoid dynamic memory allocations and, thus, make memory operations highly efficient.
Typically, one instance of the client stack is created per running process. The client stack is loaded from the configuration file(s) by default, although it is also possible to create and initialize the stack by means of API calls (not covered in this document). The location of the configuration directory is specified by the structure apt_dir_layout_t.
apt_dir_layout_t *dir_layout = apt_default_dir_layout_create(root_dir_path,pool);
mrcp_client_t *mrcp_client = unimrcp_client_create(dir_layout);
One or more instances of mrcp_application_t objects can be created and further registered to the client stack. An instance of mrcp_application_t is a logical representation of a user application communicating with the client stack. A message handler (mrcp_app_message_handler_f) must be provided upon creation of the application instance. The handler is used to receive messages sent from the client stack.
mrcp_application_t *mrcp_app = mrcp_application_create(app_message_handler,engine,pool);
The client stack is running in a loop waiting for messages either from the registered user applications and/or from other internal tasks.
· Synchronous start
By default, the client stack is started synchronously. This means that the executable context of the calling user application will be blocked until the client stack is initialized and ready to process messages.
· Asynchronous start
In order to start the client stack asynchronously, an event handler of type mrcp_client_handler_f must be set before attempting to start the message loop. This will allow to release the executable context of the calling user application while the stack is being initialized. The registered handler will be invoked asynchronously once the client stack is ready to process messages. Note that no requests can be sent from the application until the handler is invoked.
mrcp_session_t *mrcp_session = mrcp_application_session_create(mrcp_app,profile,NULL);
mrcp_channle_t *mrcp_channel = mrcp_application_channel_create(
mrcp_session, MRCP_RECOGNIZER_RESOURCE, termination, NULL, obj);
As a result, the client stack sends an offer to the MRCP server requesting to add/enable a resource channel. The request is processed asynchronously. The user application receives a response when the corresponding on_channel_add() callback is invoked by the client stack.
Read the MRCP Message Usage guide in order to see how to create an MRCP message object, set its header fields and the body.
This function sends a request to the MRCP server. A response is received asynchronously.
This callback is invoked when a response or event is received from the MRCP server.
The allocated MRCP resource channel can optionally be de-allocated first. If not, the channel will be de-allocated with the session termination, anyway.
This function sends an offer to the MRCP server requesting to remove/disable a resource channel. The request is processed asynchronously. The user application receives a response when the corresponding on_channel_remove() callback is invoked by the client stack.
This function initiates session termination by sending corresponding request to the MRCP server. The user application receives a response when on_session_terminate() callback is invoked. Note that session termination can be initiated at any time during the lifetime of the session.
This function ultimately destroys the MRCP session by releasing all the memory allocated in the scope of the session. Note that the session MUST be terminated first and can be destroyed only when the corresponding session termination response has been received.
This function stops the message processing loop and also terminates all other activities in the client stack.
This function ultimately destroy the client stack and releases all the allocated memory.
The unimrcpclient is a sample user client application written in the C language based on the libunimrcpclient library.
The umc is another sample user client application written in the C++ language based on the libunimrcpclient library.
You may use one of the sample applications as a base or a prototype for your own application. However, generally speaking, there is no such a requirement.
No, you should not. One instance of the client stack is designed and also supposed to serve concurrent MRCP sessions.
At least one instance of mrcp_application_t must be created and registered to the client stack. In this term, mrcp_application_t is a logical representation of the user client application. And yes, it is possible to have more than one instance of mrcp_application_t registered to the same client stack.
The user client application MUST register a message handler in order to receive messages from the client stack. All the responses and events from the client stack are delivered asynchronously as mrcp_app_message_t objects, which must be further processed by the client user application. Depending on internal architecture of the application, the messages can be processed in the context of the client stack or be passed to and processed from one of internal threads of the user application.
· unimrcpclient – a sample user client application written in C
· umc - a sample user client application written in C++
· mod_unimrcp – an MRCP module for FreeSWITCH
· res-speech-unimrcp – an MRCP based implementation of the Asterisk Generic Speech Recognition API
· app-unimrcp – an MRCP speech application module for Asterisk
· UML Design Concepts – hierarchy, activity and sequence diagrams of the client stack.
· API Reference – a documentation generated by Doxygen from the source code