mirror of https://github.com/sipwise/rtpengine.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
2506 lines
111 KiB
2506 lines
111 KiB
|
|
|
|
|
|
|
|
What is rtpengine?
|
|
=======================
|
|
|
|
The [Sipwise](http://www.sipwise.com/) NGCP rtpengine is a proxy for RTP traffic and other UDP based
|
|
media traffic. It's meant to be used with the [Kamailio SIP proxy](http://www.kamailio.org/)
|
|
and forms a drop-in replacement for any of the other available RTP and media
|
|
proxies.
|
|
|
|
Currently the only supported platform is GNU/Linux.
|
|
|
|
Mailing List
|
|
============
|
|
|
|
For general questions, discussion, requests for support, and community chat,
|
|
join our [mailing list](https://rtpengine.com/mailing-list). Please do not use
|
|
the Github issue tracker for this purpose.
|
|
|
|
Features
|
|
=========
|
|
|
|
* Media traffic running over either IPv4 or IPv6
|
|
* Bridging between IPv4 and IPv6 user agents
|
|
* Bridging between different IP networks or interfaces
|
|
* TOS/QoS field setting
|
|
* Customizable port range
|
|
* Multi-threaded
|
|
* Advertising different addresses for operation behind NAT
|
|
* In-kernel packet forwarding for low-latency and low-CPU performance
|
|
* Automatic fallback to normal userspace operation if kernel module is unavailable
|
|
* Support for *Kamailio*'s *rtpproxy* module
|
|
* Legacy support for old *OpenSER* *mediaproxy* module
|
|
* HTTP, HTTPS, and WebSocket (WS and WSS) interfaces
|
|
|
|
When used through the *rtpengine* module (or its older counterpart called *rtpproxy-ng*),
|
|
the following additional features are available:
|
|
|
|
- Full SDP parsing and rewriting
|
|
- Supports non-standard RTCP ports (RFC 3605)
|
|
- ICE (RFC 5245) support:
|
|
+ Bridging between ICE-enabled and ICE-unaware user agents
|
|
+ Optionally acting only as additional ICE relay/candidate
|
|
+ Optionally forcing relay of media streams by removing other ICE candidates
|
|
+ Optionally act as an "ICE lite" peer only
|
|
- SRTP (RFC 3711) support:
|
|
+ Support for SDES (RFC 4568) and DTLS-SRTP (RFC 5764)
|
|
+ AES-CM and AES-F8 ciphers, both in userspace and in kernel
|
|
+ HMAC-SHA1 packet authentication
|
|
+ Bridging between RTP and SRTP user agents
|
|
+ Opportunistic SRTP (RFC 8643)
|
|
+ AES-GCM Authenticated Encryption (AEAD) (RFC 7714)
|
|
- Support for RTCP profile with feedback extensions (RTP/AVPF, RFC 4585 and 5124)
|
|
- Arbitrary bridging between any of the supported RTP profiles (RTP/AVP, RTP/AVPF,
|
|
RTP/SAVP, RTP/SAVPF)
|
|
- RTP/RTCP multiplexing (RFC 5761) and demultiplexing
|
|
- Breaking of BUNDLE'd media streams (draft-ietf-mmusic-sdp-bundle-negotiation)
|
|
- Recording of media streams, decrypted if possible
|
|
- Transcoding and repacketization
|
|
- Transcoding between RFC 2833/4733 DTMF event packets and in-band DTMF tones (and vice versa)
|
|
- Injection of DTMF events or PCM DTMF tones into running audio streams
|
|
- Playback of pre-recorded streams/announcements
|
|
- Transcoding between T.38 and PCM (G.711 or other audio codecs)
|
|
- Silence detection and comfort noise (RFC 3389) payloads
|
|
* Media forking
|
|
* Publish/subscribe mechanism for N-to-N media forwarding
|
|
|
|
There is also limited support for *rtpengine* to be used as a drop-in
|
|
replacement for *Janus* using the native Janus control protocol (see below).
|
|
|
|
*Rtpengine* does not (yet) support:
|
|
|
|
* ZRTP, although ZRTP passes through *rtpengine* just fine
|
|
|
|
Compiling and Installing
|
|
=========================
|
|
|
|
Package Repositories
|
|
--------------------
|
|
|
|
Prebuilt packages for some newer releases of Debian are available on [this repository](https://dfx.at/rtpengine)
|
|
|
|
Compiling on a Debian System
|
|
----------------------------
|
|
|
|
On a Debian system, everything can be built and packaged into Debian packages
|
|
by executing `dpkg-buildpackage` (which can be found in the `dpkg-dev` package) in the main directory.
|
|
This script will issue an error and stop if any of the dependency packages are
|
|
not installed. The script `dpkg-checkbuilddeps` can be used to check missing dependencies.
|
|
(See the note about G.729 at the end of this section.)
|
|
|
|
This will produce a number of `.deb` files, which can then be installed using the
|
|
`dpkg -i` command.
|
|
|
|
The generated files are (with version 6.2.0.0 being built on an amd64 system):
|
|
|
|
* `ngcp-rtpengine_6.2.0.0+0~mr6.2.0.0_all.deb`
|
|
|
|
This is a meta-package, which doesn't contain or install anything on its own, but rather
|
|
only depends on the other packages to be installed. Not strictly necessary to be installed.
|
|
|
|
* `ngcp-rtpengine-daemon_6.2.0.0+0~mr6.2.0.0_amd64.deb`
|
|
|
|
This installed the userspace daemon, which is the main workhorse of rtpengine. This is
|
|
the minimum requirement for anything to work.
|
|
|
|
* `ngcp-rtpengine-iptables_6.2.0.0+0~mr6.2.0.0_amd64.deb`
|
|
|
|
Installs the plugin for `iptables` and `ip6tables`. Necessary for in-kernel operation.
|
|
|
|
* `ngcp-rtpengine-kernel-dkms_6.2.0.0+0~mr6.2.0.0_all.deb`
|
|
|
|
Kernel module, DKMS version of the package. Recommended for in-kernel operation. The kernel
|
|
module will be compiled against the currently running kernel using DKMS.
|
|
|
|
* `ngcp-rtpengine-kernel-source_6.2.0.0+0~mr6.2.0.0_all.deb`
|
|
|
|
If DKMS is unavailable or not desired, then this package will install the sources for the kernel
|
|
module for manual compilation. Required for in-kernel operation, but only if the DKMS package
|
|
can't be used.
|
|
|
|
* `ngcp-rtpengine-recording-daemon_6.2.0.0+0~mr6.2.0.0_amd64.deb`
|
|
|
|
Optional separate userspace daemon used for call recording features.
|
|
|
|
* `-dbg...` or `-dbgsym...` packages
|
|
|
|
Debugging symbols for the various components. Optional.
|
|
|
|
For transcoding purposes, Debian provides an additional package `libavcodec-extra` to replace
|
|
the regular `libavcodec` package. It is recommended to install this extra package to offer support
|
|
for additional codecs.
|
|
|
|
To support the G.729 codec for transcoding purposes, the external library *bcg729* is required. Please
|
|
see the section on *G.729 support* below for details.
|
|
|
|
Manual Compilation
|
|
------------------
|
|
|
|
There are 3 main parts to *rtpengine* plus one optional component, which can be
|
|
found in the respective subdirectories. Running `make` on the top source
|
|
directory will build all parts. Running `make check` additionally will run the
|
|
test suite.
|
|
|
|
* `daemon`
|
|
|
|
The userspace daemon and workhorse, minimum requirement for anything to work. Running `make`
|
|
will compile the binary, which will be called `rtpengine`. The following software packages
|
|
including their development headers are required to compile the daemon:
|
|
|
|
- *pkg-config*
|
|
- *GLib* including *GThread* and *GLib-JSON* version 2.x
|
|
- *zlib*
|
|
- *OpenSSL*
|
|
- *PCRE* library
|
|
- *XMLRPC-C* version 1.16.08 or higher
|
|
- *hiredis* library
|
|
- *gperf*
|
|
- *libcurl* version 3.x or 4.x
|
|
- *libevent* version 2.x
|
|
- *libpcap*
|
|
- *libsystemd*
|
|
- *spandsp*
|
|
- *MySQL* or *MariaDB* client library (optional for media playback and call recording daemon)
|
|
- *libiptc* library for iptables management (optional)
|
|
- *ffmpeg* codec libraries for transcoding (optional) such as *libavcodec*, *libavfilter*, *libswresample*
|
|
- *bcg729* for full G.729 transcoding support (optional)
|
|
- *libmosquitto*
|
|
- *libwebsockets*
|
|
- *libopus*
|
|
|
|
The `Makefile` contains a few Debian-specific flags, which may have to removed for compilation to
|
|
be successful. This will not affect operation in any way.
|
|
|
|
If you do not wish to (or cannot) compile the optional iptables management feature, the
|
|
`Makefile` also contains a switch to disable it. See the `--iptables-chain` option for
|
|
a description. The name of the `make` switch and its default value is `with_iptables_option=yes`.
|
|
|
|
Similarly, the transcoding feature can be excluded via a switch in the `Makefile`, making it
|
|
unnecessary to have the *ffmpeg* libraries installed. The name of the `make` switch and
|
|
its default value is `with_transcoding=yes`.
|
|
|
|
Both `Makefile` switches can be provided to the `make` system via environment variables, for
|
|
example by building with the shell command `with_transcoding=no make`.
|
|
|
|
* `iptables-extension`
|
|
|
|
Required for in-kernel packet forwarding.
|
|
|
|
With the `iptables` development headers installed, issuing `make` will compile the plugin for
|
|
`iptables` and `ip6tables`. The file will be called `libxt_RTPENGINE.so` and needs to be copied
|
|
into the `xtables` module directory. It is copied on `make install`. The location of this
|
|
directory can be determined through `pkg-config xtables --variable=xtlibdir` on newer systems,
|
|
and/or is usually either `/lib/xtables/` or `/usr/lib/x86_64-linux-gnu/xtables/`.
|
|
|
|
* `kernel-module`
|
|
|
|
Required for in-kernel packet forwarding.
|
|
|
|
Compilation of the kernel module requires the kernel development headers to be installed in
|
|
`/lib/modules/$VERSION/build/`, where *$VERSION* is the output of the command `uname -r`. For
|
|
example, if the command `uname -r` produces the output `3.9-1-amd64`, then the kernel headers
|
|
must be present in `/lib/modules/3.9-1-amd64/build/`. The last component of this path (`build`)
|
|
is usually a symlink somewhere into `/usr/src/`, which is fine.
|
|
|
|
Successful compilation of the module will produce the file `xt_RTPENGINE.ko`. The module can be inserted
|
|
into the running kernel manually through `insmod xt_RTPENGINE.ko` (which will result in an error if
|
|
depending modules aren't loaded, for example the `x_tables` module), but it's recommended to copy the
|
|
module into `/lib/modules/$VERSION/updates/`, followed by running `depmod -a`. This copying is performed
|
|
on `make install`. After this, the module can be loaded by issuing `modprobe xt_RTPENGINE`.
|
|
|
|
* `recording-daemon`
|
|
|
|
Optional component for the call recording feature. Prerequisites are
|
|
usage of the kernel module and availability of transcoding (via
|
|
*ffmpeg*)
|
|
|
|
Usage
|
|
=====
|
|
|
|
Userspace Daemon
|
|
----------------
|
|
|
|
The options are described in detail in the rtpengine(1) man page. If you're
|
|
reading this on Github, you can view the current master's man page
|
|
[here](https://github.com/sipwise/rtpengine/blob/master/daemon/rtpengine.pod).
|
|
|
|
In-kernel Packet Forwarding
|
|
---------------------------
|
|
|
|
In normal userspace-only operation, the overhead involved in processing each individual RTP or media packet
|
|
is quite significant. This comes from the fact that each time a packet is received on a network interface,
|
|
the packet must first traverse the stack of the kernel's network protocols, down to locating a process's
|
|
file descriptor. At this point the linked user process (the daemon) has to be signalled that a new packet
|
|
is available to be read, the process has to be scheduled to run, once running the process must read the packet,
|
|
which means it must be copied from kernel space to user space, involving an expensive context switch. Once the
|
|
packet has been processed by the daemon, it must be sent out again, reversing the whole process.
|
|
|
|
All this wouldn't be a big deal if it wasn't for the fact that RTP traffic generally consists of many small
|
|
packets being transferred at high rates. Since the forwarding overhead is incurred on a per-packet basis, the
|
|
ratio of useful data processed to overhead drops dramatically.
|
|
|
|
For these reasons, *rtpengine* provides a kernel module to offload the bulk of the packet forwarding
|
|
duties from user space to kernel space. Using this technique, a large percentage of the overhead can be
|
|
eliminated, CPU usage greatly reduced and the number of concurrent calls possible to be handled increased.
|
|
|
|
In-kernel packet forwarding is implemented as an *iptables* module
|
|
(or more precisely, an *x\_tables* module). As such, it comes in two parts, both of
|
|
which are required for proper operation. One part is the actual kernel module called `xt_RTPENGINE`. The
|
|
second part is a plugin to the `iptables` and `ip6tables` command-line utilities to make it possible to
|
|
actually add the required rule to the tables.
|
|
|
|
### Overview ###
|
|
|
|
In short, the prerequisites for in-kernel packet forwarding are:
|
|
|
|
1. The `xt_RTPENGINE` kernel module must be loaded.
|
|
2. An `iptables` and/or `ip6tables` rule must be present in the `INPUT` chain (or in a custom user-defined
|
|
chain which is then called by the `INPUT` chain) to send packets
|
|
to the `RTPENGINE` target. This rule should be limited to UDP packets, but otherwise there
|
|
are no restrictions.
|
|
3. The `rtpengine` daemon must be running.
|
|
4. All of the above must be set up with the same forwarding table ID (see below).
|
|
|
|
The sequence of events for a newly established media stream is then:
|
|
|
|
1. The SIP proxy (e.g. *Kamailio*) controls *rtpengine* and informs it about a newly established call.
|
|
2. The `rtpengine` daemon allocates local UDP ports and sets up preliminary forward rules
|
|
based on the info received
|
|
from the SIP proxy. Only userspace forwarding is set up, nothing is pushed to the kernel module yet.
|
|
3. An RTP packet is received on the local port.
|
|
4. It traverses the *iptables* chains and gets passed to the *xt\_RTPENGINE* module.
|
|
5. The module doesn't recognize it as belonging to an established stream and thus ignores it.
|
|
6. The packet continues normal processing and eventually ends up in the daemon's receive queue.
|
|
7. The daemon reads it, processes it and forwards it. It also updates some internal data.
|
|
8. This userspace-only processing and forwarding continues for a little while, during which time information
|
|
about additional streams and/or endpoints may be obtained from the SIP proxy.
|
|
9. After a few seconds, when the daemon is satisfied with what it has learned about the media endpoints,
|
|
it pushes the forwarding rules to the kernel.
|
|
10. From this moment on, the kernel module will recognize incoming packets belonging to those streams
|
|
and will forward them on its own. It will stop those packets from traversing the network stacks any
|
|
further, so the daemon will not see them any more on its receive queues.
|
|
11. In-kernel forwarding is allowed to cease to work at any given time, either accidentally (e.g. by
|
|
removal of the *iptables* rule) or deliberately (the daemon will do so in case of a re-invite), in which
|
|
case forwarding falls back to userspace-only operation.
|
|
|
|
### The Kernel Module ###
|
|
|
|
The kernel module supports multiple forwarding tables (not to be confused with the tables managed
|
|
by *iptables*), which are identified through their ID number. By default, up to 64 forwarding tables
|
|
can be created and used, giving them the ID numbers 0 through 63.
|
|
|
|
Each forwarding table can be thought of a separate proxy instance. Each running instance of the
|
|
*rtpengine* daemon controls one such table, and each table can only be controlled by one
|
|
running instance of the daemon at any given time. In the most common setup, there will be only a single
|
|
instance of the daemon running and there will be only a single forwarding table in use, with ID zero.
|
|
|
|
The kernel module can be loaded with the command `modprobe xt_RTPENGINE`. With the module loaded, a new
|
|
directory will appear in `/proc/`, namely `/proc/rtpengine/`. After loading, the directory will contain
|
|
only two pseudo-files, `control` and `list`. The `control` file is write-only and is used to create and
|
|
delete forwarding tables, while the `list` file is read-only and will produce a list of currently
|
|
active forwarding tables. With no tables active, it will produce an empty output.
|
|
|
|
The `control` pseudo-file supports two commands, `add` and `del`, each followed by the forwarding table
|
|
ID number. To manually create a forwarding table with ID 42, the following command can be used:
|
|
|
|
echo 'add 42' > /proc/rtpengine/control
|
|
|
|
After this, the `list` pseudo-file will produce the single line `42` as output. This will also create a
|
|
directory called `42` in `/proc/rtpengine/`, which contains additional pseudo-files to control this
|
|
particular forwarding table.
|
|
|
|
To delete this forwarding table, the command `del 42` can be issued like above. This will only work
|
|
if no *rtpengine* daemon is currently running and controlling this table.
|
|
|
|
Each subdirectory `/proc/rtpengine/$ID/` corresponding to each forwarding table contains the pseudo-files
|
|
`blist`, `control`, `list` and `status`. The `control` file is write-only while the others are read-only.
|
|
The `control` file will be kept open by the *rtpengine* daemon while it's running to issue updates
|
|
to the forwarding rules during runtime. The daemon also reads the `blist` file on a regular basis, which
|
|
produces a list of currently active forwarding rules together with their stats and other details
|
|
within that table in a binary format. The same output,
|
|
but in human-readable format, can be obtained by reading the `list` file. Lastly, the `status` file produces
|
|
a short stats output for the forwarding table.
|
|
|
|
Manual creation of forwarding tables is normally not required as the daemon will do so itself, however
|
|
deletion of tables may be required after shutdown of the daemon or before a restart to ensure that the
|
|
daemon can create the table it wants to use.
|
|
|
|
The kernel module can be unloaded through `rmmod xt_RTPENGINE`, however this only works if no forwarding
|
|
table currently exists and no *iptables* rule currently exists.
|
|
|
|
### The *iptables* module ###
|
|
|
|
In order for the kernel module to be able to actually forward packets, an *iptables* rule must be set up
|
|
to send packets into the module. Each such rule is associated with one forwarding table. In the simplest case,
|
|
for forwarding table 42, this can be done through:
|
|
|
|
iptables -I INPUT -p udp -j RTPENGINE --id 42
|
|
|
|
If IPv6 traffic is expected, the same should be done using `ip6tables`.
|
|
|
|
It is possible but not strictly
|
|
necessary to restrict the rules to the UDP port range used by *rtpengine*, e.g. by supplying a parameter
|
|
like `--dport 30000:40000`. If the kernel module receives a packet that it doesn't recognize as belonging
|
|
to an active media stream, it will simply ignore it and hand it back to the network stack for normal
|
|
processing.
|
|
|
|
The `RTPENGINE` rule need not necessarily be present directly in the `INPUT` chain. It can also be in a
|
|
user-defined chain which is then referenced by the `INPUT` chain, like so:
|
|
|
|
iptables -N rtpengine
|
|
iptables -I INPUT -p udp -j rtpengine
|
|
iptables -I rtpengine -j RTPENGINE --id 42
|
|
|
|
This can be a useful setup if certain firewall scripts are being used.
|
|
|
|
Summary
|
|
-------
|
|
|
|
A typical start-up sequence including in-kernel forwarding might look like this:
|
|
|
|
# this only needs to be one once after system (re-) boot
|
|
modprobe xt_RTPENGINE
|
|
iptables -I INPUT -p udp -j RTPENGINE --id 0
|
|
ip6tables -I INPUT -p udp -j RTPENGINE --id 0
|
|
|
|
# ensure that the table we want to use doesn't exist - usually needed after a daemon
|
|
# restart, otherwise will error
|
|
echo 'del 0' > /proc/rtpengine/control
|
|
|
|
# start daemon
|
|
/usr/bin/rtpengine --table=0 --interface=10.64.73.31 --interface=2001:db8::4f3:3d \
|
|
--listen-ng=127.0.0.1:2223 --tos=184 --pidfile=/run/rtpengine.pid --no-fallback
|
|
|
|
Running Multiple Instances
|
|
--------------------------
|
|
|
|
In some cases it may be desired to run multiple instances of *rtpengine* on the same machine, for example
|
|
if the host is multi-homed and has multiple usable network interfaces with different addresses. This is
|
|
supported by running multiple instances of the daemon using different command-line options (different
|
|
local addresses and different listening ports), together with
|
|
multiple different kernel forwarding tables.
|
|
|
|
For example, if one local network interface has address 10.64.73.31 and another has address 192.168.65.73,
|
|
then the start-up sequence might look like this:
|
|
|
|
modprobe xt_RTPENGINE
|
|
iptables -I INPUT -p udp -d 10.64.73.31 -j RTPENGINE --id 0
|
|
iptables -I INPUT -p udp -d 192.168.65.73 -j RTPENGINE --id 1
|
|
|
|
echo 'del 0' > /proc/rtpengine/control
|
|
echo 'del 1' > /proc/rtpengine/control
|
|
|
|
/usr/bin/rtpengine --table=0 --interface=10.64.73.31 \
|
|
--listen-ng=127.0.0.1:2223 --tos=184 --pidfile=/run/rtpengine-10.pid --no-fallback
|
|
/usr/bin/rtpengine --table=1 --interface=192.168.65.73 \
|
|
--listen-ng=127.0.0.1:2224 --tos=184 --pidfile=/run/rtpengine-192.pid --no-fallback
|
|
|
|
With this setup, the SIP proxy can choose which instance of *rtpengine* to talk to and thus which local
|
|
interface to use by sending its control messages to either port 2223 or port 2224.
|
|
|
|
Transcoding
|
|
===========
|
|
|
|
Currently transcoding is supported for audio streams. The feature can be disabled on a compile-time
|
|
basis, and is enabled by default.
|
|
|
|
Even though the transcoding feature is available by default, it is not automatically engaged for
|
|
normal calls. Normally *rtpengine* leaves codec negotiation up to the clients involved in the call
|
|
and does not interfere. In this case, if the clients fail to agree on a codec, the call will fail.
|
|
|
|
The transcoding feature can be engaged for a call by instructing *rtpengine* to do so by using
|
|
one of the transcoding options in the *ng* control protocol, such as `transcode` or `ptime` (see below).
|
|
If a codec is requested via the `transcode` option that was not originally offered, transcoding will
|
|
be engaged for that call.
|
|
|
|
With transcoding active for a call, all unsupported codecs will be removed from the SDP. Transcoding
|
|
happens in userspace only, so in-kernel packet forwarding will not be available for transcoded codecs.
|
|
However, even if the transcoding feature has been engaged for a call, not all codecs will necessarily
|
|
end up being transcoded. Codecs that are supported by both sides will simply be passed through
|
|
transparently (unless repacketization is active). In-kernel packet forwarding will still be available
|
|
for these codecs.
|
|
|
|
The following codecs are supported by *rtpengine*:
|
|
|
|
* G.711 (a-Law and µ-Law)
|
|
* G.722
|
|
* G.723.1
|
|
* G.729
|
|
* Speex
|
|
* GSM
|
|
* iLBC
|
|
* Opus
|
|
* AMR (narrowband and wideband)
|
|
* EVS (if supplied -- see below)
|
|
|
|
Codec support is dependent on support provided by the `ffmpeg` codec libraries, which may vary from
|
|
version to version. Use the `--codecs` command line option to have *rtpengine* print a list of codecs
|
|
and their supported status. The list includes some codecs that are not listed above. Some of these
|
|
are not actual VoIP codecs (such as MP3), while others lack support for encoding by *ffmpeg* at the
|
|
time of writing (such as QCELP or ATRAC). If encoding support for these codecs becomes available
|
|
in *ffmpeg*, *rtpengine* will be able to support them.
|
|
|
|
Audio format conversion including resampling and mono/stereo up/down-mixing happens automatically
|
|
as required by the codecs involved. For example, one side could be using stereo Opus at 48 kHz
|
|
sampling rate, and the other side could be using mono G.711 at 8 kHz, and *rtpengine* will perform
|
|
the necessary conversions.
|
|
|
|
If repacketization (using the `ptime` option) is requested, the transcoding feature will also be
|
|
engaged for the call, even if no additional codecs were requested.
|
|
|
|
G.729 support
|
|
-------------
|
|
|
|
As *ffmpeg* does not currently provide an encoder for G.729, transcoding support for it is available
|
|
via the [bcg729](https://www.linphone.org/technical-corner/bcg729/) library
|
|
(mirror on [GitHub](https://github.com/BelledonneCommunications/bcg729)). The build system looks for
|
|
the *bcg729* headers in a few locations and uses the library if found. If the library is located
|
|
elsewhere, see `daemon/Makefile` to control where the build system is looking for it.
|
|
|
|
In a Debian build environment, `debian/control` lists a build-time dependency
|
|
on *bcg729*. Newer Debian releases (currently *bullseye*, *bookworm*, *sid*)
|
|
include *bcg729* as a package so nothing needs to be done there. Older Debian
|
|
releases do not currently include a *bcg729* package, but one can be built
|
|
locally using these instructions on
|
|
[GitHub](https://github.com/ossobv/bcg729-deb). *Sipwise* provides a
|
|
pre-packaged version of this as part of our [C5
|
|
CE](https://www.sipwise.com/products/class-5-softswitch-carrier-grade-for-voice-over-ip/)
|
|
product which is [available
|
|
here](https://deb.sipwise.com/spce/mr6.2.1/pool/main/b/bcg729/).
|
|
|
|
Alternatively the build dependency
|
|
can be removed from `debian/control` or by switching to a different Debian build profile.
|
|
Set the environment variable
|
|
`export DEB_BUILD_PROFILES="pkg.ngcp-rtpengine.nobcg729"` (or use the `-P` flag to the *dpkg* tools)
|
|
and then build the *rtpengine* packages.
|
|
|
|
DTMF transcoding
|
|
----------------
|
|
|
|
*Rtpengine* supports transcoding between RFC 2833/4733 DTMF event packets (`telephone-event` payloads)
|
|
and in-band DTMF audio tones. When enabled, *rtpengine* translates DTMF event packets to in-band DTMF
|
|
audio by generating DTMF tones and injecting them into the audio stream, and translates in-band DTMF
|
|
tones by running the audio stream through a DSP, and generating DTMF event packets when a DTMF tone
|
|
is detected.
|
|
|
|
Support for DTMF transcoding can be enabled in one of two ways:
|
|
|
|
* In the forward direction, DTMF transcoding is enabled by adding the codec `telephone-event` to the
|
|
list of codecs offered for transcoding. Specifically, if the incoming SDP body doesn't yet list
|
|
`telephone-event` as a supported codec, adding the option *codec → transcode → telephone-event* would
|
|
enable DTMF transcoding. The receiving RTP client can then accept this codec and start sending DTMF
|
|
event packets, which *rtpengine* would translate into in-band DTMF audio. If the receiving RTP client
|
|
also offers `telephone-event` in their behalf, *rtpengine* would then detect in-band DTMF audio coming
|
|
from the originating RTP client and translate it to DTMF event packets.
|
|
|
|
* In the reverse direction, DTMF transcoding is enabled by adding the option `always transcode` to the
|
|
`flags` if the incoming SDP body offers `telephone-event` as a supported codec. If the receiving RTP
|
|
client then rejects the offered `telephone-event` codec, DTMF transcoding is then enabled and is
|
|
performed in the same way as described above.
|
|
|
|
Enabling DTMF transcoding (in one of the two ways described above) implicitly enables the flag
|
|
`always transcode` for the call and forces all of the audio to pass through the transcoding engine.
|
|
Therefore, for performance reasons, this should only be done when really necessary.
|
|
|
|
T.38
|
|
----
|
|
*Rtpengine* can translate between fax endpoints that speak T.38 over UDPTL and fax endpoints that speak
|
|
T.30 over regular audio channels. Any audio codec can theoretically be used for T.30 transmissions, but
|
|
codecs that are too compressed will make the fax transmission fail. The most commonly used audio codecs
|
|
for fax are the G.711 codecs (`PCMU` and `PCMA`), which are the default codecs *rtpengine* will use in
|
|
this case if no other codecs are specified.
|
|
|
|
For further information, see the section on the `T.38` dictionary key below.
|
|
|
|
AMR and AMR-WB
|
|
--------------
|
|
|
|
As AMR supports dynamically adapting the encoder bitrate, as well as restricting the available bitrates,
|
|
there are some slight peculiarities about its usage when transcoding.
|
|
|
|
When setting the bitrate, for example as `AMR-WB/16000/1/23850` in either the `codec-transcode` or the
|
|
`codec-set` options, that bitrate will be used as the highest permitted bitrate for the encoder. If
|
|
no `mode-set` parameter is communicated in the SDP, then that is the bitrate that will be used.
|
|
|
|
If a `mode-set` is present, then the highest bitrate from that mode set which is lower or equal to the
|
|
given bitrate will be used. If only higher bitrates are allowed by the mode set, then the next higher
|
|
bitrate will be used.
|
|
|
|
To produce an SDP that includes the `mode-set` option (when adding AMR to the codec list via
|
|
`codec-transcode`), the full format parameter string can be appended to the codec specification, e.g.
|
|
`codec-transcode-AMR-WB/16000/1/23850//mode-set=0,1,2,3,4,5;octet-align=1`. In this example, the bitrate
|
|
23850 won't actually be used, as the highest permitted mode is 5 (18250 bps) and so that bitrate will
|
|
be used.
|
|
|
|
If a literal `=` cannot be used due to parsing constraints (i.e. being wrongly interpreted as a
|
|
key-value pair), it can be escaped by using two dashes instead, e.g.
|
|
`codec-transcode-AMR-WB/16000/1/23850//mode-set--0,1,2,3,4,5;octet-align--1`
|
|
|
|
The default (highest) bitrates for AMR and AMR-WB are 6700 and 14250, respectively.
|
|
|
|
If a Codec Mode Request (CMR) is received from the AMR peer, then *rtpengine* will adhere to the request
|
|
and switch encoder bitrate unconditionally, even if it's a higher bitrate than originally desired.
|
|
|
|
To enable sending CMRs to the AMR peer, the codec-specific option `CMR-interval` is provided. It takes
|
|
a number of milliseconds as argument. Throughout each interval, *rtpengine* will track which AMR frame
|
|
types were received from the peer, and then based on that will make a decision at the end of the
|
|
interval. If a higher bitrate is allowed by the mode set that was not received from the AMR peer at all,
|
|
then *rtpengine* will request switching to that bitrate per CMR. Only the next-highest bitrate mode that
|
|
was not received will ever be requested, and a CMR will be sent only once per interval. Full example to
|
|
specify a CMR interval of 500 milliseconds (with `=` escapes):
|
|
`codec-transcode-AMR-WB/16000/1/23850//mode-set--0,1,2/CMR-interval--500`
|
|
|
|
Similar to the `CMR-interval` option, *rtpengine* can optionally attempt to periodically increase the
|
|
outgoing bitrate without being requested to by the peer via a CMR. To enable this, set the option
|
|
`mode-change-interval` to the desired interval in milliseconds. If the last CMR from the AMR peer was
|
|
longer than this interval ago, *rtpengine* will increase the bitrate by one step if possible. Afterwards,
|
|
the interval starts over.
|
|
|
|
EVS
|
|
---
|
|
|
|
Enhanced Voice Services (EVS) is a patent-encumbered codec for which (at the
|
|
time of writing) no implementation exists which can be freely used and
|
|
distributed. As such, support for EVS is only available if an implementation is
|
|
supplied separately. Currently the only implementation supported is the
|
|
ETSI/3GPP reference implementation (either floating-point or fixed-point). Any
|
|
licensing issues that might result from such usage are the responsibility of
|
|
the user of this software.
|
|
|
|
The EVS codec implementation can be provided as a shared object library (*.so*)
|
|
which is loaded in during runtime (at startup). The supported implementations
|
|
can be seen as subdirectories within the `evs/` directory. Currently supported
|
|
are version 17.0.0 of the ETSI/3GPP reference implementation, [*126.442*](https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=1464) for the
|
|
fixed-point implementation and [*126.443*](https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=1465) for the floating-point implementation.
|
|
(The floating-point implementation seems to be significantly faster, but is not
|
|
bit-precise.)
|
|
|
|
To supply the codec implementation as a shared object during runtime, extract
|
|
the reference implementation's *.zip* file and apply the provided `patch`
|
|
([from here](https://github.com/sipwise/rtpengine/tree/master/evs)) that is
|
|
appropriate for the chosen implementation. Run the build using `make`
|
|
(suggested build flags are `RELEASE=1 make`) and it should produce a file
|
|
`lib3gpp-evs.so`. Point *rtpengine* to this file using the `evs-lib-path=`
|
|
option to enable support for EVS.
|
|
|
|
Call recording
|
|
==============
|
|
|
|
Call recording can be accomplished in one of two ways:
|
|
|
|
* The *rtpengine* daemon can write `libpcap`-formatted captures directly (`--recording-method=pcap`);
|
|
|
|
* The *rtpengine* daemon can write audio frames into a sink in `/proc/rtpengine` (`--recording-method=proc`). These frames must then be consumed within a short period by another process; while this can be any process, the packaged `rtpengine-recording` daemon is a useful ready implementation of a call recording solution. The recording daemon uses `ffmpeg` libraries to implement a variety of on-the-fly format conversion and mixing options, as well as metadata logging. See `rtpengine-recording -h` for details.
|
|
|
|
**Important note**: The *rtpengine* daemon emits data into a "spool directory" (`--recording-dir` option), by default `/var/spool/rtpengine`. The recording daemon is then configured to consume this using the `--spool-dir` option, and to store the final emitted recordings (in whatever desired target format, etc.) in `--output-dir`. Ensure that the `--spool-dir` and the `--output-dir` are **different** directories, or you will run into problems (as discussed in [#81](https://github.com/sipwise/rtpengine/issues/808)).
|
|
|
|
The *ng* Control Protocol
|
|
=========================
|
|
|
|
In order to enable several advanced features in *rtpengine*, a new advanced
|
|
control protocol has been devised which passes the complete SDP body from the
|
|
SIP proxy to the *rtpengine* daemon, has the body rewritten in the daemon, and
|
|
then passed back to the SIP proxy to embed into the SIP message.
|
|
|
|
This control protocol is supported over a number of different transports (plain
|
|
UDP, plain TCP, HTTP, WebSocket) and loosely follows the same format as used by
|
|
*Kamailio*'s *rtpproxy* module. Each message passed between the SIP proxy and
|
|
the media proxy contains of two parts: a unique message cookie and a dictionary
|
|
document, separated by a single space. The message cookie is used to match
|
|
requests to responses and to detect retransmissions. The message cookie in the
|
|
response generated to a particular request therefore must be the same as in the
|
|
request.
|
|
|
|
The dictionary document can be in one of two formats. It can be a JSON object
|
|
or it can be a dictionary in [bencode](http://en.wikipedia.org/wiki/Bencode)
|
|
format. *Bencoding* supports a subset of the features of JSON
|
|
(dictionaries/hashes, lists/arrays, arbitrary byte strings) but offers some
|
|
benefits over JSON encoding, e.g. simpler and more efficient encoding, less
|
|
encoding overhead, deterministic encoding and faster encoding and decoding.
|
|
Disadvantages compared to JSON are that it's not a readily human readable
|
|
format and that support in programming languages might be difficult to come by.
|
|
Internally *rtpengine* uses *bencoding* natively, leading to additional
|
|
overhead when JSON is in use as it has to be converted.
|
|
|
|
The dictionary of each request must contain at least one key called `command`. The corresponding value must be
|
|
a string and determines the type of message. Currently the following commands are defined:
|
|
|
|
* ping
|
|
* offer
|
|
* answer
|
|
* delete
|
|
* query
|
|
* start recording
|
|
* stop recording
|
|
* block DTMF
|
|
* unblock DTMF
|
|
* block media
|
|
* unblock media
|
|
* silence media
|
|
* unsilence media
|
|
* start forwarding
|
|
* stop forwarding
|
|
* play media
|
|
* stop media
|
|
* play DTMF
|
|
* statistics
|
|
* publish
|
|
* subscribe request
|
|
* subscribe answer
|
|
* unsubscribe
|
|
|
|
The response dictionary must contain at least one key called `result`. The value can be either `ok` or `error`.
|
|
For the `ping` command, the additional value `pong` is allowed. If the result is `error`, then another key
|
|
`error-reason` must be given, containing a string with a human-readable error message. No other keys should
|
|
be present in the error case. If the result is `ok`, the optional key `warning` may be present, containing a
|
|
human-readable warning message. This can be used for non-fatal errors.
|
|
|
|
For readability, all data objects below are represented in a JSON-like notation and without the message cookie.
|
|
For example, a `ping` message and its corresponding `pong` reply would be written as:
|
|
|
|
{ "command": "ping" }
|
|
{ "result": "pong" }
|
|
|
|
While the actual messages as encoded on the wire, including the message cookie,
|
|
might look like this in *bencode* format:
|
|
|
|
5323_1 d7:command4:pinge
|
|
5323_1 d6:result4:ponge
|
|
|
|
All keys and values are case-sensitive unless specified otherwise. The requirement stipulated by the *bencode*
|
|
standard that dictionary keys must be present in lexicographical order is not currently honoured.
|
|
|
|
The *ng* protocol is used by *Kamailio*'s *rtpengine* module, which is based on
|
|
the older module called *rtpproxy-ng*, and utilises *bencoding* and the UDP
|
|
transport by default, or alternatively WebSocket if so configured.
|
|
|
|
Of course the agent controlling *rtpengine* via the *ng* protocol does not have
|
|
to be a SIP proxy. Any process that involves SDP can potentially talk to
|
|
*rtpengine* via this protocol.
|
|
|
|
`ping` Message
|
|
--------------
|
|
|
|
The request dictionary contains no other keys and the reply dictionary also contains no other keys. The
|
|
only valid value for `result` is `pong`.
|
|
|
|
`offer` Message
|
|
---------------
|
|
|
|
The request dictionary must contain at least the following keys:
|
|
|
|
* `sdp`
|
|
|
|
Contains the complete SDP body as string.
|
|
|
|
* `call-id`
|
|
|
|
The SIP call ID as string.
|
|
|
|
* `from-tag`
|
|
|
|
The SIP `From` tag as string.
|
|
|
|
Optionally included keys are:
|
|
|
|
* `from-tags`
|
|
|
|
Contains a list of strings used to selected multiple existing call
|
|
participants (e.g. for the `subscribe request` message). An alternative
|
|
way to list multiple tags is by putting them into the `flags` list,
|
|
each prefixed with `from-tags-`.
|
|
|
|
* `via-branch`
|
|
|
|
The SIP `Via` branch as string. Used to additionally refine the matching logic between media streams
|
|
and calls and call branches.
|
|
|
|
* `label` or `from-label`
|
|
|
|
A custom free-form string which *rtpengine* remembers for this participating endpoint and reports
|
|
back in logs and statistics output. For some commands (e.g. `block media`) the given label is not
|
|
used to set the label of the call participant, but rather to select an existing call participant.
|
|
|
|
* `set-label`
|
|
|
|
Some commands (e.g. `block media`) use the given `label` to select
|
|
an existing call participant. For these commands, `set-label` instead
|
|
of `label` can be used to set the label at the same time, either for
|
|
the selected call participant (if selected via `from-tag`) or for the
|
|
newly created participant (e.g. for `subscribe request`).
|
|
|
|
* `to-label`
|
|
|
|
Commands that allow selection of two call participants (e.g. `block
|
|
media`) can use `label` instead of `from-tag` to select the first call
|
|
participant. The `to-label` can then be used instead of `to-tag` to
|
|
select the other call participant.
|
|
|
|
For `subscribe request` the `to-label` is synonymous with `set-label`.
|
|
|
|
* `flags`
|
|
|
|
The value of the `flags` key is a list. The list contains zero or more of the following strings.
|
|
Spaces in each string may be replaced by hyphens.
|
|
|
|
- `SIP source address`
|
|
|
|
Ignore any IP addresses given in the SDP body and use the source address of the received
|
|
SIP message (given in `received from`) as default endpoint address. This was the default
|
|
behaviour of older versions of *rtpengine* and can still be made the default behaviour
|
|
through the `--sip-source` CLI switch.
|
|
Can be overridden through the `media address` key.
|
|
|
|
- `trust address`
|
|
|
|
The opposite of `SIP source address`. This is the default behaviour unless the CLI switch
|
|
`--sip-source` is active. Corresponds to the *rtpproxy* `r` flag.
|
|
Can be overridden through the `media address` key.
|
|
|
|
- `symmetric`
|
|
|
|
Corresponds to the *rtpproxy* `w` flag. Not used by *rtpengine* as this is the default,
|
|
unless `asymmetric` is specified.
|
|
|
|
- `asymmetric`
|
|
|
|
Corresponds to the *rtpproxy* `a` flag. Advertises an RTP endpoint which uses asymmetric
|
|
RTP, which disables learning of endpoint addresses (see below).
|
|
|
|
- `unidirectional`
|
|
|
|
When this flag is present, kernelize also one-way rtp media.
|
|
|
|
- `strict source`
|
|
|
|
Normally, *rtpengine* attempts to learn the correct endpoint address for every stream during
|
|
the first few seconds after signalling by observing the source address and port of incoming
|
|
packets (unless `asymmetric` is specified). Afterwards, source address and port of incoming
|
|
packets are normally ignored and packets are forwarded regardless of where they're coming from.
|
|
With the `strict source` option set, *rtpengine* will continue to inspect the source address
|
|
and port of incoming packets after the learning phase and compare them with the endpoint
|
|
address that has been learned before. If there's a mismatch, the packet will be dropped and
|
|
not forwarded.
|
|
|
|
- `media handover`
|
|
|
|
Similar to the `strict source` option, but instead of dropping packets when the source address
|
|
or port don't match, the endpoint address will be re-learned and moved to the new address. This
|
|
allows endpoint addresses to change on the fly without going through signalling again. Note that
|
|
this opens a security hole and potentially allows RTP streams to be hijacked, either partly or
|
|
in whole.
|
|
|
|
- `reset`
|
|
|
|
This causes *rtpengine* to un-learn certain aspects of the RTP endpoints involved, such as
|
|
support for ICE or support for SRTP. For example, if `ICE=force` is given, then *rtpengine*
|
|
will initially offer ICE to the remote endpoint. However, if a subsequent answer from that
|
|
same endpoint indicates that it doesn't support ICE, then no more ICE offers will be made
|
|
towards that endpoint, even if `ICE=force` is still specified. With the `reset` flag given,
|
|
this aspect will be un-learned and *rtpengine* will again offer ICE to this endpoint.
|
|
This flag is valid only in an `offer` message and is useful when the call has been
|
|
transferred to a new endpoint without change of `From` or `To` tags.
|
|
|
|
- `port latching`
|
|
|
|
Forces *rtpengine* to retain its local ports during a signalling exchange even when the
|
|
remote endpoint changes its port.
|
|
|
|
- `no port latching`
|
|
|
|
Port latching is enabled by default for endpoints which speak
|
|
ICE. With this option preset, a remote port change will result
|
|
in a local port change even for endpoints which speak ICE,
|
|
which will imply an ICE restart.
|
|
|
|
- `record call`
|
|
|
|
Identical to setting `record call` to `on` (see below).
|
|
|
|
- `no rtcp attribute`
|
|
|
|
Omit the `a=rtcp` line from the outgoing SDP.
|
|
|
|
- `full rtcp attribute`
|
|
|
|
Include the full version of the `a=rtcp` line (complete with network address) instead of
|
|
the short version with just the port number.
|
|
|
|
- `loop protect`
|
|
|
|
Inserts a custom attribute (`a=rtpengine:...`) into the outgoing SDP to prevent *rtpengine*
|
|
processing and rewriting the same SDP multiple times. This is useful if your setup
|
|
involves signalling loops and need to make sure that *rtpengine* doesn't start looping
|
|
media packets back to itself. When this flag is present and *rtpengine* sees a matching
|
|
attribute already present in the SDP, it will leave the SDP untouched and not process
|
|
the message.
|
|
|
|
- `always transcode`
|
|
|
|
Legacy flag, synonymous to `codec-accept=all`.
|
|
|
|
- `single codec`
|
|
|
|
Using this flag in an `answer` message will leave only the first listed codec in place
|
|
and will remove all others from the list. Useful for RTP clients which get confused if
|
|
more than one codec is listed in an answer.
|
|
|
|
- `reuse codecs` or `no codec renegotiation`
|
|
|
|
Instructs *rtpengine* to prevent endpoints from switching codecs during call run-time
|
|
if possible. Codecs that were listed as preferred in the past will be kept as preferred
|
|
even if the re-offer lists other codecs as preferred, or in a different order. Recommended
|
|
to be combined with `single codec`.
|
|
|
|
- `allow transcoding`
|
|
|
|
This flag is only useful in commands that provide an explicit answer SDP to *rtpengine*
|
|
(e.g. `subscribe answer`). For these commands, if the answer SDP does not accept all
|
|
codecs that were offered, the default behaviour is to reject the answer. With this flag
|
|
given, the answer will be accepted even if some codecs were rejected, and codecs will be
|
|
transcoded as required.
|
|
|
|
- `all`
|
|
|
|
Synonymous to `all=all` (see below).
|
|
|
|
- `pad crypto`
|
|
|
|
Legacy alias to SDES=pad.
|
|
|
|
- `generate mid`
|
|
|
|
Add `a=mid` attributes to the outgoing SDP if they were not already present.
|
|
|
|
- `strip extmap`
|
|
|
|
Remove `a=rtpmap` attributes from the outgoing SDP.
|
|
|
|
- `original sendrecv`
|
|
|
|
With this flag present, *rtpengine* will leave the media direction attributes
|
|
(`sendrecv`, `recvonly`, `sendonly`, and `inactive`) from the received SDP body
|
|
unchanged. Normally *rtpengine* would consume these attributes and insert its
|
|
own version of them based on other media parameters (e.g. a media section with
|
|
a zero IP address would come out as `sendonly` or `inactive`).
|
|
|
|
- `inject DTMF`
|
|
|
|
Signals to *rtpengine* that the audio streams involved in this `offer` or `answer`
|
|
(the flag should be present in both of them) are to be made available for DTMF
|
|
injection via the `play DTMF` control message. See `play DTMF` below for additional
|
|
information.
|
|
|
|
- `detect DTMF`
|
|
|
|
When present in a message that sets up codec handlers, enables
|
|
the DSP to detect in-band DTMF audio tones even when it
|
|
wouldn't otherwise be necessary.
|
|
|
|
- `generate RTCP`
|
|
|
|
Identical to setting `generate RTCP = on`.
|
|
|
|
- `RTCP mirror`
|
|
|
|
Useful only for `subscribe request` message. Instructs
|
|
*rtpengine* to not only create a one-way subscription for both
|
|
RTP and RTCP from the source to the sink, but also create a
|
|
reverse subscription for RTCP only from the sink back to the
|
|
source. This makes it possible for the media source to receive
|
|
feedback from all media receivers (sinks).
|
|
|
|
- `debug` or `debugging`
|
|
|
|
Enabled full debug logging for this call, regardless of global log level settings.
|
|
|
|
- `pierce NAT`
|
|
|
|
Sends empty UDP packets to the remote RTP peer as soon as an
|
|
endpoint address is available from a received SDP, for as long
|
|
as no incoming packets have been received. Useful to create an
|
|
initial NAT mapping. Not needed when ICE is in use.
|
|
|
|
- `NAT-wait`
|
|
|
|
Prevents forwarding media packets to the respective endpoint
|
|
until at least one media packet has been received from that
|
|
endpoint. This is to allow a NAT binding to open in the ingress
|
|
direction before sending packets out, which could result in an
|
|
automated firewall block.
|
|
|
|
- `trickle ICE`
|
|
|
|
Useful for `offer` messages when ICE is advertised to also advertise
|
|
support for trickle ICE.
|
|
|
|
- `reject ICE`
|
|
|
|
Useful for `offer` messages that advertise support for ICE.
|
|
Instructs *rtpengine* to reject the offered ICE. This is
|
|
similar to using `ICE=remove` in the respective `answer`.
|
|
|
|
* `generate RTCP`
|
|
|
|
Contains a string, either `on` or `off`. If enabled for a call,
|
|
received RTCP packets will not simply be passed through as usual, but
|
|
instead will be consumed, and instead *rtpengine* will generate its own
|
|
RTCP packets to send to the RTP peers. This flag will be effective for
|
|
both sides of a call.
|
|
|
|
* `replace`
|
|
|
|
Similar to the `flags` list. Controls which parts of the SDP body should be rewritten.
|
|
Contains zero or more of:
|
|
|
|
- `origin`
|
|
|
|
Replace the address found in the *origin* (o=) line of the SDP body. Corresponds
|
|
to *rtpproxy* `o` flag.
|
|
|
|
- `session connection` or `session-connection`
|
|
|
|
Replace the address found in the *session-level connection* (c=) line of the SDP body.
|
|
Corresponds to *rtpproxy* `c` flag.
|
|
|
|
- `SDP version` or `SDP-version`
|
|
|
|
Take control of the version field in the SDP and make sure it's increased every
|
|
time the SDP changes, and left unchanged if the SDP is the same.
|
|
|
|
- `force-increment-sdp-ver`
|
|
|
|
Force increasing the SDP version, even if the SDP hasn't been changed.
|
|
|
|
- `username`
|
|
|
|
Take control of the origin username field in the SDP. With this
|
|
option in use, *rtpengine* will make sure the username field in
|
|
the `o=` line always remains the same in all SDPs going to a
|
|
particular RTP endpoint.
|
|
|
|
- `session name` or `session-name`
|
|
|
|
Same as `username` but for the entire contents of the `s=` line.
|
|
|
|
- `zero address`
|
|
|
|
Using a zero endpoint address is an obsolete way to signal a
|
|
muted or sendonly stream. Streams with zero addresses are
|
|
normally flagged as sendonly and the zero address in the SDP is
|
|
passed through. With this option set, the zero address is
|
|
replaced with a real address.
|
|
|
|
* `direction`
|
|
|
|
Contains a list of two strings and corresponds to the *rtpproxy* `e` and `i` flags. Each element must
|
|
correspond to one of the named logical interfaces configured on the
|
|
command line (through `--interface`). For example, if there is one logical interface named `pub` and
|
|
another one named `priv`, then if side A (originator of the message) is considered to be
|
|
on the private network and side B (destination of the message) on the public network, then that would
|
|
be rendered within the dictionary as:
|
|
|
|
{ ..., "direction": [ "priv", "pub" ], ... }
|
|
|
|
This only needs to be done for an initial `offer`; for the `answer` and any subsequent offers (between
|
|
the same endpoints) *rtpengine* will remember the selected network interface.
|
|
|
|
As a special case to support legacy usage of this option, if the given interface names are
|
|
`internal` or `external` and if no such interfaces have been configured, then they're understood as
|
|
selectors between IPv4 and IPv6 addresses.
|
|
However, this mechanism for selecting the address family is now obsolete
|
|
and the `address family` dictionary key should be used instead.
|
|
|
|
For legacy support, the special direction keyword `round-robin-calls` can be used to invoke the
|
|
round-robin interface selection algorithm described in the section *Interfaces configuration*.
|
|
If this special keyword is used, the round-robin selection will run over all configured
|
|
interfaces, whether or not they are configured using the `BASE:SUFFIX` interface name notation.
|
|
This special keyword is provided only for legacy support and should be considered obsolete.
|
|
It will be removed in future versions.
|
|
|
|
* `interface`
|
|
|
|
Contains a single string naming one of the configured interfaces, just like `direction` does. The
|
|
`interface` option is used instead of `direction` where only one interface is required (e.g. outside
|
|
of an offer/answer scenario), for example in the `publish` or `subscribe request` commands.
|
|
|
|
* `received from`
|
|
|
|
Contains a list of exactly two elements. The first element denotes the address family and the second
|
|
element is the SIP message's source address itself. The address family can be one of `IP4` or `IP6`.
|
|
Used if SDP addresses are neither trusted (through `SIP source address` or `--sip-source`) nor the
|
|
`media address` key is present.
|
|
|
|
* `drop-traffic`
|
|
|
|
Contains a string, valid values are `start` or `stop`.
|
|
|
|
`start` signals to *rtpengine* that all RTP involved in this call is dropped.
|
|
Can be present either in `offer` or `answer`, the behavior is for the entire call.
|
|
|
|
`stop` signals to *rtpengine* that all RTP involved in this call is NOT dropped anymore.
|
|
Can be present either in `offer` or `answer`, the behavior is for the entire call.
|
|
|
|
`stop` has priority over `start`, if both are present.
|
|
|
|
* `ICE`
|
|
|
|
Contains a string which must be one of the following values:
|
|
|
|
With `remove`, any ICE attributes are stripped from the SDP body. Also
|
|
see the flag `reject ICE` to effect an early removal of ICE support
|
|
during an `offer`.
|
|
|
|
With `force`, ICE attributes are first stripped, then new attributes are
|
|
generated and inserted, which leaves the media proxy as the only ICE candidate.
|
|
|
|
With `default`, the behaviour will be the same as with `force` if the incoming SDP already
|
|
had ICE attributes listed. If the incoming SDP did not contain ICE attributes, then no
|
|
ICE attributes are added.
|
|
|
|
With `force-relay`, existing ICE candidates are left in place except `relay`
|
|
type candidates, and *rtpengine* inserts itself as a `relay` candidate. It will also leave SDP
|
|
c= and m= lines unchanged.
|
|
|
|
With `optional`, if no ICE attributes are present, a new set is generated and the
|
|
media proxy lists itself as ICE candidate; otherwise, the media proxy inserts itself as a
|
|
low-priority candidate. This used to be the default behaviour in previous versions of
|
|
*rtpengine*.
|
|
|
|
The default behaviour (no `ICE` key present at all) is the same as `default`.
|
|
|
|
This flag operates independently of the `replace` flags.
|
|
|
|
Note that if config parameter `save-interface-ports = true`, ICE will be broken, because
|
|
rtpengine will bind ports only on the first local interface of desired family of logical interface.
|
|
|
|
* `ICE-lite`
|
|
|
|
Contains a string which must be one of the following values:
|
|
|
|
- `forward` to enable "ICE lite" mode towards the peer that this offer is sent to.
|
|
|
|
- `backward` to enable "ICE lite" mode towards the peer that has sent this offer.
|
|
|
|
- `both` to enable "ICE lite" towards both peers.
|
|
|
|
- `off` to disable "ICE lite" towards both peers and revert to full ICE support.
|
|
|
|
The default (keyword not present at all) is to use full ICE support, or to leave the previously
|
|
set "ICE lite" mode unchanged. This keyword is valid in `offer` messages only.
|
|
|
|
* `transport protocol`
|
|
|
|
The transport protocol specified in the SDP body is to be rewritten to the string value given here.
|
|
The media
|
|
proxy will expect to receive this protocol on the allocated ports, and will talk this protocol when
|
|
sending packets out. Translation between different transport protocols will happen as necessary.
|
|
|
|
Valid values are: `RTP/AVP`, `RTP/AVPF`, `RTP/SAVP`, `RTP/SAVPF`.
|
|
|
|
Additionally the string `accept` can be given in `answer` messages to allow a special case: By
|
|
default (when no `transport-protocol` override is given) in answer messages, *rtpengine* will
|
|
use the transport protocol that was originally offered. However, an answering client may answer
|
|
with a different protocol than what was offered (e.g. offer was for `RTP/AVP` and answer comes
|
|
with `RTP/AVPF`). The default behaviour for *rtpengine* is to ignore this protocol change and
|
|
still proceed with the protocol that was originally offered. Using the `accept` option here
|
|
tells *rtpengine* to go along with this protocol change and pass it to the original offerer.
|
|
|
|
* `media address`
|
|
|
|
This can be used to override both the addresses present in the SDP body
|
|
and the `received from` address. Contains either an IPv4 or an IPv6 address, expressed as a simple
|
|
string. The format must be dotted-quad notation for IPv4 or RFC 5952 notation for IPv6.
|
|
It's up to the RTP proxy to determine the address family type.
|
|
|
|
* `address family`
|
|
|
|
A string value of either `IP4` or `IP6` to select the primary address family in the substituted SDP
|
|
body. The default is to auto-detect the address family if possible (if the receiving end is known
|
|
already) or otherwise to leave it unchanged.
|
|
|
|
* `rtcp-mux`
|
|
|
|
A list of strings controlling the behaviour regarding rtcp-mux (multiplexing RTP and RTCP on a single
|
|
port, RFC 5761). The default behaviour is to go along with the client's preference. The list can contain
|
|
zero of more of the following strings. Note that some of them are mutually exclusive.
|
|
|
|
- `offer`
|
|
|
|
Instructs *rtpengine* to always offer rtcp-mux, even if the client itself doesn't offer it.
|
|
|
|
- `require`
|
|
|
|
Similar to `offer` but pretends that the receiving client has already accepted rtcp-mux.
|
|
The effect is that no separate RTCP ports will be advertised, even in an initial offer
|
|
(which is against RFC 5761). This option is provided to talk to WebRTC clients.
|
|
|
|
- `demux`
|
|
|
|
If the client is offering rtcp-mux, don't offer it to the other side, but accept it back to
|
|
the offering client.
|
|
|
|
- `accept`
|
|
|
|
Instructs *rtpengine* to accept rtcp-mux and also offer it to the other side if it has been
|
|
offered.
|
|
|
|
- `reject`
|
|
|
|
Reject rtcp-mux if it has been offered. Can be used together with `offer` to achieve the opposite
|
|
effect of `demux`.
|
|
|
|
* `TOS`
|
|
|
|
Contains an integer. If present, changes the TOS value for the entire call, i.e. the TOS value used
|
|
in outgoing RTP packets of all RTP streams in all directions. If a negative value is used, the previously
|
|
used TOS value is left unchanged. If this key is not present or its value is too large (256 or more), then
|
|
the TOS value is reverted to the default (as per `--tos` command line).
|
|
|
|
* `DTLS`
|
|
|
|
Contains a string and influences the behaviour of DTLS-SRTP. Possible values are:
|
|
|
|
- `off` or `no` or `disable`
|
|
|
|
Prevents *rtpengine* from offering or acceping DTLS-SRTP when otherwise it would. The default
|
|
is to offer DTLS-SRTP when encryption is desired and to favour it over SDES when accepting
|
|
an offer.
|
|
|
|
- `passive`
|
|
|
|
Instructs *rtpengine* to prefer the passive (i.e. server) role for the DTLS
|
|
handshake. The default is to take the active (client) role if possible. This is useful in cases
|
|
where the SRTP endpoint isn't able to receive or process the DTLS handshake packets, for example
|
|
when it's behind NAT or needs to finish ICE processing first.
|
|
|
|
- `active`
|
|
|
|
Reverts the `passive` setting. Only useful if the `dtls-passive` config option is set.
|
|
|
|
* `DTLS-reverse`
|
|
|
|
Contains a string and influences the behaviour of DTLS-SRTP. Unlike the regular `DTLS` flag, this one
|
|
is used to control behaviour towards DTLS that was offered to *rtpengine*. In particular, if `passive`
|
|
mode is used, it prevents *rtpengine* from prematurely sending active DTLS connection attempts.
|
|
Possible values are:
|
|
|
|
- `passive`
|
|
|
|
Instructs *rtpengine* to prefer the passive (i.e. server) role for the DTLS
|
|
handshake. The default is to take the active (client) role if possible. This is useful in cases
|
|
where the SRTP endpoint isn't able to receive or process the DTLS handshake packets, for example
|
|
when it's behind NAT or needs to finish ICE processing first.
|
|
|
|
- `active`
|
|
|
|
Reverts the `passive` setting. Only useful if the `dtls-passive` config option is set.
|
|
|
|
* `DTLS-fingerprint`
|
|
|
|
Contains a string and is used to select the hashing function to generate the DTLS fingerprint
|
|
from the certificate. The default is SHA-256, or the same hashing function as was used by the
|
|
peer. Available are `SHA-1`, `SHA-224`, `SHA-256`, `SHA-384`, and `SHA-512`.
|
|
|
|
* `SDES`
|
|
|
|
A list of strings controlling the behaviour regarding SDES. The default is to offer SDES without any
|
|
session parameters when encryption is desired, and to accept it when DTLS-SRTP is unavailable. If two
|
|
SDES endpoints are connected to each other, then the default is to offer SDES with the same options
|
|
as were received from the other endpoint. Additionally, all other supported SDES crypto suites are
|
|
added to the outgoing offer by default.
|
|
|
|
These options can also be put into the `flags` list using a prefix of `SDES-`. All options controlling
|
|
SDES session parameters can be used either in all lower case or in all upper case.
|
|
|
|
- `off` or `no` or `disable`
|
|
|
|
Prevents *rtpengine* from offering SDES, leaving DTLS-SRTP as the other option.
|
|
|
|
- `unencrypted_srtp`, `unencrypted_srtcp` and `unauthenticated_srtp`
|
|
|
|
Enables the respective SDES session parameter (see section 6.3 or RFC 4568). The default is to
|
|
copy these options from the offering client, or not to have them enabled if SDES wasn't offered.
|
|
|
|
- `encrypted_srtp`, `encrypted_srtcp` and `authenticated_srtp`
|
|
|
|
Negates the respective option. This is useful if one of the session parameters was offered by
|
|
an SDES endpoint, but it should not be offered on the far side if this endpoint also speaks SDES.
|
|
|
|
- `no-`*SUITE*
|
|
|
|
Exclude individual crypto suites from being included in the offer. For example,
|
|
`no-NULL_HMAC_SHA1_32` would exclude the crypto suite `NULL_HMAC_SHA1_32` from
|
|
the offer. This has two effects: if a given crypto suite was present in a received
|
|
offer, it will be removed and will be missing in the outgoing offer; and if a given crypto
|
|
suite was not present in the received offer, it will not be added to it.
|
|
|
|
*Remark: if after applying the policies to the processed offer, there are no crypto suites left,*
|
|
*which can be used later in the answer towards the offerer, then RTPEngine will intentionally*
|
|
*leave the top most one offered, for the answer towards the originator.*
|
|
*However it will be not used for the recipient.*
|
|
|
|
- `only-`*SUITE*
|
|
|
|
Add only these individual crypto suites and none of the others. For example,
|
|
`only-NULL_HMAC_SHA1_32` would only accept the crypto suite `NULL_HMAC_SHA1_32` for
|
|
the offer being generated. This takes precedence over the `SDES-no-` flag(s),
|
|
if used together, so the `SDES-no` will be not taken into account.
|
|
This has two effects: if a given crypto suite was present in a received offer, it will
|
|
be kept, so will be present in the outgoing offer; and if a given crypto suite was not
|
|
present in the received offer, it will be added to it. The rest, which is not mentioned,
|
|
will be dropped/not added.
|
|
|
|
*Remark: if after applying the policies to the processed offer, there are no crypto suites left,*
|
|
*which can be used later in the answer towards the offerer, then RTPEngine will intentionally*
|
|
*leave the top most one offered, for the answer towards the originator.*
|
|
*However it will be not used for the recipient.*
|
|
|
|
- `nonew`
|
|
|
|
Don't add any new crypto suites into the offer. This means, offered SDES crypto suites
|
|
will accepted, meanwhile no new is going to be generated by RTPEngine.
|
|
It takes precedence over the `SDES-no` and `SDES-only` flags, if used in combination.
|
|
|
|
- `order:`*SUITES LIST*
|
|
|
|
The order, in which crypto suites are being added to the SDP.
|
|
Example: `SDES-order:AES_256_CM_HMAC_SHA;AES_256_CM_HMAC_SHA1_32;AES_192_CM_HMAC_SHA1_80;`,
|
|
this means — those listed SDES crypto suites will be added into the generated SDP body at the top
|
|
of crypto suites list, in the given order. But, each of them is added, only if it is
|
|
about to be added/generated. In other words, the `SDES-order:` flag itself doesn't add crypto suites,
|
|
it just affects the order of those suites to be added.
|
|
|
|
And the rest of non-mentioned suites (not mentioned in the `SDES-order:` list),
|
|
which are also to be added, will be appended after those given, in the free manner of ordering.
|
|
|
|
Important thing to remember - it doesn't change the crypto suite tag
|
|
for the recipient, even though changing the order of them.
|
|
|
|
This flag does not contradict with `SDES-nonew`, `SDES-only-` and `SDES-no-` flags.
|
|
It just orders the list of crypto suites already prepared to be sent out.
|
|
|
|
- `pad`
|
|
|
|
RFC 4568 (section 6.1) is somewhat ambiguous regarding the base64 encoding format of
|
|
`a=crypto` parameters added to an SDP body. The default interpretation is that trailing
|
|
`=` characters used for padding should be omitted. With this flag set, these padding
|
|
characters will be left in place.
|
|
|
|
- `lifetime`
|
|
|
|
Add the key lifetime parameter `2^31` to each crypto key.
|
|
|
|
- `static`
|
|
|
|
Instructs *rtpengine* to skip the full SDES negotiation routine during a re-invite
|
|
(e.g. pick the first support crypto suite, look for possible SRTP passthrough)
|
|
and instead leave the previously negotiated crypto suite in place. Only useful in
|
|
subsequent `answer` messages and ignored in `offer` messages.
|
|
|
|
* `OSRTP`
|
|
|
|
Similar to `SDES` but controls OSRTP behaviour. Default behaviour is to pass through
|
|
OSRTP negotiations. Supported options:
|
|
|
|
- `offer`
|
|
|
|
When processing a non-OSRTP offer, convert it to an OSRTP offer. Will result
|
|
in RTP/SRTP transcoding if the OSRTP offer is accepted.
|
|
|
|
- `accept`
|
|
|
|
When processing a non-OSRTP answer in response to an OSRTP offer, accept the
|
|
OSRTP offer anyway. Results in RTP/SRTP transcoding.
|
|
|
|
* `endpoint-learning`
|
|
|
|
Contains one of the strings `off`, `immediate`, `delayed` or `heuristic`. This tells rtpengine which endpoint learning algorithm to use and overrides the `endpoint-learning` configuration option. This option can also be put into the `flags` list using a prefix of `endpoint-learning-`.
|
|
|
|
* `record call`
|
|
|
|
Contains one of the strings `yes`, `no`, `on` or `off`. This tells the rtpengine
|
|
whether or not to record the call to PCAP files. If the call is recorded, it
|
|
will generate PCAP files for each stream and a metadata file for each call.
|
|
Note that rtpengine *will not* force itself into the media path, and other
|
|
flags like `ICE=force` may be necessary to ensure the call is recorded.
|
|
|
|
See the `--recording-dir` option above.
|
|
|
|
Enabling call recording via this option has the same effect as doing it separately
|
|
via the `start recording` message, except that this option guarantees that the
|
|
entirety of the call gets recorded, including all details such as SDP bodies
|
|
passing through *rtpengine*.
|
|
|
|
* `metadata`
|
|
|
|
This is a generic metadata string. The metadata will be written to the bottom of
|
|
metadata files within `/path/to/recording_dir/metadata/` or to
|
|
`recording_metakeys` table. In the latter case, `metadata` string must
|
|
contain a list of `key:val` pairs separated by `|` character. `metadata` can be used to
|
|
record additional information about recorded calls. `metadata` values passed in
|
|
through subsequent messages will overwrite previous metadata values.
|
|
|
|
See the `--recording-dir` option above.
|
|
|
|
* `codec`
|
|
|
|
Contains a dictionary controlling various aspects of codecs (or RTP payload types).
|
|
|
|
These options can also be put into the `flags` list using a prefix of `codec-`. For example,
|
|
to set the codec options for two variants of Opus when they're implicitly accepted, (see
|
|
the example under `set`), one would put the following into the `flags` list:
|
|
`codec-set-opus/48000/1/16000` `codec-set-opus/48000/2/32000`
|
|
|
|
The following keys are understood:
|
|
|
|
* `strip`
|
|
|
|
Contains a list of strings. Each string is the name of a codec or RTP payload
|
|
type that should be removed from the SDP. Codec names are case sensitive, and
|
|
can be either from the list of codecs explicitly defined by the SDP through
|
|
an `a=rtpmap` attribute, or can be from the list of RFC-defined codecs. Examples
|
|
are `PCMU`, `opus`, or `telephone-event`. Codecs stripped using this option
|
|
are treated as if they had never been in the SDP.
|
|
|
|
It is possible to specify codec format parameters alongside with the codec name
|
|
in the same format as they're written in SDP for codecs that support them,
|
|
for example `opus/48000` to
|
|
specify Opus with 48 kHz sampling rate and one channel (mono), or
|
|
`opus/48000/2` for stereo Opus. If any format parameters are specified,
|
|
the codec will only be stripped if all of the format parameters match, and other
|
|
instances of the same codec with different format parameters will be left
|
|
untouched.
|
|
|
|
As a special keyword, `all` can be used to remove all codecs, except the ones
|
|
that should explicitly offered (see below). Note that it is an error to strip
|
|
all codecs and leave none that could be offered. In this case, the original
|
|
list of codecs will be left unchanged.
|
|
|
|
The keyword `full` can also be used, which behaves the same as `all` with the
|
|
exception listed under `transcode` below.
|
|
|
|
* `except`
|
|
|
|
Contains a list of strings. Each string is the name of a codec that should be
|
|
included in the list of codecs offered. This is primarily useful to block all
|
|
codecs (`strip -> all` or `mask -> all`) except the ones given in the `except`
|
|
whitelist. Codecs that were not present in the original list of codecs
|
|
offered by the client will be ignored.
|
|
|
|
This list also supports codec format parameters as per above.
|
|
|
|
* `offer`
|
|
|
|
This is identical to `except` but additionally allows the codec order to be
|
|
changed. So the first codec listed in `offer` will be the primary (preferred)
|
|
codec in the output SDP, even if it wasn't originally so.
|
|
|
|
* `transcode`
|
|
|
|
Similar to `offer` but allows codecs to be added to the list of offered codecs
|
|
even if they were not present in the original list of codecs. In this case,
|
|
the transcoding engine will be engaged. Only codecs that are supported for both
|
|
decoding and encoding can be added in this manner. This also has the side effect
|
|
of automatically stripping all unsupported codecs from the list of offered codecs,
|
|
as *rtpengine* must expect to receive or even send in any codec that is present
|
|
in the list.
|
|
|
|
Note that using this option does not necessarily always engage the transcoding
|
|
engine. If all codecs given in the `transcode` list were present in the original
|
|
list of offered codecs, then no transcoding will be done. Also note that if
|
|
transcoding takes place, in-kernel forwarding is disabled for this media stream
|
|
and all processing happens in userspace.
|
|
|
|
If no codec format parameters are specified in this list (e.g. just `opus`
|
|
instead of `opus/48000/2`), default values will be chosen for them.
|
|
|
|
For codecs that support different bitrates, it can be specified by appending
|
|
another slash followed by the bitrate in bits per second,
|
|
e.g. `opus/48000/2/32000`. In this case, all format parameters (clock rate,
|
|
channels) must also be specified.
|
|
|
|
Additional options that can be appended to the codec string with additional slashes
|
|
are ptime, the `fmtp` string, and additional codec-specific options. For example
|
|
`iLBC/8000/1///mode=30` to use `mode=30` as `fmtp` string.
|
|
|
|
For Opus, the string of codec-specific options is passed
|
|
directly to ffmpeg, so all ffmpeg codec options can be set. Use
|
|
space, colon, semicolon, or comma to separate individual
|
|
options. For example to set the encoding complexity (also known
|
|
as compression level by ffmpeg):
|
|
`opus/48000/2////compression_level=2`
|
|
|
|
If a literal `=` cannot be used due to parsing constraints (i.e. being wrongly
|
|
interpreted as a key-value pair), it can be escaped by using two dashes instead,
|
|
e.g. `iLBC/8000/1///mode--30`.
|
|
|
|
As a special case, if the `strip=all` or `mask=all` option has been used and
|
|
the `transcode` option is used on a codec that was originally present in the offer,
|
|
then *rtpengine* will treat this codec the same as if it had been used with the
|
|
`offer` option, i.e. it will simply restore it from the list of stripped codecs and
|
|
won't actually engage transcoding for this codec. On the other hand, if a codec has
|
|
been stripped explicitly by name using the `strip` or `mask` option and then used again
|
|
with the `transcode` option, then the codec will not simply be restored from the
|
|
list of stripped codecs, but instead a new transcoded instance of the codec will
|
|
be inserted into the offer. (This special exception does not apply to `mask=full`
|
|
or `strip=full`.)
|
|
|
|
This option is only processed in `offer` messages and ignored otherwise.
|
|
|
|
* `mask`
|
|
|
|
Similar to `strip` except that codecs listed here will still be accepted and
|
|
used for transcoding on the offering side. Useful only in combination with
|
|
`transcode`. For example, if an offer advertises Opus and the options
|
|
`mask=opus, transcode=G723` are given, then the rewritten outgoing offer
|
|
will contain only G.723 as offered codec, and transcoding will happen
|
|
between Opus and G.723. In contrast, if only `transcode=G723` were given, then
|
|
the rewritten outgoing offer would contain both Opus and G.723. On the other
|
|
hand, if `strip=opus, transcode=G723` were given, then Opus would be unavailable
|
|
for transcoding.
|
|
|
|
As with the `strip` option, the special keywords `all` and `full` can be used
|
|
to mask all codecs that have been offered.
|
|
|
|
This option is only processed in `offer` messages and ignored otherwise.
|
|
|
|
* `consume`
|
|
|
|
Identical to `mask` but enables the transcoding engine even if no other transcoding
|
|
related options are given.
|
|
|
|
* `accept`
|
|
|
|
Similar to `mask` and `consume` but doesn't remove the codec from the list of
|
|
offered codecs. This means that a codec listed under `accept` will still be offered
|
|
to the remote peer, but if the remote peer rejects it, it will still be accepted
|
|
towards the original offerer and then used for transcoding. It is a more selective
|
|
version of what the `always transcode` flag does.
|
|
|
|
The special string `any` can be used for the `publish` message.
|
|
See below for more details.
|
|
|
|
* `set`
|
|
|
|
Contains a list of strings. This list makes it possible to set codec options
|
|
(bitrate in particular) for codecs that are implicitly accepted for transcoding.
|
|
For example, if `AMR` was offered, `transcode=PCMU` was given, and the remote
|
|
ended up accepting `PCMU`, then this option can be used to set the bitrate used
|
|
for the AMR transcoding process.
|
|
|
|
Each string must be a full codec specification as per above, including clock rate
|
|
and number of channels. Using the example above, `set=AMR/8000/1/7400` can be used
|
|
to transcode to AMR with 7.4 kbit/s.
|
|
|
|
Codec options (bitrate) are only applied to codecs that match the given parameters
|
|
(clock rate, channels), and multiple options can be given for the same coded with
|
|
different parameters. For example, to specify different bitrates for Opus for both
|
|
mono and stereo output, one could use `set=[opus/48000/1/16000,opus/48000/2/32000]`.
|
|
|
|
This option is only processed in `offer` messages and ignored otherwise.
|
|
|
|
* `ptime`
|
|
|
|
Contains an integer. If set, changes the `a=ptime` attribute's value in the outgoing
|
|
SDP to the provided value. It also engages the transcoding engine for supported codecs
|
|
to provide repacketization functionality, even if no additional codec has actually
|
|
been requested for transcoding. Note that not all codecs support all packetization
|
|
intervals.
|
|
|
|
The selected ptime (which represents the duration of a single media packet in milliseconds)
|
|
will be used towards the endpoint receiving this offer, even if the matching answer
|
|
prefers a different ptime.
|
|
|
|
This option is ignored in `answer` messages. See below for the reverse.
|
|
|
|
* `ptime-reverse`
|
|
|
|
This is the reciprocal to `ptime`. It sets the ptime to be used towards the endpoint
|
|
who has sent the offer. It will be inserted in the `answer` SDP. This option is also
|
|
ignored in `answer` messages.
|
|
|
|
* `T.38`
|
|
|
|
Contains a list of strings. Each string is a flag that controls the behaviour regarding
|
|
T.38 transcoding. These flags are ignored if the message is not an `offer`.
|
|
Recognised flags are:
|
|
|
|
- `decode`
|
|
|
|
If the received SDP contains a media section with an `image` type, `UDPTL`
|
|
transport, and `t38` format string, this flag instructs *rtpengine* to convert
|
|
this media section into an `audio` type using RTP as transport protocol.
|
|
Other transport protocols (such as SRTP) can be selected using `transport protocol`
|
|
as described above.
|
|
|
|
The default audio codecs to be offered are `PCMU` and `PCMA`. Other audio codecs
|
|
can be specified using the `transcode=` flag described above, in which case the
|
|
default codecs will not be offered automatically.
|
|
|
|
- `force`
|
|
|
|
If the received SDP contains an audio media section using RTP transport, this flag
|
|
instructs *rtpengine* to convert it to an `image` type media section using the UDPTL
|
|
protocol. The first supported audio codec that was offered will be used to transport
|
|
T.30. Default options for T.38 are used for the generated SDP.
|
|
|
|
- `stop`
|
|
|
|
Stops a currently active T.38 gateway that was previously engaged using the `decode`
|
|
or `force` flags. This is useful to handle a rejected T.38 offer and revert the
|
|
session back to media passthrough.
|
|
|
|
- `no-ECM`
|
|
|
|
Disable support for ECM. Support is enabled by default.
|
|
|
|
- `no-V.17`
|
|
|
|
Disable support for V.17. Support is enabled by default.
|
|
|
|
- `no-V.27ter`
|
|
|
|
Disable support for V.27ter. Support is enabled by default.
|
|
|
|
- `no-V.29`
|
|
|
|
Disable support for V.29. Support is enabled by default.
|
|
|
|
- `no-V.34`
|
|
|
|
Disable support for V.34. Support is enabled by default.
|
|
|
|
- `no-IAF`
|
|
|
|
Disable support for IAF. Support is enabled by default.
|
|
|
|
- `FEC`
|
|
|
|
Use UDPTL FEC instead of redundancy. Only useful with `T.38=force` as
|
|
it's a negotiated parameter.
|
|
|
|
* `supports`
|
|
|
|
Contains a list of strings. Each string indicates support for an additional feature
|
|
that the controlling SIP proxy supports. Currently defined values are:
|
|
|
|
* `load limit`
|
|
|
|
Indicates support for an extension to the *ng* protocol to facilitate certain load
|
|
balancing mechanisms. If *rtpengine* is configured with certain session or load
|
|
limit options enabled (such as the `max-sessions` option), then normally *rtpengine*
|
|
would reply with an error to an `offer` if one of the limits is exceeded. If support
|
|
for the `load limit` extension is indicated, then instead of replying with an error,
|
|
*rtpengine* responds with the string `load limit` in the `result` key of the response
|
|
dictionary. The response dictionary may also contain the optional key `message` with
|
|
an explanatory string. No other key is required in the response dictionary.
|
|
|
|
* `xmlrpc-callback`
|
|
|
|
Contains a string that encodes an IP address (either IPv4 or IPv6) in printable format.
|
|
If specified, then this address will be used as destination address for the XMLRPC timeout
|
|
callback (see `b2b-url` option).
|
|
|
|
* `media echo` or `media-echo`
|
|
|
|
Contains a string to enable a special media echo mode. Recognised values are:
|
|
|
|
- `blackhole` or `sinkhole`
|
|
|
|
Media arriving from either side of the call is simply discarded
|
|
and not forwarded.
|
|
|
|
- `forward`
|
|
|
|
Enables media echo towards the receiver of this message (e.g.
|
|
the called party if the message is an `offer` from the caller).
|
|
Media arriving from that side is echoed back to its sender
|
|
(with a new SSRC if it's RTP). Media arriving from the opposite
|
|
side is discarded.
|
|
|
|
- `backwards`
|
|
|
|
Enables media echo towards the sender of this message (i.e. the
|
|
opposite of `forward`). Media arriving from the other side is
|
|
discarded.
|
|
|
|
- `both`
|
|
|
|
Enables media echo towards both the sender and the receiver of
|
|
this message.
|
|
|
|
* `DTMF-security`
|
|
|
|
Used in the `block DTMF` message to select the DTMF blocking mode. The
|
|
default mode is `drop` which simply drops DTMF event packets. The other
|
|
supported modes are: `silence` which replaces DTMF events with silence
|
|
audio; `tone` which replaces DTMF events with a single sine wave tone;
|
|
`random` which replaces DTMF events with random other DTMF events (both
|
|
in-band DTMF audio tones and RFC event packets); `zero` which is
|
|
similar to `random` except that a zero event is always used; `DTMF`
|
|
which is similar to `zero` except that a different DTMF digit can be
|
|
specified; `off` to disable DTMF blocking.
|
|
|
|
* `DTMF-security-trigger`
|
|
|
|
Blocking mode to enable when the DTMF `trigger` (see below) is detected.
|
|
|
|
* `DTMF-security-trigger-end`
|
|
|
|
Blocking mode to enable when the DTMF `end trigger` (see below) is
|
|
detected.
|
|
|
|
* `trigger`
|
|
|
|
A string of DTMF digits that enable a DTMF blocking mode when detected.
|
|
|
|
* `end trigger` or `trigger-end`
|
|
|
|
A string of DTMF digits that disable DTMF blocking or enable a
|
|
different DTMF blocking mode when detected, but only after the initial
|
|
enabling `trigger` has been detected.
|
|
|
|
* `trigger-end-time`
|
|
|
|
Time in milliseconds that a DTMF blocking mode enabled by the `trigger`
|
|
should remain active the most. After the time has expired, the blocking
|
|
mode is switched to the `trigger-end` mode.
|
|
|
|
* `trigger-end-digits`
|
|
|
|
Number of DTMF digits that a DTMF blocking mode enabled by the
|
|
`trigger` should remain active the most. After this number of DTMF
|
|
digits has been detected, the blocking mode is switched to the
|
|
`trigger-end` mode.
|
|
|
|
* `frequency` or `frequencies`
|
|
|
|
Sets the tone frequency or frequencies for `DTMF-security=tone` in Hertz.
|
|
The default is a single frequency of 400 Hz. A list of frequencies can be
|
|
given either as a list object, or as a string containing a comma-separated
|
|
list of integers. The given frequencies will be picked from the list in
|
|
order, one for each DTMF event detected, and will be repeated once the end
|
|
of the list is reached.
|
|
|
|
* `volume`
|
|
|
|
Sets the tone volume for `DTMF-security` modes `tone`, `zero, `DTMF`,
|
|
and `random` in negative dB. The default is -10 dB. The highest
|
|
possible volume is 0 dB and the lowest possible volume is -63 dB.
|
|
|
|
* `digit` or `code`
|
|
|
|
Sets the replacement digit for `DTMF-security=DTMF`.
|
|
|
|
* `delay-buffer`
|
|
|
|
Takes an integer as value. When set to non-zero, enables the delay
|
|
buffer when setting up codec handlers. The delay buffer delays all
|
|
media by the given number of milliseconds before passing it on. Once
|
|
the delay buffer is configured, it must explicitly be disabled again by
|
|
setting this value to zero. The delay buffer setting is honoured in all
|
|
messages that set up codec handlers, such as `block DTMF`.
|
|
|
|
* `DTMF-delay`
|
|
|
|
Time in milliseconds to delay DTMF events (both RFC event packets and
|
|
DTMF tones) for. With this option enabled (set to non-zero), DTMF
|
|
events are initially replaced by silence and then subsequently
|
|
reproduced after the given delay. DTMF blocking modes are honoured at
|
|
the time when the DTMF events are reproduced.
|
|
|
|
* `all`
|
|
|
|
Can be set to the string `none` to disable any extra behaviour (which
|
|
is the default if this key is omitted altogether) or to one of `all`,
|
|
`offer-answer`, `except-offer-answer` or `flows`. Applicable to
|
|
certain messages only. The behaviour is explained below separately for
|
|
each affected message.
|
|
|
|
An example of a complete `offer` request dictionary could be (SDP body abbreviated):
|
|
|
|
{ "command": "offer", "call-id": "cfBXzDSZqhYNcXM", "from-tag": "mS9rSAn0Cr",
|
|
"sdp": "v=0\r\no=...", "via-branch": "5KiTRPZHH1nL6",
|
|
"flags": [ "trust address" ], "replace": [ "origin", "session connection" ],
|
|
"address family": "IP6", "received-from": [ "IP4", "10.65.31.43" ],
|
|
"ICE": "force", "transport protocol": "RTP/SAVPF", "media address": "2001:d8::6f24:65b",
|
|
"DTLS": "passive" }
|
|
|
|
The response message only contains the key `sdp` in addition to `result`, which contains the re-written
|
|
SDP body that the SIP proxy should insert into the SIP message.
|
|
|
|
Example response:
|
|
|
|
{ "result": "ok", "sdp": "v=0\r\no=..." }
|
|
|
|
`answer` Message
|
|
----------------
|
|
|
|
The `answer` message is identical to the `offer` message, with the additional requirement that the
|
|
dictionary must contain the key `to-tag` containing the SIP `To` tag. It doesn't make sense to include
|
|
the `direction` key in the `answer` message.
|
|
|
|
The reply message is identical as in the `offer` reply.
|
|
|
|
`delete` Message
|
|
----------------
|
|
|
|
The `delete` message must contain at least the keys `call-id` and `from-tag` and may optionally include
|
|
`to-tag` and `via-branch`, as defined above. It may also optionally include a key `flags` containing a list
|
|
of zero or more strings. The following flags are defined:
|
|
|
|
* `fatal`
|
|
|
|
Specifies that any non-syntactical error encountered when deleting the stream
|
|
(such as unknown call-ID) shall
|
|
result in an error reply (i.e. `"result": "error"`). The default is to reply with a warning only
|
|
(i.e. `"result": "ok", "warning": ...`).
|
|
|
|
Other optional keys are:
|
|
|
|
* `delete delay`
|
|
|
|
Contains an integer and overrides the global command-line option `delete-delay`. Call/branch will be
|
|
deleted immediately if a zero is given. Value must be positive (in seconds) otherwise.
|
|
|
|
The reply message may contain additional keys with statistics about the deleted call. Those additional keys
|
|
are the same as used in the `query` reply.
|
|
|
|
`list` Message
|
|
--------------
|
|
|
|
The `list` command retrieves the list of currently active call-ids. This list is limited to 32 elements by
|
|
default.
|
|
|
|
* `limit`
|
|
|
|
Optional integer value that specifies the maximum number of results (default: 32). Must be > 0. Be
|
|
careful when setting big values, as the response may not fit in a UDP packet, and therefore be invalid.
|
|
|
|
`query` Message
|
|
---------------
|
|
|
|
The minimum requirement is the presence of the `call-id` key. Keys `from-tag` and/or `to-tag` may optionally
|
|
be specified.
|
|
|
|
The response dictionary contains the following keys:
|
|
|
|
* `created`
|
|
|
|
Contains an integer corresponding to the creation time of this call within the media proxy,
|
|
expressed as seconds since the UNIX epoch.
|
|
|
|
* `last signal`
|
|
|
|
The last time a signalling event (offer, answer, etc) occurred. Also expressed as an integer
|
|
UNIX timestamp.
|
|
|
|
* `tags`
|
|
|
|
Contains a dictionary. The keys of the dictionary are all the SIP tags (From-tag, To-Tag) known
|
|
by *rtpengine* related to this call. One of the keys may be an empty string, which corresponds to
|
|
one side of a dialogue which hasn't signalled its SIP tag yet. Each value of the dictionary is
|
|
another dictionary with the following keys:
|
|
|
|
- `created`
|
|
|
|
UNIX timestamp of when this SIP tag was first seen by *rtpengine*.
|
|
|
|
- `tag`
|
|
|
|
Identical to the corresponding key of the `tags` dictionary. Provided to allow for easy
|
|
traversing of the dictionary values without paying attention to the keys.
|
|
|
|
- `label`
|
|
|
|
The label assigned to this endpoint in the `offer` or `answer` message.
|
|
|
|
- `in dialogue with`
|
|
|
|
Contains the SIP tag of the other side of this dialogue. May be missing in case of a
|
|
half-established dialogue, in which case the other side is represented by the null-string
|
|
entry of the `tags` dictionary.
|
|
|
|
- `medias`
|
|
|
|
Contains a list of dictionaries, one for each SDP media stream known to *rtpengine*. The
|
|
dictionaries contain the following keys:
|
|
|
|
+ `index`
|
|
|
|
Integer, sequentially numbered index of the media, starting with one.
|
|
|
|
+ `type`
|
|
|
|
Media type as string, usually `audio` or `video`.
|
|
|
|
+ `protocol`
|
|
|
|
If the protocol is recognized by *rtpengine*, this string contains it.
|
|
Usually `RTP/AVP` or `RTP/SAVPF`.
|
|
|
|
+ `flags`
|
|
|
|
A list of strings containing various status flags. Contains zero of more
|
|
of: `initialized`, `rtcp-mux`, `DTLS-SRTP`, `SDES`, `passthrough`, `ICE`.
|
|
|
|
+ `streams`
|
|
|
|
Contains a list of dictionary representing the packet streams associated
|
|
with this SDP media. Usually contains two entries, one for RTP and one for RTCP.
|
|
The keys found in these dictionaries are listed below:
|
|
|
|
+ `local port`
|
|
|
|
Integer representing the local UDP port. May be missing in case of an inactive stream.
|
|
|
|
+ `endpoint`
|
|
|
|
Contains a dictionary with the keys `family`, `address` and `port`. Represents the
|
|
endpoint address used for packet forwarding. The `family` may be one of `IPv4` or
|
|
`IPv6`.
|
|
|
|
+ `advertised endpoint`
|
|
|
|
As above, but representing the endpoint address advertised in the SDP body.
|
|
|
|
+ `crypto suite`
|
|
|
|
Contains a string such as `AES_CM_128_HMAC_SHA1_80` representing the encryption
|
|
in effect. Missing if no encryption is active.
|
|
|
|
+ `last packet`
|
|
|
|
UNIX timestamp of when the last UDP packet was received on this port.
|
|
|
|
+ `flags`
|
|
|
|
A list of strings with various internal flags. Contains zero or more of:
|
|
`RTP`, `RTCP`, `fallback RTCP`, `filled`, `confirmed`, `kernelized,`
|
|
`no kernel support`.
|
|
|
|
+ `stats`
|
|
|
|
Contains a dictionary with the keys `bytes`, `packets` and `errors`.
|
|
Statistics counters for this packet stream.
|
|
|
|
* `totals`
|
|
|
|
Contains a dictionary with two keys, `RTP` and `RTCP`, each one containing another dictionary
|
|
identical to the `stats` dictionary described above.
|
|
|
|
A complete response message might look like this (formatted for readability):
|
|
|
|
{
|
|
"totals": {
|
|
"RTCP": {
|
|
"bytes": 2244,
|
|
"errors": 0,
|
|
"packets": 22
|
|
},
|
|
"RTP": {
|
|
"bytes": 100287,
|
|
"errors": 0,
|
|
"packets": 705
|
|
}
|
|
},
|
|
"last_signal": 1402064116,
|
|
"tags": {
|
|
"cs6kn1rloc": {
|
|
"created": 1402064111,
|
|
"medias": [
|
|
{
|
|
"flags": [
|
|
"initialized"
|
|
],
|
|
"streams": [
|
|
{
|
|
"endpoint": {
|
|
"port": 57370,
|
|
"address": "10.xx.xx.xx",
|
|
"family": "IPv4"
|
|
},
|
|
"flags": [
|
|
"RTP",
|
|
"filled",
|
|
"confirmed",
|
|
"kernelized"
|
|
],
|
|
"local port": 30018,
|
|
"last packet": 1402064124,
|
|
"stats": {
|
|
"packets": 343,
|
|
"errors": 0,
|
|
"bytes": 56950
|
|
},
|
|
"advertised endpoint": {
|
|
"family": "IPv4",
|
|
"port": 57370,
|
|
"address": "10.xx.xx.xx"
|
|
}
|
|
},
|
|
{
|
|
"stats": {
|
|
"bytes": 164,
|
|
"errors": 0,
|
|
"packets": 2
|
|
},
|
|
"advertised endpoint": {
|
|
"family": "IPv4",
|
|
"port": 57371,
|
|
"address": "10.xx.xx.xx"
|
|
},
|
|
"endpoint": {
|
|
"address": "10.xx.xx.xx",
|
|
"port": 57371,
|
|
"family": "IPv4"
|
|
},
|
|
"last packet": 1402064123,
|
|
"local port": 30019,
|
|
"flags": [
|
|
"RTCP",
|
|
"filled",
|
|
"confirmed",
|
|
"kernelized",
|
|
"no kernel support"
|
|
]
|
|
}
|
|
],
|
|
"protocol": "RTP/AVP",
|
|
"index": 1,
|
|
"type": "audio"
|
|
}
|
|
],
|
|
"in dialogue with": "0f0d2e18",
|
|
"tag": "cs6kn1rloc"
|
|
},
|
|
"0f0d2e18": {
|
|
"in dialogue with": "cs6kn1rloc",
|
|
"tag": "0f0d2e18",
|
|
"medias": [
|
|
{
|
|
"protocol": "RTP/SAVPF",
|
|
"index": 1,
|
|
"type": "audio",
|
|
"streams": [
|
|
{
|
|
"endpoint": {
|
|
"family": "IPv4",
|
|
"address": "10.xx.xx.xx",
|
|
"port": 58493
|
|
},
|
|
"crypto suite": "AES_CM_128_HMAC_SHA1_80",
|
|
"local port": 30016,
|
|
"last packet": 1402064124,
|
|
"flags": [
|
|
"RTP",
|
|
"filled",
|
|
"confirmed",
|
|
"kernelized"
|
|
],
|
|
"stats": {
|
|
"bytes": 43337,
|
|
"errors": 0,
|
|
"packets": 362
|
|
},
|
|
"advertised endpoint": {
|
|
"address": "10.xx.xx.xx",
|
|
"port": 58493,
|
|
"family": "IPv4"
|
|
}
|
|
},
|
|
{
|
|
"local port": 30017,
|
|
"last packet": 1402064124,
|
|
"flags": [
|
|
"RTCP",
|
|
"filled",
|
|
"confirmed",
|
|
"kernelized",
|
|
"no kernel support"
|
|
],
|
|
"endpoint": {
|
|
"family": "IPv4",
|
|
"port": 60193,
|
|
"address": "10.xx.xx.xx"
|
|
},
|
|
"crypto suite": "AES_CM_128_HMAC_SHA1_80",
|
|
"advertised endpoint": {
|
|
"family": "IPv4",
|
|
"port": 60193,
|
|
"address": "10.xx.xx.xx"
|
|
},
|
|
"stats": {
|
|
"packets": 20,
|
|
"bytes": 2080,
|
|
"errors": 0
|
|
}
|
|
}
|
|
],
|
|
"flags": [
|
|
"initialized",
|
|
"DTLS-SRTP",
|
|
"ICE"
|
|
]
|
|
}
|
|
],
|
|
"created": 1402064111
|
|
}
|
|
},
|
|
"created": 1402064111,
|
|
"result": "ok"
|
|
}
|
|
|
|
`start recording` Message
|
|
-------------------------
|
|
|
|
The `start recording` message must contain at least the key `call-id` and may optionally include `from-tag`,
|
|
`to-tag` and `via-branch`, as defined above. The reply dictionary contains no additional keys.
|
|
|
|
Enables call recording for the call, either for the entire call or for only the specified call leg. Currently
|
|
*rtpengine* always enables recording for the entire call and does not support recording only individual
|
|
call legs, therefore all keys other than `call-id` are currently ignored.
|
|
|
|
If the chosen recording method doesn't support in-kernel packet forwarding, enabling call recording
|
|
via this messages will force packet forwarding to happen in userspace only.
|
|
|
|
If the optional 'output-destination' key is set, then its value will be used
|
|
as an output file. Note that a filename extension will not be added.
|
|
|
|
`stop recording` Message
|
|
-------------------------
|
|
|
|
The `stop recording` message must contain the key `call-id` as defined above. The reply dictionary contains
|
|
no additional keys.
|
|
|
|
Disables call recording for the call. This can be sent during a call to immediately stop recording it.
|
|
|
|
`block DTMF` and `unblock DTMF` Messages
|
|
----------------------------------------
|
|
|
|
These message types must include the key `call-id` in the message. They enable and disable blocking of DTMF
|
|
events (RFC 4733 type packets), respectively.
|
|
|
|
Packets can be blocked for an entire call if only the `call-id` key is present in the message, or can be blocked
|
|
directionally for individual participants. Participants can be selected by their SIP tag if the `from-tag` key
|
|
is included in the message, they can be selected by their SDP media address if the `address` key is included
|
|
in the message, or they can be selected by the user-provided `label` if the `label` key is included in the
|
|
message. For an address, it can be an IPv4 or IPv6 address, and any participant that is
|
|
found to have a matching address advertised as their SDP media address will have their originating RTP
|
|
packets blocked (or unblocked).
|
|
|
|
Unblocking packets for the entire call (i.e. only `call-id` is given) does not
|
|
automatically unblock packets for participants which had their packets blocked
|
|
directionally, unless the string `all` (equivalent to setting `all=all`) is
|
|
included in the `flags` section of the message.
|
|
|
|
When DTMF blocking is enabled, DTMF event packets will not be forwarded to the receiving peer.
|
|
If DTMF logging is enabled, DTMF events will still be logged to syslog while blocking is enabled. Blocking
|
|
of DTMF events can be enabled and disabled at any time during call runtime.
|
|
|
|
`block media` and `unblock media` Messages
|
|
------------------------------------------
|
|
|
|
Analogous to `block DTMF` and `unblock DTMF` but blocks media packets instead of DTMF packets. DTMF packets
|
|
can still pass through when media blocking is enabled. Media packets can be blocked for an entire call, or
|
|
directionally for individual participants. See `block DTMF` above for details.
|
|
|
|
In addition to blocking media for just one call participant, it's possible to
|
|
block media for just a single media flow. This is relevant to scenarios that
|
|
involve forked media that were established with one or more `subscribe
|
|
request`. To select just one media flow for media blocking, in addition to
|
|
selecting a source call participant as above, a destination call participant
|
|
must be specified using the `to-tag` or `to-label`key in the message.
|
|
|
|
Another possibility to block media for individual media flows is to use one of
|
|
the special `all=` keywords instead of directly specifying a single `to-tag` or
|
|
`to-label`. With `all=offer-answer` all media flows from the given `from-tag`
|
|
that resulted from an offer/answer negotiation are affected. Respectively with
|
|
`all=except-offer-answer` the opposite happens. With `all=flows` all currently
|
|
established media flows are affected regardless or how they were created.
|
|
|
|
`silence media` and `unsilence media` Messages
|
|
----------------------------------------------
|
|
|
|
Identical to `block media` and `unblock media` except that media packets are
|
|
not simply blocked, but rather have their payload replaced with silence audio.
|
|
This is only supported for certain trivial audio codecs (i.e. G.711, G.722).
|
|
|
|
`start forwarding` and `stop forwarding` Messages
|
|
-------------------------------------------------
|
|
|
|
These messages control the recording daemon's mechanism to forward PCM via TCP/TLS. Unlike the call recording
|
|
mechanism, forwarding can be enabled for individual participants (directionally) only, therefore these
|
|
messages can be used with the same options as the `block` and `unblock` messages above. The PCM forwarding
|
|
mechanism is independent of the call recording mechanism, and so forwarding and recording can be started
|
|
and stopped independently of each other.
|
|
|
|
`play media` Message
|
|
--------------------
|
|
|
|
Only available if compiled with transcoding support. The message must contain the key `call-id` and one
|
|
of the participant selection keys described under the `block DTMF` message (such as `from-tag`,
|
|
`address`, or `label`). Alternatively, the `all` flag can be set to play the media to all involved
|
|
call parties.
|
|
|
|
Starts playback of a provided media file to the selected call participant. The format of the media file
|
|
can be anything that is supported by *ffmpeg*, for example a `.wav` or `.mp3` file. It will automatically
|
|
be resampled and transcoded to the appropriate sampling rate and codec. The selected participant's first
|
|
listed (preferred) codec that is supported will be chosen for this purpose.
|
|
|
|
Media files can be provided through one of these keys:
|
|
|
|
* `file`
|
|
|
|
Contains a string that points to a file on the local file system. File names can be relative
|
|
to the daemon's working direction.
|
|
|
|
* `blob`
|
|
|
|
Contains a binary blob (string) of the contents of a media file. Due to the limitations of the
|
|
*ng* transport protocol, only very short files can be provided this way, and so this is primarily
|
|
useful for testing and debugging.
|
|
|
|
* `db-id`
|
|
|
|
Contains an integer. This requires the daemon to be configured for accessing a *MySQL* (or *MariaDB*)
|
|
database via (at the minimum) the `mysql-host` and `mysql-query` config keys. The daemon will then
|
|
retrieve the media file as a binary blob (not a file name!) from the database via the provided query.
|
|
|
|
* `repeat-times`
|
|
|
|
Contains an integer. How many times to repeat playback of the media. Default is 1.
|
|
|
|
* `start-pos`
|
|
|
|
Contains an integer. The start frame position to begin the playback from.
|
|
|
|
In addition to the `result` key, the response dictionary may contain the key `duration` if the length of
|
|
the media file could be determined. The duration is given as in integer representing milliseconds.
|
|
|
|
`stop media` Message
|
|
--------------------
|
|
|
|
Stops the playback previously started by a `play media` message. Media playback stops automatically when
|
|
the end of the media file is reached, so this message is only useful for prematurely stopping playback.
|
|
The same participant selection keys as for the `play media` message can and must be used. Will return the
|
|
last frame played in `last-frame-pos` key.
|
|
|
|
`play DTMF` Message
|
|
-------------------
|
|
|
|
Instructs *rtpengine* to inject a DTMF tone or event into a running audio stream. A call participant must
|
|
be selected in the same way as described under the `play media` message above (including the possibility
|
|
of using the `all` flag). The selected call participant is the one generating the DTMF event, not the
|
|
one receiving it.
|
|
|
|
The dictionary key `code` (or alternatively `digit`) must be present in the message,
|
|
indicating the DTMF event to be generated. It can
|
|
be either an integer with values 0-15, or a string containing a single character
|
|
(`0` - `9`, `*`, `#`, `A` - `D`). Additional optional dictionary keys are: `duration` indicating the duration
|
|
of the event in milliseconds (defaults to 250 ms, with a minimum of 100 and a maximum of 5000);
|
|
`volume` indicating the volume in absolute decibels (defaults to -8 dB, with 0 being the maximum volume and
|
|
positive integers being interpreted as negative); and `pause` indicating the pause in between consecutive
|
|
DTMF events in milliseconds (defaults to 100 ms, with a minimum of 100 and a maximum of 5000).
|
|
|
|
This message can be used to implement `application/dtmf-relay` or `application/dtmf` payloads carried
|
|
in SIP INFO messages. Multiple DTMF events can be queued up by issuing multiple consecutive
|
|
`play DTMF` messages.
|
|
|
|
If the destination participant supports the `telephone-event` RTP payload type, then it will be used to
|
|
send the DTMF event. Otherwise a PCM DTMF tone will be inserted into the audio stream. Audio samples
|
|
received during a generated DTMF event will be suppressed.
|
|
|
|
The call must be marked for DTMF injection using the `inject DTMF` flag used in both `offer` and `answer`
|
|
messages. Enabling this flag forces all audio to go through the transcoding engine, even if input and output
|
|
codecs are the same (similar to DTMF transcoding, see above).
|
|
|
|
`statistics` Message
|
|
--------------------
|
|
|
|
Returns a set of general statistics metrics with identical content and format as the `list jsonstats` CLI
|
|
command. Sample return dictionary:
|
|
|
|
{
|
|
"statistics": {
|
|
"currentstatistics": {
|
|
"sessionsown": 0,
|
|
"sessionsforeign": 0,
|
|
"sessionstotal": 0,
|
|
"transcodedmedia": 0,
|
|
"packetrate": 0,
|
|
"byterate": 0,
|
|
"errorrate": 0
|
|
},
|
|
"totalstatistics": {
|
|
"uptime": "18",
|
|
"managedsessions": 0,
|
|
"rejectedsessions": 0,
|
|
"timeoutsessions": 0,
|
|
"silenttimeoutsessions": 0,
|
|
"finaltimeoutsessions": 0,
|
|
"offertimeoutsessions": 0,
|
|
"regularterminatedsessions": 0,
|
|
"forcedterminatedsessions": 0,
|
|
"relayedpackets": 0,
|
|
"relayedpacketerrors": 0,
|
|
"zerowaystreams": 0,
|
|
"onewaystreams": 0,
|
|
"avgcallduration": "0.000000"
|
|
},
|
|
"intervalstatistics": {
|
|
"totalcallsduration": "0.000000",
|
|
"minmanagedsessions": 0,
|
|
"maxmanagedsessions": 0,
|
|
"minofferdelay": "0.000000",
|
|
"maxofferdelay": "0.000000",
|
|
"avgofferdelay": "0.000000",
|
|
"minanswerdelay": "0.000000",
|
|
"maxanswerdelay": "0.000000",
|
|
"avganswerdelay": "0.000000",
|
|
"mindeletedelay": "0.000000",
|
|
"maxdeletedelay": "0.000000",
|
|
"avgdeletedelay": "0.000000",
|
|
"minofferrequestrate": 0,
|
|
"maxofferrequestrate": 0,
|
|
"avgofferrequestrate": 0,
|
|
"minanswerrequestrate": 0,
|
|
"maxanswerrequestrate": 0,
|
|
"avganswerrequestrate": 0,
|
|
"mindeleterequestrate": 0,
|
|
"maxdeleterequestrate": 0,
|
|
"avgdeleterequestrate": 0
|
|
},
|
|
"controlstatistics": {
|
|
"proxies": [
|
|
{
|
|
"proxy": "127.0.0.1",
|
|
"pingcount": 0,
|
|
"offercount": 0,
|
|
"answercount": 0,
|
|
"deletecount": 0,
|
|
"querycount": 0,
|
|
"listcount": 0,
|
|
"startreccount": 0,
|
|
"stopreccount": 0,
|
|
"startfwdcount": 0,
|
|
"stopfwdcount": 0,
|
|
"blkdtmfcount": 0,
|
|
"unblkdtmfcount": 0,
|
|
"blkmedia": 0,
|
|
"unblkmedia": 0,
|
|
"playmedia": 0,
|
|
"stopmedia": 0,
|
|
"playdtmf": 0,
|
|
"statistics": 0,
|
|
"errorcount": 0
|
|
}
|
|
],
|
|
"totalpingcount": 0,
|
|
"totaloffercount": 0,
|
|
"totalanswercount": 0,
|
|
"totaldeletecount": 0,
|
|
"totalquerycount": 0,
|
|
"totallistcount": 0,
|
|
"totalstartreccount": 0,
|
|
"totalstopreccount": 0,
|
|
"totalstartfwdcount": 0,
|
|
"totalstopfwdcount": 0,
|
|
"totalblkdtmfcount": 0,
|
|
"totalunblkdtmfcount": 0,
|
|
"totalblkmedia": 0,
|
|
"totalunblkmedia": 0,
|
|
"totalplaymedia": 0,
|
|
"totalstopmedia": 0,
|
|
"totalplaydtmf": 0,
|
|
"totalstatistics": 0,
|
|
"totalerrorcount": 0
|
|
}
|
|
},
|
|
"result": "ok"
|
|
}
|
|
|
|
`publish` Message
|
|
-----------------
|
|
|
|
Similar to an `offer` message except that it is used outside of an offer/answer
|
|
scenario. The media described by the SDP is published to *rtpengine* directly,
|
|
and other peer can then subscribe to the published media to receive a copy.
|
|
|
|
The message must include the key `sdp` which should describe `sendonly` media;
|
|
and the key `call-id` and `from-tag` to identify the publisher. Most other keys
|
|
and options supported by `offer` are also supported for `publish`.
|
|
|
|
The reply message will contain an answer SDP in `sdp`, but unlike with `offer`
|
|
this is not a rewritten version of the received SDP, but rather a `recvonly`
|
|
answer SDP generated by *rtpengine* locally. Only one codec for each media
|
|
section will be listed, and by default this will be the first supported codec
|
|
from the published media. This can be influenced with the `codec` options
|
|
described above, in particular the `accept` option.
|
|
|
|
The list of codecs given in the `accept` option is treated as a list of codec
|
|
preferences, with the first codec listed being the most preferred codec to be
|
|
accepted, and so on. It is allowable to list codecs that are not supported for
|
|
transcoding. If no codecs from the `accept` list are present in the offer, then
|
|
the first codec that is supported for transcoding is selected. If no such codec
|
|
is present, then the offer is rejected. The special string `any` can be given
|
|
in the `accept` list to influence this behaviour: If `any` is listed, then the
|
|
first codec from the offer is accepted even if it's not supported for
|
|
transcoding.
|
|
|
|
`subscribe request` Message
|
|
---------------------------
|
|
|
|
This message is used to request subscription (i.e. receiving a copy of the
|
|
media) to one or multiple existing call participants, which must have been
|
|
created either through the offer/answer mechanism, or through the publish
|
|
mechanism.
|
|
|
|
A single call participant can be selected in the same way as described under
|
|
`block DTMF`. Multiple call participants can be selected either by using the
|
|
`all` keyword, in which case all call participants that were created through
|
|
the offer/answer mechanism will be selected, or by providing a list of tags
|
|
(from-tags) in the `from-tags` list.
|
|
|
|
This message then creates a new call participant, which corresponds to the
|
|
subscription. This new call participant will be identified by a newly generated
|
|
unique tag, or by the tag given in the `to-tag` key. If a label is to be set
|
|
for the newly created subscription, it can be set through `set-label`.
|
|
|
|
The reply message will contain a sendonly offer SDP in `sdp` which by default
|
|
will mirror the SDP of the call participant being subscribed to. If multiple
|
|
call participants are subscribed to at the same time, then this SDP will
|
|
contain multiple media sections, combined out of the media sections of all
|
|
selected call participants. This offer SDP can be manipulated with the same
|
|
flags as used in an `offer` message, including the option to manipulate the
|
|
codecs. The reply message will also contain the `from-tags` (corresponding to
|
|
the call participants being subscribed to) and the `to-tag` (corresponding to
|
|
the subscription, either generated or taken from the received message).
|
|
|
|
If a `subscribe request` is made for an existing `to-tag` then all existing
|
|
subscriptions for that `to-tag` are deleted before the new subscriptions are
|
|
created.
|
|
|
|
`subscribe answer` Message
|
|
--------------------------
|
|
|
|
This message is expected to be received after responding to a `subscribe
|
|
request` message. The message should contain the same `to-tag` as the reply to
|
|
the `subscribe request` as well as the answer SDP in `sdp`.
|
|
|
|
By default, the answer SDP must accept all codecs that were presented in the
|
|
offer SDP (given in the reply to `subscribe request`). If not all codecs were
|
|
accepted, then the `subscribe answer` will be rejected. This behaviour can be
|
|
changed by including the `allow transcoding` flag in the message. If this flag
|
|
is present, then the answer SDP will be accepted as long as at least one valid
|
|
codec is present, and the media will be transcoded as required. This also holds
|
|
true if some codecs were added for transcoding in the `subscribe request`
|
|
message, which means that `allow transcoding` must always be included in
|
|
`subscribe answer` if any transcoding is to be allowed.
|
|
|
|
The reply message will simply indicate success or failure. If successful, media
|
|
forwarding will start to the endpoint given in the answer SDP.
|
|
|
|
`unsubscribe` Message
|
|
---------------------
|
|
|
|
This message is a counterpart to `subsscribe answer` to stop an established
|
|
subscription. The subscription to be stopped is identified by the `to-tag`.
|
|
|
|
The *tcp-ng* Control Protocol
|
|
=========================
|
|
|
|
*rtpengine* also has support for *ng* control protocol where transport is
|
|
TCP (If enabled in the config via the --listen-tcp-ng option). Everything
|
|
said for UDP based *ng* protocol counts for TCP variant too.
|
|
|
|
HTTP/WebSocket support
|
|
======================
|
|
|
|
If enabled in the config, *rtpengine* can handle requests made to it via HTTP,
|
|
HTTPS, or WebSocket (WS or WSS) connections. The supported HTTP URIs and
|
|
WebSocket subprotocols are described below.
|
|
|
|
Dummy Test Interfaces
|
|
---------------------
|
|
|
|
For HTTP and HTTPS, the URI `/ping` is provided, which simply responds with
|
|
`pong` if requested via `GET`. For WebSockets, the subprotocol
|
|
`echo.rtpengine.com` is provided, which simply echoes back any messages that
|
|
are sent to it.
|
|
|
|
CLI Interface
|
|
-------------
|
|
|
|
This interface supports the same commands as the CLI tool `rtpengine-ctl` that
|
|
comes packaged with `rtpengine`. For HTTP and HTTPS, the command is appended to
|
|
the URI base `/cli/` and the request is made via `GET`, with spaces replaced by
|
|
plus signs as required by HTTP (e.g. `GET /cli/list+totals`). For WebSockets,
|
|
the subprotocol is `cli.rtpengine.com` and each WebSocket message corresponds
|
|
to one CLI command and produces one message in response. The format of each
|
|
response is exactly the same as produced by the CLI tool `rtpengine-ctl` and
|
|
therefore meant for plain text representation.
|
|
|
|
*ng* Protocol Interface
|
|
-----------------------
|
|
|
|
This interface can be used to send and receive *ng* protocol messages over HTTP
|
|
or WebSocket connections instead of plain UDP.
|
|
|
|
For HTTP and HTTPS, the URI `/ng` is used, with the request being made by
|
|
`POST` and the content-type set to `application/x-rtpengine-ng`. The message
|
|
body must be in the same format as the body of an UDP-based *ng* message and
|
|
must therefore consist of a unique cookie string, followed by a single space,
|
|
followed by the message in *bencode* format. Likewise, the response will be in
|
|
the same format, including the unique cookie.
|
|
|
|
For WebSockets, the subprotocol `ng.rtpengine.com` is used and the protocol
|
|
follows the same format. Messages must consist of a unique cookie and a string
|
|
in bencode format, and responses will also be in the same format.
|
|
|
|
Prometheus Stats Exporter
|
|
-------------------------
|
|
|
|
The Prometheus metrics can be found under the URI `/metrics`.
|
|
|
|
*Janus* Interface and Replacement Functionality
|
|
===============================================
|
|
|
|
*Rtpengine* supports a limited and narrow subset of the features provided by
|
|
[Janus](https://janus.conf.meetecho.com/), specifically the basic business
|
|
logic behind the *videoroom* plugin. This makes it possible to use *rtpengine*
|
|
as a drop-in replacement for *Janus* for this one specific use case, and has
|
|
the benefit of being able to use all the extra features that *rtpengine*
|
|
provides, such as transcoding, in-kernel packet forwarding for improved
|
|
performance, etc.
|
|
|
|
The required subset of the *Janus* API is exposed via *rtpengine*'s HTTP/WS
|
|
interface. The HTTP admin API is connected to the `/admin` URI path using a
|
|
JSON payload (same as *Janus* does), while the module communication happens on
|
|
the WS protocol `janus-protocol`, also with JSON payloads (same as *Janus*
|
|
does). Unlike *Janus*, both HTTP and WS endpoints are running on the same port.
|
|
In fact, there is no real distinction between both interfaces, therefore both
|
|
admin and non-admin messages can be sent via either interface. HTTPS and WSS
|
|
are also supported.
|
|
|
|
Token-based plugin authentication works similar to how it works in *Janus*
|
|
except that only the single *videoroom* plugin is supported. The configuration
|
|
setting `janus-secret` must be set to enable clients to connect to this
|
|
simulated *Janus* interface and make use of its features.
|
|
|
|
Under the hood the functionality of the *videoroom* plugin is facilitated using
|
|
*rtpengine*'s `publish` and `subscribe` methods, which are mapped directly to
|
|
the respective *Janus* methods. One *Janus* video room becomes one *rtpengine*
|
|
call, with a distinctive and unique call ID based on the video room ID.
|
|
|
|
There's currently no support for customising the SDP features and options used
|
|
within the *Janus* drop-in mode, and, as *Janus* is WebRTC-specific, all SDPs
|
|
produced from this mode can be used directly by WebRTC clients. Non-WebRTC
|
|
clients can participate in the same video room as *Janus* clients if the
|
|
respective mapped `publish` and `subscribe` methods are used, and with the call
|
|
ID mapped to the video room ID.
|