1 /* RTP Retransmission sender element for GStreamer
5 * Copyright (C) 2013 Collabora Ltd.
6 * @author Julien Isorce <julien.isorce@collabora.co.uk>
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
25 * SECTION:element-rtprtxsend
27 * See #GstRtpRtxReceive for examples
29 * The purpose of the sender RTX object is to keep a history of RTP packets up
30 * to a configurable limit (max-size-time or max-size-packets). It will listen
31 * for upstream custom retransmission events (GstRTPRetransmissionRequest) that
32 * comes from downstream (#GstRtpSession). When receiving a request it will
33 * look up the requested seqnum in its list of stored packets. If the packet
34 * is available, it will create a RTX packet according to RFC 4588 and send
35 * this as an auxiliary stream. RTX is SSRC-multiplexed
43 #include <gst/rtp/gstrtpbuffer.h>
46 #include "gstrtprtxsend.h"
48 GST_DEBUG_CATEGORY_STATIC (gst_rtp_rtx_send_debug);
49 #define GST_CAT_DEFAULT gst_rtp_rtx_send_debug
51 #define DEFAULT_RTX_PAYLOAD_TYPE 0
52 #define DEFAULT_MAX_SIZE_TIME 0
53 #define DEFAULT_MAX_SIZE_PACKETS 100
59 PROP_RTX_PAYLOAD_TYPE,
61 PROP_MAX_SIZE_PACKETS,
62 PROP_NUM_RTX_REQUESTS,
67 static GstStaticPadTemplate src_factory = GST_STATIC_PAD_TEMPLATE ("src",
70 GST_STATIC_CAPS ("application/x-rtp")
73 static GstStaticPadTemplate sink_factory = GST_STATIC_PAD_TEMPLATE ("sink",
76 GST_STATIC_CAPS ("application/x-rtp")
79 static gboolean gst_rtp_rtx_send_src_event (GstPad * pad, GstObject * parent,
81 static gboolean gst_rtp_rtx_send_sink_event (GstPad * pad, GstObject * parent,
83 static GstFlowReturn gst_rtp_rtx_send_chain (GstPad * pad, GstObject * parent,
86 static GstStateChangeReturn gst_rtp_rtx_send_change_state (GstElement *
87 element, GstStateChange transition);
89 static void gst_rtp_rtx_send_set_property (GObject * object, guint prop_id,
90 const GValue * value, GParamSpec * pspec);
91 static void gst_rtp_rtx_send_get_property (GObject * object, guint prop_id,
92 GValue * value, GParamSpec * pspec);
93 static void gst_rtp_rtx_send_finalize (GObject * object);
95 G_DEFINE_TYPE (GstRtpRtxSend, gst_rtp_rtx_send, GST_TYPE_ELEMENT);
105 buffer_queue_item_free (BufferQueueItem * item)
107 gst_buffer_unref (item->buffer);
112 gst_rtp_rtx_send_class_init (GstRtpRtxSendClass * klass)
114 GObjectClass *gobject_class;
115 GstElementClass *gstelement_class;
117 gobject_class = (GObjectClass *) klass;
118 gstelement_class = (GstElementClass *) klass;
120 gobject_class->get_property = gst_rtp_rtx_send_get_property;
121 gobject_class->set_property = gst_rtp_rtx_send_set_property;
122 gobject_class->finalize = gst_rtp_rtx_send_finalize;
124 g_object_class_install_property (gobject_class, PROP_RTX_SSRC,
125 g_param_spec_uint ("rtx-ssrc", "Retransmission SSRC",
126 "SSRC of the retransmission stream for SSRC-multiplexed mode "
127 "(default = random)", 0, G_MAXUINT, -1,
128 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
130 g_object_class_install_property (gobject_class, PROP_RTX_PAYLOAD_TYPE,
131 g_param_spec_uint ("rtx-payload-type", "RTX Payload Type",
132 "Payload type of the retransmission stream (fmtp in SDP)", 0,
133 G_MAXUINT, DEFAULT_RTX_PAYLOAD_TYPE,
134 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
136 g_object_class_install_property (gobject_class, PROP_MAX_SIZE_TIME,
137 g_param_spec_uint ("max-size-time", "Max Size Time",
138 "Amount of ms to queue (0 = unlimited)", 0, G_MAXUINT,
139 DEFAULT_MAX_SIZE_TIME, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
141 g_object_class_install_property (gobject_class, PROP_MAX_SIZE_PACKETS,
142 g_param_spec_uint ("max-size-packets", "Max Size Packets",
143 "Amount of packets to queue (0 = unlimited)", 0, G_MAXINT16,
144 DEFAULT_MAX_SIZE_PACKETS,
145 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
147 g_object_class_install_property (gobject_class, PROP_NUM_RTX_REQUESTS,
148 g_param_spec_uint ("num-rtx-requests", "Num RTX Requests",
149 "Number of retransmission events received", 0, G_MAXUINT,
150 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
152 g_object_class_install_property (gobject_class, PROP_NUM_RTX_PACKETS,
153 g_param_spec_uint ("num-rtx-packets", "Num RTX Packets",
154 " Number of retransmission packets sent", 0, G_MAXUINT,
155 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
157 gst_element_class_add_pad_template (gstelement_class,
158 gst_static_pad_template_get (&src_factory));
159 gst_element_class_add_pad_template (gstelement_class,
160 gst_static_pad_template_get (&sink_factory));
162 gst_element_class_set_static_metadata (gstelement_class,
163 "RTP Retransmission Sender", "Codec",
164 "Retransmit RTP packets when needed, according to RFC4588",
165 "Julien Isorce <julien.isorce@collabora.co.uk>");
167 gstelement_class->change_state =
168 GST_DEBUG_FUNCPTR (gst_rtp_rtx_send_change_state);
172 gst_rtp_rtx_send_reset (GstRtpRtxSend * rtx, gboolean full)
174 g_mutex_lock (&rtx->lock);
175 g_sequence_remove_range (g_sequence_get_begin_iter (rtx->queue),
176 g_sequence_get_end_iter (rtx->queue));
177 g_queue_foreach (rtx->pending, (GFunc) gst_buffer_unref, NULL);
178 g_queue_clear (rtx->pending);
179 rtx->master_ssrc = 0;
180 rtx->next_seqnum = g_random_int_range (0, G_MAXUINT16);
181 rtx->rtx_ssrc = g_random_int ();
182 rtx->num_rtx_requests = 0;
183 rtx->num_rtx_packets = 0;
184 g_mutex_unlock (&rtx->lock);
188 gst_rtp_rtx_send_finalize (GObject * object)
190 GstRtpRtxSend *rtx = GST_RTP_RTX_SEND (object);
192 gst_rtp_rtx_send_reset (rtx, TRUE);
193 g_sequence_free (rtx->queue);
194 g_queue_free (rtx->pending);
195 g_mutex_clear (&rtx->lock);
197 G_OBJECT_CLASS (gst_rtp_rtx_send_parent_class)->finalize (object);
201 gst_rtp_rtx_send_init (GstRtpRtxSend * rtx)
203 GstElementClass *klass = GST_ELEMENT_GET_CLASS (rtx);
206 gst_pad_new_from_template (gst_element_class_get_pad_template (klass,
208 GST_PAD_SET_PROXY_CAPS (rtx->srcpad);
209 GST_PAD_SET_PROXY_ALLOCATION (rtx->srcpad);
210 gst_pad_set_event_function (rtx->srcpad,
211 GST_DEBUG_FUNCPTR (gst_rtp_rtx_send_src_event));
212 gst_element_add_pad (GST_ELEMENT (rtx), rtx->srcpad);
215 gst_pad_new_from_template (gst_element_class_get_pad_template (klass,
217 GST_PAD_SET_PROXY_CAPS (rtx->sinkpad);
218 GST_PAD_SET_PROXY_ALLOCATION (rtx->sinkpad);
219 gst_pad_set_event_function (rtx->sinkpad,
220 GST_DEBUG_FUNCPTR (gst_rtp_rtx_send_sink_event));
221 gst_pad_set_chain_function (rtx->sinkpad,
222 GST_DEBUG_FUNCPTR (gst_rtp_rtx_send_chain));
223 gst_element_add_pad (GST_ELEMENT (rtx), rtx->sinkpad);
225 rtx->queue = g_sequence_new ((GDestroyNotify) buffer_queue_item_free);
226 rtx->pending = g_queue_new ();
227 g_mutex_init (&rtx->lock);
229 rtx->next_seqnum = g_random_int_range (0, G_MAXUINT16);
230 rtx->rtx_ssrc = g_random_int ();
232 rtx->max_size_time = DEFAULT_MAX_SIZE_TIME;
233 rtx->max_size_packets = DEFAULT_MAX_SIZE_PACKETS;
237 choose_ssrc (GstRtpRtxSend * rtx)
242 ssrc = g_random_int ();
244 /* make sure to be different than master */
245 if (ssrc != rtx->master_ssrc)
252 buffer_queue_items_cmp (BufferQueueItem * a, BufferQueueItem * b,
255 /* gst_rtp_buffer_compare_seqnum returns the opposite of what we want,
256 * it returns negative when seqnum1 > seqnum2 and we want negative
257 * when b > a, i.e. a is smaller, so it comes first in the sequence */
258 return gst_rtp_buffer_compare_seqnum (b->seqnum, a->seqnum);
262 gst_rtp_rtx_send_src_event (GstPad * pad, GstObject * parent, GstEvent * event)
264 GstRtpRtxSend *rtx = GST_RTP_RTX_SEND (parent);
267 switch (GST_EVENT_TYPE (event)) {
268 case GST_EVENT_CUSTOM_UPSTREAM:
270 const GstStructure *s = gst_event_get_structure (event);
272 /* This event usually comes from the downstream gstrtpsession */
273 if (gst_structure_has_name (s, "GstRTPRetransmissionRequest")) {
277 /* retrieve seqnum of the packet that need to be restransmisted */
278 if (!gst_structure_get_uint (s, "seqnum", &seqnum))
281 /* retrieve ssrc of the packet that need to be restransmisted */
282 if (!gst_structure_get_uint (s, "ssrc", &ssrc))
285 GST_DEBUG_OBJECT (rtx,
286 "request seqnum: %" G_GUINT16_FORMAT ", ssrc: %" G_GUINT32_FORMAT,
289 g_mutex_lock (&rtx->lock);
290 /* check if request is for us */
291 if (rtx->master_ssrc == ssrc) {
293 BufferQueueItem search_item;
295 /* update statistics */
296 ++rtx->num_rtx_requests;
298 search_item.seqnum = seqnum;
299 iter = g_sequence_lookup (rtx->queue, &search_item,
300 (GCompareDataFunc) buffer_queue_items_cmp, NULL);
302 BufferQueueItem *item = g_sequence_get (iter);
303 GST_DEBUG_OBJECT (rtx, "found %" G_GUINT16_FORMAT, item->seqnum);
304 g_queue_push_tail (rtx->pending, gst_buffer_ref (item->buffer));
307 g_mutex_unlock (&rtx->lock);
309 gst_event_unref (event);
312 /* This event usually comes from the downstream gstrtpsession */
313 } else if (gst_structure_has_name (s, "GstRTPCollision")) {
316 if (!gst_structure_get_uint (s, "ssrc", &ssrc))
319 GST_DEBUG_OBJECT (rtx, "collision ssrc: %" G_GUINT32_FORMAT, ssrc);
321 g_mutex_lock (&rtx->lock);
323 /* choose another ssrc for our retransmited stream */
324 if (ssrc == rtx->rtx_ssrc) {
325 rtx->rtx_ssrc = choose_ssrc (rtx);
327 /* clear buffers we already saved */
328 g_sequence_remove_range (g_sequence_get_begin_iter (rtx->queue),
329 g_sequence_get_end_iter (rtx->queue));
331 /* clear buffers that are about to be retransmited */
332 g_queue_foreach (rtx->pending, (GFunc) gst_buffer_unref, NULL);
333 g_queue_clear (rtx->pending);
335 g_mutex_unlock (&rtx->lock);
337 /* no need to forward to payloader because we make sure to have
340 gst_event_unref (event);
343 g_mutex_unlock (&rtx->lock);
345 /* forward event to payloader in case collided ssrc is
347 res = gst_pad_event_default (pad, parent, event);
350 res = gst_pad_event_default (pad, parent, event);
355 res = gst_pad_event_default (pad, parent, event);
362 gst_rtp_rtx_send_sink_event (GstPad * pad, GstObject * parent, GstEvent * event)
364 GstRtpRtxSend *rtx = GST_RTP_RTX_SEND (parent);
366 switch (GST_EVENT_TYPE (event)) {
372 gst_event_parse_caps (event, &caps);
373 g_assert (gst_caps_is_fixed (caps));
375 s = gst_caps_get_structure (caps, 0);
376 gst_structure_get_int (s, "clock-rate", &rtx->clock_rate);
378 GST_DEBUG_OBJECT (rtx, "got clock-rate from caps: %d", rtx->clock_rate);
385 return gst_pad_event_default (pad, parent, event);
388 /* like rtp_jitter_buffer_get_ts_diff() */
390 gst_rtp_rtx_send_get_ts_diff (GstRtpRtxSend * self)
392 guint64 high_ts, low_ts;
393 BufferQueueItem *high_buf, *low_buf;
397 g_sequence_get (g_sequence_iter_prev (g_sequence_get_end_iter
399 low_buf = g_sequence_get (g_sequence_get_begin_iter (self->queue));
401 if (!high_buf || !low_buf || high_buf == low_buf)
404 high_ts = high_buf->timestamp;
405 low_ts = low_buf->timestamp;
407 /* it needs to work if ts wraps */
408 if (high_ts >= low_ts) {
409 result = (guint32) (high_ts - low_ts);
411 result = (guint32) (high_ts + G_MAXUINT32 + 1 - low_ts);
414 /* return value in ms instead of clock ticks */
415 return (guint32) gst_util_uint64_scale_int (result, 1000, self->clock_rate);
418 /* Copy fixed header and extension. Add OSN before to copy payload
419 * Copy memory to avoid to manually copy each rtp buffer field.
422 _gst_rtp_rtx_buffer_new (GstBuffer * buffer, guint32 ssrc, guint16 seqnum,
425 GstMemory *mem = NULL;
426 GstRTPBuffer rtp = GST_RTP_BUFFER_INIT;
427 GstRTPBuffer new_rtp = GST_RTP_BUFFER_INIT;
428 GstBuffer *new_buffer = gst_buffer_new ();
430 guint payload_len = 0;
432 gst_rtp_buffer_map (buffer, GST_MAP_READ, &rtp);
434 /* gst_rtp_buffer_map does not map the payload so do it now */
435 gst_rtp_buffer_get_payload (&rtp);
437 /* If payload type is not set through SDP/property then
438 * just bump the value */
440 fmtp = gst_rtp_buffer_get_payload_type (&rtp) + 1;
442 /* copy fixed header */
443 mem = gst_memory_copy (rtp.map[0].memory, 0, rtp.size[0]);
444 gst_buffer_append_memory (new_buffer, mem);
446 /* copy extension if any */
448 mem = gst_memory_copy (rtp.map[1].memory, 0, rtp.size[1]);
449 gst_buffer_append_memory (new_buffer, mem);
452 /* copy payload and add OSN just before */
453 payload_len = 2 + rtp.size[2];
454 mem = gst_allocator_alloc (NULL, payload_len, NULL);
456 gst_memory_map (mem, &map, GST_MAP_WRITE);
457 GST_WRITE_UINT16_BE (map.data, gst_rtp_buffer_get_seq (&rtp));
459 memcpy (map.data + 2, rtp.data[2], rtp.size[2]);
460 gst_memory_unmap (mem, &map);
461 gst_buffer_append_memory (new_buffer, mem);
463 /* everything needed is copied */
464 gst_rtp_buffer_unmap (&rtp);
466 /* set ssrc, seqnum and fmtp */
467 gst_rtp_buffer_map (new_buffer, GST_MAP_WRITE, &new_rtp);
468 gst_rtp_buffer_set_ssrc (&new_rtp, ssrc);
469 gst_rtp_buffer_set_seq (&new_rtp, seqnum);
470 gst_rtp_buffer_set_payload_type (&new_rtp, fmtp);
471 /* RFC 4588: let other elements do the padding, as normal */
472 gst_rtp_buffer_set_padding (&new_rtp, FALSE);
473 gst_rtp_buffer_unmap (&new_rtp);
478 /* push pending retransmission packet.
479 * it constructs rtx packet from original paclets */
481 do_push (GstBuffer * buffer, GstRtpRtxSend * rtx)
483 /* RFC4588 two streams multiplexed by sending them in the same session using
484 * different SSRC values, i.e., SSRC-multiplexing. */
485 GST_DEBUG_OBJECT (rtx,
486 "retransmit seqnum: %" G_GUINT16_FORMAT ", ssrc: %" G_GUINT32_FORMAT,
487 rtx->next_seqnum, rtx->rtx_ssrc);
488 gst_pad_push (rtx->srcpad, _gst_rtp_rtx_buffer_new (buffer, rtx->rtx_ssrc,
489 rtx->next_seqnum++, rtx->rtx_payload_type));
493 gst_rtp_rtx_send_chain (GstPad * pad, GstObject * parent, GstBuffer * buffer)
495 GstRtpRtxSend *rtx = GST_RTP_RTX_SEND (parent);
496 GstFlowReturn ret = GST_FLOW_ERROR;
497 GQueue *pending = NULL;
498 GstRTPBuffer rtp = GST_RTP_BUFFER_INIT;
499 BufferQueueItem *item;
501 guint32 ssrc, rtptime;
503 rtx = GST_RTP_RTX_SEND (parent);
505 /* read the information we want from the buffer */
506 gst_rtp_buffer_map (buffer, GST_MAP_READ, &rtp);
507 seqnum = gst_rtp_buffer_get_seq (&rtp);
508 ssrc = gst_rtp_buffer_get_ssrc (&rtp);
509 rtptime = gst_rtp_buffer_get_timestamp (&rtp);
510 gst_rtp_buffer_unmap (&rtp);
512 g_mutex_lock (&rtx->lock);
514 /* retrieve master stream ssrc */
515 rtx->master_ssrc = ssrc;
516 /* check if our initial aux ssrc is equal to master */
517 if (rtx->rtx_ssrc == rtx->master_ssrc)
520 /* add current rtp buffer to queue history */
521 item = g_new0 (BufferQueueItem, 1);
522 item->seqnum = seqnum;
523 item->timestamp = rtptime;
524 item->buffer = gst_buffer_ref (buffer);
525 g_sequence_append (rtx->queue, item);
527 /* remove oldest packets from history if they are too many */
528 if (rtx->max_size_packets) {
529 while (g_sequence_get_length (rtx->queue) > rtx->max_size_packets)
530 g_sequence_remove (g_sequence_get_begin_iter (rtx->queue));
532 if (rtx->max_size_time) {
533 while (gst_rtp_rtx_send_get_ts_diff (rtx) > rtx->max_size_time)
534 g_sequence_remove (g_sequence_get_begin_iter (rtx->queue));
537 /* within lock, get packets that have to be retransmited */
538 if (g_queue_get_length (rtx->pending) > 0) {
539 pending = rtx->pending;
540 rtx->pending = g_queue_new ();
542 /* update statistics - assume we will succeed to retransmit those packets */
543 rtx->num_rtx_packets += g_queue_get_length (pending);
546 /* transfer payload type while holding the lock */
547 rtx->rtx_payload_type = rtx->rtx_payload_type_pending;
549 /* no need to hold the lock to push rtx packets */
550 g_mutex_unlock (&rtx->lock);
552 /* retransmit requested packets */
554 g_queue_foreach (pending, (GFunc) do_push, rtx);
555 g_queue_free_full (pending, (GDestroyNotify) gst_buffer_unref);
559 "push seqnum: %" G_GUINT16_FORMAT ", ssrc: %" G_GUINT32_FORMAT, seqnum,
562 /* push current rtp packet */
563 ret = gst_pad_push (rtx->srcpad, buffer);
569 gst_rtp_rtx_send_get_property (GObject * object,
570 guint prop_id, GValue * value, GParamSpec * pspec)
572 GstRtpRtxSend *rtx = GST_RTP_RTX_SEND (object);
576 g_mutex_lock (&rtx->lock);
577 g_value_set_uint (value, rtx->rtx_ssrc);
578 g_mutex_unlock (&rtx->lock);
580 case PROP_RTX_PAYLOAD_TYPE:
581 g_mutex_lock (&rtx->lock);
582 g_value_set_uint (value, rtx->rtx_payload_type_pending);
583 g_mutex_unlock (&rtx->lock);
585 case PROP_MAX_SIZE_TIME:
586 g_mutex_lock (&rtx->lock);
587 g_value_set_uint (value, rtx->max_size_time);
588 g_mutex_unlock (&rtx->lock);
590 case PROP_MAX_SIZE_PACKETS:
591 g_mutex_lock (&rtx->lock);
592 g_value_set_uint (value, rtx->max_size_packets);
593 g_mutex_unlock (&rtx->lock);
595 case PROP_NUM_RTX_REQUESTS:
596 g_mutex_lock (&rtx->lock);
597 g_value_set_uint (value, rtx->num_rtx_requests);
598 g_mutex_unlock (&rtx->lock);
600 case PROP_NUM_RTX_PACKETS:
601 g_mutex_lock (&rtx->lock);
602 g_value_set_uint (value, rtx->num_rtx_packets);
603 g_mutex_unlock (&rtx->lock);
606 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
612 gst_rtp_rtx_send_set_property (GObject * object,
613 guint prop_id, const GValue * value, GParamSpec * pspec)
615 GstRtpRtxSend *rtx = GST_RTP_RTX_SEND (object);
619 g_mutex_lock (&rtx->lock);
620 rtx->rtx_ssrc = g_value_get_uint (value);
621 g_mutex_unlock (&rtx->lock);
623 case PROP_RTX_PAYLOAD_TYPE:
624 g_mutex_lock (&rtx->lock);
625 rtx->rtx_payload_type_pending = g_value_get_uint (value);
626 g_mutex_unlock (&rtx->lock);
628 case PROP_MAX_SIZE_TIME:
629 g_mutex_lock (&rtx->lock);
630 rtx->max_size_time = g_value_get_uint (value);
631 g_mutex_unlock (&rtx->lock);
633 case PROP_MAX_SIZE_PACKETS:
634 g_mutex_lock (&rtx->lock);
635 rtx->max_size_packets = g_value_get_uint (value);
636 g_mutex_unlock (&rtx->lock);
639 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
644 static GstStateChangeReturn
645 gst_rtp_rtx_send_change_state (GstElement * element, GstStateChange transition)
647 GstStateChangeReturn ret;
650 rtx = GST_RTP_RTX_SEND (element);
652 switch (transition) {
658 GST_ELEMENT_CLASS (gst_rtp_rtx_send_parent_class)->change_state (element,
661 switch (transition) {
662 case GST_STATE_CHANGE_PAUSED_TO_READY:
663 gst_rtp_rtx_send_reset (rtx, TRUE);
673 gst_rtp_rtx_send_plugin_init (GstPlugin * plugin)
675 GST_DEBUG_CATEGORY_INIT (gst_rtp_rtx_send_debug, "rtprtxsend", 0,
676 "rtp retransmission sender");
678 return gst_element_register (plugin, "rtprtxsend", GST_RANK_NONE,
679 GST_TYPE_RTP_RTX_SEND);