IFileSourceFilter Interface

Interface Methods:

HRESULT GetCurfile(LPOLESTR *ppszFileName, AM_MEDIA_TYPE *pmt);

Parameters

ppszFileName

A valid pointer to a pointer that will receive a copy of the URL string. This cannot be NULL.

pmt

A pointer to an AM_MEDIA_TYPE structure. This pointer is optional and you can pass NULL if you do not need the media type.

Description

Gets the current URL string. This string contains the IP address, the port and the network card address. See the Load method for more information on the format of the URL string.

If the function succeeds, the ppszFileName pointer gets updated with a pointer to a buffer containing the URL. This buffer was allocated with CoTaskMemAlloc. You are responsible for freeing this buffer when you are done with it by calling CoTaskMemFree.

If the function succeeds and pmt is set to a valid pointer to AM_MEDIA_TYPE structure, this structure gets initialized with a copy of the stream media type. You are responsible for freeing the data allocated in this structure by calling the FreeMediaType function. Please refer to the Microsoft documentation for more information on this function.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

E_POINTER

ppszFilename is NULL

 

HRESULT Load(LPCOLESTR pszFileName, const AM_MEDIA_TYPE *pmt);

Parameters

pszFileName

A valid pointer to a buffer containing the URL of the UDP stream. This cannot be NULL.

pmt

A pointer to an AM_MEDIA_TYPE structure indicating the media type of the data being streamed. This pointer can be NULL, in which case a default media type will be assumed.

Description

This function sets the URL of UDP, TCP or RTSP stream. This string specifies the following three items:

  1. IP address of the server sending the data

  2. (Optional) The UDP, TCP or RTSP port on which the data will be received. If no port is specified, 9005 will be used for UDP/TCP and 554 for RTSP.

  3. (Optional) The IP address of network card receiving the data. If no network card is specified, the default network connection will be used.

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]]

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

   rtsp://[username[:password]@]ip_address[:rtsp_port]/server_URL[?param1=val1[&param2=val2]...[&paramN=valN]]

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 (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 RTP streams containing dynamic payloads for certain raw samples. Right now, this is used only with raw H264 streams. See Note 1 below for the possible values of parameters and values. Multiple parameter pairs should be separated using the '&' character.

 

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 (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 RTP streams containing dynamic payloads for certain raw samples. Right now, this is used only with raw H264 streams. See Note 1 below for the possible values of parameters and values. Multiple parameter pairs should be separated using the '&' character.

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

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.

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

rtsp_port

(Optional) The port number on which the server is listening for RTSP commands. The port must be a number from 1 to 65535. If absent, the default RTSP port (554) will be used.

username

(Optional) For servers that use authentication, you can pass a username as part of the connection string. Passing the username and password will avoid the message box asking for the username and password. If you pass the username and password but still get the message box, the server has rejected supplied username and/or password.

password

(Optional) For servers that use authentication, you can pass a username and password as part of the connection string. Passing the username and password will avoid the message box asking for the username and password. If you pass the username and password but still get the message box, the server has rejected supplied username and password.

server_URL

The URL of the server RTSP. Obtain this from the server documentation.

paramN=valN

(Optional) Some of these parameters are for the filter, while others are passed to the RTSP server. Consult the server's documentation for more information on server-dependent parameters. Server-dependent parameters are commonly used for managing the server's behavior (such as the video or audio compression, video size, etc.). See the following examples for such parameters.

The parameters used by the filter are in the following table. Any parameters not listed below are considered server-dependent and are passed along to the server:

 

Parameter

Possible values

 

Transport

unicast - The data should be set through a unicast stream using UDP packets. This is the default, so you don't really need to use this value.

multicast - The data should be set through a multicast stream using UDP packets. The server is responsible for picking the multicast address.

Note: Both parameter and value are case sensitive, so you should use "Transport=multicast", not "transport=multicast".

HTTP - The data is sent using RTSP through HTTP tunneling in TCP packets. The data for all the streams is sent though the same port, so the performance is not as good as using UDP packets. But in some situations the firewalls between the camera and the client might prevent the UDP packets for getting through, so HTTP tunneling is the only way to stream the data.

Note: Not all the RTSP servers support HTTP tunneling. The LTMM_E_HTTP_GET_FAILED  (0x8005003E) error code will be returned when you try to render the source stream if the server does not support HTTP tunneling.

Examples of valid strings:

UDP URLs:

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

udp://224.1.1.1:9005/20.5.1.200 - Receive 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 – Receive the TCP stream from 127.0.0.1 (local computer) on port 9005

udp://192.168.1.100:40000?rtpmap=99;H264/90000 - Receive 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==" - Receive 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 - Receive 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 Note 2 for more details on the syntax for playing raw uncompressed streams.

RTSP URLs:

rtsp://192.168.0.164/axis-media/media.amp - Connect to a RTSP server running on 192.168.0.164 at the "axis-media/media.amp" URL. The data will be streamed using the default compression.

rtsp://root:pass@192.168.0.164/axis-media/media.amp?videocodec=jpeg - Connect to a RTSP server running on 192.168.0.164 at the "axis-media/media.amp" URL. The data will be streamed using the jpeg compression. This server is using authentication, and we are connecting as username 'root' and with the password 'pass' in order to avoid having to enter a username and password.

rtsp://192.168.6.100/mpeg4/media.amp?Transport=multicast - Connect to a RTSP running on 192.168.6.100 at the "mpeg4/media.amp" url and stream the data in multicast mode. The data will be streamed using the MPEG4 compression.

rtsp://192.168.6.100/mpeg4/media.amp?Transport=HTTP - Connect to a RTSP running on 192.168.6.100 at the "mpeg4/media.amp" url and stream the data using RTSP over HTTP tunneling mode. The data will be streamed using the MPEG4 compression and sent using TCP packets.

See the RTSP Source URL syntax topic for an in-depth discussion about the URLs used by RTSP servers. The topic also contains a table with sample URLs for servers that we tested, together with the video and audio compressions used by each server.

Each RTSP server can have its own URL. Consult each server's documentation to find out its URL. See Note 2 below for a list of URLs for some RTSP servers that we tested.

To determine the IP addresses of the network connections on your a computer running Windows XP, type the ipconfig command at the DOS prompt. For more information on obtaining your machine's host name, refer to How to Get Your Own IP Address Programmatically.

One might want to use a particular network card when the system has two network connections and one is faster than the other. For example, a laptop might be connected to the network with a wireless network card and a regular network wire. In this case, it would be better to use the wired connection because it is faster and more reliable.

The UDP source filter 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 and uncompressed video.

Note 1: Parameters used to describe raw 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 2: Parameters used to describe raw 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.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

Value

Meaning

HRESULT_FROM_WIN32(WSAHOST_NOT_FOUND)

(0x80072AF9) The URL is invalid.

HRESULT_FROM_WIN32(WSAETIMEDOUT)

(0x8007274C) The URL might be valid, but the remote end is not sending data.

E_OUTOFMEMORY

(0x8007000E) Out of memory.

E_FAIL                                                                           

 (0x80004005) Unspecified error.

HRESULT_FROM_WIN32(xxx)

A Windows error xxx has occurred. Consult the Microsoft documentation for the definition of the HRESULT_FROM_WIN32 macro and the complete list of Windows error codes.