rtprtxqueue: add basic documentation and example pipelines

Mostly explaining the difference between rtprtxqueue and rtprtxsend.

diff --git a/gst/rtpmanager/gstrtprtxqueue.c b/gst/rtpmanager/gstrtprtxqueue.c
index cdf3b03..0fa10d0 100644 (file)
--- a/gst/rtpmanager/gstrtprtxqueue.c
+++ b/gst/rtpmanager/gstrtprtxqueue.c
@@ -22,6 +22,44 @@
 
 /**
  * SECTION:element-rtprtxqueue
+ *
+ * rtprtxqueue maintains a queue of transmitted RTP packets, up to a
+ * configurable limit (see #GstRTPRtxQueue::max-size-time,
+ * #GstRTPRtxQueue::max-size-packets), and retransmits them upon request
+ * from the downstream rtpsession (GstRTPRetransmissionRequest event).
+ *
+ * This element is similar to rtprtxsend, but it has differences:
+ * - Retransmission from rtprtxqueue is not RFC 4588 compliant. The
+ * retransmitted packets have the same ssrc and payload type as the original
+ * stream.
+ * - As a side-effect of the above, rtprtxqueue does not require the use of
+ * rtprtxreceive on the receiving end. rtpjitterbuffer alone is able to
+ * reconstruct the stream.
+ * - Retransmission from rtprtxqueue happens as soon as the next regular flow
+ * packet is chained, while rtprtxsend retransmits as soon as the retransmission
+ * event is received, using a helper thread.
+ * - rtprtxqueue can be used with rtpbin without the need of hooking to its
+ * #GstRtpBin::request-aux-sender signal, which means it can be used with
+ * rtpbin using gst-launch.
+ *
+ * See also #GstRtpRtxSend, #GstRtpRtxReceive
+ *
+ * # Example pipelines
+ * |[
+ * gst-launch-1.0 rtpbin name=b rtp-profile=avpf \
+ *    audiotestsrc is-live=true ! opusenc ! rtpopuspay pt=96 ! rtprtxqueue ! b.send_rtp_sink_0 \
+ *    b.send_rtp_src_0 ! identity drop-probability=0.01 ! udpsink host="127.0.0.1" port=5000 \
+ *    udpsrc port=5001 ! b.recv_rtcp_sink_0 \
+ *    b.send_rtcp_src_0 ! udpsink host="127.0.0.1" port=5002 sync=false async=false
+ * ]| Sender pipeline
+ * |[
+ * gst-launch-1.0 rtpbin name=b rtp-profile=avpf do-retransmission=true \
+ *    udpsrc port=5000 caps="application/x-rtp,media=(string)audio,clock-rate=(int)48000,encoding-name=(string)OPUS,payload=(int)96" ! \
+ *        b.recv_rtp_sink_0 \
+ *    b. ! rtpopusdepay ! opusdec ! audioconvert ! audioresample ! autoaudiosink \
+ *    udpsrc port=5002 ! b.recv_rtcp_sink_0 \
+ *    b.send_rtcp_src_0 ! udpsink host="127.0.0.1" port=5001 sync=false async=false
+ * ]| Receiver pipeline
  */
 
 #ifdef HAVE_CONFIG_H