Actions

Recorder 2.0 - API

From Zenitel Wiki

Revision as of 11:41, 11 January 2017 by Roarl (talk)
AlphaCom icon 300px.png

Introduction

This article describes the API for the Vingtor-Stentofon Recorder 2.0.
Use of the API is a licensed feature of the recorder and can be ordered as

  • 1190110160 - Vingtor-Stentofon Recorder - API

It is possible to generate a temporary license for companies wishing to write an interface based on the API.

Supporting documentation and software

The following documentation and support files are available:

  • This article
  • From the AlphaWiki download area: the file 'Recorder2.0_API.zip' - this files contains:
    • A Help-file: 'NHI NVR2 API Documentation.chm'
    • A sample application including commented source code

The 4 dll's, which are normally required, are distributed as part of the sample application:

  • NHI.Nvr2.SharedLibs.dll
  • Nvr2.API.dll
  • NHI.Protocols.Rtp.dll
  • NHI.Media.Audio.Codecs.dll

The majority of functionality necessary to use the API is located in the Nvr2.API assembly, in the ApiImpl class. Instantiating this class and then utilizing the methods therein form the necessary core of the API.

Sample application

The sample application shows the following:

  • How to connect to the recorder service
  • How to subscribe to an event
  • How to retrieve a list of defined devices
  • How to retrieve the description object of a device - the GUID of the device can be used to connect to a live stream of the device

Note that the recorder and its API were originally focusing on CCTV only. Any reference to 'Camera' should be taken as a reference to 'Device' as also audio devices are now supported by the recorder and its API.

Live and recorded audio and video

Live MJPG video

Live MJPG Video (which cameras and recordings are in MJPG format can be determined via the API) can be retrieved using the following URI scheme:
http://<NAVR_IP>:<MJPG_PORT>/LIVE/<ID_OF_CAMERA>, where:

  • <NAVR_IP> IP Address of the recorder
  • <MJPG_PORT> Port on which the recorder serves MJPG video - discoverable via the API
  • <ID_OF_CAMERA> String representation of the GUID that uniquely identifies the camera - discoverable via the API

Loading this URI will result in an MJPG stream of frames to the requester, provided the following:

  • If Connection Restriction is enabled on the recorder, the client must be on the list of allowed clients, or on the local recorder machine. Failing this will result in a dropped connection.
  • The recorder requires HTTP Basic Authentication for MJPG connections (as defined in RFC 1945).

The username and password required match the recorder username and password of the viewer. Not providing authentication information, or providing incorrect authentication information will result in a response of “401 Authorization Required’. Users of VLC or a web browser can pre-empt this error by providing the request in the following format: http://<username>:<password>@<NAVR_IP>:<MJPG_PORT>/LIVE/<ID_OF_CAMERA> This will inform the browser to supply this information as basic authentication information.

  • The Live View permission is checked for the given user against the stream that they wish to view. The user specified via HTTP Basic Authentication not having Live View permission for the given camera will result in a response of ‘401 Authorization Required’.

Recorded MJPG video

Recorded MJPG Video can be retrieved using the following URI scheme:
http://<NAVR_IP>:<MJPG_PORT>/REC/<ID_OF_RECORDING>?<PLAYBACK_ID>, where:

  • <NAVR_IP> IP Address of the recorder
  • <MJPG_PORT> Port on which the recorder serves MJPG video - discoverable via the API
  • <ID_OF_RECORDING> String representation of the GUID that uniquely identifies the recording - discoverable via the API
  • <PLAYBACK_ID> Random string used to help uniquely identify the video session. Generated by the client/viewer.

The string “<ID_OF_RECORDING>?<PLAYBACK_ID>” is referred to as ‘playbackSessionId’. This value is used to uniquely identify a playback session. Therefore, when changing playback speed, checking playback time, or other operations related to viewing a particular recording, this value is used to specify to the recorder which playback session is being referred to. The <ID_OF_RECORDING> can also be composed of multiple recording IDs, by concatenating them together with the pipe symbol (“|”), which is encoded for HTTP as ‘%7C’. If multiple recording IDs are specified, they shall be streamed to the user as a single continuous session. Recording IDs should be specified sorted by time of recording, with earlier recordings being listed before later ones. Behaviour with recordings that overlap is undefined. All requirements of the Live MJPG Video with regard to authentication and authorization remain in effect.

Live RTSP audio and video

Live RTSP audio and video can be retrieved using the following URI scheme:
rtsp://<NAVR_IP>:<RTSP_PORT>/LIVE/<ID_OF_CAMERA>, where:

  • <NAVR_IP> IP Address of the recorder
  • <RTSP_PORT> Port on which the recorder serves RTSP video - discoverable via the API
  • <ID_OF_CAMERA> String representation of the GUID that uniquely identifies the camera - discoverable via the API

Requesting this URI with software capable of RTSP/RTP video streaming will result in an RTP stream of H264, MPEG4 or audio(depending upon the device being called) to the requester, provided the following:

  • If Connection Restriction is enabled on the recorder, the client must be on the list of allowed clients, or on the local recorder machine. Failing this will result in a dropped connection.
  • The recorder requires HTTP Basic Authentication for RTSP connections (as defined in RFC 1945, and specified to RTSP in RFC 2326). The username and password required match the recorder username and password of the user. Not providing authentication information, or providing incorrect authentication information will result in a response of “401 Authorization Required’.

In some RTSP renderers, such as VLC, it is possible to pre-empt this error by providing the request in the following format: rtsp://<username>:<password>@<NAVR_IP>:<RTSP_PORT>/LIVE/<ID_OF_CAMERA> This will inform the rendering software to supply this information as basic authentication information.

  • The Live Session permission is checked for the given user against the stream that they wish to view. The user specified via HTTP Basic Authentication not having Live access permission for the given device will result in a response of ‘401 Authorization Required’.

Recorded RTSP audio and video

Recorded RTSP audio and video can be retrieved using the following URI scheme:
rtsp://<NAVR_IP>:<RTSP_PORT>/REC/<ID_OF_RECORDING>?<PLAYBACK_ID>, where:

  • <NAVR_IP> IP Address of the recorder
  • <RTSP_PORT> Port on which the recorder serves RTSP video - discoverable via the API
  • <ID_OF_RECORDING> String representation of the GUID that uniquely identifies the recording - discoverable via the API
  • <PLAYBACK_ID> Random string used to help uniquely identify the playback session. Generated by the client/viewer.

The string “<ID_OF_RECORDING>?<PLAYBACK_ID>” is referred to as ‘playbackSessionId’. This value is used to uniquely identify a playback session. Therefore, when changing playback speed, checking playback time, or other operations related to accessing a particular recording, this value is used to specify to the recorder which playback session is being referred to. The <ID_OF_RECORDING> can also be composed of multiple recording IDs, by concatenating them together with the pipe symbol (“|”). If multiple recording IDs are specified, they shall be streamed to the user as a single continuous session. Recording IDs should be specified sorted by time of recording, with earlier recordings being listed before later ones. Behaviour with recordings that overlap is undefined. All requirements of the Live RTSP Video with regard to authentication and authorization remain in effect.

Playing audio and video

MJPG video as provided by the recorder can be viewed using VLC. Some older versions of the Chrome and Firefox web browsers support MJPG format video. Internet Explorer does not natively support MJPEG. VLC is capable of playing the RTSP streams supplied by the recorder. VLC exists as a standalone application, as well as having ActiveX plugins as part of its installer. VLC URL: http://www.videolan.org/vlc/index.html VLC is a third party product that is compatible with the recorder; VLC is not supported by Zenitel.

Errors

If an attempt is made to create an API connection to a recorder which is currently restricting connections by listed IP addresses, AND the connection is being made from a host that is not allowed, the connection will be closed immediately. If an attempt is made to send an API command to a recorder with an incorrect API license for the application utilizing the API, the response will be null or False. If an attempt is made to send an API command with invalid authentication information, or with valid authentication that does not have sufficient privileges for the command being invoked, the response will be null or False.

Retrieved from "https://wiki.zenitel.com/w/index.php?title=Recorder_2.0_-_API&oldid=133624"