rtpsession: GStreamer Good Plugins 1.0 Plugins Reference Manual

rtpsession

Properties

gdouble	bandwidth	Read / Write
RTPSession *	internal-session	Read
guint	num-active-sources	Read
guint	num-sources	Read
gdouble	rtcp-fraction	Read / Write
GstStructure *	sdes	Read / Write
gint	rtcp-rr-bandwidth	Read / Write
gint	rtcp-rs-bandwidth	Read / Write
gboolean	use-pipeline-clock	Read / Write
guint64	rtcp-min-interval	Read / Write
guint	probation	Read / Write
GstStructure *	stats	Read
GstRTPProfile	rtp-profile	Read / Write
GstRtpNtpTimeSource	ntp-time-source	Read / Write
guint	max-dropout-time	Read / Write
guint	max-misorder-time	Read / Write
gboolean	rtcp-sync-send-time	Read / Write

Signals

void	clear-pt-map	Action
void	on-bye-ssrc	Run Last
void	on-bye-timeout	Run Last
void	on-new-ssrc	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	on-new-sender-ssrc	Run Last
void	on-sender-ssrc-active	Run Last

Types and Values

struct

GstRtpSession

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GstObject
            ╰── GstElement
                ╰── GstRtpSession

Description

The RTP session manager models participants with unique SSRC in an RTP session. This session can be used to send and receive RTP and RTCP packets. Based on what REQUEST pads are requested from the session manager, specific functionality can be activated.

The session manager currently implements RFC 3550 including:

RTP packet validation based on consecutive sequence numbers.
Maintainance of the SSRC participant database.
Keeping per participant statistics based on received RTCP packets.
Scheduling of RR/SR RTCP packets.
Support for multiple sender SSRC.

The rtpsession will not demux packets based on SSRC or payload type, nor will it correct for packet reordering and jitter. Use GstRtpsSrcDemux, GstRtpPtDemux and GstRtpJitterBuffer in addition to GstRtpSession to perform these tasks. It is usually a good idea to use GstRtpBin, which combines all these features in one element.

To use GstRtpSession as an RTP receiver, request a recv_rtp_sink pad, which will automatically create recv_rtp_src pad. Data received on the recv_rtp_sink pad will be processed in the session and after being validated forwarded on the recv_rtp_src pad.

To also use GstRtpSession as an RTCP receiver, request a recv_rtcp_sink pad, which will automatically create a sync_src pad. Packets received on the RTCP pad will be used by the session manager to update the stats and database of the other participants. SR packets will be forwarded on the sync_src pad so that they can be used to perform inter-stream synchronisation when needed.

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

To use GstRtpSession as a sender, request a send_rtp_sink pad, which will automatically create a send_rtp_src pad. The session manager will forward the packets on the send_rtp_src pad after updating its internal state.

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.

Example pipelines

1	gst-launch-1.0 udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink rtpsession .recv_rtp_src ! rtptheoradepay ! theoradec ! xvimagesink

Receive theora RTP packets from port 5000 and send them to the depayloader, decoder and display. Note that the application/x-rtp caps on udpsrc should be configured based on some negotiation process such as RTSP for this pipeline to work correctly.

1
2
3

gst-launch-1.0 udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink rtpsession name=session \
       .recv_rtp_src ! rtptheoradepay ! theoradec ! xvimagesink \
    udpsrc port=5001 caps="application/x-rtcp" ! session.recv_rtcp_sink

Receive theora RTP packets from port 5000 and send them to the depayloader, decoder and display. Receive RTCP packets from port 5001 and process them in the session manager. Note that the application/x-rtp caps on udpsrc should be configured based on some negotiation process such as RTSP for this pipeline to work correctly.

1	gst-launch-1.0 videotestsrc ! theoraenc ! rtptheorapay ! .send_rtp_sink rtpsession .send_rtp_src ! udpsink port=5000

Send theora RTP packets through the session manager and out on UDP port 5000.

1 2	gst-launch-1.0 videotestsrc ! theoraenc ! rtptheorapay ! .send_rtp_sink rtpsession name=session .send_rtp_src \ ! udpsink port=5000 session.send_rtcp_src ! udpsink port=5001

Send theora RTP packets through the session manager and out on UDP port 5000. Send RTCP packets on port 5001. Note that this pipeline will not preroll correctly because the second udpsink will not preroll correctly (no RTCP packets are sent in the PAUSED state). Applications should manually set and keep (see gst_element_set_locked_state()) the RTCP udpsink to the PLAYING state.

Synopsis

Element Information

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

Element Pads

name	recv_rtcp_sink
direction	sink
presence	request
details	application/x-rtcp

name	recv_rtp_sink
direction	sink
presence	request
details	application/x-rtp

name	send_rtp_sink
direction	sink
presence	request
details	application/x-rtp

name	recv_rtp_src
direction	source
presence	sometimes
details	application/x-rtp

name	send_rtp_src
direction	source
presence	sometimes
details	application/x-rtp

name	sync_src
direction	source
presence	sometimes
details	application/x-rtcp

name	send_rtcp_src
direction	source
presence	request
details	application/x-rtcp

Functions

Types and Values

struct GstRtpSession

struct GstRtpSession;

Property Details

The `“bandwidth”` property

  “bandwidth”                gdouble

The bandwidth of the session in bytes per second (0 for auto-discover).

Flags: Read / Write

Allowed values: >= 0

Default value: 0

The `“internal-session”` property

  “internal-session”         RTPSession *

The internal RTPSession object.

Flags: Read

The `“num-active-sources”` property

  “num-active-sources”       guint

The number of active sources in the session.

Flags: Read

Default value: 0

The `“num-sources”` property

  “num-sources”              guint

The number of sources in the session.

Flags: Read

Default value: 0

The `“rtcp-fraction”` property

  “rtcp-fraction”            gdouble

The RTCP bandwidth of the session in bytes per second (or as a real fraction of the RTP bandwidth if < 1.0).

Flags: Read / Write

Allowed values: >= 0

Default value: 0.05

The `“sdes”` property

  “sdes”                     GstStructure *

The SDES items of this session.

Flags: Read / Write

The `“rtcp-rr-bandwidth”` property

  “rtcp-rr-bandwidth”        gint

The RTCP bandwidth used for receivers in bytes per second (-1 = default).

Flags: Read / Write

Allowed values: >= G_MAXULONG

Default value: -1

The `“rtcp-rs-bandwidth”` property

  “rtcp-rs-bandwidth”        gint

The RTCP bandwidth used for senders in bytes per second (-1 = default).

Flags: Read / Write

Allowed values: >= G_MAXULONG

Default value: -1

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-min-interval”` property

  “rtcp-min-interval”        guint64

Minimum interval between Regular RTCP packet (in ns).

Flags: Read / Write

Default value: 5000000000

The `“probation”` property

  “probation”                guint

Consecutive packet sequence numbers to accept the source.

Flags: Read / Write

Default value: 2

The `“stats”` property

  “stats”                    GstStructure *

Various statistics.

Flags: Read

The `“rtp-profile”` property

  “rtp-profile”              GstRTPProfile

RTP profile to use.

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 `“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

Signal Details

The `“clear-pt-map”` signal

void
user_function (GstRtpSession *sess,
               gpointer       user_data)

Clear the cached pt-maps requested with “request-pt-map”.

Parameters

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

Flags: Action

The `“on-bye-ssrc”` signal

void
user_function (GstRtpSession *sess,
               guint          ssrc,
               gpointer       user_data)

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

Parameters

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

Flags: Run Last

The `“on-bye-timeout”` signal

void
user_function (GstRtpSession *sess,
               guint          ssrc,
               gpointer       user_data)

Notify of an SSRC that has timed out because of BYE

Parameters

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

Flags: Run Last

The `“on-new-ssrc”` signal

void
user_function (GstRtpSession *sess,
               guint          ssrc,
               gpointer       user_data)

Notify of a new SSRC that entered session .

Parameters

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

Flags: Run Last

The `“on-sender-timeout”` signal

void
user_function (GstRtpSession *sess,
               guint          ssrc,
               gpointer       user_data)

Notify of a sender SSRC that has timed out and became a receiver

Parameters

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

Flags: Run Last

The `“on-ssrc-active”` signal

void
user_function (GstRtpSession *sess,
               guint          ssrc,
               gpointer       user_data)

Notify of a SSRC that is active, i.e., sending RTCP.

Parameters

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

Flags: Run Last

The `“on-ssrc-collision”` signal

void
user_function (GstRtpSession *gstrtpsession,
               guint          arg1,
               gpointer       user_data)

Flags: Run Last

The `“on-ssrc-sdes”` signal

void
user_function (GstRtpSession *session,
               guint          src,
               gpointer       user_data)

Notify that a new SDES was received for SSRC.

Parameters

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

Flags: Run Last

The `“on-ssrc-validated”` signal

void
user_function (GstRtpSession *gstrtpsession,
               guint          arg1,
               gpointer       user_data)

Flags: Run Last

The `“on-timeout”` signal

void
user_function (GstRtpSession *sess,
               guint          ssrc,
               gpointer       user_data)

Notify of an SSRC that has timed out

Parameters

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

Flags: Run Last

The `“request-pt-map”` signal

GstCaps*
user_function (GstRtpSession *sess,
               guint          pt,
               gpointer       user_data)

Request the payload type as GstCaps for pt .

Parameters

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

Flags: Run Last

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

void
user_function (GstRtpSession *sess,
               guint          ssrc,
               gpointer       user_data)

Parameters

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

Flags: Run Last

Since: 1.8

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

void
user_function (GstRtpSession *sess,
               guint          ssrc,
               gpointer       user_data)

Parameters

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

Flags: Run Last

Since: 1.8

rtpsession

Properties

Signals

Types and Values

Object Hierarchy

Description

Example pipelines

Synopsis

Element Information

Element Pads

Functions

Types and Values

struct GstRtpSession

Property Details

The “bandwidth” property

The “internal-session” property

The “num-active-sources” property

The “num-sources” property

The “rtcp-fraction” property

The “sdes” property

The “rtcp-rr-bandwidth” property

The “rtcp-rs-bandwidth” property

The “use-pipeline-clock” property

The “rtcp-min-interval” property

The “probation” property

The “stats” property

The “rtp-profile” property

The “ntp-time-source” property

The “max-dropout-time” property

The “max-misorder-time” property

The “rtcp-sync-send-time” property

Signal Details

The “clear-pt-map” signal

Parameters

The “on-bye-ssrc” signal

Parameters

The “on-bye-timeout” signal

Parameters

The “on-new-ssrc” signal

Parameters

The “on-sender-timeout” signal

Parameters

The “on-ssrc-active” signal

Parameters

The “on-ssrc-collision” signal

The “on-ssrc-sdes” signal

Parameters

The “on-ssrc-validated” signal

The “on-timeout” signal

Parameters

The “request-pt-map” signal

Parameters

The “on-new-sender-ssrc” signal

Parameters

The “on-sender-ssrc-active” signal

Parameters

See Also

The `“bandwidth”` property

The `“internal-session”` property

The `“num-active-sources”` property

The `“num-sources”` property

The `“rtcp-fraction”` property

The `“sdes”` property

The `“rtcp-rr-bandwidth”` property

The `“rtcp-rs-bandwidth”` property

The `“use-pipeline-clock”` property

The `“rtcp-min-interval”` property

The `“probation”` property

The `“stats”` property

The `“rtp-profile”` property

The `“ntp-time-source”` property

The `“max-dropout-time”` property

The `“max-misorder-time”` property

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

The `“clear-pt-map”` signal

The `“on-bye-ssrc”` signal

The `“on-bye-timeout”` signal

The `“on-new-ssrc”` 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 `“on-new-sender-ssrc”` signal

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