RtpApp

RTP Application Configuration

The RTP Application generates the outbound RTP packet streams, under the direct instruction of another app such as the SrpSipApp, or the LhoSipApp (internal announcement mode).

A typical configuration will consist of a single SrpSipApp which directs multiple copies of the RtpApp. This is done by setting the repeat count on the RtpApp application. Each RtpApp executes as an independent process, which provides multi-core scalability for the CPU-intensive and real-time-critical work associated with generating outbound RTP audio and (as necessary) performing DTMF wave-filter analysis of inbound RTP audio.

The RtpApp performs the related codec tasks. Specifically the RtpApp will:

  1. Negotiate the codec selection, based on the codecs which it is configured to support.
  2. Read the coded audio packets from disk or database and stream them.
  3. Generate silence packets appropriate for the specified codec.
  4. Decode received audio packets for the purpose of DTMF detection.

Here is a config example which starts-up 6 copies of the RtpApp, each of which will perform audio packet streaming for up to 40 simultaneous RTP streams.

    <?xml version="1.0" encoding="utf-8"?>
    <n2svcd>
      ...
      <applications>
        ...
        <application name="RTP" module="RtpApp" repeat="6">
          <include>
            <lib>../../n2sip/apps/rtp/lib</lib>
            <lib>../../n2sip/lib</lib>
            <lib>../apps/db/lib</lib>
          </include>
          <parameters>
            <parameter name="trace_level" value="1"/>
            <parameter name="edr_enabled" value="1"/>
            <parameter name="rtp_streams_per_app" value="40"/>
            <parameter name="rtp_start_port" value="6970"/>
            <parameter name="rtp_local_ip" value="192.168.1.5"/>

            <parameter name="rtp_audio_encodings" value="PCMU/8000,PCMA/8000"/>
            <parameter name="rtp_dtmf_inband_supported" value="no"/>
            <parameter name="rtp_event_sendonly" value="0"/>
            <parameter name="leading_silence" value="40"/>

            <parameter name="audio_dir" value="../../n2sip/demo/audio/ulaw"/>
            <!-- <parameter name="db_app_name" value="DB-AUDIO"/> -->
            <!-- <parameter name="db_sql_set" value="simple"/> -->
          </parameters>
          <config>
            <!-- Internal RTP announcement languages. -->
            <languages>
              <language name="English" default="1"/>
              <language name="German"/>
            </languages>
          </config>
        </application>
        ...
      </application>
      ...
    </n2svcd>

Configuration Details

The application element attributes for an RTP Application instance may include the below.

For details of the various parameter types used, refer to Common Configuration.

Parameter Name Type XML Type Description
See: Common Application configuration
name String Attribute [Required] A unique name for this application instance.
module String Attribute [Required] RtpApp
include.lib String Attribute [Required] ../../n2sip/apps/rtp/lib
[Required] ../../n2sip/lib
parameters Array Element Array of name = value Parameters for this Application instance.
"rtp_streams_per_app" Integer Attribute Number of simultaneous audio streams that a single RtpApp will support.
(Default = 20).
"rtp_local_host" String Attribute IPv4 Host Name or A.B.C.D IPv4 Address advertised for the RTP socket.
Defaults to the "public" IP address.
"rtp_start_port" Integer Attribute The lowest IPv4 Port Number which will be assigned. This must be an even-numbered port.
Each stream requires two ports – the even-numbered port for RTP and the odd-numbered port for RTCP.
Hence each RtpApp will use 2 * rtp_streams_per_app ports.
The lowest port will be rtp_start_port and the highest port will be rtp_start_port + (2 * repeat * rtp_streams_per_app) - 1.
All ports in the range must be strictly reserved. The stream will fail if the port is not available.
(Default = 6970).
"rtp_audio_encodings" String Attribute Comma-separated list of supported RTP Audio Encodings for the purpose of constructing SDP Answer and SDP Offer. When constructing a SDP Offer, these encodings will be offered in the order listed (first is highest priority).
This configuration is for audio encoding only, the SDP Answer/Offer of telephone-event encoding is performed separately.
Supported options are:
  1. PCMU/8000 - raw ITU-T REC G.711 µ-law, 8000 Hz, mono
  2. PCMA/8000 - raw ITU-T REC G.711 A-law, 8000 Hz, mono
  3. AMR/8000 - 3GPP TS 26.073 Adaptive Multi-Rate (Narrowband), 8000 Hz, mono
  4. AMR-WB/16000 - ITU-T REC G.722.2 Adaptive Multi-Rate Wideband, 16000 Hz, mono
(Default = PCMU/8000).
"rtp_dtmf_inband_supported" yes / no / 1 / 0 Attribute If we cannot negotiate telephone-event-id, should we enable inband DTMF detection (using Fast-Fourier audio packet analysis)?
(Default = yes).
"rtp_event_sendonly" YES / NO / 1 / 0 Attribute When we are expecting RTP telephony-event packets from the RTP client, can we save bandwidth and use a=sendonly in the Session Description Protocol (SDP).
(Default = YES).
"rtp_event_early_media" YES / NO / 1 / 0 Attribute When we are expecting RTP telephony-event packets from the RTP client, is this compatible with the use of SIP Early Media (1XX Proceeding Response).
(Default = YES).
"end_digit_policy" always / cs1 Attribute When collecting exactly one digit, any specified end digit is ignored and treated as input.
Otherwise, when do we honour the specified end digit for an interaction.
always: Always, unconditionally.
cs1: End digit will be ignored when minDigits equals maxDigits.
(Default = always).
"default_min_digits" Integer Attribute The minimum number of digits that must be collected for valid input, if no value for minDigits is specified in the PromptAndCollectUserInformation.
(Default = 1).
"default_max_digits" Integer Attribute The maximum number of digits that may be collected for valid input, if no value for maxDigits is specified in the PromptAndCollectUserInformation.
(Default = 31).
"default_first_digit_timeout" Integer Attribute Timeout in seconds before which the first digit must be entered or collection is abandoned, if no value for firstDigitTimeOut is specified in the PromptAndCollectUserInformation.
(Default = 8).
"default_inter_digit_timeout" Integer Attribute Timeout in seconds before which subsequent digits must be entered or collection is abandoned, if no value for firstDigitTimeOut is specified in the PromptAndCollectUserInformation.
(Default = 4).
"default_interruptable" YES / NO / 1 / 0 Attribute Should Prompting be able to return early if sufficient digits have been collected, even if the announcement has not yet completed playing. In practice, this will never be used since it will always be overridden by the interruptableAnnInd specified or defaulted in the PromptAndCollectUserInformation.
(Default = YES).
"max_collect_seconds" Integer Attribute A hard limit on the number of seconds we will wait for collecting DTMF input.
(Default = 240).
"leading_silence" Integer Attribute Duration of filler silence before the first announcement in each session.
This can help if you are hearing a stutter during RTP setup at the start of interactions.
This value is in milliseconds, and will be rounded up to make it a multiple of the audio encoding's frame duration.
(Default = 0).
"db_app_name" String Attribute The name of a DBApp to use when announcement configuration and media for RTP streaming is stored in Database.
The expected structure of the database must match the SQL queries specified by the db_sql_set parameter.
Specify at most one of db_app_name or audio_dir.
(Default = Database Loading is Not Used).
"db_sql_set" n2ivr.v1 / simple Attribute Specifies which SQL queries to use. See the expanded details in the subsequent section.
(Default = n2ivr.v1).
"audio_dir" String Attribute Directory path to use when announcement configuration and media for RTP streaming is stored on-disk.
The directory must contain a mapping.json file which contains the configuration for every announcement/language combination.
The directory will also contain subdirectories for each configured language.
(Default = "/var/lib/n2sip/audio").
"cache_check_seconds" Integer Attribute When caching audio files, how often we check the on-disk mapper and audio files to see if they have been modified.
(Default = 120).
"instruction_timer_ms" Integer Attribute How long an RTP stream will wait to receive "play" instructions from the controlling application, being the SrpSipApp or LhoSipApp. This applies both to the first play instruction after the RTP stream is accepted, and for subsequent play/hangup instructions.
If no instruction is received within the indicated period, the RtpApp will teardown the RTP stream and send a RTP-SHUTDOWN message to the controlling app.
This timer value should be set higher than the corresponding timers in the controlling app such as the SrpSipApp or LhoSipApp.
(Default = 3000).
config Object Element Container for extended configuration for this Application instance.
.languages Array Element Array of language elements defining language names which the Lua service logic may specify.
.language Object Element Defines a language name which the Lua service logic may specify when requesting an interaction.

Language Names

Each language name definition defines a known language name.

Names must be unique. Only one name may be marked as default.

Each language Object in the config.languages Array is configured as follows.

Parameter Name Type XML Type Description
name String Attribute [Required] Unique name for this language, which matches the relevant associated resources as described above.
default yes / no Attribute Sets this to be the default language name used if the service logic does not provide a language name for interaction.
Only one entry may be marked as default = yes.
(Default = the language is not the default language).

The language name English is always added if not present.

If no language is configured as default, then the English language will be marked as the default.

SQL SELECT Sets

Each SQL SELECT set has the following bind parameters and return row keys.

Cache Label Bind Parameters (Positional) Return Keys (Named, Case-Sensitive)
id resource_id language_name
play_list
file language_name
file_name
suffix
audio_stream
vpfile language_name
vpfile_name
suffix
audio_stream

SET n2ivr.v1

This default set is:

SELECT announcement_id, language_name, play_list FROM announcement a
    INNER JOIN language l ON l.language_id = a.language_id WHERE resource_id = ?"
SELECT content AS audio_stream FROM n2ivr.audio_file f
  JOIN n2ivr.audio_file_version v USING (audio_file_id)
  JOIN n2ivr.language l USING (language_id)
  JOIN n2ivr.audio_file_encoding e USING (audio_file_encoding_id)
  JOIN n2ivr.audio_file_content c USING (content_md5_hash)
WHERE
  f.announcement_set_id = (SELECT announcement_set_id FROM n2ivr.announcement_set WHERE type_of_set = 'active')
  AND l.language_name = ? AND f.audio_file_name = ? AND e.file_extension = ?
SELECT content AS audio_stream FROM n2ivr.audio_file f
  JOIN n2ivr.audio_file_version v USING (audio_file_id)
  JOIN n2ivr.language l USING (language_id)
  JOIN n2ivr.audio_file_encoding e USING (audio_file_encoding_id)
  JOIN n2ivr.audio_file_content c USING (content_md5_hash)
WHERE
  f.announcement_set_id = (SELECT announcement_set_id FROM n2ivr.announcement_set WHERE type_of_set = 'active')
  AND l.language_name = ? AND f.audio_file_name = ? AND e.file_extension = ?

SET simple

The simple set is:

SELECT id, language_name, play_list FROM announcement_mapping WHERE resource_id = ?
SELECT id, audio_stream FROM file_audio WHERE language_name = ? AND file_name = ? AND suffix = ?
SELECT id, audio_stream FROM vpfile_audio WHERE language_name = ? AND vpfile_name = ? AND suffix = ?

Message Handling

The RtpApp uses the following messages: