Virtual Camera API Protocol: How to Import Files to Camera Archive

This article explains the process of importing files to the camera archive of Virtual Camera using the Server API.

Virtual Camera

Virtual Camera is a camera that doesn’t have a live stream but instead has an archive that can be uploaded to the server as a series of files.

Common uses for the Virtual Camera:

1. action cameras and wearable devices: you can record files on the camera, then upload them to Nx Witness and use the timeline to navigate the archive
2. promotion videos: you can upload several video files to show them on separate screens
3. post-processing videos: you can upload videos after some additional non-real time processing

Create a Virtual Camera automatically using API

Use /ec2/saveCamera (POST) method and pass the camera object as JSON in the request body.

 To find the right structure for the camera object:

1. Add Virtual Camera manually using the desktop application
2. Make /ec2/getCameras request
3. Find your newly created camera there
4. Copy the object, remove id parameter and replace the name parameter with yours
5. Use this new object to create cameras using /ec2/saveCamera method

Adding a file to the archive for Virtual Camera

General workflow

The sequence for uploading a video chunk is as follows:

1. Upload file to the server

1. Create an upload.
2. Upload all chunks.
3. Check status, make sure everything went OK.

2. Once your file is on the server - import it into a Virtual Camera.

1. Lock the camera
2. Start importing
3. Poll camera with extending calls, monitor progress
4. Release the camera

Uploading a file

Step 1: Create a new upload job

POST /api/downloads/<fileName> - creates a new record about the file to be stored on the server. Note that file name is passed in the URL path, everything else - in GET parameters. Errors are reported via HTTP codes or in JSON format as a Server reply body.

• size — size in bytes
• chunkSize — chunk size in bytes, to be used with chunk upload calls. Splitting a file into small chunks lets you upload a file using several connections and have better stability during upload. If the file is small - it is reasonable to upload the whole file at once.
• md5 — md5 checksum of the entire upload
• ttl — file ttl in ms, once ttl has passed the file will be deleted
• upload — marks this as a file upload operation if the parameter is present (its value, if any, is ignored)

Example:

/api/downloads/mynewfile?size=6548590&chunkSize=6548590&md5=90c87ebc26723597b6fb64461e861f47&ttl=86400000&upload

Step 2: Upload chunks

PUT /api/downloads/<fileName>/chunks/<chunkIndex> — uploads a file chunk. Pass the chunk binary data in the PUT body. Errors are reported via HTTP codes or in JSON format as a Server reply body.

Example:

PUT /api/downloads/mynewfile/chunks/0

NOTE: Use the header 'Content-Type': 'application/octet-stream' and add the binary content of the chunk to the request payload.

Use this method for each chunk until every one of them is successfully uploaded.

Step 3: Validate the file upload

GET /api/downloads/<name>/status — checks the status of the upload. Returns a JSON map:

• List of statuses — "uploading" / "downloaded" 
• "downloaded" means the upload was successful
• no other fields are needed

Example:

/api/downloads/mynewfile/status

Importing a file into a Virtual Camera

Step 4: Lock the camera

POST /api/wearableCamera/lock — locks Virtual Camera.

Parameters:

• cameraId — id of the camera
• userId — id of the user performing the lock. You may find it by issuing /ec2/getUsers request. “Id” parameter for the “admin” user that you need
• ttl — lock timeout in ms. After this time the lock token is invalidated automatically.

Returns a JSON object:

• "success": <lock was successfully acquired>
• "locked": <currently locked>
• "consuming": <currently consuming virtual footage>
• "userId": <userId of the user who has the lock, if any>
• "token": <lock token>
• "progress": <reports consume progress in percentage, if ongoing>

Step 5: Import the file

POST /api/wearableCamera/consume — starts a consume operation that imports uploaded files as camera footage.

Parameters:

• cameraId — id of the camera
• token — token acquired when this camera was locked at the previous step.
• uploadId — name of the previously uploaded file, equal to <name> at Step 1.
• startTime — starting time of the file in msecs since epoch

Step 6: Monitor progress

POST /api/wearableCamera/extend — extends Virtual Camera lock

Parameters:

• cameraId — id of the camera
• userId — id of the user performing the lock (refer to /ec2/getUsers API request)
• ttl — lock timeout in ms
• token — token acquired when this camera was locked at the “Lock the camera” step

Returns the same JSON map as /api/virtualCamera/lock (Step 4).

Call this function until the progress is complete.

Step 7: Release the camera

POST /api/wearableCamera/release — releases Virtual Camera lock.

• cameraId — id of the camera
• token — token acquired when this camera was first locked

Returns the same JSON map as /api/wearableCamera/lock (Step 4)

Known limitations

The Virtual Camera might be sensitive to certain codecs and video formats; the recommended codec is H.264. If you have trouble with your specific video files, please contact our support.

The attached file below contains a python script that can be used to help execute the steps explained above. We recommend using Jupyter.