gstrtpsession

gstrtpsession — Implement an RTP session

Synopsis

struct              GstRtpSession;

Object Hierarchy

  GObject
   +----GstObject
         +----GstElement
               +----GstRtpSession

Properties

  "bandwidth"                gdouble               : Read / Write
  "internal-session"         RTPSession*           : Read
  "ntp-ns-base"              guint64               : Read / Write
  "num-active-sources"       guint                 : Read
  "num-sources"              guint                 : Read
  "rtcp-fraction"            gdouble               : Read / Write
  "sdes"                     GstStructure*         : Read / Write
  "rtcp-rr-bandwidth"        gint                  : Read / Write
  "rtcp-rs-bandwidth"        gint                  : Read / Write
  "use-pipeline-clock"       gboolean              : Read / Write
  "rtcp-min-interval"        guint64               : Read / Write

Signals

  "clear-pt-map"                                   : Action
  "on-bye-ssrc"                                    : Run Last
  "on-bye-timeout"                                 : Run Last
  "on-new-ssrc"                                    : Run Last
  "on-sender-timeout"                              : Run Last
  "on-ssrc-active"                                 : Run Last
  "on-ssrc-collision"                              : Run Last
  "on-ssrc-sdes"                                   : Run Last
  "on-ssrc-validated"                              : Run Last
  "on-timeout"                                     : Run Last
  "request-pt-map"                                 : Run Last

Description

The RTP session manager models one participant with a 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.

The gstrtpsession 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 modify the SSRC in the RTP packets to its own SSRC and wil 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 udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink gstrtpsession .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 udpsrc port=5000 caps="application/x-rtp, ..." ! .recv_rtp_sink gstrtpsession 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 videotestsrc ! theoraenc ! rtptheorapay ! .send_rtp_sink gstrtpsession .send_rtp_src ! udpsink port=5000
Send theora RTP packets through the session manager and out on UDP port 5000. 
1
2
 
gst-launch videotestsrc ! theoraenc ! rtptheorapay ! .send_rtp_sink gstrtpsession 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.

Last reviewed on 2007-05-28 (0.10.5)

Synopsis

Element Information

plugin

 gstrtpmanager

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

Details

struct GstRtpSession

struct GstRtpSession;

Property Details

The "bandwidth" property

  "bandwidth"                gdouble               : Read / Write

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

Allowed values: >= 0

Default value: 64000

The "internal-session" property

  "internal-session"         RTPSession*           : Read

The internal RTPSession object.

The "ntp-ns-base" property

  "ntp-ns-base"              guint64               : Read / Write

The NTP base time corresponding to running_time 0 (deprecated).

Default value: 0

The "num-active-sources" property

  "num-active-sources"       guint                 : Read

The number of active sources in the session.

Default value: 0

The "num-sources" property

  "num-sources"              guint                 : Read

The number of sources in the session.

Default value: 0

The "rtcp-fraction" property

  "rtcp-fraction"            gdouble               : Read / Write

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

Allowed values: >= 0

Default value: 3200

The "sdes" property

  "sdes"                     GstStructure*         : Read / Write

The SDES items of this session.

The "rtcp-rr-bandwidth" property

  "rtcp-rr-bandwidth"        gint                  : Read / Write

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

Allowed values: >= G_MAXULONG

Default value: -1

The "rtcp-rs-bandwidth" property

  "rtcp-rs-bandwidth"        gint                  : Read / Write

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

Allowed values: >= G_MAXULONG

Default value: -1

The "use-pipeline-clock" property

  "use-pipeline-clock"       gboolean              : Read / Write

Use the pipeline clock to set the NTP time in the RTCP SR messages.

Default value: FALSE

The "rtcp-min-interval" property

  "rtcp-min-interval"        guint64               : Read / Write

Minimum interval between Regular RTCP packet (in ns).

Default value: 5000000000

Signal Details

The "clear-pt-map" signal

void                user_function                      (GstRtpSession *sess,
                                                        gpointer       user_data)      : Action

Clear the cached pt-maps requested with "request-pt-map".

sess :

 the object which received the signal

user_data :

 user data set when the signal handler was connected.

The "on-bye-ssrc" signal

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

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

sess :

 the object which received the signal

ssrc :

 the SSRC

user_data :

 user data set when the signal handler was connected.

The "on-bye-timeout" signal

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

Notify of an SSRC that has timed out because of BYE

sess :

 the object which received the signal

ssrc :

 the SSRC

user_data :

 user data set when the signal handler was connected.

The "on-new-ssrc" signal

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

Notify of a new SSRC that entered session.

sess :

 the object which received the signal

ssrc :

 the SSRC

user_data :

 user data set when the signal handler was connected.

The "on-sender-timeout" signal

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

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

sess :

 the object which received the signal

ssrc :

 the SSRC

user_data :

 user data set when the signal handler was connected.

The "on-ssrc-active" signal

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

gstrtpsession :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "on-ssrc-collision" signal

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

gstrtpsession :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "on-ssrc-sdes" signal

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

Notify that a new SDES was received for SSRC.

session :

 the object which received the signal

src :

 the SSRC

user_data :

 user data set when the signal handler was connected.

The "on-ssrc-validated" signal

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

gstrtpsession :

 the object which received the signal.

user_data :

 user data set when the signal handler was connected.

The "on-timeout" signal

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

Notify of an SSRC that has timed out

sess :

 the object which received the signal

ssrc :

 the SSRC

user_data :

 user data set when the signal handler was connected.

The "request-pt-map" signal

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

Request the payload type as GstCaps for pt.

sess :

 the object which received the signal

pt :

 the pt

user_data :

 user data set when the signal handler was connected.

See Also

gstrtpjitterbuffer, gstrtpbin, gstrtpptdemux, gstrtpssrcdemux
Generated by GTK-Doc V1.18