1 /* GStreamer plugin for forward error correction
2 * Copyright (C) 2017 Pexip
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18 * Author: Mikhail Fludkov <misha@pexip.com>
22 * SECTION:element-rtpulpfecdec
23 * @short_description: Generic RTP Forward Error Correction (FEC) decoder
24 * @title: rtpulpfecdec
26 * Generic Forward Error Correction (FEC) decoder for Uneven Level
27 * Protection (ULP) as described in RFC 5109.
29 * This element will work in combination with an upstream #GstRtpStorage
30 * element and attempt to recover packets declared lost through custom
31 * 'GstRTPPacketLost' events, usually emitted by #GstRtpJitterBuffer.
33 * As such, this element cannot be usefully used from the command line,
34 * because a reference to the upstream storage object needs to be
35 * provided to it through its #GstRtpUlpFecDec:storage property, example
36 * programs are available at
37 * <https://github.com/sdroege/gstreamer-rs/blob/master/examples/src/bin/rtpfecserver.rs>
39 * <https://github.com/sdroege/gstreamer-rs/blob/master/examples/src/bin/rtpfecclient.rs>.
41 * Additionally, the payload types of the protection packets *must* be
42 * provided to this element via its #GstRtpUlpFecDec:pt property.
44 * When using #GstRtpBin, this element should be inserted through the
45 * #GstRtpBin::request-fec-decoder signal.
47 * See also: #GstRtpUlpFecEnc, #GstRtpBin, #GstRtpStorage
51 #include <gst/rtp/gstrtpbuffer.h>
52 #include <gst/rtp/gstrtp-enumtypes.h>
54 #include "rtpulpfeccommon.h"
55 #include "gstrtpulpfecdec.h"
57 static GstStaticPadTemplate sinktemplate = GST_STATIC_PAD_TEMPLATE ("sink",
60 GST_STATIC_CAPS ("application/x-rtp")
63 static GstStaticPadTemplate srctemplate = GST_STATIC_PAD_TEMPLATE ("src",
66 GST_STATIC_CAPS ("application/x-rtp")
79 #define DEFAULT_FEC_PT 0
81 static GParamSpec *klass_properties[N_PROPERTIES] = { NULL, };
83 GST_DEBUG_CATEGORY (gst_rtp_ulpfec_dec_debug);
84 #define GST_CAT_DEFAULT (gst_rtp_ulpfec_dec_debug)
86 G_DEFINE_TYPE (GstRtpUlpFecDec, gst_rtp_ulpfec_dec, GST_TYPE_ELEMENT);
88 #define RTP_FEC_MAP_INFO_NTH(dec, data) (&g_array_index (\
89 ((GstRtpUlpFecDec *)dec)->info_arr, \
91 GPOINTER_TO_UINT(data)))
94 _compare_fec_map_info (gconstpointer a, gconstpointer b, gpointer userdata)
97 gst_rtp_buffer_get_seq (&RTP_FEC_MAP_INFO_NTH (userdata, a)->rtp);
99 gst_rtp_buffer_get_seq (&RTP_FEC_MAP_INFO_NTH (userdata, b)->rtp);
100 return gst_rtp_buffer_compare_seqnum (bseq, aseq);
104 gst_rtp_ulpfec_dec_start (GstRtpUlpFecDec * self, GstBufferList * buflist,
105 guint8 fec_pt, guint16 lost_seq)
107 guint fec_packets = 0;
109 g_assert (NULL == self->info_media);
110 g_assert (0 == self->info_fec->len);
111 g_assert (0 == self->info_arr->len);
113 g_array_set_size (self->info_arr, gst_buffer_list_length (buflist));
116 i < gst_buffer_list_length (buflist) && !self->lost_packet_from_storage;
118 GstBuffer *buffer = gst_buffer_list_get (buflist, i);
119 RtpUlpFecMapInfo *info = RTP_FEC_MAP_INFO_NTH (self, i);
121 if (!rtp_ulpfec_map_info_map (gst_buffer_ref (buffer), info))
122 g_assert_not_reached ();
124 if (fec_pt == gst_rtp_buffer_get_payload_type (&info->rtp)) {
125 GST_DEBUG_RTP_PACKET (self, "rtp header (fec)", &info->rtp);
128 if (rtp_ulpfec_buffer_is_valid (&info->rtp)) {
129 GST_DEBUG_FEC_PACKET (self, &info->rtp);
130 g_ptr_array_add (self->info_fec, GUINT_TO_POINTER (i));
133 GST_LOG_RTP_PACKET (self, "rtp header (incoming)", &info->rtp);
135 if (lost_seq == gst_rtp_buffer_get_seq (&info->rtp)) {
136 GST_DEBUG_OBJECT (self, "Received lost packet from from the storage");
137 g_list_free (self->info_media);
138 self->info_media = NULL;
139 self->lost_packet_from_storage = TRUE;
142 g_list_insert_sorted_with_data (self->info_media,
143 GUINT_TO_POINTER (i), _compare_fec_map_info, self);
146 if (!self->lost_packet_from_storage) {
147 self->fec_packets_received += fec_packets;
148 self->fec_packets_rejected += fec_packets - self->info_fec->len;
153 gst_rtp_ulpfec_dec_stop (GstRtpUlpFecDec * self)
155 g_array_set_size (self->info_arr, 0);
156 g_ptr_array_set_size (self->info_fec, 0);
157 g_list_free (self->info_media);
158 self->info_media = NULL;
159 self->lost_packet_from_storage = FALSE;
160 self->lost_packet_returned = FALSE;
164 gst_rtp_ulpfec_dec_get_media_buffers_mask (GstRtpUlpFecDec * self,
165 guint16 fec_seq_base)
168 for (GList * it = self->info_media; it; it = it->next) {
169 RtpUlpFecMapInfo *info = RTP_FEC_MAP_INFO_NTH (self, it->data);
171 rtp_ulpfec_packet_mask_from_seqnum (gst_rtp_buffer_get_seq (&info->rtp),
178 gst_rtp_ulpfec_dec_is_recovered_pt_valid (GstRtpUlpFecDec * self, gint media_pt,
181 if (media_pt == recovered_pt)
184 for (GList * it = self->info_media; it; it = it->next) {
185 RtpUlpFecMapInfo *info = RTP_FEC_MAP_INFO_NTH (self, it->data);
186 if (gst_rtp_buffer_get_payload_type (&info->rtp) == recovered_pt)
193 gst_rtp_ulpfec_dec_recover_from_fec (GstRtpUlpFecDec * self,
194 RtpUlpFecMapInfo * info_fec, guint32 ssrc, gint media_pt, guint16 seq,
197 guint64 fec_mask = rtp_ulpfec_buffer_get_mask (&info_fec->rtp);
198 gboolean fec_mask_long = rtp_ulpfec_buffer_get_fechdr (&info_fec->rtp)->L;
199 guint16 fec_seq_base = rtp_ulpfec_buffer_get_seq_base (&info_fec->rtp);
202 g_array_set_size (self->scratch_buf, 0);
203 rtp_buffer_to_ulpfec_bitstring (&info_fec->rtp, self->scratch_buf, TRUE,
206 for (GList * it = self->info_media; it; it = it->next) {
207 RtpUlpFecMapInfo *info = RTP_FEC_MAP_INFO_NTH (self, it->data);
208 guint64 packet_mask =
209 rtp_ulpfec_packet_mask_from_seqnum (gst_rtp_buffer_get_seq (&info->rtp),
212 if (fec_mask & packet_mask) {
213 fec_mask ^= packet_mask;
214 rtp_buffer_to_ulpfec_bitstring (&info->rtp, self->scratch_buf, FALSE,
220 rtp_ulpfec_bitstring_to_media_rtp_buffer (self->scratch_buf,
221 fec_mask_long, ssrc, seq);
223 /* We are about to put recovered packet back in self->info_media to be able
224 * to reuse it later for recovery of other packets
226 gint i = self->info_arr->len;
227 RtpUlpFecMapInfo *info;
230 g_array_set_size (self->info_arr, self->info_arr->len + 1);
231 info = RTP_FEC_MAP_INFO_NTH (self, i);
233 if (!rtp_ulpfec_map_info_map (gst_buffer_ref (ret), info)) {
234 GST_WARNING_OBJECT (self, "Invalid recovered packet");
235 goto recovered_packet_invalid;
238 recovered_pt = gst_rtp_buffer_get_payload_type (&info->rtp);
239 if (!gst_rtp_ulpfec_dec_is_recovered_pt_valid (self, media_pt,
241 GST_WARNING_OBJECT (self,
242 "Recovered packet has unexpected payload type (%u)", recovered_pt);
243 goto recovered_packet_invalid;
246 GST_DEBUG_RTP_PACKET (self, "rtp header (recovered)", &info->rtp);
248 g_list_insert_sorted_with_data (self->info_media, GUINT_TO_POINTER (i),
249 _compare_fec_map_info, self);
250 *dst_pt = recovered_pt;
254 recovered_packet_invalid:
255 g_array_set_size (self->info_arr, self->info_arr->len - 1);
256 gst_buffer_unref (ret);
261 gst_rtp_ulpfec_dec_recover_from_storage (GstRtpUlpFecDec * self,
262 guint8 * dst_pt, guint16 * dst_seq)
264 RtpUlpFecMapInfo *info;
266 if (self->lost_packet_returned)
269 g_assert (g_list_length (self->info_media) == 1);
271 info = RTP_FEC_MAP_INFO_NTH (self, self->info_media->data);
272 *dst_seq = gst_rtp_buffer_get_seq (&info->rtp);
273 *dst_pt = gst_rtp_buffer_get_payload_type (&info->rtp);
274 self->lost_packet_returned = TRUE;
275 GST_DEBUG_RTP_PACKET (self, "rtp header (recovered)", &info->rtp);
276 return gst_buffer_ref (info->rtp.buffer);
280 gst_rtp_ulpfec_dec_recover (GstRtpUlpFecDec * self, guint32 ssrc, gint media_pt,
281 guint8 * dst_pt, guint16 * dst_seq)
283 guint64 media_mask = 0;
284 gint media_mask_seq_base = -1;
286 if (self->lost_packet_from_storage)
287 return gst_rtp_ulpfec_dec_recover_from_storage (self, dst_pt, dst_seq);
289 /* Looking for a FEC packet which can be used for recovery */
290 for (gsize i = 0; i < self->info_fec->len; ++i) {
291 RtpUlpFecMapInfo *info = RTP_FEC_MAP_INFO_NTH (self,
292 g_ptr_array_index (self->info_fec, i));
293 guint16 seq_base = rtp_ulpfec_buffer_get_seq_base (&info->rtp);
294 guint64 fec_mask = rtp_ulpfec_buffer_get_mask (&info->rtp);
295 guint64 missing_packets_mask;
297 if (media_mask_seq_base != (gint) seq_base) {
298 media_mask_seq_base = seq_base;
299 media_mask = gst_rtp_ulpfec_dec_get_media_buffers_mask (self, seq_base);
302 /* media_mask has 1s if packet exist.
303 * fec_mask is the mask of protected packets
304 * The statement below excludes existing packets from the protected. So
305 * we are left with 1s only for missing packets which can be recovered
306 * by this FEC packet. */
307 missing_packets_mask = fec_mask & (~media_mask);
309 /* Do we have any 1s? Checking if current FEC packet can be used for recovery */
310 if (0 != missing_packets_mask) {
311 guint trailing_zeros = __builtin_ctzll (missing_packets_mask);
313 /* Is it the only 1 in the mask? Checking if we lacking single packet in
314 * that case FEC packet can be used for recovery */
315 if (missing_packets_mask == (1ULL << trailing_zeros)) {
319 seq_base + (RTP_ULPFEC_SEQ_BASE_OFFSET_MAX (TRUE) - trailing_zeros);
321 gst_rtp_ulpfec_dec_recover_from_fec (self, info, ssrc, media_pt,
332 gst_rtp_ulpfec_dec_chain (GstPad * pad, GstObject * parent, GstBuffer * buf)
334 GstRtpUlpFecDec *self = GST_RTP_ULPFEC_DEC (parent);
336 if (G_LIKELY (GST_FLOW_OK == self->chain_return_val)) {
337 if (G_UNLIKELY (self->unset_discont_flag)) {
338 self->unset_discont_flag = FALSE;
339 buf = gst_buffer_make_writable (buf);
340 GST_BUFFER_FLAG_UNSET (buf, GST_BUFFER_FLAG_DISCONT);
342 return gst_pad_push (self->srcpad, buf);
345 gst_buffer_unref (buf);
346 return self->chain_return_val;
350 gst_rtp_ulpfec_dec_handle_packet_loss (GstRtpUlpFecDec * self, guint16 seqnum,
351 GstClockTime timestamp, GstClockTime duration)
353 gint caps_pt = self->have_caps_pt ? self->caps_pt : -1;
355 GstBufferList *buflist =
356 rtp_storage_get_packets_for_recovery (self->storage, self->fec_pt,
357 self->caps_ssrc, seqnum);
360 GstBuffer *recovered_buffer = NULL;
361 guint16 recovered_seq = 0;
362 guint8 recovered_pt = 0;
364 gst_rtp_ulpfec_dec_start (self, buflist, self->fec_pt, seqnum);
366 while (NULL != (recovered_buffer =
367 gst_rtp_ulpfec_dec_recover (self, self->caps_ssrc, caps_pt,
368 &recovered_pt, &recovered_seq))) {
369 if (seqnum == recovered_seq) {
370 recovered_buffer = gst_buffer_make_writable (recovered_buffer);
371 GST_BUFFER_PTS (recovered_buffer) = timestamp;
372 /* GST_BUFFER_DURATION (recovered_buffer) = duration;
373 * JB does not set the duration, so we will not too */
375 if (!self->lost_packet_from_storage)
376 rtp_storage_put_recovered_packet (self->storage,
377 gst_buffer_ref (recovered_buffer), recovered_pt, self->caps_ssrc,
380 GST_DEBUG_OBJECT (self,
381 "Pushing recovered packet ssrc=0x%08x seq=%u %" GST_PTR_FORMAT,
382 self->caps_ssrc, seqnum, recovered_buffer);
385 self->unset_discont_flag = TRUE;
386 self->chain_return_val = gst_pad_push (self->srcpad, recovered_buffer);
390 rtp_storage_put_recovered_packet (self->storage,
391 recovered_buffer, recovered_pt, self->caps_ssrc, recovered_seq);
394 gst_rtp_ulpfec_dec_stop (self);
395 gst_buffer_list_unref (buflist);
398 GST_DEBUG_OBJECT (self, "Packet lost ssrc=0x%08x seq=%u", self->caps_ssrc,
405 gst_rtp_ulpfec_dec_handle_sink_event (GstPad * pad, GstObject * parent,
408 GstRtpUlpFecDec *self = GST_RTP_ULPFEC_DEC (parent);
409 gboolean forward = TRUE;
411 GST_LOG_OBJECT (self, "Received event %" GST_PTR_FORMAT, event);
413 if (GST_FLOW_OK == self->chain_return_val &&
414 GST_EVENT_CUSTOM_DOWNSTREAM == GST_EVENT_TYPE (event) &&
415 gst_event_has_name (event, "GstRTPPacketLost")) {
417 GstClockTime timestamp, duration;
419 g_assert (self->have_caps_ssrc);
420 g_assert (self->storage);
422 if (!gst_structure_get (gst_event_get_structure (event),
423 "seqnum", G_TYPE_UINT, &seqnum,
424 "timestamp", G_TYPE_UINT64, ×tamp,
425 "duration", G_TYPE_UINT64, &duration, NULL))
426 g_assert_not_reached ();
429 gst_rtp_ulpfec_dec_handle_packet_loss (self, seqnum, timestamp,
432 ++self->packets_unrecovered;
434 ++self->packets_recovered;
435 GST_DEBUG_OBJECT (self, "Unrecovered / Recovered: %lu / %lu",
436 (gulong) self->packets_unrecovered, (gulong) self->packets_recovered);
437 } else if (GST_EVENT_CAPS == GST_EVENT_TYPE (event)) {
439 gboolean have_caps_pt = FALSE;
440 gboolean have_caps_ssrc = FALSE;
444 gst_event_parse_caps (event, &caps);
446 gst_structure_get_uint (gst_caps_get_structure (caps, 0), "ssrc",
449 gst_structure_get_int (gst_caps_get_structure (caps, 0), "payload",
452 if (self->have_caps_ssrc != have_caps_ssrc || self->caps_ssrc != caps_ssrc)
453 GST_DEBUG_OBJECT (self, "SSRC changed %u, 0x%08x -> %u, 0x%08x",
454 self->have_caps_ssrc, self->caps_ssrc, have_caps_ssrc, caps_ssrc);
455 if (self->have_caps_pt != have_caps_pt || self->caps_pt != caps_pt)
456 GST_DEBUG_OBJECT (self, "PT changed %u, %u -> %u, %u",
457 self->have_caps_pt, self->caps_pt, have_caps_pt, caps_pt);
459 self->have_caps_ssrc = have_caps_ssrc;
460 self->have_caps_pt = have_caps_pt;
461 self->caps_ssrc = caps_ssrc;
462 self->caps_pt = caps_pt;
466 return gst_pad_push_event (self->srcpad, event);
467 gst_event_unref (event);
472 gst_rtp_ulpfec_dec_init (GstRtpUlpFecDec * self)
474 self->srcpad = gst_pad_new_from_static_template (&srctemplate, "src");
475 self->sinkpad = gst_pad_new_from_static_template (&sinktemplate, "sink");
476 GST_PAD_SET_PROXY_CAPS (self->sinkpad);
477 GST_PAD_SET_PROXY_ALLOCATION (self->sinkpad);
478 gst_pad_set_chain_function (self->sinkpad,
479 GST_DEBUG_FUNCPTR (gst_rtp_ulpfec_dec_chain));
480 gst_pad_set_event_function (self->sinkpad,
481 GST_DEBUG_FUNCPTR (gst_rtp_ulpfec_dec_handle_sink_event));
483 gst_element_add_pad (GST_ELEMENT (self), self->srcpad);
484 gst_element_add_pad (GST_ELEMENT (self), self->sinkpad);
486 self->fec_pt = DEFAULT_FEC_PT;
488 self->chain_return_val = GST_FLOW_OK;
489 self->have_caps_ssrc = FALSE;
491 self->info_fec = g_ptr_array_new ();
492 self->info_arr = g_array_new (FALSE, TRUE, sizeof (RtpUlpFecMapInfo));
493 g_array_set_clear_func (self->info_arr,
494 (GDestroyNotify) rtp_ulpfec_map_info_unmap);
495 self->scratch_buf = g_array_new (FALSE, TRUE, sizeof (guint8));
499 gst_rtp_ulpfec_dec_dispose (GObject * obj)
501 GstRtpUlpFecDec *self = GST_RTP_ULPFEC_DEC (obj);
503 GST_INFO_OBJECT (self,
505 " packets_recovered=%" G_GSIZE_FORMAT
506 " packets_unrecovered=%" G_GSIZE_FORMAT,
507 self->caps_ssrc, self->caps_pt,
508 self->packets_recovered, self->packets_unrecovered);
511 g_object_unref (self->storage);
513 g_assert (NULL == self->info_media);
514 g_assert (0 == self->info_fec->len);
515 g_assert (0 == self->info_arr->len);
517 if (self->fec_packets_received) {
518 GST_INFO_OBJECT (self,
519 " fec_packets_received=%" G_GSIZE_FORMAT
520 " fec_packets_rejected=%" G_GSIZE_FORMAT
521 " packets_rejected=%" G_GSIZE_FORMAT,
522 self->fec_packets_received,
523 self->fec_packets_rejected, self->packets_rejected);
526 g_ptr_array_free (self->info_fec, TRUE);
527 g_array_free (self->info_arr, TRUE);
528 g_array_free (self->scratch_buf, TRUE);
530 G_OBJECT_CLASS (gst_rtp_ulpfec_dec_parent_class)->dispose (obj);
534 gst_rtp_ulpfec_dec_set_property (GObject * object, guint prop_id,
535 const GValue * value, GParamSpec * pspec)
537 GstRtpUlpFecDec *self = GST_RTP_ULPFEC_DEC (object);
541 self->fec_pt = g_value_get_uint (value);
545 g_object_unref (self->storage);
546 self->storage = g_value_get_object (value);
548 g_object_ref (self->storage);
551 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
557 gst_rtp_ulpfec_dec_get_property (GObject * object, guint prop_id,
558 GValue * value, GParamSpec * pspec)
560 GstRtpUlpFecDec *self = GST_RTP_ULPFEC_DEC (object);
564 g_value_set_uint (value, self->fec_pt);
567 g_value_set_object (value, self->storage);
570 g_value_set_uint (value, (guint) self->packets_recovered);
572 case PROP_UNRECOVERED:
573 g_value_set_uint (value, (guint) self->packets_unrecovered);
576 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
582 gst_rtp_ulpfec_dec_class_init (GstRtpUlpFecDecClass * klass)
584 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
585 GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
587 GST_DEBUG_CATEGORY_INIT (gst_rtp_ulpfec_dec_debug,
588 "rtpulpfecdec", 0, "RTP FEC Decoder");
590 gst_element_class_add_pad_template (element_class,
591 gst_static_pad_template_get (&srctemplate));
592 gst_element_class_add_pad_template (element_class,
593 gst_static_pad_template_get (&sinktemplate));
595 gst_element_class_set_static_metadata (element_class,
597 "Codec/Depayloader/Network/RTP",
598 "Decodes RTP FEC (RFC5109)", "Mikhail Fludkov <misha@pexip.com>");
600 gobject_class->set_property =
601 GST_DEBUG_FUNCPTR (gst_rtp_ulpfec_dec_set_property);
602 gobject_class->get_property =
603 GST_DEBUG_FUNCPTR (gst_rtp_ulpfec_dec_get_property);
604 gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_rtp_ulpfec_dec_dispose);
606 klass_properties[PROP_PT] = g_param_spec_uint ("pt", "pt",
607 "FEC packets payload type", 0, 127,
608 DEFAULT_FEC_PT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
609 klass_properties[PROP_STORAGE] =
610 g_param_spec_object ("storage", "RTP storage", "RTP storage",
611 G_TYPE_OBJECT, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
612 klass_properties[PROP_RECOVERED] =
613 g_param_spec_uint ("recovered", "recovered",
614 "The number of recovered packets", 0, G_MAXUINT, 0,
615 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
616 klass_properties[PROP_UNRECOVERED] =
617 g_param_spec_uint ("unrecovered", "unrecovered",
618 "The number of unrecovered packets", 0, G_MAXUINT, 0,
619 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
621 g_object_class_install_properties (gobject_class, N_PROPERTIES,