audiorate: add documentation

diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index 121784ddf54659bf5487aaab8d865eb6992d4c89..3dfcbf7a42a9f3965c8b01663deb294ac4c31dae 100644 (file)
--- 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 1b4f1a00cd50edea56873099e25ca06c7008235a..aa1e0af3be07c2c9334ef4e61c3b326965efb150 100644 (file)
--- 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 5ae661a65692636cd85a92d1f6d886c54f0923d1..9ff8c815bab7a881faae492be79961c71e4e46f1 100644 (file)
--- a/docs/plugins/gst-plugins-base-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-base-plugins-sections.txt
@@ -153,6 +153,20 @@ audio_convert_get_sizes
 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>

diff --git a/gst/audiorate/gstaudiorate.c b/gst/audiorate/gstaudiorate.c
index e3b9f6a127dfadec37ff462b67cd6bc8307bffe0..fd39b662e2c5e3c49a555ac686d63fd6b4f23f67 100644 (file)
--- 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