# rtpsession

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.

- Maintenance 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 rtpssrcdemux, rtpptdemux and GstRtpJitterBuffer in addition to rtpsession to perform these tasks. It is usually a good idea to use rtpbin, which combines all these features in one element.

To use rtpsession 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 rtpsession 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 rtpsession 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

     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.

     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.

     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.

     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.

## Hierarchy

    GObject
        ╰──GInitiallyUnowned
            ╰──GstObject
                ╰──GstElement
                    ╰──rtpsession

## Factory details

Authors: – Wim Taymans

Classification: – `Filter/Network/RTP`

Rank – none

Plugin – rtpmanager

Package – GStreamer Good Plug-ins

## Pad Templates

### `recv_rtcp_sink`

    application/x-rtcp:

Presence – request

Direction – sink

Object type – GstPad

### `recv_rtp_sink`

    application/x-rtp:

Presence – request

Direction – sink

Object type – GstPad

### `recv_rtp_src`

    application/x-rtp:

Presence – sometimes

Direction – src

Object type – GstPad

### `send_rtcp_src`

    application/x-rtcp:

Presence – request

Direction – src

Object type – GstPad

### `send_rtp_sink`

    application/x-rtp:

Presence – request

Direction – sink

Object type – GstPad

### `send_rtp_src`

    application/x-rtp:

Presence – sometimes

Direction – src

Object type – GstPad

### `sync_src`

    application/x-rtcp:

Presence – sometimes

Direction – src

Object type – GstPad

## Signals

### on-bye-ssrc

    on_bye_ssrc_callback (GstElement * sess,
                          guint ssrc,
                          gpointer udata)

    def on_bye_ssrc_callback (sess, ssrc, udata):
        #python callback for the 'on-bye-ssrc' signal

    function on_bye_ssrc_callback(sess: GstElement * sess, ssrc: guint ssrc, udata: gpointer udata): {
        // javascript callback for the 'on-bye-ssrc' signal
    }

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

Parameters:

`sess` –

the object which received the signal

`ssrc` –

the SSRC

`udata` –
No description available

Flags: Run Last

### on-bye-timeout

    on_bye_timeout_callback (GstElement * sess,
                             guint ssrc,
                             gpointer udata)

    def on_bye_timeout_callback (sess, ssrc, udata):
        #python callback for the 'on-bye-timeout' signal

    function on_bye_timeout_callback(sess: GstElement * sess, ssrc: guint ssrc, udata: gpointer udata): {
        // javascript callback for the 'on-bye-timeout' signal
    }

Notify of an SSRC that has timed out because of BYE

Parameters:

`sess` –

the object which received the signal

`ssrc` –

the SSRC

`udata` –
No description available

Flags: Run Last

### on-new-sender-ssrc

    on_new_sender_ssrc_callback (GstElement * sess,
                                 guint ssrc,
                                 gpointer udata)

    def on_new_sender_ssrc_callback (sess, ssrc, udata):
        #python callback for the 'on-new-sender-ssrc' signal

    function on_new_sender_ssrc_callback(sess: GstElement * sess, ssrc: guint ssrc, udata: gpointer udata): {
        // javascript callback for the 'on-new-sender-ssrc' signal
    }

Notify of a new sender SSRC that entered session.

Parameters:

`sess` –

the object which received the signal

`ssrc` –

the sender SSRC

`udata` –
No description available

Flags: Run Last

Since : 1.8

### on-new-ssrc

    on_new_ssrc_callback (GstElement * sess,
                          guint ssrc,
                          gpointer udata)

    def on_new_ssrc_callback (sess, ssrc, udata):
        #python callback for the 'on-new-ssrc' signal

    function on_new_ssrc_callback(sess: GstElement * sess, ssrc: guint ssrc, udata: gpointer udata): {
        // javascript callback for the 'on-new-ssrc' signal
    }

Notify of a new SSRC that entered session.

Parameters:

`sess` –

the object which received the signal

`ssrc` –

the SSRC

`udata` –
No description available

Flags: Run Last

### on-sender-ssrc-active

    on_sender_ssrc_active_callback (GstElement * sess,
                                    guint ssrc,
                                    gpointer udata)

    def on_sender_ssrc_active_callback (sess, ssrc, udata):
        #python callback for the 'on-sender-ssrc-active' signal

    function on_sender_ssrc_active_callback(sess: GstElement * sess, ssrc: guint ssrc, udata: gpointer udata): {
        // javascript callback for the 'on-sender-ssrc-active' signal
    }

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

Parameters:

`sess` –

the object which received the signal

`ssrc` –

the sender SSRC

`udata` –
No description available

Flags: Run Last

Since : 1.8

### on-sender-timeout

    on_sender_timeout_callback (GstElement * sess,
                                guint ssrc,
                                gpointer udata)

    def on_sender_timeout_callback (sess, ssrc, udata):
        #python callback for the 'on-sender-timeout' signal

    function on_sender_timeout_callback(sess: GstElement * sess, ssrc: guint ssrc, udata: gpointer udata): {
        // javascript callback for the 'on-sender-timeout' signal
    }

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

Parameters:

`sess` –

the object which received the signal

`ssrc` –

the SSRC

`udata` –
No description available

Flags: Run Last

### on-ssrc-active

    on_ssrc_active_callback (GstElement * sess,
                             guint ssrc,
                             gpointer udata)

    def on_ssrc_active_callback (sess, ssrc, udata):
        #python callback for the 'on-ssrc-active' signal

    function on_ssrc_active_callback(sess: GstElement * sess, ssrc: guint ssrc, udata: gpointer udata): {
        // javascript callback for the 'on-ssrc-active' signal
    }

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

Parameters:

`sess` –

the object which received the signal

`ssrc` –

the SSRC

`udata` –
No description available

Flags: Run Last

### on-ssrc-collision

    on_ssrc_collision_callback (GstElement * param_0,
                                guint arg0,
                                gpointer udata)

    def on_ssrc_collision_callback (param_0, arg0, udata):
        #python callback for the 'on-ssrc-collision' signal

    function on_ssrc_collision_callback(param_0: GstElement * param_0, arg0: guint arg0, udata: gpointer udata): {
        // javascript callback for the 'on-ssrc-collision' signal
    }

Parameters:

`param_0` –
No description available
`arg0` –
No description available
`udata` –
No description available

Flags: Run Last

### on-ssrc-sdes

    on_ssrc_sdes_callback (GstElement * session,
                           guint src,
                           gpointer udata)

    def on_ssrc_sdes_callback (session, src, udata):
        #python callback for the 'on-ssrc-sdes' signal

    function on_ssrc_sdes_callback(session: GstElement * session, src: guint src, udata: gpointer udata): {
        // javascript callback for the 'on-ssrc-sdes' signal
    }

Notify that a new SDES was received for SSRC.

Parameters:

`session` –

the object which received the signal

`src` –

the SSRC

`udata` –
No description available

Flags: Run Last

### on-ssrc-validated

    on_ssrc_validated_callback (GstElement * param_0,
                                guint arg0,
                                gpointer udata)

    def on_ssrc_validated_callback (param_0, arg0, udata):
        #python callback for the 'on-ssrc-validated' signal

    function on_ssrc_validated_callback(param_0: GstElement * param_0, arg0: guint arg0, udata: gpointer udata): {
        // javascript callback for the 'on-ssrc-validated' signal
    }

Parameters:

`param_0` –
No description available
`arg0` –
No description available
`udata` –
No description available

Flags: Run Last

### on-timeout

    on_timeout_callback (GstElement * sess,
                         guint ssrc,
                         gpointer udata)

    def on_timeout_callback (sess, ssrc, udata):
        #python callback for the 'on-timeout' signal

    function on_timeout_callback(sess: GstElement * sess, ssrc: guint ssrc, udata: gpointer udata): {
        // javascript callback for the 'on-timeout' signal
    }

Notify of an SSRC that has timed out

Parameters:

`sess` –

the object which received the signal

`ssrc` –

the SSRC

`udata` –
No description available

Flags: Run Last

### request-pt-map

    GstCaps *
    request_pt_map_callback (GstElement * sess,
                             guint pt,
                             gpointer udata)

    def request_pt_map_callback (sess, pt, udata):
        #python callback for the 'request-pt-map' signal

    function request_pt_map_callback(sess: GstElement * sess, pt: guint pt, udata: gpointer udata): {
        // javascript callback for the 'request-pt-map' signal
    }

Request the payload type as GstCaps for pt.

Parameters:

`sess` –

the object which received the signal

`pt` –

the pt

`udata` –
No description available
Returns (GstCaps *) –
No description available

Flags: Run Last

## Action Signals

### clear-pt-map

    g_signal_emit_by_name (sess, "clear-pt-map");

    ret = sess.emit ("clear-pt-map")

    let ret = sess.emit ("clear-pt-map");

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

Parameters:

`sess` (GstElement *) –

the object which received the signal

Flags: Run Last / Action

## Properties

### bandwidth

    “bandwidth” gdouble

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

Flags : Read / Write

Default value : 0

### internal-session

    “internal-session” RTPSession *

The internal RTPSession object

Flags : Read

### max-dropout-time

    “max-dropout-time” guint

The maximum time (milliseconds) of missing packets tolerated.

Flags : Read / Write

Default value : 60000

### max-misorder-time

    “max-misorder-time” guint

The maximum time (milliseconds) of misordered packets tolerated.

Flags : Read / Write

Default value : 2000

### ntp-time-source

    “ntp-time-source” GstRtpNtpTimeSource *

NTP time source for RTCP packets

Flags : Read / Write

Default value : ntp (0)

### num-active-sources

    “num-active-sources” guint

The number of active sources in the session

Flags : Read

Default value : 0

### num-sources

    “num-sources” guint

The number of sources in the session

Flags : Read

Default value : 0

### probation

    “probation” guint

Consecutive packet sequence numbers to accept the source

Flags : Read / Write

Default value : 2

### rtcp-fraction

    “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

Default value : 0.05

### rtcp-min-interval

    “rtcp-min-interval” guint64

Minimum interval between Regular RTCP packet (in ns)

Flags : Read / Write

Default value : 5000000000

### rtcp-rr-bandwidth

    “rtcp-rr-bandwidth” gint

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

Flags : Read / Write

Default value : -1

### rtcp-rs-bandwidth

    “rtcp-rs-bandwidth” gint

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

Flags : Read / Write

Default value : -1

### rtcp-sync-send-time

    “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

### rtp-profile

    “rtp-profile” GstRTPProfile *

RTP profile to use

Flags : Read / Write

Default value : avp (1)

### sdes

    “sdes” GstStructure *

The SDES items of this session

Flags : Read / Write

### stats

    “stats” GstStructure *

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

- "recv-rtx-req-count" G_TYPE_UINT The number of retransmission events received from downstream (in receiver mode) (Since 1.16)
- "sent-rtx-req-count" G_TYPE_UINT The number of retransmission events sent downstream (in sender mode) (Since 1.16)
- "rtx-count" G_TYPE_UINT DEPRECATED Since 1.16, same as "recv-rtx-req-count".
- "rtx-drop-count" G_TYPE_UINT The number of retransmission events dropped (due to bandwidth constraints)
- "sent-nack-count" G_TYPE_UINT Number of NACKs sent
- "recv-nack-count" G_TYPE_UINT Number of NACKs received
- "source-stats" G_TYPE_BOXED GValueArray of stats for all RTP sources (Since 1.8)

Flags : Read

Default value :

    application/x-rtp-session-stats, rtx-drop-count=(uint)0, sent-nack-count=(uint)0, recv-nack-count=(uint)0, source-stats=(GValueArray)<  >, rtx-count=(uint)0, recv-rtx-req-count=(uint)0, sent-rtx-req-count=(uint)0;

Since : 1.4

### timeout-inactive-sources

    “timeout-inactive-sources” gboolean

Whether inactive sources should be timed out

Flags : Read / Write

Default value : true

Since : 1.24

### twcc-stats

    “twcc-stats” GstStructure *

Various statistics derived from TWCC. This property returns a GstStructure with name RTPTWCCStats with the following fields:

"bitrate-sent" G_TYPE_UINT The actual sent bitrate of TWCC packets "bitrate-recv" G_TYPE_UINT The estimated bitrate for the receiver. "packets-sent" G_TYPE_UINT Number of packets sent "packets-recv" G_TYPE_UINT Number of packets reported recevied "packet-loss-pct" G_TYPE_DOUBLE Packetloss percentage, based on packets reported as lost from the receiver. Note: depending on the implementation of the receiver and due to the nature of the TWCC RRs being sent with high frequency, out of order packets may not be fully accounted for and this number could be higher than other measurement sources of packet loss. "avg-delta-of-delta", G_TYPE_INT64 In nanoseconds, a moving window average of the difference in inter-packet spacing between sender and receiver. A sudden increase in this number can indicate network congestion.

Flags : Read

Since : 1.18

### update-ntp64-header-ext

    “update-ntp64-header-ext” gboolean

Whether RTP NTP header extension should be updated with actual NTP time. If not, use the NTP time from buffer timestamp metadata

Flags : Read / Write

Default value : true

Since : 1.22

### use-pipeline-clock

    “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

## Named constants

### GstRtpNtpTimeSource

#### Members

`ntp` (0) – NTP time based on realtime clock
`unix` (1) – UNIX time based on realtime clock
`running-time` (2) – Running time based on pipeline clock
`clock-time` (3) – Pipeline clock time

The results of the search are