Top |
Properties
gboolean | do-lost | Read / Write |
gboolean | drop-on-latency | Read / Write |
guint | latency | Read / Write |
gint64 | ts-offset | Read / Write |
RTPJitterBufferMode | mode | Read / Write |
gint | percent | Read |
gboolean | do-retransmission | Read / Write |
gint | rtx-delay | Read / Write |
gint | rtx-delay-reorder | Read / Write |
gint | rtx-retry-period | Read / Write |
gint | rtx-retry-timeout | Read / Write |
GstStructure * | stats | Read |
guint | rtx-min-delay | Read / Write |
gint | rtx-min-retry-timeout | Read / Write |
gint | rtx-max-retries | Read / Write |
gboolean | rtx-next-seqnum | Read / Write |
guint | max-dropout-time | Read / Write |
guint | max-misorder-time | Read / Write |
gint | max-rtcp-rtp-time-diff | Read / Write |
gboolean | rfc7273-sync | Read / Write |
gint | rtx-deadline | Read / Write |
guint | rtx-stats-timeout | Read / Write |
guint | faststart-min-packets | Read / Write |
guint64 | max-ts-offset-adjustment | Read / Write |
Signals
void | clear-pt-map | Action |
void | handle-sync | Run Last |
void | on-npt-stop | Run Last |
GstCaps* | request-pt-map | Run Last |
guint64 | 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 |
Synopsis
Element Information
plugin |
rtpmanager |
author |
Philippe Kalaf <philippe.kalaf@collabora.co.uk>, Wim Taymans <wim.taymans@gmail.com> |
class |
Filter/Network/RTP |
Property Details
The “do-lost”
property
“do-lost” gboolean
Send out a GstRTPPacketLost event downstream when a packet is considered lost.
Flags: Read / Write
Default value: FALSE
The “drop-on-latency”
property
“drop-on-latency” gboolean
Drop oldest buffers when the queue is completely filled.
Flags: Read / Write
Default value: FALSE
The “latency”
property
“latency” guint
The maximum latency of the jitterbuffer. Packets will be kept in the buffer for at most this time.
Flags: Read / Write
Default value: 200
The “ts-offset”
property
“ts-offset” gint64
Adjust GStreamer output buffer timestamps in the jitterbuffer with offset. This is mainly used to ensure interstream synchronisation.
Flags: Read / Write
Default value: 0
The “mode”
property
“mode” RTPJitterBufferMode
Control the buffering and timestamping mode used by the jitterbuffer.
Flags: Read / Write
Default value: Slave receiver to sender clock
The “percent”
property
“percent” gint
The percent of the jitterbuffer that is filled.
Flags: Read
Allowed values: [0,100]
Default value: 0
The “do-retransmission”
property
“do-retransmission” gboolean
Send out a GstRTPRetransmission event upstream when a packet is considered late and should be retransmitted.
Flags: Read / Write
Default value: FALSE
Since: 1.2
The “rtx-delay”
property
“rtx-delay” gint
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.
Flags: Read / Write
Allowed values: >= G_MAXULONG
Default value: -1
Since: 1.2
The “rtx-delay-reorder”
property
“rtx-delay-reorder” gint
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. When 0 is used packet reordering alone will not cause a retransmission event (Since 1.10).
Flags: Read / Write
Allowed values: >= G_MAXULONG
Default value: 3
Since: 1.2
The “rtx-retry-period”
property
“rtx-retry-period” gint
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.
Flags: Read / Write
Allowed values: >= G_MAXULONG
Default value: -1
Since: 1.2
The “rtx-retry-timeout”
property
“rtx-retry-timeout” gint
Retry sending a transmission event after this timeout in ms (-1 automatic).
Flags: Read / Write
Allowed values: >= G_MAXULONG
Default value: -1
The “stats”
property
“stats” GstStructure *
Various jitterbuffer statistics. This property returns a GstStructure with name application/x-rtp-jitterbuffer-stats with the following fields:
guint64
"num-pushed"
: the number of packets pushed out.guint64
"num-lost"
: the number of packets considered lost.guint64
"num-late"
: the number of packets arriving too late.guint64
"num-duplicates"
: the number of duplicate packets.guint64
"rtx-count"
: the number of retransmissions requested.guint64
"rtx-success-count"
: the number of successful retransmissions.gdouble
"rtx-per-packet"
: average number of RTX per packet.guint64
"rtx-rtt"
: average round trip time per RTX.
Flags: Read
Since: 1.4
The “rtx-min-delay”
property
“rtx-min-delay” guint
When a packet did not arrive at the expected time, wait at least this extra amount of time before sending a retransmission event.
Flags: Read / Write
Default value: 0
Since: 1.6
The “rtx-min-retry-timeout”
property
“rtx-min-retry-timeout” gint
Minimum timeout between sending a transmission event in ms (-1 automatic).
Flags: Read / Write
Allowed values: >= G_MAXULONG
Default value: -1
The “rtx-max-retries”
property
“rtx-max-retries” gint
The maximum number of retries to request a retransmission.
This implies that as maximum (rtx-max-retries + 1) retransmissions will be requested. When -1 is used, the number of retransmission request will not be limited.
Flags: Read / Write
Allowed values: >= G_MAXULONG
Default value: -1
Since: 1.6
The “rtx-next-seqnum”
property
“rtx-next-seqnum” gboolean
Estimate when the next packet should arrive and schedule a retransmission request for it. This is, when packet N arrives, a GstRTPRetransmission event is schedule for packet N+1. So it will be requested if it does not arrive at the expected time. The expected time is calculated using the dts of N and the packet spacing.
Flags: Read / Write
Default value: TRUE
Since: 1.6
The “max-dropout-time”
property
“max-dropout-time” guint
The maximum time (milliseconds) of missing packets tolerated.
Flags: Read / Write
Default value: 60000
The “max-misorder-time”
property
“max-misorder-time” guint
The maximum time (milliseconds) of misordered packets tolerated.
Flags: Read / Write
Default value: 2000
The “max-rtcp-rtp-time-diff”
property
“max-rtcp-rtp-time-diff” gint
The maximum amount of time in ms that the RTP time in the RTCP SRs is allowed to be ahead of the last RTP packet we received. Use -1 to disable ignoring of RTCP packets.
Flags: Read / Write
Allowed values: >= G_MAXULONG
Default value: 1000
Since: 1.8
The “rfc7273-sync”
property
“rfc7273-sync” gboolean
Synchronize received streams to the RFC7273 clock (requires clock and offset to be provided).
Flags: Read / Write
Default value: FALSE
The “rtx-deadline”
property
“rtx-deadline” gint
The deadline for a valid RTX request in ms.
How long the RTX RTCP will be valid for. When -1 is used, the size of the jitterbuffer will be used.
Flags: Read / Write
Allowed values: >= G_MAXULONG
Default value: -1
Since: 1.10
The “rtx-stats-timeout”
property
“rtx-stats-timeout” guint
The time to wait for a retransmitted packet after it has been considered lost in order to collect statistics (ms).
Flags: Read / Write
Default value: 1000
The “faststart-min-packets”
property
“faststart-min-packets” guint
The number of consecutive packets needed to start (set to 0 to disable faststart. The jitterbuffer will by default start after the latency has elapsed)
Flags: Read / Write
Default value: 0
Since: 1.14
The “max-ts-offset-adjustment”
property
“max-ts-offset-adjustment” guint64
The maximum number of nanoseconds per frame that time offset may be adjusted with. This is used to avoid sudden large changes to time stamps.
Flags: Read / Write
Default value: 0
Signal Details
The “clear-pt-map”
signal
void user_function (GstRtpJitterBuffer *buffer, gpointer user_data)
Invalidate the clock-rate as obtained with the “request-pt-map” signal.
Parameters
buffer |
the object which received the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Action
The “handle-sync”
signal
void user_function (GstRtpJitterBuffer *buffer, GstStructure *struct, gpointer user_data)
Be notified of new sync values.
Parameters
buffer |
the object which received the signal |
|
struct |
a GstStructure containing sync values. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “on-npt-stop”
signal
void user_function (GstRtpJitterBuffer *buffer, gpointer user_data)
Signal that the jitterbufer has pushed the RTP packet that corresponds to the npt-stop position.
Parameters
buffer |
the object which received the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “request-pt-map”
signal
GstCaps* user_function (GstRtpJitterBuffer *buffer, guint pt, gpointer user_data)
Request the payload type as GstCaps for pt
.
Parameters
buffer |
the object which received the signal |
|
pt |
the pt |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
The “set-active”
signal
guint64 user_function (GstRtpJitterBuffer *buffer, gboolean Returns, guint64 arg2, gpointer user_data)
Start pushing out packets with the given base time. This signal is only useful in buffering mode.
Parameters
buffer |
the object which received the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Action