audiorate: add documentation

4 files changed, 48 insertions, 0 deletions

diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index 121784dd..3dfcbf7a 100644
--- a/docs/plugins/Makefile.am
+++ b/docs/plugins/Makefile.am
@@ -107,6 +107,7 @@ EXTRA_HFILES = \
 	$(top_srcdir)/gst/gdp/gstgdppay.h \
 	$(top_srcdir)/gst/playback/gstplay-enum.h \
 	$(top_srcdir)/gst/playback/gstsubtitleoverlay.h \
+	$(top_srcdir)/gst/audiorate/gstaudiorate.h \
 	$(top_srcdir)/gst/audioresample/gstaudioresample.h \
 	$(top_srcdir)/gst/tcp/gstmultifdsink.h \
 	$(top_srcdir)/gst/tcp/gsttcpclientsrc.h \
diff --git a/docs/plugins/gst-plugins-base-plugins-docs.sgml b/docs/plugins/gst-plugins-base-plugins-docs.sgml
index 1b4f1a00..aa1e0af3 100644
--- a/docs/plugins/gst-plugins-base-plugins-docs.sgml
+++ b/docs/plugins/gst-plugins-base-plugins-docs.sgml
@@ -24,6 +24,7 @@
     <xi:include href="xml/element-alsasink.xml" />
     <xi:include href="xml/element-alsasrc.xml" />
     <xi:include href="xml/element-audioconvert.xml" />
+    <xi:include href="xml/element-audiorate.xml" />
     <xi:include href="xml/element-audioresample.xml" />
     <xi:include href="xml/element-audiotestsrc.xml" />
     <xi:include href="xml/element-cdparanoiasrc.xml" />
diff --git a/docs/plugins/gst-plugins-base-plugins-sections.txt b/docs/plugins/gst-plugins-base-plugins-sections.txt
index 5ae661a6..9ff8c815 100644
--- a/docs/plugins/gst-plugins-base-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-base-plugins-sections.txt
@@ -154,6 +154,20 @@ audio_convert_prepare_context
 </SECTION>
 
 <SECTION>
+<FILE>element-audiorate</FILE>
+<TITLE>audiorate</TITLE>
+GstAudioRate
+<SUBSECTION Standard>
+GST_AUDIO_RATE
+GST_IS_AUDIO_RATE
+GST_TYPE_AUDIO_RATE
+gst_audio_rate_get_type
+GST_AUDIO_RATE_CLASS
+GST_IS_AUDIO_RATE_CLASS
+GstAudioRateClass
+</SECTION>
+
+<SECTION>
 <FILE>element-audioresample</FILE>
 <TITLE>audioresample</TITLE>
 GstAudioResample
diff --git a/gst/audiorate/gstaudiorate.c b/gst/audiorate/gstaudiorate.c
index e3b9f6a1..fd39b662 100644
--- a/gst/audiorate/gstaudiorate.c
+++ b/gst/audiorate/gstaudiorate.c
@@ -17,6 +17,38 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-audiorate
+ * @see_also: #GstVideoRate
+ *
+ * This element takes an incoming stream of timestamped raw audio frames and
+ * produces a perfect stream by inserting or dropping samples as needed.
+ *
+ * This operation may be of use to link to elements that require or otherwise
+ * implicitly assume a perfect stream as they do not store timestamps,
+ * but derive this by some means (e.g. bitrate for some AVI cases).
+ *
+ * The properties #GstAudioRate:in, #GstAudioRate:out, #GstAudioRate:add
+ * and #GstAudioRate:drop can be read to obtain information about number of
+ * input samples, output samples, dropped samples (i.e. the number of unused input
+ * samples) and inserted samples (i.e. the number of samples added to stream).
+ *
+ * When the #GstAudioRate:silent property is set to FALSE, a GObject property
+ * notification will be emitted whenever one of the #GstAudioRate:add or
+ * #GstAudioRate:drop values changes.
+ * This can potentially cause performance degradation.
+ * Note that property notification will happen from the streaming thread, so
+ * applications should be prepared for this.
+ *
+ * <refsect2>
+ * <title>Example pipelines</title>
+ * |[
+ * gst-launch -v alsasrc ! audiorate ! wavenc ! filesink location=alsa.wav
+ * ]| Capture audio from an ALSA device, and turn it into a perfect stream
+ * for saving in a raw audio file.
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif