UDP Source URL Syntax

The LEAD MPEG2 Transport UDP Source will play MPEG-2 Transport data streamed through UDP or TCP sockets. But it can also play raw data packetized in RTP packets (H264, JPEG, uncompressed, etc). Some of these formats (e.g., JPEG) contain all of the data needed to stream the video. Others (e.g., H264 and uncompressed) require extra information to be passed via 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 LEAD MPEG2 Transport UDP Source will listen for incoming data for 16 seconds. If nothing is received during this time, the load will fail. The value of the timeout can be changed 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]] 

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:
 

ip_address

The IP address of the server sending the data. This can be in the usual Ipv4 format (xxx.xxx.xxx.xxx), 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 octet in the Ipv4 address is between 224..239 (0xE0 .. 0xEF). If the first octet is not in this range, the stream is unicast.

network_card

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

udp_port

(Optional). The port number on which to listen. The port must be a number from 1 to 65535. Note that the port should not be blocked by any firewall that is on the client, on the server, or between the client and server.

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:

ip_address

The IP address of the server sending the data. This can be in the usual Ipv4 format (xxx.xxx.xxx.xxx), 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.

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

tcp_port

p>(Optional). The port number on which to listen. The port must be a number from 1 to 65535. Note that the port should not be blocked by any firewall that is on the client, on the server, or between the client and server.

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.

paramN

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

Logging

(Optional, default value is 0, no logging). Indicates whether the UDP source should log time information, which can be used to determine exactly when it started receiving data. Set this parameter to 1 to enable logging and 0 to disable.

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 the start time for the received stream has been logged. The start time can be used to synchronize two UDP streams received independently by recording the absolute start time for each stream. With two absolute start times for two or more streams, one 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.

Timeout

(Optional, default value is 16 seconds). Indicates how long (in seconds) the UDP source will wait for data before giving up. If no data is received 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.

Latency

(Optional, only for Raw streams. The default value is 0 ms). Indicates how much time (in milliseconds) raw data should be buffered before playback starts. Increase this parameter to possibly achieve smoother playback of raw streams. For example, a value of 500 will buffer data for 0.5 seconds before playing video. This means that the playback will be 0.5 seconds behind the live stream, but the video may play more smoothly and will tolerate variations of up to 0.5 seconds in the time the samples arrive.

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 in 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 payload number and the associated compression.

• The number of RTP units per second.

• The sequence header information, if it is not sent with the video stream.

The UDP source requires this information to process these streams. There are two useful parameters (rtpmap and fmtp), and their syntax is described as follows:

rtpmap=payload_type;compression/RTP_units_per_second 

RTPMAP Parameters

payload_type

The# payload type value must be between 96 and 127, inclusive.

compression

The string describing the compression. 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 (;): rtpmap=99;H264/90000

An example URL for an H264 stream sent to port 40000 containing RTP packets with a payload of 99 and sequence header packets (NAL units 7 and 8) sent inside the compressed stream:

udp://192.168.1.100:40000?rtpmap=99;H264/90000 
 
fmtp=payload_type;sprop-parameter-sets="seq1,seq2,seqN" 

FMTP Parameters

payload_type

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

sprop-parameter-sets

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.

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 formatting this extra information is the Session Description Protocol, also known as SDP. The SDP describes the stream. The UDP source needs only the following:

• The payload number and associated compression.

• The number of RTP units per second.

• The video characteristics (colorspace, width, height, and bits per channel).

The UDP source requires this information to process these streams. There are two useful parameters (rtpmap and fmtp) and their syntax is described as follows:

rtpmap=payload_type;compression/RTP_units_per_second 

For uncompressed video, compression should be raw:

rtpmap=payload_type;raw/RTP_units_per_second 
 
fmtp=payload_type;sampling=sampling_mode;width=video_width;height=video_height;depth=bits_per_channel 

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)

This is a valid example for the fmtp parameter:

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

Putting both parameters 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, 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; consult the device's manual for more information.

Examples of Valid URLs

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.

Standard RTP packets have a static payload type set to a value inclusively 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 by passing the rtpmap parameter on the URL:

rtpmap=payload_type;compression/RTP_units_per_second 

Compression Values

The following values are supported for compression (it is case-sensitive):

• H264 - H264 video. See Note 2 for more information

• raw - Raw uncompressed video. See Note 3 for more information

• MPEG2 - MPEG2 Video in MPEG2 Program or Transport packets. In this case, the RTP_units_per_second is optional, because MPEG2 packets will contain timing information

• JPEG - JPEG video.

Examples of Valid URLs

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 wishes to abort the wait, call ResetSource, which will abort the load process with the E_ABORT error.

Append the Timeout=xxx to the URL query string 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

The Timeout parameter can be combined 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, 3 parameters are specified (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, use the comp parameter and pass the intended compression and the sequence headers used by this 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.

Syntax

The syntax is as follows:

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

A raw H264 stream can be indicated as follows:

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

Examples of valid URLs:

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"