OpenVideo Streaming API RTSP Connection Methods July 26, 2016 Page 1 of 13
Table of Contents 1. Introduction... 3 1.1. Overview...3 1.2. Purpose...3 1.3. Intended Audience...3 1.4. Definitions, Acronyms, Abbreviations...3 1.5. References...4 1.6. Limitations...4 2. RTP Media Retrieval from Lenel NVR... 5 2.1. Getting Live Media (Video/Audio) from the Lenel NVR via RTP...5 2.2. Getting Recorded Media (Video/Audio) from the Lenel NVR via RTP...6 2.2.1. Time Range Selection...7 2.3. Extended RTSP Usage (Requires Custom Client Behavior)...8 2.3.1. Requesting Time-Range in the Range Header Instead of the URL...8 2.3.2. ONVIF (Client-Side Rate Control) Example...9 2.3.3. ONVIF Immediate Mode Seeking... 10 2.4. TIME FORMATS... 11 2.4.1. TIME FORMAT from RFC2326... 11 2.4.2. TIME FORMAT from ISO 8601 EXTENDED... 11 2.5. RTSP Errors... 11 2.6. Configuring Preferred Input Networking Transports in VLC... 11 July 26, 2016 Page 2 of 13
1. Introduction 1.1. Overview This document provides a description of Lenel NVR RTP/RTSP Server version 7.2 (and later) supported commands for external clients to consume media (video/audio) from the LNVR. This document covers the following: Methods to retrieve live video from the Lenel NVR via RTP/RTSP. Methods to retrieve recorded video from the Lenel NVR via RTP/RTSP. Alternate methods to retrieve recorded video from the Lenel NVR via RTP/RTSP. This document does not describe methods to include RTP video on a web page which requires the use of a RTP/RTSP plug-in client for the specific web browser. Also, the RTP/RTSP server does not support delivery of video on HTTP transport. 1.2. Purpose The document provides information for the purpose of developing software that needs to receive video from the Lenel NVR (LNVR) via RTP/RTSP. 1.3. Intended Audience This document is intended for 3 rd -party Lenel partners who develop the software intended to interface with Lenel NVR. 1.4. Definitions, Acronyms, Abbreviations Lenel NVR Lenel Network Video Recorder July 26, 2016 Page 3 of 13
1.5. References 1 RFC2326 - RTSP http://www.ietf.org/rfc/rfc2326.txt 2 RFC3550 - RTP & RTCP http://www.ietf.org/rfc/rfc3550.txt 3 RFC3640 - RTP MP4-ES http://www.ietf.org/rfc/rfc3640.txt 4 RFC6416 - RTP MP4 A/V http://www.ietf.org/rfc/rfc6416.txt 5 RFC3984 - RTP H264 http://www.ietf.org/rfc/rfc3984.txt 6 RFC2435 - RTP MJPEG http://www.ietf.org/rfc/rfc2435.txt 7 RFC3551 - RTP Profile for A/V Min. Ctrl (G711.0) http://www.ietf.org/rfc/rfc3551.txt 8 RFC4856 - Media Types Registration http://www.ietf.org/rfc/rfc4856.txt 1.6. Limitations The following limitations shall apply when retrieving any video from the Lenel NVR: 1. The video will not be rotated. This is a limitation of the RTP specification therefore video will be presented as it is received from the camera. The Lenel Video components have logic to rotate the video as needed so it is expected that the clients will do the same. 2. The video will be provided as it is stored / retrieved on the recorder. This means that the recorder will preserve the Media (MJPEG, MPEG4, H264) / size (resolution) / and speed (frame-rate), and will provide the same as an output. In essence, there is no transcoding on the recorder to reduce the requested bandwidth. 3. The Lenel NVR supports client-side flow-control as defined in the ONVIF Streaming specification; however, use of this feature requires modification of the media player (e.g., VLC) to send the appropriate RTSP feature-request tags and headers. July 26, 2016 Page 4 of 13
2. RTP Media Retrieval from Lenel NVR 2.1. Getting Live Media (Video/Audio) from the Lenel NVR via RTP In order to get live RTP content from the LNVR, a standards-based RTP client must be used. VLC Player is a popular open-source client which can be downloaded at www.videolan.org. In this document the VLC Player is used as the RTP client that can use the API calls. In order to use the VLC Player to retrieve a media stream from the LNVR, from the Media menu, select Open Network Stream. The Open Media dialog will then be displayed. July 26, 2016 Page 5 of 13
In this dialog, on the Network tab, enter the RTSP URL for the LNVR: rtsp://username:password@ipaddressoflnvr/media/live/channel where username and password are the credentials used to access the LNVR. (Note that, if security in the LNVR is set to anonymous, passing credentials is not required.) IPADDRESSOFLNVR is the IP address of the LNVR such as 192.168.13.14 channel is the number of the channel in the LNVR. Channel numbers are located OnGuard s System Administration. This is OnGuard for the specific LNVR. Examples: - To access content for channel 4 on an LNVR at IP Address 192.168.13.14 with no security set (i.e. Anonymous access is allowed), type the following: rtsp://192.168.13.14/media/live/4 - To access content for channel 4 on an LNVR at IP Address 192.168.13.14 with security set and credentials set to username= 192.168.13.14\root, password= pass, type the following: rtsp://root:pass@192.168.13.14/media/live/4 After entering the URL, click the Play button in order to have VLC send RTSP commands to request the stream from the LNVR. By default, VLC will attempt to acquire the stream using RTP over UDP. This initial behavior is configurable in VLC. (See section Error! Reference source not found. below.) 2.2. Getting Recorded Media (Video/Audio) from the Lenel NVR via RTP In order to retrieve recorded media from the LNVR using VLC, open the network stream dialog in the same way as with live streaming (From the Media menu, select Open Network Stream.) The RTSP URL entered in the Open Media dialog contains the information required to identify the desired media segment. July 26, 2016 Page 6 of 13
The format of the recorded media URL is as follows: where rtsp://username:password@ipaddressoflnvr/media/begintime/endtime/channel username and password are the credentials used to access the LNVR. (Note that if security in the LNVR is set to anonymous, passing the credentials is not required.) IPADDRESSOFLNVR is the IP address of the LNVR such as 192.168.13.14 BEGINTIME is the start time of the requested recorded video. ENDTIME is the end time of the requested recorded video. channel is the number of the channel in LNVR. This is the same channel number used with live streaming requests that are viewable from the System Administration in OnGuard for the specific LNVR. Examples: - To access recorded media for channel 4 on an LNVR at IP Address 192.168.13.14 with no security set (i.e. Anonymous access is allowed) from November 8, 2012 at 14:23:00.000 until November 8, 2012 at 14:35:20.000, type the following: rtsp://192.168.13.14/media/2012-11-08t14:23:00.000z/2012-11- 08T14:35:20.000Z/4 - To access recorded media for channel 4 on an LNVR at IP Address 192.168.13.14 with security set and credentials as username= 192.168.13.14\root, password= pass, from November 8, 2012 at 14:23:00.000 until November 8, 2012 at 14:35:20.000, type: rtsp://root:pass@192.168.13.14/media/2012-11-08t14:23:00.000z/2012-11- 08T14:35:20.000Z/4 2.2.1. Time Range Selection 2.2.1.1. BEGINTIME This value, given in GMT, is typically the starting time for which the client is interested in video; however, there is no guarantee that the LNVR has media for this time. RESTRICTION Future time Description If this value is in the future of the current time within the LNVR machine, then an error will be returned when RTSP PLAY is attempted. The LNVR will search the storage for media starting at this time and return anything that is found after this time. If the RTSP Range: header is also given with the RTSP PLAY request, then the server will attempt to seek to that time instead, with the same caveat that it will return anything at that starting time or later. A RTCP Sender Report (SR) will be sent immediately at the start of the RTP stream to indicate the absolute (NTP) time of the first RTP packet. (A sequence of RTP packets with same RTP timestamp comprise a media frame ). In standard RTCP, the SR reports timestamps that refer to the current stream time (i.e. real time relative to the current wall-clock); however, the LNVR server will report the recorded media s absolute time instead. July 26, 2016 Page 7 of 13
For video-only channels, an alternative to determining the exact absolute time of the first RTP packet is to make use of the Range: headers with the RTSP PLAY request and subsequent response. This method does not rely on RTCP. 2.2.1.2. ENDTIME This value, also given in GMT, sets the limit after which the client is no longer interested in receiving media. This value can be any time value after the BEGINTIME. It can be in the future; however, internally the value will be clamped to the current time. 2.3. Extended RTSP Usage (Requires Custom Client Behavior) 2.3.1. Requesting Time-Range in the Range Header Instead of the URL "Play all media on channel 1, with Range Header indicating exact UTC Range. Note: The time range in the URL is from Unix epoch to current time ( now ) which amounts to the largest possible time-range. However, it would also be possible to specify the exact time-range in the URL, as well as the Range header. The exact time specified in Range header is 16:35:00 to 16:36:00 GMT. Client PLAY request PLAY rtsp://user:password@hostname/media/1970-01-01t00:00:00.000z/2013-11- 01T16:42:48Z/2 RTSP/1.0 CSeq: 835 Session: 12345678 Range: clock=20131101t163500.000z-20131101t163600.000z The server responds, indicating it can satisfy the request. The server also provides the exact starting time of the first expected RTP packet (media sample). Note: For video-only channels, the starting time in the Range header of the response from the server can be used to determine the absolute time of the first RTP packet without relying on RTCP. After the absolute time of the first RTP packet is determined, the subsequent times of the other packets in the stream can be computed using the relative RTP timestamps (i.e. 90 khz media clock value for video) and the absolute time of the first RTP packet (i.e. starting Range value in response) as the origin time. Lnr RTP Server 7.2 S->C: RTSP/1.0 200 OK CSeq: 835 Date: Fri, 01 Nov 2013 16:42:49 GMT Range: clock=20131101t163500z-20131101t163600z RTP-Info: url=rtsp://hostname/media/1970-01-01t00:00:00.000z/2013-11- 01T16:42:48Z/2/streamID=0;seq=48130;rtptime=2012430467, url=rtsp://hostname/media/1970-01-01t00:00:00.000z/2013-11- 01T16:42:48Z/2/streamID=1;seq=6028;rtptime=471014843 Note: In this example response, the starting time value is same as the requested time; however, this value, in actuality, can be slightly prior to or after the request s start time in the Range header. This is due to availability of a reference video frame (aka, key frame) at the given start time. If the nearest reference frame is slightly prior to the requested Range s start time, then that is the video frame that will be chosen for delivery to the client; otherwise, the closest reference video frame after the start time in the Range header will be delivered. July 26, 2016 Page 8 of 13
2.3.2. ONVIF (Client-Side Rate Control) Example Play all media for this Period on channel 1, AS FAST AS POSSIBLE. Note: The client should setup RTSP interleaved/tunnel for the RTP data channels in order to rely on TCP flow control. Client SETUP request (stream 0) SETUP rtsp://user:password@hostname/media/2013-11-01t16:35:00z/2013-11- 01T16:36:00Z/2?StreamID=0 RTSP/1.0 CSeq: 833 Transport: RTP/AVP/TCP;unicast;interleaved=0-1 Note: The first stream SETUP request returns the Session ID which is added to the subsequent stream s SETUP. Client SETUP request (stream 1) SETUP rtsp://user:password@hostname/media/2013-11-01t16:35:00z/2013-11- 01T16:36:00Z/2?StreamID=1 RTSP/1.0 CSeq: 834 Session: 12345678 Transport: RTP/AVP/TCP;unicast;interleaved=2-3 The PLAY request must contain the necessary ONVIF headers: Client PLAY request PLAY rtsp://user:password@hostname/media/2013-11-01t16:35:00z/2013-11-01t16:36:00z/2 RTSP/1.0 CSeq: 835 Session: 12345678 Require: onvif-replay Range: npt=0.000- Rate-Control: no The server responds, indicating it can satisfy the request. Lnr RTP Server 7.2 S->C: RTSP/1.0 200 OK CSeq: 835 Date: Fri, 01 Nov 2013 16:42:49 GMT Range: npt=0-60 RTP-Info: url=rtsp://hostname/media/2013-11-01t16:35:00z/2013-11- 01T16:36:00Z/2/streamID=0;seq=48130;rtptime=2012430467, url=rtsp://hostname/media/2013-11-01t16:35:00z/2013-11- 01T16:36:00Z/2/streamID=1;seq=6028;rtptime=471014843 July 26, 2016 Page 9 of 13
2.3.3. ONVIF Immediate Mode Seeking Seek recorded playback to a different time-range within the existing playback session immediately, without waiting for the previous PLAY command to complete (i.e. before the last media sample has been played). By default, any standard RTSP server can accept pipelined PLAY requests, whereby each PLAY time-range will be honored serially. To support the ability to seek to a particular time within the previously requested time-range and abort the playback of previously requested time-ranges, the ONVIF Streaming specification defined an immediate header which can be given in PLAY requests for this purpose. This feature is most convenient when using Range headers to control the PLAY seeking. INITIAL Client PLAY request PLAY rtsp://user:password@hostname/media/1970-01-01t00:00:00.000z/2013-11- 01T16:42:48Z/1 RTSP/1.0 CSeq: 835 Session: 12345678 Range: clock=20131101t163500.000z-20131101t163600.000z After the server responds positively to this request, and begins streaming the media, the client decides to seek 30 seconds farther into the clip by issuing an immediate PLAY request with a new time-range in the Range header. SEEKING Client PLAY request PLAY rtsp://user:password@hostname/media/1970-01-01t00:00:00.000z/2013-11- 01T16:42:48Z/1 RTSP/1.0 CSeq: 836 Session: 12345678 Require: onvif-replay Range: clock=20131101t163530.000z-20131101t163600.000z Immediate: yes The server responds, indicating it can satisfy the request. The client will also receive an immediate RTCP SR which sets a new absolute NTP time for the next RTP packet. Lnr RTP Server 7.2 S->C: RTSP/1.0 200 OK CSeq: 835 Date: Fri, 01 Nov 2013 16:42:49 GMT Range: clock=20131101t163530.133z-20131101t163600.000z RTP-Info: url=rtsp://hostname/media/1970-01-01t00:00:00.000z/2013-11- 01T16:42:48Z/1/streamID=0;seq=51130;rtptime=2112430467 This mode of operation can be combined with client-side rate control, described previously (i.e. Rate-Control: no ). July 26, 2016 Page 10 of 13
2.4. TIME FORMATS 2.4.1. TIME FORMAT from RFC2326 3.7 Absolute Time Absolute time is expressed as ISO 8601 timestamps, using UTC (GMT). Fractions of a second may be indicated. utc-range = "clock" "=" utc-time "-" [ utc-time ] utc-time = utc-date "T" utc-time "Z" utc-date = 8DIGIT ; < YYYYMMDD > utc-time = 6DIGIT [ "." fraction ] ; < HHMMSS.fraction > Example for November 8, 1996 at 14h37 and 20 and a quarter seconds UTC: 19961108T143720.25Z 2.4.2. TIME FORMAT from ISO 8601 EXTENDED utc-range = "clock" "=" utc-time "-" [ utc-time ] utc-time = utc-date "T" utc-time "Z" utc-date = 4DIGIT-2DIGIT-2DIGIT ; < YYYY-MM-DD > utc-time = 2DIGIT-2DIGIT-2DIGIT [ "." fraction ] ; < HH:MM:SS.fraction > Example for November 8, 1996 at 14h37 and 20 and a quarter seconds UTC: 1996-11-08T14:37:20.25Z Note: The server uses ISO 8601 Extended time format for communicating with clients using standard URLs. However, the URL in the Range header uses standard ISO 8601 timestamps, as found in RFC2326. 2.5. RTSP Errors Error Description Request Cause Code 200 OK any Normal operation 404 Not Found DESCRIBE Returned by the server when under the following conditions: OPTIONS An Unknown channel number given in the URL. The LNVR recorder services (capture / retrieval) 500 Internal Server Error PLAY are not started (are not available). This is a catchall error code. Typically it is returned by the server for the following possible reasons: A recorded media request where BEGINTIME is greater than or equal to ENDTIME A recorded media request where BEGINTIME is in the future 2.6. Configuring Preferred Input Networking Transports in VLC RTSP requests are always made with TCP transport protocol; however, requested media streams sent from the server to the client can use different transports. The most common are RTP over UDP or RTP tunneled within the RTSP (TCP) session. In VLC, the initial streaming attempt will be made using either of the two common methods. This preference is configured from the Setting dialog accessible by selecting Preferences from the Tools menu. July 26, 2016 Page 11 of 13
When the settings dialog is displayed, select Inputs / Codecs in the panel on the left, and then select the radio buttons in the Network settings, choosing either RTP over UDP or tunneled in RTSP. The HTTP (default) represents the default behavior of RTP over UDP, while the RTP over RTSP (TCP) represents the tunneled transport. Note: The latter will be attempted even if the former is selected but fails. (This is the failed stream fallback behavior of VLC). July 26, 2016 Page 12 of 13
2016 United Technologies Lenel is a part of UTC Climate, Controls & Security, a unit of United Technologies 15