OpenVideo Streaming API RTSP Connection Methods · 2015-02-06 · 2. The video will be provided as it is stored / retrieved on the recorder. This means that the recorder will preserve

Copyright 2013 Lenel Systems International, Inc. LENEL NVR 7.1 RTP Guidelines Confidential Information.

3-Jan-14 12:02 PM Page 1 of 12

OpenVideo Streaming API RTSP Connection Methods


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

3-Jan-14 12:05 PM Page 2 of 12


1. Introduction

1.1. Overview This document provides a description of Lenel NVR RTP/RTSP Server version 7.1 (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 3rd-party Lenel partners who develop the software intended to interface with Lenel NVR.

1.4. Definitions, Acronyms, Abbreviations • Lenel NVR Lenel Network Video Recorder

3-Jan-14 12:05 PM Page 3 of 12


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.

3-Jan-14 12:05 PM Page 4 of 12

http://www.ietf.org/rfc/rfc2326.txt









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.

3-Jan-14 12:05 PM Page 5 of 12

http://www.videolan.org/


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:[email protected]/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.

3-Jan-14 12:05 PM Page 6 of 12


The format of the recorded media URL is as follows:

rtsp://username:password@IPADDRESSOFLNVR/media/BEGINTIME/ENDTIME/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 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:[email protected]/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 Description

Future time 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.

3-Jan-14 12:05 PM Page 7 of 12


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.1 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.

3-Jan-14 12:05 PM Page 8 of 12


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.1 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

3-Jan-14 12:05 PM Page 9 of 12


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.1 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”).

3-Jan-14 12:05 PM Page 10 of 12


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 Code

Description Request Cause

200 OK any Normal operation 404 Not Found

DESCRIBE OPTIONS

Returned by the server when under the following conditions: • An Unknown channel number given in the URL. • The LNVR recorder services (capture / retrieval)

are not started (are not available). 500 Internal Server

Error PLAY 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.

3-Jan-14 12:05 PM Page 11 of 12


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).

3-Jan-14 12:05 PM Page 12 of 12

Copyright 2008 Lenel Systems International, Inc. OpenVideo - Capture Standard

Page 34 of 34

OpenVideo Streaming API RTSP Connection Methods · 2015-02-06 · 2. The video will be provided as it is stored / retrieved on the recorder. This means that the recorder will preserve

Documents