Client to ONVIF NVT devices
npm install ts-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)
All methods accepts options from the ONVIF specs and returns data inside the
method getCapabilities accepts one argument with the type GetCapabilities and returns result with the typeCapabilities This is the inner structure of the GetCapabilitiesResponse type:
``ts`
export interface GetCapabilitiesResponse {
/* Capability information. /
capabilities?: Capabilities;
}
class Device {
// ...
async getCapabilities(options?: GetCapabilities): Promise
// ...
}
// ...
}
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 becomesSetSystemDateAndTimeExtended with dateTime?: Date; field.
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 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 xs:anyAttribute
elements, as described in
onvif.xsd,
along with additional, unknown elements (note that is currently unsupported) returned by the device:`xml`
This structure turns into this autogenerated interface in typescript ( directory)`ts`
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 the XML will be look like`xml`
42
When you want to get the data in the request it becomes a little bit strange object, but it's ok`js`
{
elementItem : [{
name : 'elementItem1',
param1 : { data : 42 },
param2 : 'param2',
__any__ : {
'Name' : ['elementItem1'],
'Param1' : [{
'Data' : ['42']
}],
'Param2' : 'param2'
}
}]
}
Here we have required field in the element item. Also parsed unknown for the schema xs:any fields: param1 andparam2. 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 elementItem[0].name = 'hello'
method, we just need to follow two simple rules:
* change known fields as is:
* change anything we don't know about in the specification in the field elementItem[0].__any__.Param2 = 'hi'
And this structure will be easy picked up and converted into the appropriate SOAP XML!
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