Adding a Camera or 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.

Adding a Camera

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 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 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)

You can find an example of the code in this article in the Github repository. To learn how to change the resource attributes of an RTSP stream, refer to this article.