JBoss.orgCommunity Documentation

Mobicents Media Server User Guide

by Oleg Kulikov, Amit Bhayani, Bartosz Baranowski, Tom Wells, Jared Morgan, and Douglas Silas

Abstract

The Mobicents Platform is the first and only open source VoIP platform certified for JAIN SLEE 1.0 / 1.1 and SIP Servlets 1.1 compliance. Mobicents serves as a high-performance core for Service Delivery Platforms (SDPs) and IP Multimedia Subsystems (IMSs) by leveraging J2EE to enable the convergence of data and video in Next-Generation Intelligent Network (NGIN) applications.

The Mobicents enables the composition of predefined Service Building Blocks (SBBs) such as Call-Control, Billing, User-Provisioning, Administration and Presence-Sensing. Out-of-the-box monitoring and management of Mobicents components is achieved through JMX Consoles. JSLEE allows popular protocol stacks such as SIP to be plugged in as Resource Adapters (RAs), and Service Building Blocks—which share many similarities with EJBs—allow the easy accommodation and integration of enterprise applications with end points such as the Web, Customer Relationship Management (CRM) systems and Service-Oriented Architectures (SOAs). The Mobicents Platform is the natural choice for telecommunication Operations Support Systems (OSSs) and Network Management Systems (NMSs).

In addition to the telecommunication industry, the Mobicents is suitable for a variety of problem domains demanding an Event-Driven Architecture (EDA) for high-volume, low-latency signaling, such as financial trading, online gaming, (RFID) sensor network integration, and distributed control.


Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Provide feedback to the authors!
1. Introduction to the Mobicents Media Server
1.1. Introduction
1.2. What is Mobicents Media Server
2. Installing the Mobicents Media Server
2.1. Java Development Kit: Installing, Configuring and Running
2.2. Media Server Binary Distribution: Installing, Configuring and Running
2.2.1. Pre-Install Requirements and Prerequisites
2.2.2. Downloading
2.2.3. Installing
2.2.4. Running
2.2.5. Start the Server With Alternate Configuration
2.2.6. Using run.sh
2.2.7. Stopping
2.2.8. Server Structure
2.2.9. Server File Set
2.2.10. Uninstalling
3. Media Server Architecture
3.1. Endpoints
3.1.1. Digital Channel DSO
3.1.2. Announcement Access Point
3.1.3. Conference bridge
3.1.4. Packet Relay
3.1.5. Interactive Voice Response
3.1.6. Soundcard
3.2. Endpoint local identifiers
3.3. Calls and Connections
3.4. Controller Modules
3.4.1. Media gateway control protocol
4. Capabilities of Mobicents Media Server
4.1. Announcement Endpoint
4.2. IVR Endpoint
4.3. Conference Endpoint
4.4. PacketRelay Endpoint
5. Configuring the Mobicents Media Server
5.1. MainDeployer
5.2. Server instance
5.3. Media types definition
5.4. Media format definition
5.4.1. Audio format definition
5.5. Codec definition
5.6. RTP Audio Video profile
5.7. RTP Manager
5.8. Dual-tone multi-frequency (DTMF) tones
5.8.1. DTMF Detector
5.8.2. DTMF Generator
5.9. Text-to-Speech engine
5.9.1. MBrola configuration
5.9.2. FreeTTS configuration
5.9.3. Voice pool configuration
5.10. Connection state manager
5.11. MGCP controller configuration
6. Advanced custom configuration and extension
6.1. Channel
6.1.1. Pipe
6.1.2. Valve
6.1.3. Components
6.2. Factories
6.3. Virtual Endpoint Composition
6.4. Connection Composition
A. Revision History

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.

In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight key caps and key-combinations. For example:

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-combination. For example:

The first sentence highlights the particular key cap to press. The second highlights two sets of three key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:

The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:

Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:

If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in Bugzilla: http://bugzilla.redhat.com/bugzilla/ against the product ${product.name}, or contact the authors.

When submitting a bug report, be sure to mention the manual's identifier:

If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.

The Mobicents Media Server is available in both binary and source code distributions. The simplest way to get started with the Media Server is to download the ready-to-run binary distribution. Alternatively, the source code for the Mobicents Media Server can be obtained by checking it out from its repository using the Subversion version control system ( SVN ), and then built using the Maven build system. Whereas installing the binary distribution is recommended for most users, obtaining and building the source code is recommended for those who want access to the latest revisions and Media Server capabilities.

Installing the Java Development Kit

The Mobicents platform is written in Java. A working Java Runtime Environment (JRE) or Java Development Kit (JDK) must be installed prior to running the server. The required version must be version 5 or higher.

It is possible to run most Mobicents servers, such as the JAIN SLEE Server, using a Java 6 JRE or JDK.

JRE or JDK?

Although Mobicents servers are capable of running on the Java Runtime Environment, this guide assumes the audience is mainly developers interested in developing Java-based, Mobicents-driven solutions. Therefore, installing the Java Development Kit is covered due to the anticipated audience requirements.

32-Bit or 64-Bit JDK

If the system uses 64-Bit Linux or Windows architecture, the 64-bit JDK is strongly recommended over the 32-bit version. The following heuristics should be considered in determining whether the 64-bit Java Virtual Machine (JVM) is suitable:

Downloading

Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: http://java.sun.com/javase/downloads/index_jdk5.jsp. Click the Download link next to "JDK 5.0 Update <x>" (where <x> is the latest minor version release number).

The Sun website offers two download options:

  • A self-extracting RPM (for example, jdk-1_5_0_16-linux-i586-rpm.bin)

  • A self-extracting file (e.g. jdk-1_5_0_16-linux-i586.bin)

If installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, it is recommended that the self-extracting file containing the RPM package is selected. This option will set up and use the SysV service scripts in addition to installing the JDK. The RPM option is also recommended if the Mobicents platform is being set up in a production environment.

Installing

The following procedures detail how to install the Java Development Kit on both Linux and Windows.

Important

A -compat package is not required for RPM installations. The -compat package performs the same SysV service script set up that the RPM version of the JDK installer does.

Configuring

Configuring the system for the JDK consists of two tasks: setting the JAVA_HOME environment variable, and ensuring the system is using the proper JDK (or JRE) using the alternatives command. Setting JAVA_HOME generally overrides the values for java, javac and java_sdk_1.5.0 in alternatives, however it is recommended to specify the value for consistency.

Setting the JAVA_HOME Environment Variable on Generic Linux

After installing the JDK, ensure the JAVA_HOME environment variable exists and points to the location of the JDK installation.

Setting the JAVA_HOME Environment Variable on Linux

Determine whether JAVA_HOME is set by executing the following command:

~]$ echo $JAVA_HOME

If JAVA_HOME is not set, the value must be set to the location of the JDK installation on the system. This can be achieved by adding two lines to the ~/.bashrc configuration file. Open ~/.bashrc (or create it if it does not exist) and add a line similar to the following one anywhere inside the file:

export JAVA_HOME="/usr/lib/jvm/jdk1.5.0_<version>"

The changes should also be applied for other users who will be running the Mobicents on the machine (any environment variables exported from ~/.bashrc files are local to that user).

Setting java, javac and java_sdk_1.5.0 using the alternatives command
Selecting the Correct System JVM on Linux using alternatives

On systems with the alternatives command, including Red Hat Enterprise Linux and Fedora, it is possible to choose which JDK (or JRE) installation to use, as well as which java and javac executables should be run when called.

As the superuser, call /usr/sbin/alternatives with the --config java option to select between JDKs and JREs installed on your system:

home]$ sudo /usr/sbin/alternatives --config java

There are 3 programs which provide 'java'.

  Selection    Command
-----------------------------------------------
   1           /usr/lib/jvm/jre-1.5.0-gcj/bin/java
   2           /usr/lib/jvm/jre-1.6.0-sun/bin/java
*+ 3         /usr/lib/jvm/jre-1.5.0-sun/bin/java

Enter to keep the current selection[+], or type selection number:
        

The Sun JDK, version 5, is required to run the java executable. In the alternatives information printout above, a plus (+) next to a number indicates the option currently being used. Press Enter to keep the current JVM, or enter the number corresponding to the JVM to select that option.

As the superuser, repeat the procedure above for the javac command and the java_sdk_1.5.0 environment variable:

home]$ sudo /usr/sbin/alternatives --config javac
home]$ sudo /usr/sbin/alternatives --config java_sdk_1.5.0
Setting the JAVA_HOME Environment Variable on Windows

For information on how to set environment variables in Windows, refer to http://support.microsoft.com/kb/931715.

Testing

To ensure the correct JDK or Java version (5 or higher), and that the java executable is in the PATH environment variable, run the java -version command in the terminal from the home directory:

home]$ java -version
java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b03)
Java HotSpot(TM) Client VM (build 1.5.0_16-b03, mixed mode, sharing)
Uninstalling

It is not necessary to remove a particular JDK from a system, because the JDK and JRE version can be switched as required using the alternatives command, and/or by setting JAVA_HOME.

Uninstalling the JDK on Linux

On RPM-based systems, uninstall the JDK using the yum remove <jdk_rpm_name> command.

Uninstalling the JDK on Windows

On Windows systems, check the JDK entry in the Start menu for an uninstall option, or use Add/Remove Programs.

This section details how to install the Mobicents Media Server.

The latest version of the Media Server is available from http://www.mobicents.org/mms/mms-downloads.html . The top row of the table holds the latest version. Click the Download link to start the download.

Once the requirements and prerequisites have been met, the Media Server can be installed onto the system. Follow the instructions below for the operating system on which the server will reside.

In the Linux terminal or Windows command prompt, the Standalone Media Server has started successfully if the last line of output is similar to the following

2100 [main] INFO  org.mobicents.media.server.bootstrap.MainDeployer  - [[[[[[[[[ Mobicents Media Server: release.version=2.0.0.GA Started ]]]]]]]]]

Now the server is installed, it is important to understand the layout of the server directories. An understanding of the server structure is useful when deploying examples, and making configuration changes. It is also useful to understand what components can be removed to reduce the server boot time.

The directory structure in the Standalone Media Server installation directory is named using a standard structure. Table 2.1, “Directory Structure” describes each directory, and the type of information contained within each location.

Table 2.1. Directory Structure

Directory NameDescription
bin All the entry point JARs and start scripts included with the Media Server distribution are located in the bin directory
conf The conf directory contains the bootstrap descriptor, bootstrap-beans.xml by default, file for a given server configuration. This defines the core services that are fixed for the lifetime of the server. It also contains the log4j.xml that defines the logging filter.
deploy The deploy directory is the default location the deployment service looks to at start time for deployment content. This may be overridden through the MainDeployer's path attribute.
lib Contains the startup JAR files used by the server.
log Contains the logs from the bootstrap logging service. The log directory is the default directory into which the bootstrap logging service places its logs, however, the location can be overridden by altering the log4j.xml configuration file. This file is located in the /conf directory. log directory is created automatically when the server is started.
mbrola Contains the MBROLA binary and voices. The available voices are

Please note that MBROLA is not LGPL model. To understand license please look at http://tcts.fpms.ac.be/synthesis/mbrola/mbrlicen.html

In addition to MBROLA, the free voices available are

media The default directory for media files. The MediaPlayer, Recorder etc components uses media directory as default directory to read from/write and play/record media files.
temp temp is created automatically when the server is started. The MainDeployer creates a temp/deployment-beans.xml which contains all the beans defined in *-beans.xml file's from /deploy directory.
native Contains the native library to read/write from dahdi channels. As of now the native library is only for linux OS.
ss7 The ss7 directory contains the configuration file ss7-beans.xml for configuring the channels. One needs to configure the Channel and MTP beans and copy this file to /deploy to enable the SS7.

The Media Server uses a number of XML configuration files that control various aspects of the server.

The following example illustrates a truncated directory structure of the mms-standalone-<version> server files:

[user@localhost <MMS_HOME>]$ tree
|-- bin
|   |-- init_redhat.sh
|   |-- run.bat
|   |-- run.jar
|   `-- run.sh
|-- conf
|   |-- bootstrap-beans.xml
|   `-- log4j.xml
|-- deploy
|   |-- avprofile-beans.xml
|   |-- comp-beans.xml
|   |-- connection-beans.xml
|   |-- connection-states-beans.xml
|   |-- controllers
|   |   `-- mgcp
|   |       |-- mgcp-conf.xml
|   |       `-- packages
|   |           |-- au
|   |           |   |-- events.xml
|   |           |   |-- package
|   |           |   |   `-- package.xml
|   |           |   `-- signals.xml
|   |           `-- dtmf
|   |               |-- events.xml
|   |               |-- package
|   |               |   `-- package.xml
|   |               `-- signals.xml
|   |-- endpoint
|   |   |-- ann-beans.xml
|   |   |-- cnf-beans.xml
|   |   |-- ivr-beans.xml
|   |   |-- mgw-beans.xml
|   |   `-- packetrelay-beans.xml
|   |-- rtp-beans.xml
|   `-- server-beans.xml
|-- lib
|   |-- activation-1.1.jar
|   |-- cmu_time_awb-1.2.2.jar
|   |-- cmu_us_kal-1.2.2.jar
|   |-- cmudict04-1.2.2.jar
|   |-- cmulex-1.2.2.jar
|   |-- cmutimelex-1.2.2.jar
|   |-- dtdparser121-1.2.1.jar
|   |-- en_us-1.2.2.jar
|   |-- freetts-1.2.2.jar
|   |-- jain-mgcp-ri-1.0.jar
|   |-- jain-sip-ri-1.2.X-20100813.024234-297.jar
|   |-- java-getopt-1.0.9.jar
|   |-- jaxb-api-2.1.9-brew.jar
|   |-- jboss-common-core-2.2.14.GA.jar
|   |-- jboss-dependency-2.0.6.GA.jar
|   |-- jboss-kernel-2.0.6.GA.jar
|   |-- jboss-logging-spi-2.1.0.GA.jar
|   |-- jboss-mdr-2.0.1.GA.jar
|   |-- jboss-reflect-2.0.2.GA.jar
|   |-- jbossxb-2.0.1.GA.jar
|   |-- jspeex-0.9.7.jar
|   |-- log4j-1.2.14.jar
|   |-- mbrola-1.2.2.jar
|   |-- mgcp-impl-2.0.0.GA.jar
|   |-- mms-controllers-mgcp-2.1.0.BETA1-SNAPSHOT.jar
|   |-- mms-controllers-rtsp-2.1.0.BETA1-SNAPSHOT.jar
|   |-- mms-impl-2.1.0.BETA1-SNAPSHOT.jar
|   |-- mms-spi-2.1.0.BETA1-SNAPSHOT.jar
|   |-- mms-standalone-2.1.0.BETA1-SNAPSHOT.jar
|   |-- mtp-1.0.0.BETA3.jar
|   |-- netty-3.2.0.BETA1.jar
|   |-- stream-1.0.0.BETA1.jar
|   |-- stun4j-1.0.MOBICENTS.jar
|   |-- tritonus_gsm-0.3.6.jar
|   |-- tritonus_share-0.3.6.jar
|   `-- xml-apis-2.9.1.jar
|-- log
|   `-- server.log
|-- mbrola
|   |-- mbrola
|   |-- mbrola.exe
|   |-- readme.txt
|   |-- us1
|   |   |-- license.txt
|   |   |-- us1
|   |   |-- us1.txt
|   |   `-- us1mrpa
|   |-- us2
|   |   |-- license.txt
|   |   |-- us2
|   |   `-- us2.txt
|   `-- us3
|       |-- license.txt
|       |-- us3
|       `-- us3.txt
|-- media
|   |-- 8kalaw.wav
|   |-- 8kulaw.wav
|   |-- gwn44m.wav
|   |-- gwn44s.wav
|   |-- sample_100kbit.mov
|   |-- sample_100kbit.mp4
|   `-- sample_50kbit.3gp
|-- native
|   `-- zap-native-linux.so
|-- ss7
|   `-- ss7-beans.xml
`-- temp
    `-- deployment-beans.xml
			
			

It is convenient to consider a media gateway as a collection of endpoints. An endpoint is a logical representation of a physical entity such as an analog phone or a channel in a trunk. Endpoints are sources or sinks of data and can be either physical or virtual. Physical endpoint creation requires hardware installation, while software is sufficient for creating virtual endpoints. An interface on a gateway that terminates at a trunk connected to a PTSN switch would be an example of a physical endpoint. An audio source in an audio content server would be an example of a virtual endpoint.

The Media Server assumes a connection model where the basic constructs are endpoints and connections. Connections are grouped in calls. One or more connections can belong to one call. Connections and calls are set up at the initiative of one or several Call Agents.

Controller Modules allows external interfaces to be implemented for the Media Server. Each controller module implements an industry standard control protocol, and uses a generic SPI to control processing components or endpoints.

The type of the endpoint determines its functionality. Our analysis, so far, has led us to isolate the following basic endpoint types:

This list is not final: other endpoint types may be defined in the future, such as test endpoints which could be used to check network quality, or frame-relay endpoints that could be used to manage audio channels multiplexed over a frame-relay virtual circuit.

Connections are created on the call agent on each endpoint that will be involved in the "call." Connections may be either point to point or multipoint. A point to point connection is an association between two endpoints with the purpose of transmitting data between these endpoints. Once this association is established for both endpoints, data transfer between these endpoints can take place. A multipoint connection is established by connecting the endpoint to a multipoint session. Connections can be established over several types of bearer networks:

In the classic example of a connection between two "DS0" endpoints (EP1 and EP2), the call agents controlling the end points will establish two connections (C1 and C2):

Each connection will be designated locally by a connection identifier, and will be characterized by connection attributes.

Once established, the connection parameters can be modified at any time by a "modify connection" command. The call agent may for example instruct the gateway to change the compression algorithm used on a connection, or to modify the IP address and UDP port to which data should be sent, if a connection is "redirected."

The call agent removes a connection by sending to the gateway a "delete connection" command. The gateway may also, under some circumstances, inform a gateway that a connection could not be sustained.

Controller Modules allows external interfaces to be implemented for the Media Server. Each controller module implements an industry standard control protocol, and uses a generic SPI to control processing components or endpoints.

One such controller module is the Media Gateway Control Protocol (MGCP). MGCP is designed as an internal protocol within a distributed system that appears to outside as a single VoIP gateway. The MGCP is composed of a Call Agent, and set of gateways including at least one "media gateway" which performs the conversion of media signal between circuit and packets, and atleast one "signalling gateway" when connected to SS7 controlled network. The Call Agent can be distributed over several computer platforms.

Each endpoint supports specific MGCP Packages and some or all of the Events/Signals defined in that package. Bellow table shows the capabilities of each endpoints defined in MMS

The Announcement Endpoint is identified by localname /mobicents/media/aap/[1..10] where number in square brackets indicates the range of endpoints configured and started by media server.

The MGCP Packages and corresponding Signals/Events supported by Announcement Endpoint is specified in bellow table. Line in italics is MGCP Signal Request/Signal Event Example

Table 4.1.  Packages and corresponding Signals/Events supported by Announcement Endpoint
Supported Package
Announcement (A) Supported Events Parameters
OperationComplete (oc)

NA

O: A/oc@1

OperationFailure (of)

NA

O: A/of@1

Supported Signals Parameters
Play Announcement (ann)

The PlayAnnouncement Signal must be qualified by a String of Parameter(s). If Play Announcemnet is not provided with a parameter specifying some form of playable audio or Text-to-Speech text an error is returned to application.

The Play Announcement takes the URL of the media file to be played as parameter. The examples are

  • On remote server http://127.0.0.1:8080/mgcpdemo/audio/RQNT-ULAW.wav

    S:A/ann@1(http://127.0.0.1:8080/mgcpdemo/audio/RQNT-ULAW.wav)

  • On local server where media server is hosted file:/home/mobicents/RQNT-ULAW.wav

    S:A/ann@1(file:/home/mobicents/RQNT-ULAW.wav)

  • In addition URL of txt file can also be passed and media server would play that text file as TTS with default voice. For ex http://ann.example.net/hello.txt or file:/home/mobicents/hello.txt

  • Segment descriptor can also be used with the ann signal to make up an announcement. The only supported Segment descriptor is 'ts'. 'ts' Specifies a text string to be converted to speech. Optionally voice name 'vc' can also be passed to direct media server to play this speech in given voice. For example ts("Your text here") vc("mbrola_us1")

    For supported voices look at Table 2.1, “Directory Structure”

    S:A/ann@6(ts(You have pressed One) vc(Mbrola_US1))

  • The relative path of audio/txt file can also be passed for example RQNT-ULAW.wav

    In this case MMS will try to serach the corresponding file in ${mms.media.dir} folder.

Advance Announcement (AU) Supported Events Parameters
OperationComplete (oc)

NA

O: A/oc@1

OperationFailure (of)

NA

O: A/of@1

Supported Signals Parameters
Play Announcement (ann)

Same as Announcement Package's Play Announcement Signal

Record (aupr)

The Record Signal must be qualified by a String of Parameter. If Record is not provided with a parameter specifying path (absolute or relative) and name of audio file, error is returned to application.

The URL can be absolute URL or relative in which case recorded file will be placed at ${mms.media.dir} folder. The examples are

  • On remote server http://127.0.0.1:8080/mgcpdemo/audio/recorded.wav

    S:AU/aupr@1(http://127.0.0.1:8080/mgcpdemo/audio/recorded.wav)

  • On local server where media server is hosted file:/home/mobicents/recorded.wav

    S:AU/aupr@1(file:/home/mobicents/recorded.wav)

  • The relative path of file can also be passed for example recorded.wav

    In this case MMS will create recorded.wav in ${mms.media.dir} folder.

DTMF (D) : Supported Events Parameters
dtmf0

NA

O: D/dtmf0@1

dtmf1

NA

O: D/dtmf1@1

dtmf2

NA

O: D/dtmf2@1

dtmf3

NA

O: D/dtmf3@1

dtmf4

NA

O: D/dtmf4@1

dtmf5

NA

O: D/dtmf5@1

dtmf6

NA

O: D/dtmf6@1

dtmf7

NA

O: D/dtmf7@1

dtmf8

NA

O: D/dtmf8@1

dtmf9

NA

O: D/dtmf9@1

dtmfA

NA

O: D/dtmfA@1

dtmfB

NA

O: D/dtmfB@1

dtmfC

NA

O: D/dtmfC@1

dtmfD

NA

O: D/dtmfD@1

dtmfHash

NA

O: D/dtmfHash@1

dtmfStar

NA

O: D/dtmfStar@1

Supported Signals Parameters
dtmf0

NA

S:D/dtmf0@1

dtmf1

NA

S:D/dtmf1@1

dtmf2

NA

S:D/dtmf2@1

dtmf3

NA

S:D/dtmf3@1

dtmf4

NA

S:D/dtmf4@1

dtmf5

NA

S:D/dtmf5@1

dtmf6

NA

S:D/dtmf6@1

dtmf7

NA

S:D/dtmf7@1

dtmf8

NA

S:D/dtmf8@1

dtmf9

NA

S:D/dtmf9@1

dtmfA

NA

S:D/dtmfA@1

dtmfB

NA

S:D/dtmfB@1

dtmfC

NA

S:D/dtmfC@1

dtmfD

NA

S:D/dtmfD@1

dtmfHash

NA

S:D/dtmfHash@1

dtmfStar

NA

S:D/dtmfStar@1

The IVR Endpoint is identified by localname /mobicents/media/IVR/[1..10] where number in square brackets indicates the range of endpoints configured and started by media server.

The MGCP Packages and corresponding Signals/Events supported by IVR Endpoint is specified in bellow table. Line in italics is MGCP Signal Request/Signal Event Example

Table 4.2.  Packages and corresponding Signals/Events supported by IVR Endpoint
Supported Package
Announcement (A) Supported Events Parameters
OperationComplete (oc)

NA

O: A/oc@1

OperationFailure (of)

NA

O: A/of@1

Supported Signals Parameters
Play Announcement (ann)

The PlayAnnouncement Signal must be qualified by a String of Parameter(s). If Play Announcemnet is not provided with a parameter specifying some form of playable audio or Text-to-Speech text an error is returned to application.

The Play Announcement takes the URL of the media file to be played as parameter. The examples are

  • On remote server http://127.0.0.1:8080/mgcpdemo/audio/RQNT-ULAW.wav

    S:A/ann@1(http://127.0.0.1:8080/mgcpdemo/audio/RQNT-ULAW.wav)

  • On local server where media server is hosted file:/home/mobicents/RQNT-ULAW.wav

    S:A/ann@1(file:/home/mobicents/RQNT-ULAW.wav)

  • In addition URL of txt file can also be passed and media server would play that text file as TTS with default voice. For ex http://ann.example.net/hello.txt or file:/home/mobicents/hello.txt

  • Segment descriptor can also be used with the ann signal to make up an announcement. The only supported Segment descriptor is 'ts'. 'ts' Specifies a text string to be converted to speech. Optionally voice name 'vc' can also be passed to direct media server to play this speech in given voice. For example ts("Your text here") vc("mbrola_us1")

    For supported voices look at Table 2.1, “Directory Structure”

    S:A/ann@6(ts(You have pressed One) vc(Mbrola_US1))

  • The relative path of audio/txt file can also be passed for example RQNT-ULAW.wav

    In this case MMS will try to serach the corresponding file in ${mms.media.dir} folder.

Advance Announcement (AU) Supported Events Parameters
OperationComplete (oc)

NA

O: A/oc@1

OperationFailure (of)

NA

O: A/of@1

Supported Signals Parameters
Play Announcement (ann)

Same as Announcement Package's Play Announcement Signal

Record (aupr)

The Record Signal must be qualified by a String of Parameter. If Record is not provided with a parameter specifying path (absolute or relative) and name of audio file, error is returned to application.

The URL can be absolute URL or relative in which case recorded file will be placed at ${mms.media.dir} folder. The examples are

  • On remote server http://127.0.0.1:8080/mgcpdemo/audio/recorded.wav

    S:AU/aupr@1(http://127.0.0.1:8080/mgcpdemo/audio/recorded.wav)

  • On local server where media server is hosted file:/home/mobicents/recorded.wav

    S:AU/aupr@1(file:/home/mobicents/recorded.wav)

  • The relative path of file can also be passed for example recorded.wav

    In this case MMS will create recorded.wav in ${mms.media.dir} folder.

DTMF (D) : Supported Events Parameters
dtmf0

NA

O: D/dtmf0@1

dtmf1

NA

O: D/dtmf1@1

dtmf2

NA

O: D/dtmf2@1

dtmf3

NA

O: D/dtmf3@1

dtmf4

NA

O: D/dtmf4@1

dtmf5

NA

O: D/dtmf5@1

dtmf6

NA

O: D/dtmf6@1

dtmf7

NA

O: D/dtmf7@1

dtmf8

NA

O: D/dtmf8@1

dtmf9

NA

O: D/dtmf9@1

dtmfA

NA

O: D/dtmfA@1

dtmfB

NA

O: D/dtmfB@1

dtmfC

NA

O: D/dtmfC@1

dtmfD

NA

O: D/dtmfD@1

dtmfHash

NA

O: D/dtmfHash@1

dtmfStar

NA

O: D/dtmfStar@1

Supported Signals Parameters
dtmf0

NA

S:D/dtmf0@1

dtmf1

NA

S:D/dtmf1@1

dtmf2

NA

S:D/dtmf2@1

dtmf3

NA

S:D/dtmf3@1

dtmf4

NA

S:D/dtmf4@1

dtmf5

NA

S:D/dtmf5@1

dtmf6

NA

S:D/dtmf6@1

dtmf7

NA

S:D/dtmf7@1

dtmf8

NA

S:D/dtmf8@1

dtmf9

NA

S:D/dtmf9@1

dtmfA

NA

S:D/dtmfA@1

dtmfB

NA

S:D/dtmfB@1

dtmfC

NA

S:D/dtmfC@1

dtmfD

NA

S:D/dtmfD@1

dtmfHash

NA

S:D/dtmfHash@1

dtmfStar

NA

S:D/dtmfStar@1

The Conference Endpoint is identified by localname /mobicents/media/cnf/[1..60] where number in square brackets indicates the range of endpoints configured and started by media server.

The MGCP Packages and corresponding Signals/Events supported by Conference Endpoint is specified in bellow table. Line in italics is MGCP Signal Request/Signal Event Example

Table 4.3.  Packages and corresponding Signals/Events supported by Conference Endpoint
Supported Package
Announcement (A) Supported Events Parameters
OperationComplete (oc)

NA

O: A/oc@1

OperationFailure (of)

NA

O: A/of@1

Supported Signals Parameters
Play Announcement (ann)

The PlayAnnouncement Signal must be qualified by a String of Parameter(s). If Play Announcemnet is not provided with a parameter specifying some form of playable audio or Text-to-Speech text an error is returned to application.

The Play Announcement takes the URL of the media file to be played as parameter. The examples are

  • On remote server http://127.0.0.1:8080/mgcpdemo/audio/RQNT-ULAW.wav

    S:A/ann@1(http://127.0.0.1:8080/mgcpdemo/audio/RQNT-ULAW.wav)

  • On local server where media server is hosted file:/home/mobicents/RQNT-ULAW.wav

    S:A/ann@1(file:/home/mobicents/RQNT-ULAW.wav)

  • In addition URL of txt file can also be passed and media server would play that text file as TTS with default voice. For ex http://ann.example.net/hello.txt or file:/home/mobicents/hello.txt

  • Segment descriptor can also be used with the ann signal to make up an announcement. The only supported Segment descriptor is 'ts'. 'ts' Specifies a text string to be converted to speech. Optionally voice name 'vc' can also be passed to direct media server to play this speech in given voice. For example ts("Your text here") vc("mbrola_us1")

    For supported voices look at Table 2.1, “Directory Structure”

    S:A/ann@6(ts(You have pressed One) vc(Mbrola_US1))

  • The relative path of audio/txt file can also be passed for example RQNT-ULAW.wav

    In this case MMS will try to serach the corresponding file in ${mms.media.dir} folder.

Advance Announcement (AU) Supported Events Parameters
OperationComplete (oc)

NA

O: A/oc@1

OperationFailure (of)

NA

O: A/of@1

Supported Signals Parameters
Play Announcement (ann)

Same as Announcement Package's Play Announcement Signal

Record (aupr)

The Record Signal must be qualified by a String of Parameter. If Record is not provided with a parameter specifying path (absolute or relative) and name of audio file, error is returned to application.

The URL can be absolute URL or relative in which case recorded file will be placed at ${mms.media.dir} folder. The examples are

  • On remote server http://127.0.0.1:8080/mgcpdemo/audio/recorded.wav

    S:AU/aupr@1(http://127.0.0.1:8080/mgcpdemo/audio/recorded.wav)

  • On local server where media server is hosted file:/home/mobicents/recorded.wav

    S:AU/aupr@1(file:/home/mobicents/recorded.wav)

  • The relative path of file can also be passed for example recorded.wav

    In this case MMS will create recorded.wav in ${mms.media.dir} folder.

DTMF (D) : Supported Events Parameters
dtmf0

NA

O: D/dtmf0@1

dtmf1

NA

O: D/dtmf1@1

dtmf2

NA

O: D/dtmf2@1

dtmf3

NA

O: D/dtmf3@1

dtmf4

NA

O: D/dtmf4@1

dtmf5

NA

O: D/dtmf5@1

dtmf6

NA

O: D/dtmf6@1

dtmf7

NA

O: D/dtmf7@1

dtmf8

NA

O: D/dtmf8@1

dtmf9

NA

O: D/dtmf9@1

dtmfA

NA

O: D/dtmfA@1

dtmfB

NA

O: D/dtmfB@1

dtmfC

NA

O: D/dtmfC@1

dtmfD

NA

O: D/dtmfD@1

dtmfHash

NA

O: D/dtmfHash@1

dtmfStar

NA

O: D/dtmfStar@1

Supported Signals Parameters
dtmf0

NA

S:D/dtmf0@1

dtmf1

NA

S:D/dtmf1@1

dtmf2

NA

S:D/dtmf2@1

dtmf3

NA

S:D/dtmf3@1

dtmf4

NA

S:D/dtmf4@1

dtmf5

NA

S:D/dtmf5@1

dtmf6

NA

S:D/dtmf6@1

dtmf7

NA

S:D/dtmf7@1

dtmf8

NA

S:D/dtmf8@1

dtmf9

NA

S:D/dtmf9@1

dtmfA

NA

S:D/dtmfA@1

dtmfB

NA

S:D/dtmfB@1

dtmfC

NA

S:D/dtmfC@1

dtmfD

NA

S:D/dtmfD@1

dtmfHash

NA

S:D/dtmfHash@1

dtmfStar

NA

S:D/dtmfStar@1

The PacketRelay Endpoint is identified by localname /mobicents/media/packetrelay/[1..10] where number in square brackets indicates the range of endpoints configured and started by media server.

The MGCP Packages and corresponding Signals/Events supported by PacketRelay Endpoint is specified in bellow table. Line in italics is MGCP Signal Request/Signal Event Example

Table 4.4.  Packages and corresponding Signals/Events supported by PacketRelay Endpoint
Supported Package
Announcement (A) Supported Events Parameters
OperationComplete (oc)

NA

O: A/oc@1

OperationFailure (of)

NA

O: A/of@1

Supported Signals Parameters
Play Announcement (ann)

The PlayAnnouncement Signal must be qualified by a String of Parameter(s). If Play Announcemnet is not provided with a parameter specifying some form of playable audio or Text-to-Speech text an error is returned to application.

The Play Announcement takes the URL of the media file to be played as parameter. The examples are

  • On remote server http://127.0.0.1:8080/mgcpdemo/audio/RQNT-ULAW.wav

    S:A/ann@1(http://127.0.0.1:8080/mgcpdemo/audio/RQNT-ULAW.wav)

  • On local server where media server is hosted file:/home/mobicents/RQNT-ULAW.wav

    S:A/ann@1(file:/home/mobicents/RQNT-ULAW.wav)

  • In addition URL of txt file can also be passed and media server would play that text file as TTS with default voice. For ex http://ann.example.net/hello.txt or file:/home/mobicents/hello.txt

  • Segment descriptor can also be used with the ann signal to make up an announcement. The only supported Segment descriptor is 'ts'. 'ts' Specifies a text string to be converted to speech. Optionally voice name 'vc' can also be passed to direct media server to play this speech in given voice. For example ts("Your text here") vc("mbrola_us1")

    For supported voices look at Table 2.1, “Directory Structure”

    S:A/ann@6(ts(You have pressed One) vc(Mbrola_US1))

  • The relative path of audio/txt file can also be passed for example RQNT-ULAW.wav

    In this case MMS will try to serach the corresponding file in ${mms.media.dir} folder.

Advance Announcement (AU) Supported Events Parameters
OperationComplete (oc)

NA

O: A/oc@1

OperationFailure (of)

NA

O: A/of@1

Supported Signals Parameters
Play Announcement (ann)

Same as Announcement Package's Play Announcement Signal

Record (aupr)

The Record Signal must be qualified by a String of Parameter. If Record is not provided with a parameter specifying path (absolute or relative) and name of audio file, error is returned to application.

The URL can be absolute URL or relative in which case recorded file will be placed at ${mms.media.dir} folder. The examples are

  • On remote server http://127.0.0.1:8080/mgcpdemo/audio/recorded.wav

    S:AU/aupr@1(http://127.0.0.1:8080/mgcpdemo/audio/recorded.wav)

  • On local server where media server is hosted file:/home/mobicents/recorded.wav

    S:AU/aupr@1(file:/home/mobicents/recorded.wav)

  • The relative path of file can also be passed for example recorded.wav

    In this case MMS will create recorded.wav in ${mms.media.dir} folder.

DTMF (D) : Supported Events Parameters
dtmf0

NA

O: D/dtmf0@1

dtmf1

NA

O: D/dtmf1@1

dtmf2

NA

O: D/dtmf2@1

dtmf3

NA

O: D/dtmf3@1

dtmf4

NA

O: D/dtmf4@1

dtmf5

NA

O: D/dtmf5@1

dtmf6

NA

O: D/dtmf6@1

dtmf7

NA

O: D/dtmf7@1

dtmf8

NA

O: D/dtmf8@1

dtmf9

NA

O: D/dtmf9@1

dtmfA

NA

O: D/dtmfA@1

dtmfB

NA

O: D/dtmfB@1

dtmfC

NA

O: D/dtmfC@1

dtmfD

NA

O: D/dtmfD@1

dtmfHash

NA

O: D/dtmfHash@1

dtmfStar

NA

O: D/dtmfStar@1

Supported Signals Parameters
dtmf0

NA

S:D/dtmf0@1

dtmf1

NA

S:D/dtmf1@1

dtmf2

NA

S:D/dtmf2@1

dtmf3

NA

S:D/dtmf3@1

dtmf4

NA

S:D/dtmf4@1

dtmf5

NA

S:D/dtmf5@1

dtmf6

NA

S:D/dtmf6@1

dtmf7

NA

S:D/dtmf7@1

dtmf8

NA

S:D/dtmf8@1

dtmf9

NA

S:D/dtmf9@1

dtmfA

NA

S:D/dtmfA@1

dtmfB

NA

S:D/dtmfB@1

dtmfC

NA

S:D/dtmfC@1

dtmfD

NA

S:D/dtmfD@1

dtmfHash

NA

S:D/dtmfHash@1

dtmfStar

NA

S:D/dtmfStar@1

The Mobicents Media Server is developed on top of existing Java technologies. The Java platform is ideal for network computing. It offers single, unified-and-unifying programming model that can connect all elements of a business infrastructure. The modularization effort is supported by use of the JBoss Microcontainer which allows to deploy services written as Plain Java Objects into a Standard Java SE runtime environment in controlled manner and achieve great level of customization.

Format specifies a particular arrangement of data in a media stream. By examing the information stored in the format, components can discover how to interpret the bits in the binary sound data. Format accommodates a number of common encoding techniques, including pulse-code modulation (PCM), mu-law encoding or a-law encoding. These encoding techniques are predefined, but user can create new encoding types.

In addition to the encoding, the format includes other properties that further specify the exact arrangement of the data which are specific for each media type.

This is the starting point for creating, maintaining and closing an RTP session. RTP Manager supports unicast session only.

The configurable aspects of the RTPFactory are:


Dual-tone multi-frequency (DTMF) signaling is used for telephone signaling over the line in the voice-frequency band to the call switching center. The version of DTMF used for telephone tone dialing is known by the trademarked term Touch-Tone, and is standardised by ITU-T Recommendation Q.23. Other multi-frequency systems are used for signaling internal to the telephone network

Changing text to speech is a capability to stream speach generated from text. Mobicents Media Server supports two TTS engines:

By default Server provides following set of voices:


Mobicents Media Server has pool of voices. At startup it creates desired number of voice generating objects. This reduces runtime overhead and delays in response from Server. Size of pool, for each voice can be configured via media player configuration property: voices.

Voices property is of Map type. Table below describes values stored in this propert:


Example configuration looks as follows:



        
<bean name="media.audio"
    class="org.mobicents.media.server.impl.resource.mediaplayer.audio.AudioPlayerFactory">
    <property name="name">media.player</property>
    <property name="audioMediaDirectory">${mms.media.dir}</property>

    <property name="voices">
        <map class="java.util.Hashtable" keyClass="java.lang.String"
            valueClass="java.lang.Integer">

            <entry>
                <key>alan</key>
                <value>1</value>
            </entry>
            <entry>
                <key>kevin16</key>
                <value>1</value>
            </entry>
            <entry>
                <key>kevin</key>
                <value>1</value>
            </entry>
            <entry>
                <key>mbrola_us3</key>
                <value>1</value>
            </entry>
            <entry>
                <key>mbrola_us2</key>
                <value>1</value>
            </entry>
            <entry>
                <key>mbrola_us1</key>
                <value>1</value>
            </entry>

        </map>
    </property>

</bean>
        
        

The Connection can be in one of the following four operational states.

There is no direct control over the states of Connection but only through Controller module

The ConnectionStateManager maps various state's of Connection with life-time (in milli seconds) of Connection in that state

ConnectionStateManager is defined by the following component:



<bean name="ConnectionStateManager" class="org.mobicents.media.server.ConnectionStateManager">
    <constructor>
        <parameter>
            <map class="java.util.Hashtable" keyClass="org.mobicents.media.server.spi.ConnectionState" valueClass="java.lang.Integer">
                <entry>
                    <key><inject bean="ConnectionState.NULL"></inject></key>    
                    <value>0</value>                    
                </entry>
                <entry>
                    <key><inject bean="ConnectionState.IDLE"></inject></key>    
                    <value>30000</value>                    
                </entry>
                <entry>
                    <key><inject bean="ConnectionState.HALF_OPEN"></inject></key>   
                    <value>3600000</value>                  
                </entry>
                <entry>
                    <key><inject bean="ConnectionState.OPEN"></inject></key>    
                    <value>3600000</value>                  
                </entry>
                <entry>
                    <key><inject bean="ConnectionState.CLOSED"></inject></key>  
                    <value>0</value>                    
                </entry>                
            </map>              
        </parameter>            
    </constructor>
</bean>

Irrespective if Connection is running or not, the Connection will be deleted after timeout (time starting from transition to this state) value specified for that state

A common theme for Mobicents Media Server is the breaking out of internal fixed subsystems into stand-alone components.Mobicents Media Server strategy for making available the various voice/video services as independent components, so that they can be wired-together on demand

Mobicents Media server architecture promotes the usage of Service Objects to represent the media flow path. The component architecture divides the process of constructing media services into two major parts:

  • Implementing components that generate, or consume, media data.

  • Assembling media component chains to build a media flow path.

The role of channel is to construct media flow path by joining components using pipes. Channel can be connected to any source/sink or to other channel. The following diagram explains channel structure.

Respective channel declaration:


Configurable aspects of the channel are:

components

The list of components used by the channel

pipes

The list of pipes wich defines the actual media flow path

Revision History
Revision 3.0Thu Jun 11 2009Jared Morgan
Second release of the "parameterized" documentation.
Revision 2.0Fri Mar 06 2009Douglas Silas
First release of the "parameterized", and much-improved JBCP documentation.