udpsrc2
udpsrc2 is a network source that reads UDP packets from the network.
It can be combined with RTP depayloaders to implement RTP streaming.
The udpsrc2 element supports automatic port allocation by setting the
port property to 0. After setting the udpsrc2 to PAUSED, the
allocated port can be obtained by reading the port property.
udpsrc2 can read from multicast groups by setting the address
property to the IP address of the multicast group.
Alternatively one can provide a custom socket to udpsrc2 with the socket
property, udpsrc2 will then not allocate a socket itself but use the provided
one.
The caps property is mainly used to give a type to the UDP packet so that they can be autoplugged in GStreamer pipelines. This is very useful for RTP implementations where the format description of the UDP packets is transferred out-of-bounds using SDP or other means.
The buffer-size property is used to change the default kernel receive buffer size used for receiving packets. The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values, on Linux, for example, the default buffer size is typically 50K and can be increased to maximally 100K.
The skip-first-bytes property is used to strip off an arbitrary number of bytes from the start of the raw UDP packet and can be used to strip off proprietary header, for example.
udpsrc2 is always a live source. It does however not provide a GstClock,
this is left for downstream elements such as an RTP session manager or demuxer
(such as an MPEG TS demuxer). As with all live sources, the captured buffers
will have their timestamp set to the current running time of the pipeline.
If supported, udpsrc2 uses receive timestamps provided by the socket for timestamping
outgoing buffers, which is generally more accurate. Otherwise it uses the time when the
buffer was received by the element from the socket.
udpsrc2 implements a GstURIHandler interface that handles udp://host:port
type URIs.
If the timeout property is set to a value bigger than 0, udpsrc2
will generate an element message named GstUDPSrcTimeout if no data was received
in the given timeout.
The message's structure contains one field:
-
guint64
timeout: the timeout in nanoseconds that expired when waiting for data.
The message is typically used to detect that no UDP packet arrives in the receiver because it is blocked by a firewall.
A custom file descriptor can be configured with the socket property. The socket will be closed when setting the element to READY by default. This behaviour can be overridden with the close-socket property, in which case the application is responsible for closing the file descriptor.
Examples
gst-launch-1.0 -v udpsrc2 ! fakesink dump=1
A pipeline to read from the default port and dump the UDP packets.
To actually generate UDP packets on the default port one can use the
udpsink element. When running the following pipeline in another terminal, the
above mentioned pipeline should dump data packets to the console.
gst-launch-1.0 -v audiotestsrc ! udpsink
gst-launch-1.0 -v udpsrc port=0 ! fakesink
read UDP packets from a free port.
Hierarchy
GObject ╰──GInitiallyUnowned ╰──GstObject ╰──GstElement ╰──GstBaseSrc ╰──GstPushSrc ╰──udpsrc2
Implemented interfaces
Factory details
Authors: – Sebastian Dröge
Classification: – Source/Network
Rank – none
Plugin – rsudp
Package – gst-plugin-udp
Pad Templates
Properties
address
“address” gchararray
IP address to bind to.
If this is a multicast address, then the socket will actually bind to 0.0.0.0
or ::1. Selection of the interface to use for receiving multicast packets can
be done with the multicast-iface property.
Flags : Read / Write
Default value : 0.0.0.0
allow-gro
“allow-gro” gboolean
Enable generic receive offload (GRO) if supported on the platform.
This allows receiving multiple packets at once and can potentially improve performance.
GRO can only be effective under certain conditions, including
- Consecutive packets must have the same size (except for the last, which can be smaller)
- IP/UDP headers must match (source / destination, etc)
- IP ID field must either be all zero or incrementing by one
- Packets must not be fragmented (and probably DF flag is required)
- UDP checksum must be valid and not zero
- NIC/driver/kernel must support it
If not possible then a single packet will be received at once.
Enabling this has two potential drawbacks:
- With the current GStreamer design, multiple packets received via GRO need to be split into individual sub-buffers before pushing downstream. The splitting of the buffers involves additional heap allocations.
- Each receive buffer needs to be overallocated: there must be space for 64 packets of the maximum packet size in each buffer. Even if GRO is not actually used because one of the conditions above is not fulfilled, the overallocation has to happen.
Flags : Read / Write
Default value : false
auto-multicast
“auto-multicast” gboolean
Automatically join/leave multicast groups
Flags : Read / Write
Default value : true
batch-size
“batch-size” guint
Configures how many packets are received and forwarded at once. This is a maximum and if fewer packets are currently available at a time then fewer packets will be processed at once.
Note that by enabling allow-gro 64 times as many packets will be received if possible.
Flags : Read / Write
Default value : 16
buffer-size
“buffer-size” guint
Socket receive buffer size.
The buffer size may be increased for high-volume connections, or may be decreased to limit the possible backlog of incoming data. The system places an absolute limit on these values, on Linux, for example, the default buffer size is typically 50K and can be increased to maximally 100K.
Setting this to 0 uses the default receive buffer size.
On Linux the maximum can be configured via /proc/sys/net/core/rmem_max.
Flags : Read / Write
Default value : 0
close-socket
“close-socket” gboolean
Close socket on state change if passed as property
Flags : Read / Write
Default value : false
mtu
“mtu” guint
Maximum expected packet size. This directly defines the allocation size of the receive buffer pool.
If bigger packets are received then they are discarded.
Flags : Read / Write
Default value : 1500
multicast-iface
“multicast-iface” gchararray
The network interface on which to join the multicast group. This allows multiple interfaces separated by comma. ("eth0,eth1")
Flags : Read / Write
Default value : NULL
port
“port” guint
Port to bind to.
If this is set to 0 then a free port will be selected and is available via this property once the element reached READY state.
Flags : Read / Write
Default value : 5000
preserve-packetization
“preserve-packetization” gboolean
By default each buffer contains a single UDP packet, i.e. preserves packetization. This is required for various protocols, e.g. RTP.
For other formats, e.g. MPEG-TS, this is not required and multiple packets can potentially be stored in a single buffer. Doing so can improve performance.
Flags : Read / Write
Default value : true
skip-first-bytes
“skip-first-bytes” guint
Number of bytes to skip for each UDP packet.
This can be used to strip off proprietary headers, for example.
Flags : Read / Write
Default value : 0
source-filter
“source-filter” gchararray
Comma-separated list of source IP addresses or hostnames for filtering
Flags : Read / Write
Default value : NULL
source-filter-exclusive
“source-filter-exclusive” gboolean
If set to TRUE (exclusive mode) all addresses in source-filter will be filtered out, otherwise (inclusive mode) only the addresses in source-filter will be accepted.
Flags : Read / Write
Default value : false
timeout
“timeout” guint64
Post a message after timeout nanoseconds (0 = disabled)
Flags : Read / Write
Default value : 0
uri
“uri” gchararray
URI in the form of udp://multicast_group:port
Flags : Read / Write
Default value : udp://0.0.0.0:5000
used-socket
“used-socket” GSocket *
Socket currently in use for UDP reception. (None = no socket)
Flags : Read
The results of the search are