• 1. Overview
• 2. Client Stack Initialization
• Create client stack
• Create application
• Start client stack processing
• 3. Session Initialization
• Create session
• Create channel
• Add channel
• 4. Message Construction
• Create message
• Generic header
• Resource header
• Message body
• 5. Message Management
• Send request
• Receive response or event
• 6. Session Deinitialization
• Remove channel
• Terminate session
• Destroy session
• 7. Client Stack Deinitialization
• Shutdown client stack processing
• Destroy client stack
• 8. References
• 9. F.A.Q.

1. Overview

This guide describes how to integrate UniMRCP client library into 3-rd party applications to provide connectivity with MRCP v1/v2 compliant servers. The nature of applications may differ, perhaps the typical use cases are IVRs and PBXs.

2. Client Stack Initialization

Create client stack

Sample code below shows one-time creation of client stack instance.

#include "unimrcp_client.h"

/* create default directory layout relative to root directory path */
apt_dir_layout_t *dir_layout = apt_default_dir_layout_create(root_dir_path,pool);
/* create client stack */
mrcp_client_t *client = unimrcp_client_create(dir_layout);

Create application

One and more applications can be created and registered with client stack.

#include "mrcp_application.h"

/* create application */
mrcp_application_t *application = mrcp_application_create(app_message_handler,obj,pool);
/* register it with client stack */
mrcp_client_application_register(client,application,name);

Start client stack processing

Start of message processing loop. Outgoing requests received from application context will be sent to MRCP server, while incoming responses and events received from MRCP server will be sent back to application context.

/* asynchronous start of client stack processing */
mrcp_client_start(client);

Asynchronous event raised from client stack context to the registered application indicates client stack is started and ready to process requests from the application.

/* mrcp_app_message_dispatcher_t interface */
on_ready(application,status);

3. Session Initialization

Create MRCP session, then create one or more channels of different resource types within the session.

Create session

#include "mrcp_session.h"

/* create session */
mrcp_session_t *session = mrcp_application_session_create(application,profile,obj);

Create channel

mrcp_channel_t *channel;
/* create synthesizer channel */
channel = mrcp_application_channel_create(
			session,                     /* session, channel belongs to */
			MRCP_SYNTHESIZER_RESOURCE,   /* MRCP resource identifier */
			termination,                 /* media termination, used to terminate audio stream */
			NULL,                        /* RTP descriptor, used to create RTP termination (NULL by default) */
			obj);                        /* object to associate */

/* create recognizer channel */
channel = mrcp_application_channel_create(
			session,                     /* session, channel belongs to */
			MRCP_RECOGNIZER_RESOURCE,    /* MRCP resource identifier */
			termination,                 /* media termination, used to terminate audio stream */
			NULL,                        /* RTP descriptor, used to create RTP termination (NULL by default) */
			obj);                        /* object to associate */

Add channel

Client stack sends offer to MRCP server to add/enable channel.

/* add channel to session (non-blocking asynchronous processing) */
mrcp_application_channel_add(session,channel);

Client stack receives answer from MRCP server.

/* function below from mrcp_app_message_dispatcher_t interface is called to raise answer to application context */
on_channel_add(application,session,channel,status);

4. Message Construction

Create message

/* create MRCP request within application context */
mrcp_message_t *mrcp_message = mrcp_application_message_create(session,channel,method_id);

Generic header

mrcp_generic_header_t *generic_header;
/* get/allocate generic header */
generic_header = mrcp_generic_header_prepare(mrcp_message);
/* set CONTENT-TYPE field */
apt_string_assign(&generic_header->content_type,"application/synthesis+ssml",mrcp_message->pool);
mrcp_generic_header_property_add(mrcp_message,GENERIC_HEADER_CONTENT_TYPE);

Resource header

Synthesizer header

mrcp_synth_header_t *synth_header;
/* get/allocate resource header */



synth_header = mrcp_resource_header_prepare(mrcp_message);
/* set VOICE-AGE field */
synth_header->voice_param.age = 25;
mrcp_resource_header_property_add(mrcp_message,SYNTHESIZER_HEADER_VOICE_AGE);

Recognizer header

mrcp_recog_header_t *recog_header;
/* get/allocate resource header */
recog_header = mrcp_resource_header_prepare(mrcp_message);
/* set CANCEL-IF-QUEUE field */
recog_header->cancel_if_queue = FALSE;
mrcp_resource_header_property_add(mrcp_message,RECOGNIZER_HEADER_CANCEL_IF_QUEUE);

Message body

/* set message body/content */
apt_string_assign(&mrcp_message->body,"actual content goes here",mrcp_message->pool);

5. Message Management

Send request

/* send MRCP request (non-blocking, asynchronous processing) */
mrcp_application_message_send(session,channel,message);

Receive response or event

/* function below from mrcp_app_message_dispatcher_t interface is called to raise MRCP response or event to application context */
on_message_receive(application,session,channel,message);

6. Session Deinitialization

Remove channel

Optionally channel can be removed from session. Client stack sends offer to MRCP server to remove/disable channel.

mrcp_application_channel_remove(session,channel);

Client stack receives answer.

on_channel_remove(session,channel);

Terminate session

Client stack sends offer to MRCP server to terminate session.

mrcp_application_session_terminate(session)

Client stack receives answer from MRCP server.

on_session_terminate(application,session,status);

Destroy session

Session must be terminated before destruction.

mrcp_application_session_destroy(session);

7. Client Stack Deinitialization

Shutdown client stack processing

mrcp_client_shutdown(client);

Destroy client stack

mrcp_client_destroy(client);

8. References

• Demo application built on top of libunimrcpclient library can be found in the platforms/unimrcp-client directory of the source tree.
• UML based design concepts include hierarchy, activity and sequence diagrams of the client stack.

9. F.A.Q.

• What is unimrcpclient application?

It is just a demo application based on libunimrcpclient library. Demo application is capable to run typical synthesizer and recognizer scenarios.

• Should I use demo framework introduced in demo application?

No, you shouldn't.

• Should I create new instance of client stack (mrcp_client_t) for each MRCP session (mrcp_session_t)?

No, one instance of client stack can and should be used for creating multiple MRCP sessions.

• What is mrcp_application_t and can I register multiple mrcp_application_t instances to mrcp_client_t stack?

You must create and register at least one intsance of mrcp_application_t on start up. It's logical and base representation of your application, which provides communication with client stack. You can have more than one mrcp_application_t instances registered if needed.

• What is message dispatcher interface (mrcp_app_message_dispatcher_t) and why isn't it handled internally in client stack?

You must register callback (mrcp_app_message_handler_f) to receive responses and events from client stack. Responses and events are delivered in messages (mrcp_app_message_t ), which must be further dispatched and processed. Depending on internal architecture of your application you may need to process the messages within the context of the thread callback is raised from or pass messages to the thread safe context of your application and only then process them.