Launch the Desktop Client from the command line or a URL

You can start the Nx Witness Desktop Client from a command line, a script, or a link. This lets you automate common setups, for example:

• Log in to a Site automatically when a workstation starts.
• Open the client on a specific monitor, at a specific position and size.
• Open a saved layout, or open specific cameras at a point in the archive.
• Turn off client auto-update on managed workstations.

This article applies to Nx Witness 6.1 and later. If your Site runs an earlier version, update to the latest version. If you can't update, contact Support.

Before you begin

1. Find the Server version. If you already know it, skip to step 2. Otherwise, use one of these methods:
   • On the Server computer: open build_info.txt. The version is on the first line.
     • Windows: C:\Program Files\Network Optix\Nx Witness\MediaServer\build_info.txt
     • Linux: /opt/networkoptix/mediaserver/build_info.txt
   • Desktop Client, if it's already installed: go to Site Administration > Updates.
2. On the workstation, install the Desktop Client version that matches the Server version. A client that doesn't match the Server can't connect.
3. To log in automatically, you need a user account on the Site and a login value for it. For details, see Choose a login method.

Note: OEM versions of the client, such as Wisenet WAVE or DW Spectrum, use a different install folder, executable name, and URL protocol. Replace the Nx Witness values in this article with the values for your product.

Launch the client from the command line

Each installed client version has its own folder. Run the executable in the folder that matches your Server version.

Windows

1. Open Command Prompt.
2. Go to the client folder for your version. Replace VERSION with the Server version, for example 6.1.1.42411. To find it, see Before you begin.

cd "C:\Program Files\Network Optix\Nx Witness\Client\VERSION"

If the folder doesn’t exist, the client might have downloaded that version for your user account, for example during an update. Go to this folder instead:

cd "%LOCALAPPDATA%\Network Optix\client\default\VERSION"

3. Start the client. Add parameters after the executable name, or leave them out:

"HD Witness.exe" --no-client-update

Linux

1. Open Terminal.
2. Go to the client folder for your version. Replace VERSION with the Server version, for example 6.1.1.42411.

cd /opt/networkoptix/client/VERSION/bin

3. Start the client. Add parameters after the executable name, or leave them out:

./client-bin --no-client-update

macOS

1. Open Terminal.
2. Go to the client folder for your version. Replace VERSION with the Server version, for example 6.1.1.42411.

cd ~/.local/share/Network\ Optix/client/default/VERSION

3. Start the client. Add parameters after the executable name, or leave them out:

./Nx\ Witness.app/Contents/MacOS/Nx\ Witness --no-client-update

Command-line parameters

All parameters are optional. You can combine several in one command.

Set the window position and size

In version 6.1.1 and later, you can place the client window anywhere on any monitor, at any size. Use these three parameters together: 

• --screen picks the monitor. Monitors are numbered from 0.
• --window-geometry=X,Y,WIDTHxHEIGHT sets the position and size. X and Y are measured from the top-left corner of the monitor that --screen selects.
• --no-fullscreen keeps the client in a window.

For example, this command opens an 800 x 600 window in the top-left corner of the second monitor:

"HD Witness.exe" --screen=1 --window-geometry=0,0,800x600 --no-fullscreen

Keep the following in mind:

• If you use --screen without --window-geometry, the client opens full screen on that monitor.
• You can use any window size, including sizes smaller than 1024 x 768. The size you set also becomes the smallest size the window can be resized to.
• At small sizes, opening the client side panels can cause display glitches. Keep the panels closed in small windows.

Note: In versions earlier than 6.1.1, --window-geometry doesn't work with --screen, and the window can't be smaller than 1024 x 768.

Open the client with an Nx URL

An Nx URL opens the client, connects to a Site, and can open specific cameras at a point in the archive. You can use an Nx URL in three ways:

• Pass it to the client executable on the command line.
• On Windows, open it with start "" "URL". Windows finds the installed client, so you don't need the version folder.
• Add it as a link on a web page or in another application.

The URL uses this format:

PROTOCOL://CLOUD_HOST/client/SITE_ADDRESS/view?auth=TOKEN&resources=CAMERA_IDS&timestamp=TIME

To find a Cloud Site ID, open the Site in the cloud portal. The ID is the part of the address after /systems/. To find a camera ID, open Camera Settings for the camera.

Choose a login method

Use one of these methods to log in from a URL. For local users, use a bearer token.

Bearer tokens, temporary user tokens, and authorization codes all expire. A user name and password doesn't expire, but that method is deprecated.

Get a bearer token

To get a bearer token, send a local or LDAP user's name and password to the Server REST API. For steps, see Authenticate using the Mediaserver API. That article is written for developers and includes a Python example.

Bearer tokens expire after a time limit set on the Site. A token that you paste into a shortcut or batch file stops working when it expires. Use a fixed token only for a link that you open soon after you create the token.

For a workstation that logs in on its own, use a script that requests a new token each time it starts the client. For example, in PowerShell:

$server = "https://192.168.1.200:7001"
$body = @{ username = "USER"; password = "PASSWORD"; setCookie = $false } | ConvertTo-Json
$login = Invoke-RestMethod -Method Post -Uri "$server/rest/v4/login/sessions" -ContentType "application/json" -Body $body
Start-Process "nx-vms://nxvms.com/client/192.168.1.200:7001?auth=$($login.token)"

Replace the following:

• USER and PASSWORD: the credentials of a local or LDAP user.
• 192.168.1.200:7001: your Server address and port, in both places.

The script stores the password in plain text. Protect the script file, and use an account with only the permissions the workstation needs.

Note: The Server uses a self-signed certificate by default. If the request fails with a certificate error, trust the Server certificate on the workstation, or run the script in PowerShell 7 and add -SkipCertificateCheck to the Invoke-RestMethod command.

Use a user name and password

Encode USER:PASSWORD in Base64, then use the result as the auth value. For example, for the user admin with the password password123:

• Windows (PowerShell): [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("admin:password123"))
• Linux or macOS: 
  echo -n 'admin:password123' | base64 

Both commands return YWRtaW46cGFzc3dvcmQxMjM=. This method uses digest authentication, which is deprecated. In version 6.1, it works only for local users that have digest authentication turned on, on Sites set to the Standard security level. It will be turned off in a future version.

Caution: Anyone who has a URL with a login value can log in as that user. Base64 isn't encryption, so anyone can decode it to get the password. Use an account with only the permissions the workstation needs, and keep these URLs out of shared documents and email.

Note: Mobile apps also open Nx URLs. On Android, the URL works only as a link on a web page, for example <a href="URL">Open camera</a>. Typing it in the browser address bar doesn't work.

Examples

The examples use Windows commands. On Linux and macOS, run the client executable from its folder, as shown in Launch the client from the command line, and pass the same URL and parameters.

In the examples, replace the following:

• TOKEN: a bearer token, or a Base64 user name and password. See Choose a login method.
• TEMP_TOKEN: a temporary user token.
• CODE: an authorization code for a cloud account.
• SITE_ID: your Cloud Site ID.
• CAMERA_ID_1, CAMERA_ID_2: the IDs of the cameras to open.
• 192.168.1.200:7001: your Server address and port.

Open the client

start "" "nx-vms://nxvms.com/"

Connect to a local Server

start "" "nx-vms://nxvms.com/client/192.168.1.200:7001?auth=TOKEN"

Connect to a Cloud Site as a temporary user

start "" "nx-vms://SITE_ID?tmp_token=TEMP_TOKEN"

Connect to a Cloud Site with an authorization code

start "" "nx-vms://nxvms.com/client/SITE_ID?code=CODE"

Use the full form shown here, including nxvms.com/client/. A code works once and expires within minutes, so generate it right before you run the command. The cloud portal uses this same method when a user chooses to open a Site in the Desktop Client from the portal directly.

Open two cameras at a point in the archive

start "" "nx-vms://nxvms.com/client/192.168.1.200:7001/view?auth=TOKEN&resources=CAMERA_ID_1:CAMERA_ID_2&timestamp=1520110800000"

Connect and open a layout

"HD Witness.exe" "nx-vms://nxvms.com/client/192.168.1.200:7001?auth=TOKEN" --layout-name="Lobby cameras"

Open a small window on the second monitor

"HD Witness.exe" "nx-vms://nxvms.com/client/192.168.1.200:7001?auth=TOKEN" --screen=1 --window-geometry=0,0,640x480 --no-fullscreen

Start a locked-down workstation

This command connects to a Site, doesn't reconnect to a previous Site, and turns off auto-update:

"HD Witness.exe" "nx-vms://nxvms.com/client/192.168.1.200:7001?auth=TOKEN" --skip-auto-login --no-client-update

A bearer token expires, so this command stops working when the token does. For a workstation that starts on its own, get TOKEN with the script in Get a bearer token, or use a user name and password.