RuhNetConsulting
/
rtpengine
mirror of https://github.com/sipwise/rtpengine
1
1
Fork 0
Code Issues 0 Projects 0 Releases 822 Wiki Activity
Browse Source

TT#50652 add documentation for media playback capability 

Change-Id: Id9fb0a095f1c54a265f3a30f0a38542db06d46b4
changes/48/27748/4
Richard Fuchs 7 years ago
parent
7f5e16d3da
commit
223996bc58
2 changed files with 92 additions and 4 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +52
    -4
      README.md
  2. +40
    -0
      daemon/rtpengine.pod

+ 52
- 4
README.md View File

@ -44,10 +44,10 @@ the following additional features are available:
- Breaking of BUNDLE'd media streams (draft-ietf-mmusic-sdp-bundle-negotiation)
- Recording of media streams, decrypted if possible
- Transcoding and repacketization
- Playback of pre-recorded streams/announcements
*Rtpengine* does not (yet) support:
* Playback of pre-recorded streams/announcements
* ZRTP, although ZRTP passes through *rtpengine* just fine
Compiling and Installing
@ -132,7 +132,7 @@ build all parts and run the test suite.
- *libevent* version 2.x
- *libpcap*
- *libsystemd*
- *MySQL* or *MariaDB* client library (optional for call recording daemon)
- *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)
@ -142,10 +142,14 @@ build all parts and run the test suite.
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.
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.
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`
@ -463,6 +467,8 @@ a string and determines the type of message. Currently the following commands ar
* unblock media
* start forwarding
* stop forwarding
* play media
* stop media
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
@ -1393,8 +1399,50 @@ directionally for individual participants. See `block DTMF` above for details.
`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` or
`address`).
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 chosed 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.
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.

+ 40
- 0
daemon/rtpengine.pod View File

@ -19,6 +19,9 @@ Most of these options are indeed optional, with two exceptions. It's
mandatory to specify at least one local IP address through B<--interface>,
and at least one of the B<--listen->I<...> options must be given.
All options can (and should) be provided in a config file instead of
at the command line. See the B<--config-file> option below for details.
=over 4
=item B<--help>
@ -247,6 +250,17 @@ How many worker threads to create, must be at least one.
The default is to create as many threads as there are CPU cores available.
If the number of CPU cores cannot be determined, the default is four.
=item B<--num-media-threads=>I<INT>
Number of threads to launch for media playback. Defaults to the same
number as B<num-threads>. This can be set to zero if no media playback
functionality is desired.
Media playback is actually handled by two threads: One for reading and
decoding the media file, and another to schedule and send out RTP packets.
So for example, if this option is set to 4, in total 8 threads will be
launched.
=item B<--sip-source>
The original B<rtpproxy> as well as older version of B<rtpengine> by default
@ -593,6 +607,32 @@ using these settings might have unexpected results.
(Linux does support thread-specific B<nice> values.)
Refer to your system's sched(7) man page.
=item B<--mysql-host=>I<HOST>|I<IP>
=item B<--mysql-port=>I<INT>
=item B<--mysql-user=>I<USERNAME>
=item B<--mysql-pass=>I<PASSWORD>
Configuration for playing back media files that are stored in a
B<MySQL> (or B<MariaDB>) database. At least B<mysql-host> must be configured
for this to work. The others are optional and default to their respective
values from the B<MySQL>/B<MariaDB> client library.
=item B<--mysql-query=>I<STRING>
Query to be used for retrieving media files from the database. No default
exist, therefore this is a mandatory configuration for media playback from
database. The provided query string must contain the single format placeholder
B<%llu> and must not contain any other format placeholders. The ID value
passed to B<rtpengine> in the B<db-id> key of the B<play media> message will
be used in place of the placeholder when querying the database.
An example configuration might look like this:
mysql-query = select data from voip.files where id = %llu
=back
=head1 INTERFACES


Write Preview
Loading…
Cancel
Save