rtpjitterbuffer

rtpjitterbuffer — A buffer that deals with network jitter and other transmission faults

Synopsis

struct              GstRtpJitterBuffer;

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GstObject
               +----GstElement
                     +----GstRtpJitterBuffer

Properties

  "do-lost"                  gboolean              : Read / Write
  "drop-on-latency"          gboolean              : Read / Write
  "latency"                  guint                 : Read / Write
  "ts-offset"                gint64                : Read / Write
  "mode"                     RTPJitterBufferMode   : Read / Write
  "percent"                  gint                  : Read
  "do-retransmission"        gboolean              : Read / Write
  "rtx-delay"                gint                  : Read / Write
  "rtx-delay-reorder"        gint                  : Read / Write
  "rtx-retry-period"         gint                  : Read / Write
  "rtx-retry-timeout"        gint                  : Read / Write
  "stats"                    GstStructure*         : Read

Signals

  "clear-pt-map"                                   : Action
  "handle-sync"                                    : Run Last
  "on-npt-stop"                                    : Run Last
  "request-pt-map"                                 : Run Last
  "set-active"                                     : Action

Description

This element reorders and removes duplicate RTP packets as they are received from a network source.

The element needs the clock-rate of the RTP payload in order to estimate the delay. This information is obtained either from the caps on the sink pad or, when no caps are present, from the "request-pt-map" signal. To clear the previous pt-map use the "clear-pt-map" signal.

The rtpjitterbuffer will wait for missing packets up to a configurable time limit using the "latency" property. Packets arriving too late are considered to be lost packets. If the "do-lost" property is set, lost packets will result in a custom serialized downstream event of name GstRTPPacketLost. The lost packet events are usually used by a depayloader or other element to create concealment data or some other logic to gracefully handle the missing packets.

The jitterbuffer will use the DTS (or PTS if no DTS is set) of the incomming buffer and the rtptime inside the RTP packet to create a PTS on the outgoing buffer.

The jitterbuffer can also be configured to send early retransmission events upstream by setting the "do-retransmission" property. In this mode, the jitterbuffer tries to estimate when a packet should arrive and sends a custom upstream event named GstRTPRetransmissionRequest when the packet is considered late. The initial expected packet arrival time is calculated as follows:

  • If seqnum N arrived at time T, seqnum N+1 is expected to arrive at T + packet-spacing + "rtx-delay". The packet spacing is calculated from the DTS (or PTS is no DTS) of two consecutive RTP packets with different rtptime.

  • If seqnum N0 arrived at time T0 and seqnum Nm arrived at time Tm, seqnum Ni is expected at time Ti = T0 + i*(Tm - T0)/(Nm - N0). Any previously scheduled timeout is overwritten.

  • If seqnum N arrived, all seqnum older than N - "rtx-delay-reorder" are considered late immediately. This is to request fast feedback for abonormally reorder packets before any of the previous timeouts is triggered.

A late packet triggers the GstRTPRetransmissionRequest custom upstream event. After the initial timeout expires and the retransmission event is sent, the timeout is scheduled for T + "rtx-retry-timeout". If the missing packet did not arrive after "rtx-retry-timeout", a new GstRTPRetransmissionRequest is sent upstream and the timeout is rescheduled again for T + "rtx-retry-timeout". This repeats until "rtx-retry-period" elapsed, at which point no further retransmission requests are sent and the regular logic is performed to schedule a lost packet as discussed above.

This element acts as a live element and so adds "latency" to the pipeline.

This element will automatically be used inside rtpbin.

Example pipelines

1
gst-launch-1.0 rtspsrc location=rtsp://192.168.1.133:8554/mpeg1or2AudioVideoTest ! rtpjitterbuffer ! rtpmpvdepay ! mpeg2dec ! xvimagesink
Connect to a streaming server and decode the MPEG video. The jitterbuffer is inserted into the pipeline to smooth out network jitter and to reorder the out-of-order RTP packets.

Synopsis

Element Information

plugin

rtpmanager

author

Philippe Kalaf <philippe.kalaf@collabora.co.uk>, Wim Taymans <wim.taymans@gmail.com>

class

Filter/Network/RTP

Element Pads

name

sink

direction

sink

presence

always

details

application/x-rtp, clock-rate=(int)[ 1, 2147483647 ]

name

sink_rtcp

direction

sink

presence

request

details

application/x-rtcp

name

src

direction

source

presence

always

details

application/x-rtp

Details

struct GstRtpJitterBuffer

struct GstRtpJitterBuffer;

Opaque jitterbuffer structure.

Property Details

The "do-lost" property

  "do-lost"                  gboolean              : Read / Write

Send out a GstRTPPacketLost event downstream when a packet is considered lost.

Default value: FALSE


The "drop-on-latency" property

  "drop-on-latency"          gboolean              : Read / Write

Drop oldest buffers when the queue is completely filled.

Default value: FALSE


The "latency" property

  "latency"                  guint                 : Read / Write

The maximum latency of the jitterbuffer. Packets will be kept in the buffer for at most this time.

Default value: 200


The "ts-offset" property

  "ts-offset"                gint64                : Read / Write

Adjust GStreamer output buffer timestamps in the jitterbuffer with offset. This is mainly used to ensure interstream synchronisation.

Default value: 0


The "mode" property

  "mode"                     RTPJitterBufferMode   : Read / Write

Control the buffering and timestamping mode used by the jitterbuffer.

Default value: Slave receiver to sender clock


The "percent" property

  "percent"                  gint                  : Read

The percent of the jitterbuffer that is filled.

Allowed values: [0,100]

Default value: 0


The "do-retransmission" property

  "do-retransmission"        gboolean              : Read / Write

Send out a GstRTPRetransmission event upstream when a packet is considered late and should be retransmitted.

Default value: FALSE

Since 1.2


The "rtx-delay" property

  "rtx-delay"                gint                  : Read / Write

When a packet did not arrive at the expected time, wait this extra amount of time before sending a retransmission event.

When -1 is used, the max jitter will be used as extra delay.

Allowed values: >= G_MAXULONG

Default value: -1

Since 1.2


The "rtx-delay-reorder" property

  "rtx-delay-reorder"        gint                  : Read / Write

Assume that a retransmission event should be sent when we see this much packet reordering.

When -1 is used, the value will be estimated based on observed packet reordering.

Allowed values: >= G_MAXULONG

Default value: 3

Since 1.2


The "rtx-retry-period" property

  "rtx-retry-period"         gint                  : Read / Write

The amount of time to try to get a retransmission.

When -1 is used, the value will be estimated based on the jitterbuffer latency and the observed round trip time.

Allowed values: >= G_MAXULONG

Default value: -1

Since 1.2


The "rtx-retry-timeout" property

  "rtx-retry-timeout"        gint                  : Read / Write

Retry sending a transmission event after this timeout in ms (-1 automatic).

Allowed values: >= G_MAXULONG

Default value: -1


The "stats" property

  "stats"                    GstStructure*         : Read

Various jitterbuffer statistics. This property returns a GstStructure with name application/x-rtp-jitterbuffer-stats with the following fields:

"rtx-count" G_TYPE_UINT64 The number of retransmissions requested "rtx-success-count" G_TYPE_UINT64 The number of successful retransmissions "rtx-per-packet" G_TYPE_DOUBLE Average number of RTX per packet "rtx-rtt" G_TYPE_UINT64 Average round trip time per RTX

Since 1.4

Signal Details

The "clear-pt-map" signal

void                user_function                      (GstRtpJitterBuffer *buffer,
                                                        gpointer            user_data)      : Action

Invalidate the clock-rate as obtained with the "request-pt-map" signal.

buffer :

the object which received the signal

user_data :

user data set when the signal handler was connected.

The "handle-sync" signal

void                user_function                      (GstRtpJitterBuffer *buffer,
                                                        GstStructure       *struct,
                                                        gpointer            user_data)      : Run Last

Be notified of new sync values.

buffer :

the object which received the signal

struct :

a GstStructure containing sync values.

user_data :

user data set when the signal handler was connected.

The "on-npt-stop" signal

void                user_function                      (GstRtpJitterBuffer *buffer,
                                                        gpointer            user_data)      : Run Last

Signal that the jitterbufer has pushed the RTP packet that corresponds to the npt-stop position.

buffer :

the object which received the signal

user_data :

user data set when the signal handler was connected.

The "request-pt-map" signal

GstCaps*            user_function                      (GstRtpJitterBuffer *buffer,
                                                        guint               pt,
                                                        gpointer            user_data)      : Run Last

Request the payload type as GstCaps for pt.

buffer :

the object which received the signal

pt :

the pt

user_data :

user data set when the signal handler was connected.

The "set-active" signal

guint64             user_function                      (GstRtpJitterBuffer *buffer,
                                                        gboolean            Returns,
                                                        guint64             arg2,
                                                        gpointer            user_data)      : Action

Start pushing out packets with the given base time. This signal is only useful in buffering mode.

buffer :

the object which received the signal

user_data :

user data set when the signal handler was connected.

Returns :

the time of the last pushed packet.