A virtual camera is a camera without a live video feed. You can upload video files to a virtual camera, and the Media Server saves the footage to the archive as if a physical camera recorded it.

This guide outlines the general workflow for importing video files to a virtual camera using the Media Server REST API. 

For more detailed information and fully functional code examples, check the Nx Open Integrations repository.

Import workflow

The REST API import process consists of the following steps:

1. Authenticate: Send a POST request to {server}/rest/v4/login/sessions with your credentials to obtain a bearer session token.

2. Create the virtual camera: Send a POST request to {server}/rest/v4/devices/*/virtual with a camera name. The server creates the virtual camera and returns its unique id.

3. Create the upload: Send a POST request to {server}/rest/v4/devices/{id}/virtual/uploads with the file metadata (filename, byte size, base64-encoded MD5 hash, and chunk size). The response confirms the upload parameters and returns an uploadId.

4. Upload file chunks: Send sequential PUT requests to {server}/rest/v4/devices/{id}/virtual/uploads/{uploadId}?chunk=<n> containing raw binary chunk data (Content-Type: application/octet-stream).

5. Verify upload status: Send a GET request to {server}/rest/v4/devices/{id}/virtual/uploads/{uploadId} to confirm that uploadProgressPercent reaches 100.

6. Lock the virtual camera: Send a PATCH request to {server}/rest/v4/devices/{id}/virtual/lock with a time-to-live (ttlMs) value. This action prevents concurrent imports and returns a lock token.

7. Start the import (consume): Send a PATCH request to {server}/rest/v4/devices/{id}/virtual/consume with the uploadId, token, and startTimeMs to process the uploaded file into the camera archive.

8. Monitor progress and extend lock: Periodically send a PATCH request to {server}/rest/v4/devices/{id}/virtual/extend with the token. This keeps the lock active and returns the current progress percentage (0–100).

9. Release the lock: Send a PATCH request to {server}/rest/v4/devices/{id}/virtual/release with your lock token to free the device for future operations.

Key implementation notes

• Time-to-live (ttlMs): Always implement a lock extension loop during long imports to prevent the camera lock from expiring before the process finishes.

• Error handling: Always release the lock in a finally block or equivalent error handler, ensuring the virtual device is unlocked even if the upload or import process fails.

• Video duration: If uploaded footage does not appear on the timeline after a successful import, the server might have failed to extract duration metadata from the video file. To fix this, explicitly provide a durationMs field in the file metadata payload during registration.

Code samples and resources

For complete, production-ready code samples with error handling, progress monitoring, and CLI parameters:

• Python sample: Review the complete script and execution instructions in the Virtual Camera Upload Sample.

• Other languages: Explore JavaScript, Node.js, and browser-based integration examples in the Nx Open Integrations Repository.