rtpbin: GStreamer Good Plugins 1.0 Plugins Reference Manual

rtpbin

Properties

gboolean	do-lost	Read / Write
guint	latency	Read / Write
GstStructure *	sdes	Read / Write
gboolean	ignore-pt	Read / Write
gboolean	autoremove	Read / Write
RTPJitterBufferMode	buffer-mode	Read / Write
gboolean	ntp-sync	Read / Write
gboolean	use-pipeline-clock	Read / Write
GstRTCPSync	rtcp-sync	Read / Write
guint	rtcp-sync-interval	Read / Write
gboolean	drop-on-latency	Read / Write
gboolean	do-sync-event	Read / Write
gboolean	do-retransmission	Read / Write
GstRTPProfile	rtp-profile	Read / Write
GstRtpNtpTimeSource	ntp-time-source	Read / Write
guint	max-dropout-time	Read / Write
guint	max-misorder-time	Read / Write
gint	max-rtcp-rtp-time-diff	Read / Write
gboolean	rtcp-sync-send-time	Read / Write
gboolean	rfc7273-sync	Read / Write
guint	max-streams	Read / Write
gint64	max-ts-offset	Read / Write
guint64	max-ts-offset-adjustment	Read / Write

Signals

void	clear-pt-map	Action
RTPSession*	get-internal-session	Action
void	on-bye-ssrc	Run Last
void	on-bye-timeout	Run Last
void	on-new-ssrc	Run Last
void	on-npt-stop	Run Last
void	on-sender-timeout	Run Last
void	on-ssrc-active	Run Last
void	on-ssrc-collision	Run Last
void	on-ssrc-sdes	Run Last
void	on-ssrc-validated	Run Last
void	on-timeout	Run Last
GstCaps*	request-pt-map	Run Last
void	reset-sync	Action
void	payload-type-change	Run Last
void	new-jitterbuffer	Run Last
GstElement*	request-aux-receiver	Run Last
GstElement*	request-aux-sender	Run Last
GstElement*	request-rtcp-decoder	Run Last
GstElement*	request-rtcp-encoder	Run Last
GstElement*	request-rtp-decoder	Run Last
GstElement*	request-rtp-encoder	Run Last
void	on-new-sender-ssrc	Run Last
void	on-sender-ssrc-active	Run Last
GstElement*	get-session	Action
guint	on-bundled-ssrc	Run Last
GObject*	get-internal-storage	Action
void	new-storage	Run Last
GstElement*	request-fec-decoder	Run Last
GstElement*	request-fec-encoder	Run Last

Types and Values

struct

GstRtpBin

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GstObject
            ╰── GstElement
                ╰── GstBin
                    ╰── GstRtpBin

Implemented Interfaces

GstRtpBin implements GstChildProxy.

Description

RTP bin combines the functions of GstRtpSession, GstRtpSsrcDemux, GstRtpJitterBuffer and GstRtpPtDemux in one element. It allows for multiple RTP sessions that will be synchronized together using RTCP SR packets.

GstRtpBin is configured with a number of request pads that define the functionality that is activated, similar to the GstRtpSession element.

To use GstRtpBin as an RTP receiver, request a recv_rtp_sink_%u pad. The session number must be specified in the pad name. Data received on the recv_rtp_sink_%u pad will be processed in the GstRtpSession manager and after being validated forwarded on GstRtpSsrcDemux element. Each RTP stream is demuxed based on the SSRC and send to a GstRtpJitterBuffer. After the packets are released from the jitterbuffer, they will be forwarded to a GstRtpPtDemux element. The GstRtpPtDemux element will demux the packets based on the payload type and will create a unique pad recv_rtp_src_%u_%u_%u on rtpbin with the session number, SSRC and payload type respectively as the pad name.

To also use GstRtpBin as an RTCP receiver, request a recv_rtcp_sink_%u pad. The session number must be specified in the pad name.

If you want the session manager to generate and send RTCP packets, request the send_rtcp_src_%u pad with the session number in the pad name. Packet pushed on this pad contain SR/RR RTCP reports that should be sent to all participants in the session.

To use GstRtpBin as a sender, request a send_rtp_sink_%u pad, which will automatically create a send_rtp_src_%u pad. If the session number is not provided, the pad from the lowest available session will be returned. The session manager will modify the SSRC in the RTP packets to its own SSRC and wil forward the packets on the send_rtp_src_%u pad after updating its internal state.

GstRtpBin can also demultiplex incoming bundled streams. The first GstRtpSession will have a GstRtpSsrcDemux element splitting the streams based on their SSRC and potentially dispatched to a different GstRtpSession. Because retransmission SSRCs need to be merged with the corresponding media stream the “on-bundled-ssrc” signal is emitted so that the application can find out to which session the SSRC belongs.

The session manager needs the clock-rate of the payload types it is handling and will signal the “request-pt-map” signal when it needs such a mapping. One can clear the cached values with the “clear-pt-map” signal.

Access to the internal statistics of rtpbin is provided with the get-internal-session property. This action signal gives access to the RTPSession object which further provides action signals to retrieve the internal source and other sources.

GstRtpBin also has signals (“request-rtp-encoder”, “request-rtp-decoder”, “request-rtcp-encoder” and “request-rtp-decoder”) to dynamically request for RTP and RTCP encoders and decoders in order to support SRTP. The encoders must provide the pads rtp_sink_%u and rtp_src_%u for RTP and rtcp_sink_%u and rtcp_src_%u for RTCP. The session number will be used in the pad name. The decoders must provide rtp_sink and rtp_src for RTP and rtcp_sink and rtcp_src for RTCP. The decoders will be placed before the GstRtpSession element, thus they must support SSRC demuxing internally.

GstRtpBin has signals (“request-aux-sender” and “request-aux-receiver” to dynamically request an element that can be used to create or merge additional RTP streams. AUX elements are needed to implement FEC or retransmission (such as RFC 4588). An AUX sender must have one sink_%u pad that matches the sessionid in the signal and it should have 1 or more src_%u pads. For each src_%\u pad, a session will be made (if needed) and the pad will be linked to the session send_rtp_sink pad. Each session will then expose its source pad as send_rtp_src_%u on GstRtpBin. An AUX receiver has 1 src_%u pad that much match the sessionid in the signal and 1 or more sink_%u pads. A session will be made for each sink_%u pad when the corresponding recv_rtp_sink_%u pad is requested on GstRtpBin.

Example pipelines

1 2	gst-launch-1.0 udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink_0 \ rtpbin ! rtptheoradepay ! theoradec ! xvimagesink

Receive RTP data from port 5000 and send to the session 0 in rtpbin.

gst-launch-1.0 rtpbin name=rtpbin \
        v4l2src ! videoconvert ! ffenc_h263 ! rtph263ppay ! rtpbin.send_rtp_sink_0 \
                  rtpbin.send_rtp_src_0 ! udpsink port=5000                            \
                  rtpbin.send_rtcp_src_0 ! udpsink port=5001 sync=false async=false    \
                  udpsrc port=5005 ! rtpbin.recv_rtcp_sink_0                           \
        audiotestsrc ! amrnbenc ! rtpamrpay ! rtpbin.send_rtp_sink_1                   \
                  rtpbin.send_rtp_src_1 ! udpsink port=5002                            \
                  rtpbin.send_rtcp_src_1 ! udpsink port=5003 sync=false async=false    \
                  udpsrc port=5007 ! rtpbin.recv_rtcp_sink_1

Encode and payload H263 video captured from a v4l2src. Encode and payload AMR audio generated from audiotestsrc. The video is sent to session 0 in rtpbin and the audio is sent to session 1. Video packets are sent on UDP port 5000 and audio packets on port 5002. The video RTCP packets for session 0 are sent on port 5001 and the audio RTCP packets for session 0 are sent on port 5003. RTCP packets for session 0 are received on port 5005 and RTCP for session 1 is received on port 5007. Since RTCP packets from the sender should be sent as soon as possible and do not participate in preroll, sync=false and async=false is configured on udpsink

gst-launch-1.0 -v rtpbin name=rtpbin                                          \
    udpsrc caps="application/x-rtp,media=(string)video,clock-rate=(int)90000,encoding-name=(string)H263-1998" \
            port=5000 ! rtpbin.recv_rtp_sink_0                                \
        rtpbin. ! rtph263pdepay ! ffdec_h263 ! xvimagesink                    \
     udpsrc port=5001 ! rtpbin.recv_rtcp_sink_0                               \
     rtpbin.send_rtcp_src_0 ! udpsink port=5005 sync=false async=false        \
    udpsrc caps="application/x-rtp,media=(string)audio,clock-rate=(int)8000,encoding-name=(string)AMR,encoding-params=(string)1,octet-align=(string)1" \
            port=5002 ! rtpbin.recv_rtp_sink_1                                \
        rtpbin. ! rtpamrdepay ! amrnbdec ! alsasink                           \
     udpsrc port=5003 ! rtpbin.recv_rtcp_sink_1                               \
     rtpbin.send_rtcp_src_1 ! udpsink port=5007 sync=false async=false

Receive H263 on port 5000, send it through rtpbin in session 0, depayload, decode and display the video. Receive AMR on port 5002, send it through rtpbin in session 1, depayload, decode and play the audio. Receive server RTCP packets for session 0 on port 5001 and RTCP packets for session 1 on port 5003. These packets will be used for session management and synchronisation. Send RTCP reports for session 0 on port 5005 and RTCP reports for session 1 on port 5007.

Synopsis

Element Information

plugin	rtpmanager
author	Wim Taymans <wim.taymans@gmail.com>
class	Filter/Network/RTP

Element Pads

name	recv_rtcp_sink_%u
direction	sink
presence	request
details	application/x-rtcp
	application/x-srtcp

name	recv_rtp_sink_%u
direction	sink
presence	request
details	application/x-rtp
	application/x-srtp

name	send_rtp_sink_%u
direction	sink
presence	request
details	application/x-rtp

name	recv_rtp_src_%u_%u_%u
direction	source
presence	sometimes
details	application/x-rtp

name	send_rtp_src_%u
direction	source
presence	sometimes
details	application/x-rtp
	application/x-srtp

name	send_rtcp_src_%u
direction	source
presence	request
details	application/x-rtcp
	application/x-srtcp

Functions

Types and Values

struct GstRtpBin

struct GstRtpBin;

Property Details

The `“do-lost”` property

  “do-lost”                  gboolean

Send an event downstream when a packet is lost.

Flags: Read / Write

Default value: FALSE

The `“latency”` property

  “latency”                  guint

Default amount of ms to buffer in the jitterbuffers.

Flags: Read / Write

Default value: 200

The `“sdes”` property

  “sdes”                     GstStructure *

The SDES items of this session.

Flags: Read / Write

The `“ignore-pt”` property

  “ignore-pt”                gboolean

Do not demultiplex based on PT values.

Flags: Read / Write

Default value: FALSE

The `“autoremove”` property

  “autoremove”               gboolean

Automatically remove timed out sources.

Flags: Read / Write

Default value: FALSE

The `“buffer-mode”` property

  “buffer-mode”              RTPJitterBufferMode

Control the buffering and timestamping mode used by the jitterbuffer.

Flags: Read / Write

Default value: Slave receiver to sender clock

The `“ntp-sync”` property

  “ntp-sync”                 gboolean

Set the NTP time from the sender reports as the running-time on the buffers. When both the sender and receiver have sychronized running-time, i.e. when the clock and base-time is shared between the receivers and the and the senders, this option can be used to synchronize receivers on multiple machines.

Flags: Read / Write

Default value: FALSE

The `“use-pipeline-clock”` property

  “use-pipeline-clock”       gboolean

Use the pipeline running-time to set the NTP time in the RTCP SR messages (DEPRECATED: Use ntp-time-source property).

Flags: Read / Write

Default value: FALSE

The `“rtcp-sync”` property

  “rtcp-sync”                GstRTCPSync

If not synchronizing (directly) to the NTP clock, determines how to sync the various streams.

Flags: Read / Write

Default value: always

The `“rtcp-sync-interval”` property

  “rtcp-sync-interval”       guint

Determines how often to sync streams using RTCP data.

Flags: Read / Write

Default value: 0

The `“drop-on-latency”` property

  “drop-on-latency”          gboolean

Tells the jitterbuffer to never exceed the given latency in size.

Flags: Read / Write

Default value: FALSE

The `“do-sync-event”` property

  “do-sync-event”            gboolean

Send event downstream when a stream is synchronized to the sender.

Flags: Read / Write

Default value: FALSE

The `“do-retransmission”` property

  “do-retransmission”        gboolean

Enables RTP retransmission on all streams. To control retransmission on a per-SSRC basis, connect to the “new-jitterbuffer” signal and set the “do-retransmission” property on the GstRtpJitterBuffer object instead.

Flags: Read / Write

Default value: FALSE

The `“rtp-profile”` property

  “rtp-profile”              GstRTPProfile

Sets the default RTP profile of newly created RTP sessions. The profile can be changed afterwards on a per-session basis.

Flags: Read / Write

Default value: GST_RTP_PROFILE_AVP

The `“ntp-time-source”` property

  “ntp-time-source”          GstRtpNtpTimeSource

NTP time source for RTCP packets.

Flags: Read / Write

Default value: NTP time based on realtime clock

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

Maximum amount of time in ms that the RTP time in RTCP SRs is allowed to be ahead (-1 disabled).

Flags: Read / Write

Allowed values: >= G_MAXULONG

Default value: 1000

The `“rtcp-sync-send-time”` property

  “rtcp-sync-send-time”      gboolean

Use send time or capture time for RTCP sync (TRUE = send time, FALSE = capture time).

Flags: Read / Write

Default value: TRUE

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 `“max-streams”` property

  “max-streams”              guint

The maximum number of streams to create for one session.

Flags: Read / Write

Default value: 4294967295

The `“max-ts-offset”` property

  “max-ts-offset”            gint64

Used to set an upper limit of how large a time offset may be. This is used to protect against unrealistic values as a result of either client,server or clock issues.

Flags: Read / Write

Allowed values: >= 0

Default value: 3000000000

Since: 1.14

The `“max-ts-offset-adjustment”` property

  “max-ts-offset-adjustment” guint64

Syncing time stamps to NTP time adds a time offset. This parameter specifies the maximum number of nanoseconds per frame that this time offset may be adjusted with. This is used to avoid sudden large changes to time stamps.

Flags: Read / Write

Default value: 0

Since: 1.14

Signal Details

The `“clear-pt-map”` signal

void
user_function (GstRtpBin *rtpbin,
               gpointer   user_data)

Clear all previously cached pt-mapping obtained with “request-pt-map”.

Parameters

rtpbin	the object which received the signal
user_data	user data set when the signal handler was connected.

Flags: Action

The `“get-internal-session”` signal

RTPSession*
user_function (GstRtpBin *rtpbin,
               guint      id,
               gpointer   user_data)

Request the internal RTPSession object as GObject in session id .

Parameters

rtpbin	the object which received the signal
id	the session id
user_data	user data set when the signal handler was connected.

Flags: Action

The `“on-bye-ssrc”` signal

void
user_function (GstRtpBin *rtpbin,
               guint      session,
               guint      ssrc,
               gpointer   user_data)

Notify of an SSRC that became inactive because of a BYE packet.

Parameters

rtpbin	the object which received the signal
session	the session
ssrc	the SSRC
user_data	user data set when the signal handler was connected.

rtpbin	the object which received the signal
jitterbuffer	the new jitterbuffer
session	the session
ssrc	the SSRC
user_data	user data set when the signal handler was connected.

rtpbin	the object which received the signal
storage	the new storage
session	the session
user_data	user data set when the signal handler was connected.

rtpbin

Properties

Signals

Types and Values

Object Hierarchy

Implemented Interfaces

Description

Example pipelines

Synopsis

Element Information

Element Pads

Functions

Types and Values

struct GstRtpBin

Property Details

The “do-lost” property

The “latency” property

The “sdes” property

The “ignore-pt” property

The “autoremove” property

The “buffer-mode” property

The “ntp-sync” property

The “use-pipeline-clock” property

The “rtcp-sync” property

The “rtcp-sync-interval” property

The “drop-on-latency” property

The “do-sync-event” property

The “do-retransmission” property

The “rtp-profile” property

The “ntp-time-source” property

The “max-dropout-time” property

The “max-misorder-time” property

The “max-rtcp-rtp-time-diff” property

The “rtcp-sync-send-time” property

The “rfc7273-sync” property

The “max-streams” property

The “max-ts-offset” property

The “max-ts-offset-adjustment” property

Signal Details

The “clear-pt-map” signal

Parameters

The “get-internal-session” signal

Parameters

The “on-bye-ssrc” signal

Parameters

The “on-bye-timeout” signal

Parameters

The “on-new-ssrc” signal

Parameters

The “on-npt-stop” signal

Parameters

The “on-sender-timeout” signal

Parameters

The “on-ssrc-active” signal

Parameters

The “on-ssrc-collision” signal

Parameters

The “on-ssrc-sdes” signal

Parameters

The “on-ssrc-validated” signal

Parameters

The “on-timeout” signal

Parameters

The “request-pt-map” signal

Parameters

The “reset-sync” signal

Parameters

The “payload-type-change” signal

Parameters

The “new-jitterbuffer” signal

Parameters

The “request-aux-receiver” signal

Parameters

The “request-aux-sender” signal

Parameters

The “request-rtcp-decoder” signal

Parameters

The “request-rtcp-encoder” signal

Parameters

The “request-rtp-decoder” signal

The `“do-lost”` property

The `“latency”` property

The `“sdes”` property

The `“ignore-pt”` property

The `“autoremove”` property

The `“buffer-mode”` property

The `“ntp-sync”` property

The `“use-pipeline-clock”` property

The `“rtcp-sync”` property

The `“rtcp-sync-interval”` property

The `“drop-on-latency”` property

The `“do-sync-event”` property

The `“do-retransmission”` property

The `“rtp-profile”` property

The `“ntp-time-source”` property

The `“max-dropout-time”` property

The `“max-misorder-time”` property

The `“max-rtcp-rtp-time-diff”` property

The `“rtcp-sync-send-time”` property

The `“rfc7273-sync”` property

The `“max-streams”` property

The `“max-ts-offset”` property

The `“max-ts-offset-adjustment”` property

The `“clear-pt-map”` signal

The `“get-internal-session”` signal

The `“on-bye-ssrc”` signal

The `“on-bye-timeout”` signal

The `“on-new-ssrc”` signal

The `“on-npt-stop”` signal

The `“on-sender-timeout”` signal

The `“on-ssrc-active”` signal

The `“on-ssrc-collision”` signal

The `“on-ssrc-sdes”` signal

The `“on-ssrc-validated”` signal

The `“on-timeout”` signal

The `“request-pt-map”` signal

The `“reset-sync”` signal

The `“payload-type-change”` signal

The `“new-jitterbuffer”` signal

The `“request-aux-receiver”` signal

The `“request-aux-sender”` signal

The `“request-rtcp-decoder”` signal

The `“request-rtcp-encoder”` signal

The `“request-rtp-decoder”` signal

The `“request-rtp-encoder”` signal

The `“on-new-sender-ssrc”` signal

The `“on-sender-ssrc-active”` signal

The `“get-session”` signal

The `“on-bundled-ssrc”` signal

The `“get-internal-storage”` signal

The `“new-storage”` signal

The `“request-fec-decoder”` signal

The `“request-fec-encoder”` signal