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:
- Negotiate the codec selection, based on the codecs which it is configured to support.
- Read the coded audio packets from disk or database and stream them.
- Generate silence packets appropriate for the specified codec.
- 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:
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.
- For internal announcements, these must be the exact name which matches the language name in the
mapping.json
file which is used to transform “Message ID” + “Language” → “Audio Filenames”. - For internal announcements using variable parts, these must be the exact name which matches the SIP Language Codec name.
- For external SRF announcements, this name must match an entry in the Language MAP used for that SRF.
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:
- HEARTBEAT Messages.
- MANAGEMENT Messages (!MANAGEMENT-*-REQUEST inbound).
- RTP Messages (RTP-ESTABLISH inbound).