In-Client JavaScript API

This API consists of global objects that are injected into the Nx Witness Desktop web browser (see the table below).

To begin, users must initialize the window.vmsApiInitd function by assigning a callback to signal that the API is ready to be used. Global objects are not accessible before this API call is made. 

Example: 

<script>
  window.vmsApiInit = 
    async function()
    {
      vms.log.info("Here we have all the API objects initialized")
    }  
</script>

Signals are used in a similar manner to event handlers via the connect(callback) function.

Example: 

vms.resources.added.connect(
  function(resource)
  {
    vms.log.info(`Added new resource: ${resource.name}`)
  })

Global Constants and structures

Global constants and structures may be used while integrating the JavaScript API inside web pages.

Error Class

Some operations may return the Error object, which shows the status of the operation execution and describes any that may have occurred:

• error.code - error code of the operation
• error.description - description of the error

vms.ErrorCode enum

Some operations return error codes. Users should not rely on numeric values but use the following defined codes which show the execution status:

• vms.ErrorCode.success - operation success
• vms.ErrorCode.failed - operation failed due to an unspecified error
• vms.ErrorCode.denied - no access rights to perform the operation
• vms.ErrorCode.invalid_args - operation failed due to invalid arguments

Example:

const error = await vms.tab.saveLayout()
if (error.code != vms.ErrorCode.success)
  alert(`Can't save layout: ${error.description}`)

TimePeriod Class

This class represents some period of time:

• startTimeMs - start time in milliseconds from Epoch (number)
• durationMs - duration time in milliseconds from Epoch (number)

Point Class

This class represents points in the desktop client window:

• x - x coordinate (number)
• y - y coordinate (number)

Size Class

This class represents the size of the Desktop Client window:

• width - width (number)
• height - height (number)

Rect Class

This class represents the position and size of the Desktop Client window:

• pos - top left point of the rectangle (point)
• size - size of the rectangle (size)

Example:

const result = await vms.tab.item(some_media_item_id)
if (result.error.code == vms.ErrorCode.success)
  vms.log.info(`Item info: speed is ${result.item.params.media.speed}`)

VMS Logging

Manage logging level and the content log messages using the standard Nx Witness logging system. The following methods are available on the vms.log object:

• vms.log.error(“some sort of error message”) - log message with ERROR log level
• vms.log.warning(“some sort of warning message”) - log message with WARNING log level
• vms.log.info(“some sort of informational message”) - log message with INFO log level
• vms.log.debug(“some sort of detailed message”) - log message with DEBUG log level
• vms.log.verbose(“some sort of detailed message”) - log message with VERBOSE log level

Example:

vms.log.warning("Something strange happened here!")

Resource Management

Use the Resource Management API to gather descriptions of Nx Witness System resources.

The vms.resources object contains methods and signals to work with available resources:

Methods

• async hasMediaStream(resourceId) - Check if a resource with the specified id may have a media stream. Returns a boolean value.
• async resources() - List of all available (to user/by the API constraints) resources. Returns an array.
• async resources(resourceId) - Description of the resource with the specified identifier.

Signals

• added(resource) - Called when a new resource is added and contains the description of the newly added resource.
• removed(id) - Called when an available resource is deleted and contains an id (string) of the resource.

Example:

const handleResourceAdded = 
  function(resource)
  {
    if (resource.type = 'io_module')
      vms.log.info(`Resource "${resource.name}" is IO module`)

    if (vms.resources.hasMediaStream(resource.id))
      vms.log.info(`Resource "${resource.name}" has media stream`)
  }

// To connect to the signal, use the "connect" function and specify a callback.
vms.resources.added.connect(handleResourceAdded)

const resources = await vms.resources.resources()
resources.forEach(handleResourceAdded)

Resource Class

This class represents information about the resource:

• resource.id - identifier of the resource identifier (string)
• resource.name - name of the resource (string)
• resource.type - type of the resource
• resource.logicalId - logical identifier of the resource (number)

ResourceType Values

This represents the available values of the resource.type class method:

• 'undefined' - Invalid resource type
• ‘server’ - Server resource
• ‘camera’ - Real camera resource
• 'io_module' - IO module resource
• ‘virtual_camera’ - Streaming resource (e.g. RTSP)
• ‘web_page’ - Web page resource
• ‘local_video’ - Video file resource
• ‘local_image’ - Image file resource

ResourceResult Class

This class represents error and resource descriptions:

• resourceResult.error - error description
• resourceResult.resource - resource description

Tab Management

Use the Tab Management API to manage items and corresponding layout properties (only available for the tab which contains the current web page).

This vms.tab object contains methods and signals to work with the tab containing the current web page.

Methods

• async state()- returns full tab state
• async item(itemId: String) - gets the description of an item with the specified identifier.
• async addItem(resourceId: String, params: ItemParams) - adds item from the resource with the  specified identifier and item parameters. Returns item description on success.
• async setItemParameters(itemId: String, params: ItemParameters) - sets parameters for the item with the specified identifier
• async removeItem(itemId: String) - removes the item with the specified identifier.
• async syncWith(itemId: String) - makes all items synced with the specified item. All items on the tab will have the same timestamp/playing state and speed.
• async stopSyncPlay() - stops syncing of the corresponding layout.
• async setLayoutProperties(properties: LayoutProperties)- sets specified properties for the corresponding layout
• async saveLayout()- saves layout
• async setItemMinimalInterfaceMode(value: Boolean) - sets the web-page widget minimal interface mode. In this mode only the close button is visible and the title bar with the button is hidden when not hovered. 

Example:

      window.vms.tab.setLayoutProperties(properties);
      window.vms.tab.saveLayout();
    });

    window.minLayoutSizeCheckbox.addEventListener(
      "change",
      updateEditsAvailability
    );
  }

Signals

• itemAdded(item: Item) - called when a new item is added
• itemRemoved(itemId: String) - called when item is removed from the tab
• itemChanged(item: Item) - called when some item is changed

Example:

export const addSelectionHandler = (list, buttons) => {
  const handleSelectionChanged = () => {
    const disabled = list.selectedIndex == -1;
    buttons.forEach((button) => (button.disabled = disabled));
  };
  list.addEventListener("change", handleSelectionChanged);
  handleSelectionChanged();
  return handleSelectionChanged;
}

MediaParams Class

This class represents media parameters for items on the tab. Media parameters exist only for items with available video streams:

• speed - playback speed (number)
• timestampMs - current timestamp of the media stream (number)
• timelineSelection - selected timeline part (TimePeriod)
• timelineWindow - visible part of the timeline (TimePeriod)

ItemParams Class

This class represents tab item parameters:

• selected - shows if item is in selection/single selected (boolean)
• focused - shows if item is a focused one (boolean)
• geometry - geometry of the item (Rect)
• media - if  applicable, media parameters of the item (MediaParams)

Example:

const mediaParams = //< Some parameters can be omitted.
{
  'speed': 2.4,
  'timestampMs': 1637802512000000
  ‘timelineSelection’:
  ‘timelineWindow’:
}

const itemParams = // Some parameters can be omitted.
{
  `selected`: false,
  `focused`: true,
  `geometry`: ,
  `media`: mediaParams
}

const error = await vms.tab.setItemParams(some_media_item_id, itemParams)
if (error.code != vms.ErrorCode.success)
  alert(`Can't set item parameters: ${error.description}`)

Item Class

This class represents the description of a tab item:

• id - unique item identifier (string)
• resource - resource connected to the item (resource)
• params - item parameters related to the appearance (ItemParams)

ItemResult Class

This class represents the result of an operation on an item:

• error - error description (error)
• item - related item description (item)

ItemSelection Class

This class represents the selection and focus of states for the tab:

• focusedItem - currently focused item on the tab.
• selectedItems - array of selected items on the tab.

LayoutProperties Class

This class represents all available API properties for the current layout on the tab:

• minimumSize - Minimum size of the layout if specified.

Example:

  constructor() {
    window.submitLayoutSettings.addEventListener("click", () => {
      const properties = {
        minimumSize: {
          width:
            window.minLayoutSizeCheckbox.checked &&
              window.minLayoutSizeWidthEdit.value
              ? window.minLayoutSizeWidthEdit.value
              : 0,
          height:
            window.minLayoutSizeCheckbox.checked &&
              window.minLayoutSizeHeightEdit.value
              ? window.minLayoutSizeHeightEdit.value
              : 0,
        },
        locked: window.lockedLayoutCheckbox.checked
      };

State Class

This class represents the current state of the tab:

• sync - shows if the current layout on the tab is synced (boolean)
• items - array of all the items on the tab (array[item])
• selection - current selection state (ItemSelection)
• properties - related layout properties (LayoutProperties)