ONVIF

Node.js implementation of the ONVIF client protocol.

[!TIP] This is a master branch for the developing version 1.x, for stable use version 0.x, see branch v0.x

This is a wrapper to ONVIF protocol which allows you to get information about your NVT (network video transmitter) device, its media sources, control PTZ (pan-tilt-zoom) movements and manage presets, detect devices in your network and control its events. It will also allow you to get information about your NVR (network video recorder) Profile G device and obtain a list of recordings.

The library uses Node.js. And works on the server-side.

This is a new version of the ONVIF library. While the previous version was written in JavaScript, this version is written in TypeScript, including interfaces that describe ONVIF data structures. Currently, a subset of methods from version 0.8 has been reimplemented, but there are more methods to be added. The list of supported ONVIF commands you can find here: https://github.com/agsh/onvif/blob/v1/CHECKED.md

Development is ongoing and more methods will be added over time.

The documentation for the new library was generated by typedoc and you can find it here: https://htmlpreview.github.io/?https://github.com/agsh/onvif/blob/v1/docs/index.html

The code, which use the old version of the library (0.8.x), should work using the compatibility class: https://github.com/agsh/onvif/blob/v1/src/compatibility/cam.ts where all methods are located. (Currently unsupported)

Interfaces

Interfaces are generated according to the latest version of the ONVIF specification.

All methods accepts options from the ONVIF specs and returns data inside the <method_name>Response. For example, method getCapabilities accepts one argument with the type GetCapabilities and returns result with the type Capabilities This is the inner structure of the GetCapabilitiesResponse type:

export interface GetCapabilitiesResponse {
  /** Capability information. */
  capabilities?: Capabilities;
}
class Device {
  // ...
  async getCapabilities(options?: GetCapabilities): Promise<Capabilities> {
    // ...
  }
  // ...
}

Of course, there are exceptions everywhere, the main rule is to try not to return an object with one property.

In some cases, where it is more convenient to use native js types, interfaces are extended by adding new fields that are more convenient to work with. A keyword is used at the end of the names, for example SetSystemDateAndTime becomes SetSystemDateAndTimeExtended with dateTime?: Date; field.

xs:any support

The ONVIF specifications include numerous extension points, which presents a challenge: on one hand, we aim to use simple and convenient methods and interfaces; on the other hand, we need a unified mechanism to handle a large volume of undocumented data provided via <xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> tags in vendor-specific APIs.

This is particularly important for ensuring backward and forward compatibility, as well as for enabling transformation between XML and JavaScript objects in ONVIF get/set methods.

Let’s take a closer look at a specific case. Suppose we have an ElementItem structure with predefined attributes and elements, as described in onvif.xsd, along with additional, unknown elements (note that xs:anyAttribute is currently unsupported) returned by the device:

<xs:element name="ElementItem" minOccurs="0" maxOccurs="unbounded">
    <xs:annotation>
        <xs:documentation>Complex value structure.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
        <xs:sequence>
            <xs:any namespace="##any" processContents="lax">
                <xs:annotation>
                    <xs:documentation>XML tree containing the element value as defined in the corresponding description.</xs:documentation>
                </xs:annotation>
            </xs:any>
        </xs:sequence>
        <xs:attribute name="Name" type="xs:string" use="required">
            <xs:annotation>
                <xs:documentation>Item name.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
    </xs:complexType>
</xs:element>

This structure turns into this autogenerated interface in typescript (src/interfaces directory)

export interface ElementItem {
  /** Item name. */
  name: string;
  /** XML tree containing the element value as defined in the corresponding description. */
  [key: string]: unknown;
}

In real cases, for example in MetadataConfiguration the XML will be look like

<Parameters>
    <ElementItem>
        <Name>elementItem1</Name>
        <Param1>
            <Data>42</Data>
        </Param1>
        <Param2>param2</Param2>
    </ElementItem>
</Parameters>

When you want to get the data in the getMetadataConifugation request it becomes a little bit strange object, but it's ok

{
  elementItem : [{
    name    : 'elementItem1',
    param1  : { data : 42 },
    param2  : 'param2',
    __any__ : {
      'Name'   : ['elementItem1'],
      'Param1' : [{
        'Data' : ['42']
      }],
      'Param2' : 'param2'
    }
  }]
}

Here we have required name field in the element item. Also parsed unknown for the schema xs:any fields: param1 and param2. And strange __any__ field. In fact this is just unprocessed item from the xml2js.

A reasonable question: why? Why do we have this here? The answer is simple. When we need to manipulate with the device and setup different extensions, parameters, etc. Especially when configuring vendor-specific extensions. We don't event know how to serialize the pretty js-object to a ugly xml-structure. But we want to work with the data easily and comfortable. So, when we want to change something in the ONVIF device, in this example it is a setMetadataConfiguration method, we just need to follow two simple rules:

• change known fields as is: elementItem[0].name = 'hello'
• change anything we don't know about in the specification in the __all__ field elementItem[0].__any__.Param2 = 'hi' And this structure will be easy picked up and converted into the appropriate SOAP XML!

Tests

All tests are written using Jest. You can run them with npm test. The tests use happytime-onvif-server as a test device.

Thanks to HappyTimeSoft company for the opportunity to test full ONVIF specification. You can download and purchase their products here: https://www.happytimesoft.com/product.html