## rtspsrc

rtspsrc

## Properties

gboolean | debug | Read / Write
gchar * | location | Read / Write
GstRTSPLowerTrans | protocols | Read / Write
guint | retry | Read / Write
guint64 | timeout | Read / Write
guint | latency | Read / Write
guint64 | tcp-timeout | Read / Write
guint64 | connection-speed | Read / Write
GstRTSPNatMethod | nat-method | Read / Write
gboolean | do-rtcp | Read / Write
gchar * | proxy | Read / Write
guint | rtp-blocksize | Read / Write
gchar * | user-id | Read / Write
gchar * | user-pw | Read / Write
GstRTSPSrcBufferMode | buffer-mode | Read / Write
gchar * | port-range | Read / Write
gint | udp-buffer-size | Read / Write
gboolean | short-header | Read / Write
gboolean | do-rtsp-keep-alive | Read / Write
gboolean | drop-on-latency | Read / Write
guint | probation | Read / Write
gboolean | udp-reconnect | Read / Write
gchar * | proxy-id | Read / Write
gchar * | proxy-pw | Read / Write
gchar * | multicast-iface | Read / Write
gboolean | ntp-sync | Read / Write
gboolean | use-pipeline-clock | Read / Write
GstStructure * | sdes | Read / Write
GTlsDatabase * | tls-database | Read / Write
GTlsCertificateFlags | tls-validation-flags | Read / Write
gboolean | do-retransmission | Read / Write
GTlsInteraction * | tls-interaction | Read / Write
GstRTSPSrcNtpTimeSource | ntp-time-source | Read / Write
gchar * | user-agent | Read / Write
gint | max-rtcp-rtp-time-diff | Read / Write
gboolean | rfc7273-sync | Read / Write
GstRTSPVersion | default-rtsp-version | Read / Write
gint64 | max-ts-offset | Read / Write
guint64 | max-ts-offset-adjustment | Read / Write
GstRTSPBackchannel | backchannel | Read / Write
guint64 | teardown-timeout | Read / Write

## Signals

void | handle-request |
void | on-sdp |
gboolean | select-stream | Run First
void | new-manager | Run First
GstCaps* | request-rtcp-key | Run Last
gboolean | accept-certificate | Run Last
gboolean | before-send | Run First
GstFlowReturn | push-backchannel-buffer | Action
gboolean | get-parameter | Action
gboolean | get-parameters | Action
gboolean | set-parameter | Action

## Types and Values

struct | GstRTSPSrc

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstElement
                    ╰── GstBin
                        ╰── GstRTSPSrc

## Implemented Interfaces

GstRTSPSrc implements GstChildProxy and GstURIHandler.

## Description

Makes a connection to an RTSP server and read the data. rtspsrc strictly follows RFC 2326 and therefore does not (yet) support RealMedia/Quicktime/Microsoft extensions.

RTSP supports transport over TCP or UDP in unicast or multicast mode. By default rtspsrc will negotiate a connection in the following order: UDP unicast/UDP multicast/TCP. The order cannot be changed but the allowed protocols can be controlled with the “protocols” property.

rtspsrc currently understands SDP as the format of the session description. For each stream listed in the SDP a new rtp_stream%d pad will be created with caps derived from the SDP media description. This is a caps of mime type "application/x-rtp" that can be connected to any available RTP depayloader element.

rtspsrc will internally instantiate an RTP session manager element that will handle the RTCP messages to and from the server, jitter removal, packet reordering along with providing a clock for the pipeline. This feature is implemented using the gstrtpbin element.

rtspsrc acts like a live source and will therefore only generate data in the PLAYING state.

If a RTP session times out then the rtspsrc will generate an element message named "GstRTSPSrcTimeout". Currently this is only supported for timeouts triggered by RTCP.

The message's structure contains three fields:

GstRTSPSrcTimeoutCause `cause`: the cause of the timeout.

gint `stream-number`: an internal identifier of the stream that timed out.

guint `ssrc`: the SSRC of the stream that timed out.

#### Example launch line

    1

    gst-launch-1.0 rtspsrc location=rtsp://some.server/url ! fakesink

Establish a connection to an RTSP server and send the raw RTP packets to a fakesink.

## Synopsis

### Element Information

plugin | rtsp
author | Wim Taymans <wim@fluendo.com>, Thijs Vermeir <thijs.vermeir@barco.com>, Lutz Mueller <lutz@topfrose.de>
class | Source/Network

### Element Pads

name | stream_%u
direction | source
presence | sometimes
details | application/x-rtp
| application/x-rdt

## Functions

## Types and Values

### struct GstRTSPSrc

    struct GstRTSPSrc;

## Property Details

### The `“debug”` property

      “debug”                    gboolean

Dump request and response messages to stdout(DEPRECATED: Printed all RTSP message to gstreamer log as 'log' level).

Owner: GstRTSPSrc

Flags: Read / Write

Default value: FALSE

### The `“location”` property

      “location”                 gchar *

Location of the RTSP url to read.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: NULL

### The `“protocols”` property

      “protocols”                GstRTSPLowerTrans

Allowed lower transport protocols.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: GST_RTSP_LOWER_TRANS_UDP|GST_RTSP_LOWER_TRANS_UDP_MCAST|GST_RTSP_LOWER_TRANS_TCP

### The `“retry”` property

      “retry”                    guint

Max number of retries when allocating RTP ports.

Owner: GstRTSPSrc

Flags: Read / Write

Allowed values: <= 65535

Default value: 20

### The `“timeout”` property

      “timeout”                  guint64

Retry TCP transport after UDP timeout microseconds (0 = disabled).

Owner: GstRTSPSrc

Flags: Read / Write

Default value: 5000000

### The `“latency”` property

      “latency”                  guint

Amount of ms to buffer.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: 2000

### The `“tcp-timeout”` property

      “tcp-timeout”              guint64

Fail after timeout microseconds on TCP connections (0 = disabled).

Owner: GstRTSPSrc

Flags: Read / Write

Default value: 20000000

### The `“connection-speed”` property

      “connection-speed”         guint64

Network connection speed in kbps (0 = unknown).

Owner: GstRTSPSrc

Flags: Read / Write

Allowed values: <= 18446744073709551

Default value: 0

### The `“nat-method”` property

      “nat-method”               GstRTSPNatMethod

Method to use for traversing firewalls and NAT.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: Send Dummy packets

### The `“do-rtcp”` property

      “do-rtcp”                  gboolean

Enable RTCP support. Some old server don't like RTCP and then this property needs to be set to FALSE.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: TRUE

### The `“proxy”` property

      “proxy”                    gchar *

Set the proxy parameters. This has to be a string of the format http://host[:port].

Owner: GstRTSPSrc

Flags: Read / Write

Default value: NULL

### The `“rtp-blocksize”` property

      “rtp-blocksize”            guint

RTP package size to suggest to server.

Owner: GstRTSPSrc

Flags: Read / Write

Allowed values: <= 65536

Default value: 0

### The `“user-id”` property

      “user-id”                  gchar *

RTSP location URI user id for authentication.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: NULL

### The `“user-pw”` property

      “user-pw”                  gchar *

RTSP location URI user password for authentication.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: NULL

### The `“buffer-mode”` property

      “buffer-mode”              GstRTSPSrcBufferMode

Control the buffering and timestamping mode used by the jitterbuffer.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: Choose mode depending on stream live

### The `“port-range”` property

      “port-range”               gchar *

Configure the client port numbers that can be used to receive RTP and RTCP.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: NULL

### The `“udp-buffer-size”` property

      “udp-buffer-size”          gint

Size of the kernel UDP receive buffer in bytes.

Owner: GstRTSPSrc

Flags: Read / Write

Allowed values: >= 0

Default value: 524288

### The `“short-header”` property

      “short-header”             gboolean

Only send the basic RTSP headers for broken encoders.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: FALSE

### The `“do-rtsp-keep-alive”` property

      “do-rtsp-keep-alive”       gboolean

Enable RTSP keep alive support. Some old server don't like RTSP keep alive and then this property needs to be set to FALSE.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: TRUE

### The `“drop-on-latency”` property

      “drop-on-latency”          gboolean

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

Owner: GstRTSPSrc

Flags: Read / Write

Default value: FALSE

### The `“probation”` property

      “probation”                guint

Consecutive packet sequence numbers to accept the source.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: 2

### The `“udp-reconnect”` property

      “udp-reconnect”            gboolean

Reconnect to the server if RTSP connection is closed when doing UDP.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: TRUE

### The `“proxy-id”` property

      “proxy-id”                 gchar *

Sets the proxy URI user id for authentication. If the URI set via the "proxy" property contains a user-id already, that will take precedence.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: ""

Since: 1.2

### The `“proxy-pw”` property

      “proxy-pw”                 gchar *

Sets the proxy URI password for authentication. If the URI set via the "proxy" property contains a password already, that will take precedence.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: ""

Since: 1.2

### The `“multicast-iface”` property

      “multicast-iface”          gchar *

The network interface on which to join the multicast group.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: NULL

### The `“ntp-sync”` property

      “ntp-sync”                 gboolean

Synchronize received streams to the NTP clock.

Owner: GstRTSPSrc

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).

Owner: GstRTSPSrc

Flags: Read / Write

Default value: FALSE

### The `“sdes”` property

      “sdes”                     GstStructure *

The SDES items of this session.

Owner: GstRTSPSrc

Flags: Read / Write

### The `“tls-database”` property

      “tls-database”             GTlsDatabase *

TLS database with anchor certificate authorities used to validate the server certificate.

Owner: GstRTSPSrc

Flags: Read / Write

### The `“tls-validation-flags”` property

      “tls-validation-flags”     GTlsCertificateFlags

TLS certificate validation flags used to validate the server certificate.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: G_TLS_CERTIFICATE_UNKNOWN_CA|G_TLS_CERTIFICATE_BAD_IDENTITY|G_TLS_CERTIFICATE_NOT_ACTIVATED|G_TLS_CERTIFICATE_EXPIRED|G_TLS_CERTIFICATE_REVOKED|G_TLS_CERTIFICATE_INSECURE|G_TLS_CERTIFICATE_GENERIC_ERROR

### The `“do-retransmission”` property

      “do-retransmission”        gboolean

Ask the server to retransmit lost packets.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: TRUE

### The `“tls-interaction”` property

      “tls-interaction”          GTlsInteraction *

A GTlsInteraction object to promt the user for password or certificate.

Owner: GstRTSPSrc

Flags: Read / Write

### The `“ntp-time-source”` property

      “ntp-time-source”          GstRTSPSrcNtpTimeSource

NTP time source for RTCP packets.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: NTP time based on realtime clock

### The `“user-agent”` property

      “user-agent”               gchar *

The User-Agent string to send to the server.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: "GStreamer/1.16.3"

### 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).

Owner: GstRTSPSrc

Flags: Read / Write

Allowed values: >= G_MAXULONG

Default value: 1000

### The `“rfc7273-sync”` property

      “rfc7273-sync”             gboolean

Synchronize received streams to the RFC7273 clock (requires clock and offset to be provided).

Owner: GstRTSPSrc

Flags: Read / Write

Default value: FALSE

### The `“default-rtsp-version”` property

      “default-rtsp-version”     GstRTSPVersion

The preferred RTSP version to use while negotiating the version with the server.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: GST_RTSP_VERSION_1_0

Since: 1.14

### 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.

Owner: GstRTSPSrc

Flags: Read / Write

Allowed values: >= 0

Default value: 3000000000

### 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.

Owner: GstRTSPSrc

Flags: Read / Write

Default value: 0

### The `“backchannel”` property

      “backchannel”              GstRTSPBackchannel

Select a type of backchannel to setup with the RTSP server. Default value is "none". Allowed values are "none" and "onvif".

Owner: GstRTSPSrc

Flags: Read / Write

Default value: No backchannel

Since: 1.14

### The `“teardown-timeout”` property

      “teardown-timeout”         guint64

When transitioning PAUSED-READY, allow up to timeout (in nanoseconds) delay in order to send teardown (0 = disabled).

Owner: GstRTSPSrc

Flags: Read / Write

Default value: 100000000

## Signal Details

### The `“handle-request”` signal

    void
    user_function (GstRTSPSrc *rtspsrc,
                   gpointer    request,
                   gpointer    response,
                   gpointer    user_data)

Handle a server request in `request` and prepare `response` .

This signal is called from the streaming thread, you should therefore not do any state changes on `rtspsrc` because this might deadlock. If you want to modify the state as a result of this signal, post a GST_MESSAGE_REQUEST_STATE message on the bus or signal the main thread in some other way.

#### Parameters

rtspsrc | a GstRTSPSrc |
request | a GstRTSPMessage |
response | a GstRTSPMessage |
user_data | user data set when the signal handler was connected. |

Since: 1.2

### The `“on-sdp”` signal

    void
    user_function (GstRTSPSrc    *rtspsrc,
                   GstSDPMessage *sdp,
                   gpointer       user_data)

Emitted when the client has retrieved the SDP and before it configures the streams in the SDP. `sdp` can be inspected and modified.

This signal is called from the streaming thread, you should therefore not do any state changes on `rtspsrc` because this might deadlock. If you want to modify the state as a result of this signal, post a GST_MESSAGE_REQUEST_STATE message on the bus or signal the main thread in some other way.

#### Parameters

rtspsrc | a GstRTSPSrc |
sdp | a GstSDPMessage |
user_data | user data set when the signal handler was connected. |

Since: 1.2

### The `“select-stream”` signal

    gboolean
    user_function (GstRTSPSrc *rtspsrc,
                   guint       num,
                   GstCaps    *caps,
                   gpointer    user_data)

Emitted before the client decides to configure the stream `num` with `caps` .

#### Parameters

rtspsrc | a GstRTSPSrc |
num | the stream number |
caps | the stream caps |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` when the stream should be selected, `FALSE` when the stream is to be ignored.

Flags: Run First

Since: 1.2

### The `“new-manager”` signal

    void
    user_function (GstRTSPSrc *rtspsrc,
                   GstElement *manager,
                   gpointer    user_data)

Emitted after a new manager (like rtpbin) was created and the default properties were configured.

#### Parameters

rtspsrc | a GstRTSPSrc |
manager | a GstElement |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 1.4

### The `“request-rtcp-key”` signal

    GstCaps*
    user_function (GstRTSPSrc *rtspsrc,
                   guint       num,
                   gpointer    user_data)

Signal emitted to get the crypto parameters relevant to the RTCP stream. User should provide the key and the RTCP encryption ciphers and authentication, and return them wrapped in a GstCaps.

#### Parameters

rtspsrc | a GstRTSPSrc |
num | the stream number |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.4

### The `“accept-certificate”` signal

    gboolean
    user_function (GstRTSPSrc          *rtspsrc,
                   GTlsConnection      *peer_cert,
                   GTlsCertificate     *errors,
                   GTlsCertificateFlags user_data,
                   gpointer             user_data)

This will directly map to GTlsConnection 's "accept-certificate" signal and be performed after the default checks of GstRTSPConnection (checking against the GTlsDatabase with the given GTlsCertificateFlags) have failed. If no GTlsDatabase is set on this connection, only this signal will be emitted.

#### Parameters

rtspsrc | a GstRTSPSrc |
peer_cert | the peer's GTlsCertificate |
errors | the problems with `peer_cert` |
user_data | user data set when the signal handler was connected. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.14

### The `“before-send”` signal

    gboolean
    user_function (GstRTSPSrc     *gstrtspsrc,
                   GstRTSPMessage *arg1,
                   gpointer        user_data)

Flags: Run First

### The `“push-backchannel-buffer”` signal

    GstFlowReturn
    user_function (GstRTSPSrc *rtspsrc,
                   guint       buffer,
                   GstBuffer  *arg2,
                   gpointer    user_data)

#### Parameters

rtspsrc | a GstRTSPSrc |
buffer | RTP buffer to send back |
user_data | user data set when the signal handler was connected. |

Flags: Action

### The `“get-parameter”` signal

    gboolean
    user_function (GstRTSPSrc *rtspsrc,
                   gchar      *parameter,
                   gchar      *Returns,
                   GstPromise *arg3,
                   gpointer    user_data)

Handle the GET_PARAMETER signal.

#### Parameters

rtspsrc | a GstRTSPSrc |
parameter | a pointer to GstPromise |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` when the command could be issued, `FALSE` otherwise

Flags: Action

### The `“get-parameters”` signal

    gboolean
    user_function (GstRTSPSrc *rtspsrc,
                   GStrv       parameter,
                   gchar      *Returns,
                   GstPromise *arg3,
                   gpointer    user_data)

Handle the GET_PARAMETERS signal.

#### Parameters

rtspsrc | a GstRTSPSrc |
parameter | a pointer to GstPromise |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` when the command could be issued, `FALSE` otherwise

Flags: Action

### The `“set-parameter”` signal

    gboolean
    user_function (GstRTSPSrc *rtspsrc,
                   gchar      *parameter,
                   gchar      *Returns,
                   gchar      *arg3,
                   GstPromise *arg4,
                   gpointer    user_data)

Handle the SET_PARAMETER signal.

#### Parameters

rtspsrc | a GstRTSPSrc |
parameter | a pointer to GstPromise |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` when the command could be issued, `FALSE` otherwise

Flags: Action