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:
- 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
- promotion videos: you can upload several video files to show them on separate screens
- 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:
- Add Virtual Camera manually using the desktop application
- Make /ec2/getCameras request
- Find your newly created camera there
- Copy the object, remove id parameter and replace the name parameter with yours
- 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
- Create an upload.
- Upload all chunks.
- Check status, make sure everything went OK.
2. Once your file is on the server - import it into a Virtual Camera.
- Lock the camera
- Start importing
- Poll camera with extending calls, monitor progress
- 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.
Comments
0 comments
Article is closed for comments.