TT#50652 add documentation for media playback capability

Change-Id: Id9fb0a095f1c54a265f3a30f0a38542db06d46b4

README.md

@@ -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.

daemon/rtpengine.pod

@@ -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