How to Add a Camera or a RTSP Stream Using API?

Nx Witness allows you to add a camera or an RTSP stream using the API. In this article, we describe how to manually perform these API calls to allow you to automate them using a script.

In order to add a camera, several API calls must be invoked sequentially:

1. manualCamera/search
2. manualCamera/status
3. manualCamera/add
4. manualCamera/stop

Note: You should poll the status of a search process after manualCamera/search by calling manualCamera/status periodically.

The Server API requires a server URL for making API calls. Use /api/ instead of /ec2/ for invoking System API. Using these API calls performs the same functions as using the ‘Add device…’ function in Nx Witness Desktop.

Invoking manualCamera/search

This API request is necessary for retrieving the processUuid. 

1. Login to WebAdmin via web browser using the following URL format:

   http://<your server address>:<port>

   For example: http://localhost:7001
2. Select the “For Developers” menu. Then, click the link “API Testing Tool (new)”
3. In the search field, type “manual”. Click the manualCamera/search link
4. Input the following information:
   • start_ip — input the camera’s IP address
     • Note: When you enter the IP address of your camera, the server will attempt to auto-discover its parameters and periodically update them. Refer to the screenshot in "Invoking manualCamera/status". Any manual changes to a camera’s parameters will not stay.
   • user — input the camera’s username
   • password — input the camera’s password
5. Click Test method
6. Review the response
   • Make sure the error value is zero in the “Response” field
   • Copy the processUuid value to the clipboard or to a text file.

Code Example

api_uri = f'/api/manualCamera/search?start_ip={camera_ip}&user={camera_user}&password={camera_password}'
search_data = request_api(server_url,
       api_uri,
       'GET',
       auth=HTTPDigestAuth(username, password),
       verify=False)

Invoking manualCamera/status

Using this API call, the attributes retrieved are used in the manualCamera/add request.

1. Click the manualCamera/status link
2. In the uuid field, paste the processUuid you retrieved from manualCamera/search
3. Click Test method

If a camera (or several) is found, in the Response field, you will see the cameras array of JSON formatted objects per camera.

If a camera is found, it will be shown in the Response field in the cameras array consisting of JSON formatted objects for each camera.

Code Example

# poll the search process status until camera(s) found or timeout exceeded
start_time = time.time()
while True:
   search_status = request_api(server_url,
           f'/api/manualCamera/status?uuid={search_data["reply"]["processUuid"]}',
           'GET',
            auth=HTTPDigestAuth(username, password),
            verify=False)
   if search_status["reply"]["cameras"] != []:
       break
   time.sleep(1)
   if time.time() - start_time > search_timeout:
       print("Timeout exceeded. No camera found.")
       exit(1)

Invoking manualCamera/add

Click the manualCamera/add link. At the top of the page, you will see an example of the data structure that is passed to the request.

{
   "user": "USERNAME",
   "password": "PASSWORD",
   "cameras": [
   {
  "uniqueId": "00-1A-07-00-FF-FF",
  "url": "192.168.0.100",
  "manufacturer": "3100"
   }
  ]
}

This structure is a JSON object. You can create this object using any tool you wish. This object must have the cameras array containing the following parameters that were retrieved via manualCamera/status:

• "uniqueId"
• "url"
• "manufacturer"

In Nx Witness 4.2, the API Testing Tool does not allow the direct passing of JSON objects to manualCamera/add. The code examples we present below use Python. Alternatively, you can use any tool of your choice; e.g. curl, bash, PHP, etc.

We assume the search_status variable contains the output of the manualCamera/status request.

camera_data = dict(
   user = camera_user,
   password = camera_password,
   cameras = [
       dict(
           uniqueId = search_status["reply"]["cameras"][0]["uniqueId"],
           url = search_status["reply"]["cameras"][0]["url"],
           manufacturer = search_status["reply"]["cameras"][0]["manufacturer"],
      )
   ]
)
add_status = request_api(server_url,
       f'/api/manualCamera/add',
       'POST',
       auth=HTTPDigestAuth(username, password),
       data = json.dumps(camera_data),
       verify=False)

Invoking manualCamera/stop

As the final step, we will finish the search and addition process by invoking manualCamera/stop in order to free up the server resources.

stop_status = request_api(server_url,
       f'/api/manualCamera/stop?uuid={search_data["reply"]["processUuid"]}',
       'GET',
       auth=HTTPDigestAuth(username, password),
       verify=False)

Adding a Generic RTSP Stream

Similarly, several API calls must be invoked sequentially in order to add a generic RTSP stream.

1. manualCamera/search
2. manualCamera/status
3. manualCamera/ad
4. manualCamera/stop

The Server API requires a server URL for making API calls. Use /api/ instead of /ec2/ for invoking System API. Using these API calls performs the same functions as using the ‘Add device…’ function in Nx Witness Desktop.

Although the procedure looks similar to adding a camera, there are minor differences.

Invoking manualCamera/search

This API request is necessary for retrieving the processUuid.

1. Login to WebAdmin via web browser using the following URL format:
   

   http://<your server address>:<port>

   For example: http://localhost:7001
2. Select the “For Developers” menu. Then, click the link “API Testing Tool (new)” 
3. In the search field, type “manual”. Click the manualCamera/search link
4. Input the following information:
   • url — input the stream’s URL
     • Note: When you enter a URL of the specific stream (as shown below for instance) the Server will assign a vendor type of “GENERIC_RTSP” and will NOT auto-discover parameters as well as will NOT update those periodically. That means any manual changes of parameters will persist.
   • user — input the camera’s username
   • password — input the camera’s password
5. Review the response
   • Make sure the error value is zero in the Response field
   • Copy the processUuid value to the clipboard or to a text file.

Code Example

api_uri = f'/api/manualCamera/search?url={camera_address}'
search_data = request_api(server_url,
   api_uri,
   'GET',
   auth=HTTPDigestAuth(username, password),
   verify=False)

Invoking manualCamera/status

Using this API call, the RTSP stream’s attributes are used in the manualCamera/add request.

1. Click the manualCamera/status link
2. In the uuid field, paste the processUuid you retrieved from manualCamera/search
3. Click Test method

Since a URL is used instead of an IP address, the manualCamera/search request will return slightly different values in the cameras array compared to a camera.

In the “Response” field, you will see the cameras array of JSON formatted objects for each camera.

Invoking manualCamera/add

The API call for adding a generic RTSP stream differs from the call for adding a camera. It utilizes an HTTP GET method; as a result, the parameters are passed in the URL, not the JSON object. The parameters must also be named like the following:

• user
• password
• uniqueId0
• url0
• manufacturer0

The code examples we present below use Python. Alternatively, you can use any tool of your choice; e.g. curl, bash, PHP, etc. We assume the search_status variable contains the output of the manualCamera/status request.

stream_data = dict(
   user = camera_user,
   password = camera_password,
   uniqueId0=search_status["reply"]["cameras"][0]["uniqueId"],
   url0=search_status["reply"]["cameras"][0]["url"],
   manufacturer0=search_status["reply"]["cameras"][0]["manufacturer"]
)
add_status = request_api(server_url,
       f'/api/manualCamera/add',
       'GET',
       auth=HTTPDigestAuth(username, password),
       params = stream_data,
       verify=False)

Invoking manualCamera/stop

As the final step, we will finish the search and addition process by invoking manualCamera/stop in order to free up the server resources.

stop_status = request_api(server_url,
       f'/api/manualCamera/stop?uuid={search_data["reply"]["processUuid"]}',
       'GET',
       auth=HTTPDigestAuth(username, password),
       verify=False)

Please refer to the repository for examples of the code here. To learn how to change the resource attributes of an RTSP stream, refer to this article.