[sr-dev] git:master:a5e7a56a: rtpengine: add docs for play_media() et al

[Richard Fuchs]

Module: kamailio
Branch: master
Commit: a5e7a56a374d76f701ac6503884d0f2c2e6f841e
URL: https://github.com/kamailio/kamailio/commit/a5e7a56a374d76f701ac6503884d0f2c2e6f841e

Author: Richard Fuchs <rfuchs at sipwise.com>
Committer: Richard Fuchs <rfuchs at sipwise.com>
Date: 2019-03-08T16:06:21-05:00

rtpengine: add docs for play_media() et al

---

Modified: src/modules/rtpengine/doc/rtpengine_admin.xml

---

Diff:  https://github.com/kamailio/kamailio/commit/a5e7a56a374d76f701ac6503884d0f2c2e6f841e.diff
Patch: https://github.com/kamailio/kamailio/commit/a5e7a56a374d76f701ac6503884d0f2c2e6f841e.patch

---

diff --git a/src/modules/rtpengine/doc/rtpengine_admin.xml b/src/modules/rtpengine/doc/rtpengine_admin.xml
index 828bfee43f..a690d51469 100644
--- a/src/modules/rtpengine/doc/rtpengine_admin.xml
+++ b/src/modules/rtpengine/doc/rtpengine_admin.xml
@@ -699,6 +699,28 @@ modparam("rtpengine", "setid_default", 11)
 	</section>
 
 
+	<section id="rtpengine.p.media_duration">
+		<title><varname>media_duration</varname> (string)</title>
+		<para>
+			The name of a pseudovariable to be filled in with the length of the
+			media being played back after a call to <quote>play_media</quote>,
+			expressed in milliseconds. It's set to -1 if the length of the media
+			could not be determined.
+		</para>
+		<para>
+			By default, this parameter is not set.
+		</para>
+		<example>
+		<title>Set <varname>media_duration</varname> parameter</title>
+<programlisting format="linespecific">
+...
+modparam("rtpengine", "media_duration", "$avp(MEDIA_DURATION)")
+...
+</programlisting>
+		</example>
+	</section>
+
+
 	<section id="rtpengine.p.mos_min_pv">
 		<title><varname>mos_min_pv</varname> (string)</title>
 		<para>
@@ -2793,6 +2815,54 @@ stop_forwarding("all");
 		</example>
 	</section>
 
+	<section id="rtpengine.f.play_media">
+		<title>
+		<function moreinfo="none">play_media([flags])</function>
+		</title>
+		<para>
+		Instructs rtpengine to play a prerecorded announcement to the selected
+		call participant, either from a local file or from a file stored in a
+		database. The participant must be selected using the same flags as are
+		described under the <quote>block_dtmf</quote> function. If none of these
+		flags are given, then the <quote>From</quote> tag from the current &sip;
+		message context is used.
+		</para>
+		<para>
+		If successful, the <quote>media_duration</quote> pseudovariable is filled
+		in with the duration of the media being played, expressed in milliseconds.
+		If the length of the media could not be determined, it's set to -1.
+		</para>
+		<example>
+		<title><function>play_media</function> usage</title>
+		<programlisting format="linespecific">
+...
+play_media("file=/use/share/media/hello.wav");
+play_media("from-tag=tfugklbildfydrtuykgfv db-id=12345");
+...
+		</programlisting>
+		</example>
+	</section>
+
+	<section id="rtpengine.f.stop_media">
+		<title>
+		<function moreinfo="none">stop_media([flags])</function>
+		</title>
+		<para>
+		Stops the playback of media previously started by <quote>play_media</quote>.
+		Media playback is automatically stopped when the end of the media file is reached,
+		so this function is only useful to prematurely stop playback.
+		</para>
+		<example>
+		<title><function>stop_media</function> usage</title>
+		<programlisting format="linespecific">
+...
+stop_media();
+stop_media("from-tag=5yqaeriguhxcikxj");
+...
+		</programlisting>
+		</example>
+	</section>
+
 
 	</section>