rtp_media_server Module

Julien Chavanton

   <jchavanton@gmail.com>

Julien Chavanton

   flowroute.com
   <jchavanton@gmail.com>

Edited by

Julien Chavanton

   flowroute.com
   <jchavanton@gmail.com>

   Copyright © 2017-2019 Flowroute.com
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Quick start, how-to build on debian

              2.1. Building on Debian, Dockerfile and docker image

        3. Dependencies

              3.1. Kamailio Modules
              3.2. External Libraries or Applications

        4. Parameters

              4.1. log_file_name (string)

        5. Functions

              5.1. rms_answer (event_route)
              5.2. rms_hangup ()
              5.3. rms_bridge (target URI, event_route)
              5.4. rms_dialog_check ()
              5.5. rms_sip_request ()
              5.6. rms_play (file, event_route)

   List of Examples

   1.1. log_file_name example
   1.2. rms_answer usage example
   1.3. rms_hangup usage example
   1.4. rms_bridge usage example
   1.5. rms_dialog_check usage example
   1.6. rms_sip_request usage example
   1.7. rms_play usage example

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Quick start, how-to build on debian

        2.1. Building on Debian, Dockerfile and docker image

   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Parameters

        4.1. log_file_name (string)

   5. Functions

        5.1. rms_answer (event_route)
        5.2. rms_hangup ()
        5.3. rms_bridge (target URI, event_route)
        5.4. rms_dialog_check ()
        5.5. rms_sip_request ()
        5.6. rms_play (file, event_route)

1. Overview

   rtp_media_server module adds RTP and media processing functionalities
   to Kamailio. Kamailio is providing SIP signaling including an endpoint
   with Dialog state, SDP parsing and scripting language.

   oRTP: is providing Real-time Transport Protocol (RFC 3550)

   mediastreamer2: is providing mediaprocessing functionnalities using
   graphs and filters, many modules are available to support various
   features, it should be relatively simple to integrated them.

   mediastreamer2 is also providing a framework to create custom
   mediaprocessing modules.

2. Quick start, how-to build on debian

   2.1. Building on Debian, Dockerfile and docker image

2.1. Building on Debian, Dockerfile and docker image

   The module includes Dockerfile that can also be used as a reference on
   how to build everything from source on Debian, the package of
   libmediastreamer on Linux is usually outdated. A Docker image is also
   available from dockerhub
   https://hub.docker.com/r/jchavanton/rtp_media_server

3. Dependencies

   3.1. Kamailio Modules
   3.2. External Libraries or Applications

3.1. Kamailio Modules

   The module depends on the following modules (in other words the listed
   modules must be loaded before this module):
     * tm - transaction module

3.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:

   If you want to build oRTP and mediastreamer from source, you can use
   the provided script for Debian "install_bc.sh".
     * oRTP git clone git://git.linphone.org/ortp.git
       oRTP is a library implemeting Real-time Transport Protocol (RFC
       3550), distributed under GNU GPLv2 or proprietary license.
     * mediastreamer2 git clone git://git.linphone.org/mediastreamer2.git
       Mediastreamer2 is a powerful and lightweight streaming engine
       specialized for voice/video telephony applications.
     * bcunit git clone
       https://github.com/BelledonneCommunications/bcunit.git
       fork of the defunct project CUnit, with several fixes and patches
       applied. CUnit is a Unit testing framework for C.

4. Parameters

   4.1. log_file_name (string)

4.1. log_file_name (string)

   oRTP and MediaStreamer2 log file settings the log mask is not
   configurable : MESSAGE | WARNING | ERROR | FATAL levels are activated.

   Default value is not-set (no logging to file).

   Example 1.1. log_file_name example
...
modparam("rtp_media_server", "log_file_name", "/var/log/rms/rms_ortp.log")
...

5. Functions

   5.1. rms_answer (event_route)
   5.2. rms_hangup ()
   5.3. rms_bridge (target URI, event_route)
   5.4. rms_dialog_check ()
   5.5. rms_sip_request ()
   5.6. rms_play (file, event_route)

5.1. rms_answer (event_route)

   Create a call leg with a SIP dialog and an RTP session call the
   event_route

   This function can be used from REQUEST_ROUTE, REPLY_ROUTE and
   FAILURE_ROUTE.

   Example 1.2. rms_answer usage example
...
event_route[rms:start] {
        xnotice("[rms:start] play ...\n");
        rms_play("/tmp/reference_8000.wav", "rms:after_play");
};

event_route[rms:after_play] {
        xnotice("[rms:after_play] play done...\n");
        rms_hangup();
};

route {
        if (t_precheck_trans()) {
                t_check_trans();
                exit;
        }
        t_check_trans();
        if (is_method("INVITE") && !has_totag()) {
                if (!rms_answer("rms:start")) {
                        t_reply("503", "server error");
                }
        }
        rms_sip_request();
...

5.2. rms_hangup ()

   Send a BYE, delete the RTP session and the media resources.

   This function can be used from EVENT_ROUTE.

   Example 1.3. rms_hangup usage example
...
        rms_hangup();
...

5.3. rms_bridge (target URI, event_route)

   Bridge the incoming call, create a second call leg using a UAC in a
   B2BUA manner, this is needed in case we want to un-bridge later, a
   feature not currently implemented Call the specified event_route,
   defaulting to [rms:bridge].

   This function can be used from REQUEST_ROUTE.

   Example 1.4. rms_bridge usage example
...
event_route[rms:bridged] {
        xnotice("[rms:bridged] !\n");
};

route {
        if (t_precheck_trans()) {
                t_check_trans();
                exit;
        }
        t_check_trans();
        if (is_method("INVITE") && !has_totag()) {
                $var(target) = "sip:" + $rU + "@mydomain.com:5060;";
                if (!rms_bridge("$var(target)", "rms:bridged")) {
                        t_reply("503", "server error");
                }
        }
        if(rms_dialog_check()) // If the dialog is managed by the RMS module, th
e in-dialog request needs to be handled by it.
                rms_sip_request();
...

5.4. rms_dialog_check ()

   Returns true if the current SIP message it handled/known by the RMS
   module, else it may be handled in any other way by Kamailio.

   This function can be used from REQUEST_ROUTE, REPLY_ROUTE and
   FAILURE_ROUTE.

   Example 1.5. rms_dialog_check usage example
...
        if (rms_dialog_check()) {
                xnotice("This dialog is handled by the RMS module\n");
                rms_sip_request();
        }
...

5.5. rms_sip_request ()

   This should be called for every in-dialog SIP request, it will be
   forwarded behaving as a B2BUA, the transaction will be suspended until
   the second leg replies.

   If the SIP dialog is not found "481 Call/Transaction Does Not Exist" is
   returned.

   This function can be used from REQUEST_ROUTE, REPLY_ROUTE and
   FAILURE_ROUTE.

   Example 1.6. rms_sip_request usage example
...
        if (rms_dialog_check()) {
                rms_sip_request();
        }
...

5.6. rms_play (file, event_route)

   Play a wav file, a resampler is automaticaly configured to resample and
   convert stereo to mono if needed.

   The second parameter is the event route that will be called when the
   file was played.

   This function can be used from EVENT_ROUTE.

   Example 1.7. rms_play usage example
...
        rms_play("file.wav", "event_route_name");
...
