Home  > Services & Support  > Support Helpweb  > Online training  > Adding Video to a Dialogic R4 IVR Application


Adding Video to a Dialogic R4 IVR Application

Introduction



About this course


This course will lead you through the steps necessary to take a Dialogic R4 application from audio-only to full multimedia. With the multimedia application, a video SIP phone may be used to view video clips, with menu navigation done using DTMF.
There is a 4-step process to convert from an audio to a multimedia application:
The principles learned in this training can then be applied to converting your own application from audio to multimedia.

Some examples of how video can be used in applications will also be reviewed.

Dialogic Host Media Processing software (HMP) is used as the basis for a Multimedia server. If you do not have an HMP system ready, you may download the Dialogic HMP software and evaluation license here.

When you are done with these exercises, you will have:

Note: The source code in this training course is provided by Dialogic "AS IS", without warranty of any kind, either expressed or implied. Dialogic shall not be liable for any damages arising out of your use of the source code in this course, even if it has been advised of the possibility of such damages.

 

Show this course in printer-friendly format


What you will need


Your skills:

To compile the samples you need:

To run the samples you need:

Why Video?



Video Applications


Before we start the training, let's look at some possible applications that can be built using Dialogic HMP software.

Video Mail/Blog Illustration


Video Portal Illustration



Video Applications, continued


Here are some other applications that can be built using Dialogic HMP software.

Streaming Media Server Illustration
A video portal is a video content delivery application that caters to both IP and 3G subscribers. It is among the most popular 3G applications today. For example, under development are 3G video portals for the UK’s popular TV shows "X-Factor" and "I’m a Celebrity, Get Me Out of Here". A streaming media server:

Video Color Ring Back Illustration
Video ringback is an extension of audio ringback. Here, a customized ringtone and video image are presented to each different caller. These are some of the ways Video Color Ringback can be used:

Build/Test Setup



Visual C++ Setup


Let's turn now to the tools for doing the programming for this training. There are several different Microsoft development environments that can be easily used. First, the older Microsoft Visual Studio (Visual C++) 6.0. And second, Microsoft Visual Studio 2005 C++ or Microsoft Visual C++ 2005 Express Edition. There are .zip files that may be downloaded for each exercise in the training that contain the all of project files needed for each development environment.

Visual Studio 6.0: If you prefer using Microsoft Visual C++ 6.0, install it along with its Service Pack 6. A "typical" installation works fine.

Visual Studio 2005/C++: This is the standard Microsoft C++ development product, Visual Studio 2005. Only the C++ development tools are needed for this training.

Visual C++ 2005 Express Edition: Microsoft also freely distributes a C++ development environment, Microsoft Visual C++ 2005 Express Edition, This may be downloaded, installed and used for Dialogic R4 development as well. In addition, the Express Edition requires Microsoft Platform SDK for Windows. Further information on using the Platform SDK with the Express Edition can be found here. The SDK contains a number of C include files and libraries needed for Microsoft C++ development.


CounterPath X-Lite Video Softphone Setup


There is a SIP video softphone, X-Lite 3.0, freely available from CounterPath which works well as a way of calling into a Dialogic HMP multimedia application. It requires a Windows PC with a soundcard and a headset. Versions for MAC OS X and Linux are also available. Click here to download.

Installation: Follow the installation wizard. The process is straightforward.
Configuration: When the softphone is first started, a SIP Account window will appear. Add a new account. X-Lite is intended to work with a SIP proxy. But, for a simple test environment, it is easier to make point-point calls between the softphone and Dialogic HMP software. To do this, configure a SIP account as follows:

Using the phone: A call may now be made:


Dylogic Mirial Softphone Setup


A second SIP video softphone that works well with HMP is the Dylogic Mirial v 4.5.0 Pro DS. It also requires a Windows PC with a soundcard and a headset. Information on this product may be found here.

Installation: Follow the installation wizard. The process is straightforward. It will ask for a license when the software is first started.
Configuration: The default configuration is close to what is wanted. Here are the exceptions:

Using the phone: The Mirial will make to make point-point calls between itself and Dialogic HMP software:

Training Instructions



Training Instructions


There are a series of 4 applications that show how to convert an existing GlobalCall-based Dialogic R4 application from audio to multimedia. You will be making changes in the applications each step of the way.

First, a description of all versions of the basic application:

Each exercise is done in the same way. There are two different options for editing, building and running it. Depending on the development environment you have installed, click on either:

Training Instructions, continued

There are two source (.cpp) files in each folder: You will do the step-by-step programming to move the app one step closer to multimedia. But you get assistance - you do this by "commenting in" and "commenting out" the appropriate code: When making changes: When your changes are complete, recompile/re-link and run the application. Then place a SIP call into the app and make sure it behaves as it should. Behavior will vary depending on the exercise you have completed.

GlobalCall and 3PCC



GlobalCall and 3rd Party Call Control


Before talking about 3rd party call control, let's look briefly at the audio application we're starting with. The application logic (described on the Training Instructions slide) is embedded in switch() statements, but the logic is simple. There are sections for:

We will start the first exercise by just running the IVR application.

3PCC. The first step toward multimedia is to change the GlobalCall call control mode from 1st party to 3rd party call control (3PCC) 3rd Party Call is usually defined as the ability to create a call on behalf of other parties. But here, we use it to get access to the Session Description Part (SDP) of the SIP message, and then to control the media (RTP) streaming ourselves.

Under 3PCC, GC no longer handles media (RTP) streaming. So, the GC device name used in gc_Open() does not contain an IPML media device:
Also, the IPCCLIB_START_DATA struct is set to “media operational mode 3PCC” on GC startup. When 3PCC is activated, GC assumes control of SDP portion of SIP messages:

GlobalCall and 3rd Party Call Control, continued


1PCC vs. 3PCC API Calls. The following table show typical call control events and API calls that would be seen using 1PCC and compares them to the events and calls used for 3PCC:

Event Action in 1PCC Action in 3PCC
GCEV_OFFERED gc_AnswerCall Parse INVITE SDP & ipm_GetLocalMediaInfo
IPMEV_GETLOCALMEDIA N/A ipm_StartMedia
IPMEV_STARTMEDIA N/A Build SDP for OK & gc_AnswerCall
GCEV_DISCONNECTED gc_DropCall ipm_Stop & gc_DropCall


For our exercises here, the changes shown above won't be complete until IPML Media Streaming is added.

Full information on 3PCC can be found in the Global Call IP for Host Media Processing Technology Guide in chapter 5, "Third Party Call Control (3PCC) Operations and Multimedia Support".


GlobalCall and 3rd Party Call Control, continued


Directions for Exercise: Part 1 - Since this is the first exercise, we want to try the audio IVR application before making any changes to it.

Part 2 - Now, GlobalCall is switched from 1PCC to 3PCC. Work through the code, commenting and uncommenting.

Trying it out: Part 1 - Build the app, start it, place a call into it, and try playing each audio clip

Part 2 - After making changes, rebuild the app and start it. GC should start successfully, and no errors should be seen in the console/log An inbound call will not be successfully handled, but will fail at gc_Answer() with an error indicating that no SDP was supplied.



GlobalCall and 3rd Party Call Control, continued


So Far: We have run the audio IVR application, and then converted the GlobalCall part of it to use 3PCC. But, the call is not being answered yet.

Next: We need to add SDP processing so that the call can be connected.

SIP SDP Parsing



Adding SIP SDP Control


Parsing SDPs can be done any way you wish - they are nothing more than a C string and can be manipulated using common string handing functions. But there is a set of Dialogic-supplied convenience functions for SDP parsing and creation - sdpapi. It is shipped as a library, with unit test and demo programs. Source is also included. The sdpapi is found under the demos directory when Dialogic HMP software is installed. You will need to build the library and reference it when you link your application to use it. There are objects for: The sdpapi library is found under the demos directory when HMP is installed. In order to use it, you will need to build the library and reference it when you link your application.

To handle an inbound SIP call under GC:


Adding SIP SDP Control, continued


Directions for Exercise: For this exercise, SDP parsing and processing are now added to the 3PCC application. Work through the code, commenting and uncommenting.

Trying it out: Build the app, start it and place a call into it. An inbound call should be successfully connected and held. SDP traces will be seen in the console/log. Media flow (RTP) is not yet there – don’t expect any audio.



Adding SIP SDP Control, continued


So Far: We added SDP processing to the GlobalCall 3PCC application. The call is being answered, but we don't hear anything yet.

Next: We need to add media streaming to hear the audio.

IPML Media Streaming



Adding IPML Media Streaming


We will now add direct control of RTP streaming using the IPML API. It is a fairly simple API, doing little more than setting up parameters for the streaming and then starting and stopping it on command. Here is how it is used:

Full IPML documentation includes the IP Media Library API for Host Media Processing Programming Guide and the IP Media Library API for Host Media Processing Library Reference


Adding IPML Media Streaming, continued


Directions for Exercise: For this exercise, IPML media streaming is added to the application. Work through the code, commenting and uncommenting.

Trying it out: Build the app, start it and place a call into it. Audio should work as it originally did in the baseline application.



Adding IPML Media Streaming, continued


So Far: We have media streaming to the GlobalCall 3PCC application, and can hear audio again.

Next: We can now move from audio-only to full multimedia.

Adding Multimedia



Adding Multimedia


Introduction: We will now spend some time looking at the Multimedia (MM) API in depth.

The MM API was originally released on Dialogic HMP software release 1.5 for Linux in 2005, and is now available on Dialogic HMP software release 3.0 for Windows. It can also be found on the Multimedia Platform, which is based on the ATCA form factor.
The video codec supported is H.263. (RFC 2190) Picture sizes are Common Intermediate Format (CIF) and Quarter CIF (QCIF). Play, record and general operation is done in “native mode”, from a proprietary set of audio and video files. There are utilities available to convert industry standard Audio Video Interleave (AVI) Type-2 file format (.avi) and 3rd Generation Partnership Project (3GPP) Release 4 file format (.3gp) to and from the native file formats.
Intra-frame Request (Picture Fast Update) is supported via SIP INFO messages. HMP licensing is done through a new ‘multimedia’ resource. Like the Dialogic audio API, the Dialogic multimedia API is independent of call control and media transport, and is connected to media transport using the "device management" API.

Multimedia fits into the Dialogic R4 API picture like this. It is an independent component, available under Dialogic HMP software. It is usually used in conjunction with IPML and likely to be used with SIP under GlobalCall. But, as we have seen, it must be used in 3PCC mode in order to get access to audio and video codec information to programmatically control media streaming using IPML. The audio API is also available under Dialogic HMP software and can be used along with MM, but independent of it, to control the application via DTMF.


Adding Multimedia, continued


Device connections: Multimeda devices need to be routed to an IPML media streaming device. This is done using a single call to dev_Connect(). It may be used to create a half or full duplex connection between IPML and MM device. Parameters needed are: Before using the connected devices, you must collect DMEV_CONNECT completion events on both of them.

The Dev Connect API is explained in the Device Management API for Windows and Linux Operating Systems Library Reference
Since DTMF recognition is used in the application, there also must be a set of "soft CTBus" connections done to allow the audio device to monitor the IPML media channel for RFC2833 or inband DTMF. So, two sets of device connections must be done. This audio connection is done with the standard R4 API calls xx_GetXmitSlot() and xx_Listen().


Adding Multimedia, continued


Multimedia API Calls The API set for multimedia closely resembles the audio API. It is possible to play or record to a file, using audio, video or both. File I/O is done directly by HMP, with terminating conditions done via API or DTMF. The full set of API calls is:
mm_Open() Opens an MM device
mm_Close() Closes a previously opened device
mm_Play() Play audio/video to set destination
mm_Record() Record audio/video from source
mm_Stop() Stop play/record operations
mm_Get/SetParms() Retrieve/Specify device level parameters
mm_ErrorInfo() Retrieve thread level error information
mm_Reset() Reset device to idle state


The MM API is fully asynchronous, and eventing is very comprehensive:
Initial API call SUCCESS or ERROR
Initiation event MMEV_X_ACK or MMEV_X_ACK_FAIL
Completion event MMEV_X or MMEV_X_FAIL
Unsolicited operational events MMEV_X


This means that a well thought-out state machine is needed to handle the events. But, as anyone who has written asynchronous telecom applications knows, a solid state machine is essential for a successful high density application.

Full MM documentation includes the Multimedia API Programming Guide and the Multimedia API Library Reference


Adding Multimedia, continued


Directions for Exercise: Multimedia (video) is now added to the 3PCC/IPML app. There are several steps needed for this exercise, so it may take a little longer: Work through the code, commenting and uncommenting.

Trying it out: Build the app, start it and place a call into it. Full multimedia play, with audio and video, should now be available.



Adding Multimedia, continued


So Far: We have a full multimedia application.

Next: Up to you. Maybe try adding record? Try finding and using some additional audio/video clips?

What next?



The MultiMedia Demo and Offline A/V File Conversion


There is a full Multimedia demo which is shipped as part of Dialogic HMP software. It is found under the demos directory when Dialogic HMP software is installed and contains most of what we have looked at here. There is one important addition - it also does a multimedia record as well as a play.
Audio/visual file conversion is also important. If you recall, HMP stores its audio/video in "native mode". So, there are utilities for conversion to/from common video file formats. These tools are intended to be used in an offline or batch mode.

Two conversion utilities are available: The tools themselves and their documentation are available in a separate download - Offline Multimedia File Conversion Tools


The End




This is the end of "Adding Video to an R4 IVR Application".

Thank you for completing the course.

Back to the normal course view

This page was formatted for printing from the Dialogic Support on-line training Web

Copyright© 2007 Dialogic Corporation. All rights reserved.

Dialogic is a registered trademark of Dialogic Corporation. *The names of actual companies and products mentioned herein may be the trademarks of their respective owners. Dialogic encourages all users of its products to procure all necessary intellectual property licenses required to implement their concepts or applications, which licenses may vary from country to country.