Products | Support | Send comments on this topic. | Email a link to this topic. | Back to Getting Started | Help Version 18.0.10.24
LEADTOOLS Filters Help
LEADTOOLS Filters Help > Filters, Codecs and Interfaces > Streaming Filters > UDP Source URL syntax

UDP Source URL Syntax

Show in webframe

The UDP source will usually play MPEG-2 Transport data streamed over UDP or TCP sockets. But it can also play raw data packetized in RTP packets (H264, JPEG, uncompressed, etc). Some of these formats (eg: JPEG) contain all the data needed to stream the video. Others (eg: H264, uncompressed) need extra information to be passed on the URL to describe the data format. See the Notes below for a discussion on how to describe raw H264(Note 2), uncompressed video (Note 3) and video with dynamic RTP payloads (Note 4).

The UDP source will listen for 16 seconds for incoming data. If nothing comes in during this time, the load will fail. You can change the value of the timeout using the "Timeout" parameter described below (Note 5).

The format of the string for UDP streaming is as follows:

   udp://ip_address[:udp_port][/network_card][?param1=val1[&param2=val2]...[&paramN=valN]]

The format of the string for TCP streaming is as follows:

   tcp://ip_address[:udp_port][/network_card][?param1=val1[&param2=val2]...[&paramN=valN]]

UDP Streaming

The format of the string for UDP streaming is as follows:
 

Parameter

Description

ip_address

The IP address of the server sending the data. This can be in the usual Ipv4 format (xx.xx.xx.xx), or it can be a valid host address accepted by the standard function inet_addr. For example, localhost is equivalent to 127.0.0.1

The stream is considered to be multicast if the first number in the Ipv4 address is between 224..239 (0xE0 .. 0xEF). If the first number is not in this range, the stream is unicast.

network_card

(Optional) The address of the network card receiving the data. This is optional if it is missing, the default network card will be used. This is used only for receiving multicast streams.

udp_port

(Optional) The port number on which to listen. The port must be a number from 1 to 65535. Note that you must make sure the port is open if you are running firewall software.

paramN=valN

(Optional, valid only with udp prefix) Parameters used to describe the format of raw or RTP streams containing dynamic payloads for certain samples. See the notes below for the possible values of parameters and values. Multiple parameter pairs should be separated using the '&' character.

 

 TCP Streaming

The format of the string for TCP streaming is as follows:

Parameter

Description

ip_address

The IP address of the server sending the data. This can be in the usual Ipv4 format (xx.xx.xx.xx), or it can be a valid host address accepted by the standard function inet_addr. For example, localhost is equivalent to 127.0.0.1. This is usually the IP address of the sending (server) computer.

TCP streams cannot be multicast. All TCP streams are assumed to be unicast.

tcp_port

(Optional) The port number on which to listen. The port must be a number from 1 to 65535. Note that you must make sure the port is open if you are running firewall software.

paramN=valN

(Optional, valid only with udp prefix) Parameters used to describe the format of raw or RTP streams containing dynamic payloads for certain samples.  See the notes below for the possible values of parameters and values. Multiple parameter pairs should be separated using the '&' character.

Note 1: List of parameters used by the UDP Source filter

Here is a list of the "paramN" parameters described above.

Parameter

Description

Logging

(Optional) Indicates whether the UDP source should log time information, which can be used to determine exactly when you started receiving data. Set this parameter to 1 to enabled logging and 0 to disabled. 0 is the default so there is no real advantage to setting Logging to 0 (you might just as well not pass it at all).

Keep in mind that Logging will increase the amount of memory used by the process, so it is recommended that you disable logging by calling ILMUDPSrc::StopLogging once you find the start time for the received stream. The start time can be used to synchronize two UDP streams received independently by recording the absolute start time for each stream. If you have the two absolute start times for two or more streams, you can then calculate the time difference and play them side-by-side, or use the difference to find out which frames were received at the same time from the two streams.

Logging must be enabled for the ILMUDPSrc::GetReceiveTime method to work.

See the Get Start Time for the Received Stream topic for more information.

Timeout

(Optional) Indicates how long will the UDP source wait for data initially before giving up (in seconds). The default is 16. If nothing comes in during this time, the filter will return a timeout error during IFileSourceFilter::Load. See Note 5 for more details.

rtpmap

(Optional, only for RTP streams or streams with dynamic payloads) Used to specify the payload type, the compression and the sample rate used by a RTP stream. See Note 2, Note 3 and Note 4 below for more details.

fmtp

(Optional, only for RTP streams) Used to provide compression-specific information. See Note 2 and Note 3 below for more details.

comp

(Optional, only for Raw streams) Used to provide compression-specific information. See Note 6 below for more details.

Note 2: Parameters used to describe RTP H264 video streams

H264 streams sent inside RTP packets use dynamic payloads with a payload type between 96 and 127. These streams can only be decoded when there is extra information being sent using a separate communication channel. The most common method of sending this extra information is through a Session Description Protocol (also known as SDP). The SDP contains extra information describing the stream. The UDP source needs only the following:

The UDP source needs to know this information in order to process these streams. There are two useful parameters right now (rtpmap and fmtp) and their syntax is described as follows:

Parameter

Description

payload_type

The payload type. This value should be between 96 and 127.

compression

The string describing the compression. Right now, only H264 is supported.

RTP_units_per_second

 The number of RTP units per second. This value is usually 90000.

These values are usually sent in the SDP information via the a=rtpmap line, as in the following example:

a=rtpmap:99 H264/90000

This should be translated by replacing the space with semicolon (';) into

rtpmap=99;H264/90000

So, the URL syntax for a H264 stream sent to port 40000 containing RTP packets with a payload of 99 and with sequence header packets (NAL units 7 and 8) sent inside the compressed stream is something like this:

udp://192.168.1.100:40000?rtpmap=99;H264/90000

Parameter

Description

payload_type

The payload type. This value should be between 96 and 127. It should match the value in the rtpmap parameter.

seqN

The base64 encoding of the sequence parameter. When there are several sequence headers, they are separated with a comma ( , ). Usually, there are two sequence headers. A double quote ( " ) should be added at the beginning and end of the sequence list.

Note that the three dots would not be passed in the string. They are there only to indicate there could be other sequence values between seq2 and seqN.

These values are usually sent in the SDP information via the a=fmtp line, as in the following example:

a=fmtp:96 packetization-mode=1; profile-level-id=420029; sprop-parameter-sets=Z0IAKeKQFge2BqwYBBuHiRFQ,aM48gA==

In the above example, there are two sequence header strings following the sprop-parameter-sets, separated with a comma. The UDP source filter is interested only in the sprop-parameter-sets field, so this line should be translated into:

fmtp=96;sprop-parameter-sets="Z0IAKeKQFge2BqwYBBuHiRFQ,aM48gA=="

And this pair should be appended to the URL to form something like this:

udp://192.168.1.100:40000?rtpmap=99;H264/90000&fmtp=96;sprop-parameter-sets="Z0IAKeKQFge2BqwYBBuHiRFQ,aM48gA=="

The above URL syntax describes a stream streaming on port 40000, with H264 data inside RTP packets with payload type set to 99, with 90000 RTP units per second and whose sequence headers are not part of the stream. Instead, they are passed through the sprop-parameter-sets component of the fmtp parameter.

Note 3: Parameters used to describe RTP uncompressed video streams

Uncompressed streams sent inside RTP packets use dynamic payloads with a payload type between 96 and 127. These streams can only be decoded when there is extra information being sent using a separate communication channel. The most common method of sending this extra information is through a Session Description Protocol (also known as SDP). The SDP contains extra information describing the stream. The UDP source needs only the following:

The UDP source needs to know this information in order to process these streams. There are two useful parameters right now (rtpmap and fmtp) and their syntax is described as follows:

For uncompressed video, compression should be 'raw', so you need to pass: rtpmap=payload_type;raw/RTP_units_per_second.

Right now, only the following values are accepted

sampling_mode: YCbCr-4:2:2

video_width: any positive value that is a multiple of 2

video_height: any positive value

bits_per_channel: 8 (note that this means each component is 8 bits, not that there are 8 bits/pixel)

So this is a valid example for the fmtp option:

fmtp=112;sampling=YCbCr-4:2:2;width=1280;height=750;depth=8

 

Putting both options together, this URL tells the UDP source filter to load uncompressed, 1280x750 UYVY video from port 8003:

udp://192.168.6.101:8003?rtpmap=112;raw/90000&fmtp=112;sampling=YCbCr-4:2:2;width=1280;height=750;depth=8

 

Note that for the above particular case, the first few lines contains VANC (non-video) data. The useful video might have 720 or even only 480 lines. Also, the useful data might start from a certain column in the video. In such cases, you can use the LEAD Video Crop Filter to strip out non-image data and leave only the useful video portion. These details are specific to the device used to stream the video and you should consult that device's manual for more information.

Examples of Valid Strings

udp://127.0.0.1:9005 - Receives the Unicast stream from 127.0.0.1 on port 9005

udp://224.1.1.1:9005/20.5.1.200 - Receives the Multicast stream 224.1.1.1 on port 9005 using the network card with the IP address of 20.5.1.200

tcp://127.0.0.1:9005 Receives the TCP stream from 127.0.0.1 (local computer) on port 9005

udp://192.168.1.100:40000?rtpmap=99;H264/90000 - Receives a Unicast stream containing raw H264 video with sequence headers from 192.168.1.100 on port 40000. The stream uses dynamic RTP packets with payload type 99 and the timestamps unit is 1/90000 of a second.

udp://192.168.1.100:40000?rtpmap=99;H264/90000&fmtp=99;sprop-parameter-sets="Z0IAKeKQFge2BqwYBBuHiRFQ,aM48gA==" - Receives a Unicast stream containing raw H264 video without sequence headers from 192.168.1.100 on port 40000. The stream uses dynamic RTP packets with payload type 99 and the timestamps unit is 1/90000 of a second.

udp://192.168.6.101:40000?rtpmap=99;raw/90000&fmtp=99;sampling=YCbCr-4:2:2;width=1280;height=720;depth=8 - Receives a Unicast stream containing raw uncompressed video conforming with RFC 4175 from 192.168.6.100 on port 40000. The stream uses dynamic RTP packets with payload type 99 and the timestamps unit is 1/90000 of a second. See  for more details on the syntax for playing raw uncompressed streams.

Note 4: Parameters used to describe streams using RTP packets with dynamic payloads

The standard RTP packets have static payload type set to values between 1 and 34 and can be automatically identified by the payload type. If the RTP packets have payloads greater than 96, the UDP source filter has no way determining the format. In this case, the stream information is specified in other means and you have to specify it by passing the rtpmap parameter on the URL:

rtpmap=payload_type;compression/RTP_units_per_second

Currently the following values are supported for 'compression' (it is case-sensitive):

Examples of Valid Strings

udp://192.168.0.149:7800?rtpmap=96;MPEG2 - Receives the Unicast stream from 192.168.0.149 on port 7800 containing MPEG2 video inside RTP packets with payload 96. Note that RTP_units_per_second is optional and not specified because the timestamps are indicated by the PTS timestamps encapsulated inside the MPEG2 headers.

udp://192.168.0.149:7800?rtpmap=97;JPEG/90000 - Receives the Unicast stream from 192.168.0.149 on port 7800 containing JPEG stream inside RTP packets with payload 96. The timing information uses 90000 units per second

 

Note 5: Timeout (selected with Timeout=xxx):

While waiting for data, ltmm sends the application EC_LOADSTATUS messages informing it that the UDP source is waiting for data. If the user decides to abort the wait, you can call ResetSource, which will abort the load process with the E_ABORT error.

Append the ?Timeout=xxx to the URL to specify a timeout value. xxx is the value in seconds of how long to wait. The default value is 16 seconds. Pass 0 for infinite wait.

Syntax:

udp://ip_address[/network_card][:udp_port]?Timeout=xxx

You can combine the Timeout parameter with the other parameters using the '&' character. For example, the following URL will specify a timeout of 60 seconds while loading a Raw H264 stream:

udp://192.168.1.100:40000?Timeout=60&rtpmap=99;H264/90000&fmtp=96;sprop-parameter-    sets="Z0IAKeKQFge2BqwYBBuHiRFQ,aM48gA=="

In the above example, I specified 3 parameters (Timeout, rtpmap and fmtp).

The toolkit sends EC_LOADSTATUS with Param1 set to AM_LOADSTATUS_WAITING_FOR_DATA and Param2 set to the number of milliseconds elapsed since the UDP source started waiting. The following example aborts the wait after 10 seconds:

 

LRESULT CMainFrame::OnPlayerNotify(WPARAM wParam, LPARAM lParam)

{

   switch(wParam)

   {

   case ltmmPlay_Notify_MediaEvent:

      {

         ltmmMediaEvent *pEventParams = (ltmmMediaEvent *)lParam;

         if(pEventParams && pEventParams->lEventCode == ltmmEC_LOADSTATUS)

            if(pEventParams->lParam1 == ltmmAM_LOADSTATUS_PROGRAM_PACKET_RECEIVED)

            {

               // MPEG2 Transport Demux has detected how many elementary streams are in the MPEG-2 Transport stream

               // you can now tell it to speed up the load by waiting only for the video streams to be discovered

               ILMMpgDmx *pMpgDmx = GetMPEG2DemuxInterface();

               if(pMpgDmx)

               {

#ifdef EXCLUDE_NONVIDEO_STREAMS

                  CMPEG2DemuxCallback::MarkNonVideoStreamsUnimportant(pMpgDmx);

#endif

                  pMpgDmx->Release();

               }

            }

            else if(pEventParams->lParam1 == ltmmAM_LOADSTATUS_WAITING_FOR_DATA)

            {

               if(pEventParams->lParam2 >= 10000)

                  m_player->ResetSource();   // abort the load if it takes more than 10 seconds

            }

      }

}

Note 6: Parameters used to describe Raw (non-RTP) streams

Some devices (like the DM6467 Texas Instruments encoder) will stream raw H264 streams without encapsulating the compressed data inside RTP packets. For these streams, data is sent as MPEG packets prefixed with 00 00 01 byte sequences. The sequence headers for these packets might be sent at rare intervals or might never be sent at all. For these streams, you should use the comp parameter and pass the intended compression and the sequence headers used by this stream if it is not passed as part of the stream.

Even if the sequence header is passed as part of the stream, the playback will start much faster if you pass the sequence header as part of the URL. If you do not pass the sequence header in the URL, playback will not start until the sequence header is received.

The syntax is as follows:

comp=compression[;seq-headers="xxx"]

Where compression can be one of the following: MPEG2, MPEG4, H264.

And seq-headers is an optional parameter that specifies the sequence headers for the particular compression in binary values converted to ascii. Each byte 0xAB is converted to the string "AB". For example, the byte sequence 0x00 0x00 0x01 0x67 0x42 would be converted to the string "0000016742".

So a raw H264 stream might be indicated as follows:

comp=H264;seq-headers="0000000167428028F40481C8800000000168DE3C80"

Examples of valid strings:

udp://127.0.0.1:5678?comp=H264 - Receives a raw H264 stream from port 5678 not encapsulated inside RTP packets. The sequence headers are sent as part of the stream.

udp://127.0.0.1:5678?comp=H264;seq-headers="0000000167428028F40481C8800000000168DE3C80" - Receives a raw H264 streams from port 5678 and with the 00 00 01 67 42 80 [...] DE 3C 80 sequence header.

Products | Support | Contact Us | Copyright Notices
© 2006-2014 All Rights Reserved. LEAD Technologies, Inc.