rtp_media_server: initial creation of README file

src/modules/rtp_media_server/README

@@ -0,0 +1,218 @@
+
+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-2018 Flowroute.com
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Parameters
+
+              3.1. log_file_name (string)
+
+        4. Functions
+
+              4.1. rms_answer ()
+              4.2. rms_hangup ()
+              4.3. rms_media_stop ()
+              4.4. rms_play ()
+
+   List of Examples
+
+   1.1. log_file_name example
+   1.2. usage example
+   1.3. usage example
+   1.4. usage example
+   1.5. usage example
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Parameters
+
+        3.1. log_file_name (string)
+
+   4. Functions
+
+        4.1. rms_answer ()
+        4.2. rms_hangup ()
+        4.3. rms_media_stop ()
+        4.4. rms_play ()
+
+1. Overview
+
+   rtp_media_server module is adding RTP and media processing
+   functionalities to Kamailio
+
+   Kamailio is providing SIP signaling including and enpoint 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. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The module depends on the following modules (in the other words the
+   listed modules must be loaded before this module):
+     * tm - accounting module
+
+2.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://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.
+
+3. Parameters
+
+   3.1. log_file_name (string)
+
+3.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")
+...
+
+4. Functions
+
+   4.1. rms_answer ()
+   4.2. rms_hangup ()
+   4.3. rms_media_stop ()
+   4.4. rms_play ()
+
+4.1. rms_answer ()
+
+   Create a session and a call leg and call the event_route[rms:start]
+   config example
+
+   This function can be used from REQUEST_ROUTE, REPLY_ROUTE and
+   FAILURE_ROUTE.
+
+   Example 1.2. 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()) {
+                        t_reply("503", "server error");
+                }
+        }
+
+        if (is_method("BYE")){
+                xnotice("BYE RECEIVED [$ci]\n");
+                rms_media_stop();
+        }
+...
+
+4.2. rms_hangup ()
+
+   Send a BYE, delete the RTP session and the media ressources.
+
+   This function can be used from EVENT_ROUTE.
+
+   Example 1.3. usage example
+...
+        rms_hangup();
+...
+
+4.3. rms_media_stop ()
+
+   This should be called on reception of a BYE, this will delete the RTP
+   session and the media ressources. and reply "200 OK".
+
+   If the SIP session 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.4. usage example
+...
+        if (is_method("BYE")){
+                rms_media_stop();
+        }
+...
+
+4.4. rms_play ()
+
+   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.5. usage example
+...
+        rms_play("file.wav", "event_route_name");
+...