Built-in HTTP server

Overview

Since VideoSDK/Room is remotely managed using the WebSocket client-server protocol, it includes an HTTP server. This server starts automatically when the application launches. The port for it will also be chosen automatically, and its value can be retrieved using the API method getHttpServerSettings. However, you can specify the port manually. To do this, when launching VideoSDK/Room, set the desired value in the command-line parameter --httpport. If the HTTP server fails to start on the specified port, the application will not launch, and corresponding error messages will be logged.

The HTTP server is used for the following functionality:

• Capturing frames from the current video capture device and from video conference participants

• User Avatars

• Files

• Slideshow

• Video capture device presets

• Background replacement

Each feature supports its own set of HTTP methods, which can be reviewed in the corresponding section. All requests without exception must pass the token parameter, which is created and obtained as follows:

• during the authorization process – the value of the tokenForHttpServer field in the response to successful authorization by the auth command;

• during the transition from the administrator control type to the user control type – the value of the tokenForHttpServer field in the response to the successful execution of the auth command;

• upon successful execution of the getTokenForHttpServer command – the value of the token field;

• when setting up a new type of security for access to management – the value of the tokenForHttpServer field in the response to the successful execution of the setAuthParams command.

As a result of executing requests, certain codes and messages are returned, which are discussed below.

The token's lifetime is 5 minutes, or until the application is shut down, or until an authorizationNeeded notification is received. If the control is set with Pin protection enabled, then the token's lifetime does not expire until the application is restarted. Token clearance can be performed by executing the clearTokens command.

HTTP Server Management

You can manage the HTTP server status when operating VideoSDK/Room:

• retrieve the current status with the getHttpServerState command;

• launch it with the startHttpServer command;

• stop using the stopHttpServer command.

Upon changing the state of the HTTP server, a httpServerStateChanged notification will be received.

Additionally, the HTTP server can be configured using the following commands: retrieving settings (getHttpServerSettings), setting configurations (setHttpServerSettings), as well as notifications about their changes (httpServerSettingChanged).

All HTTP requests have the following format:

http://room_ip:port/functionalityTag?params&token=tokenValue

Description of Parameters

• room_ip – IP address of the device where VideoSDK/Room is running

• port – the port on which the HTTP server is listening. Can be obtained from:

  • the value of the embeddedHttpPort field in the response to the successful execution of the getAppState method

  • values of the embeddedHttpPort field in the appStateChanged notification

  • an object with the field name name and its value port in the response to a successful execution of the getHttpServerSettings command

  • with an object containing the name field and its value port in the httpServerSettingChanged notification

  • of the same config.json file, which also contains the WebSocket port

• functionalityTag – tag for required functionality

• params – a set of parameters specific to the particular functionality (tag)

• token - Token

You have the option to manually set a different port using the setHttpServerSettings command.

The following shows which type of HTTP requests (GET, HEAD, POST, OPTIONS, DELETE) should be executed for each task.

Retrieving Data About the HTTP Server

The OPTIONS method in HTTP is used to obtain information about the capabilities of the web server and the methods it supports. This request does not change the state of the server or resource, but only returns metadata, such as the allowed HTTP methods, supported protocol versions, and additional headers that can be used to configure requests.

Perform an OPTIONS request of the format

http://room_ip:port/files?token=tokenValue

Parameter Description

• room_ip, port, token - are standard parameters, described above

Working with Camera Frames

To work with frames from the current video capture device and the frames of conference participants, requests sent to /frames are used. The HTTP server automatically collects these frames, and there is no need to add, update, or delete them manually - everything will be done automatically.

For each conference participant, only one last frame is retained, meaning they do not accumulate. After the event concludes, the participants' frames are deleted, but your own remain (from the camera).

Retrieving Frames

Perform a GET or HEAD request of the format

http://room_ip:port/frames?peerId=requiredPeerId&token=tokenValue

Parameter Description

• room_ip, port, token - are standard parameters, described above

• peerId is the identifier of the conference participant whose frame you need to obtain. To retrieve frames from the video capture device, pass one of the following values:

  • #self:0, which will remain valid in any state of the application (whether logged in or not, online or in a conference, etc.)

  • identifier used for authorization on the server. It can be obtained, for example, from the value of the peerId field, received after the successful execution of the getLogin method or the login notification.

User Avatars

To manage user avatars, requests sent to /avatars are used. The HTTP server automatically gathers them, and there's no need to add, update, or remove them manually – everything will be done automatically. Avatar updates can be tracked by handling the updateAvatar notification.

Retrieving Avatars

Perform a GET or HEAD request of the format

http://room_ip:port/avatars?peerId=requiredPeerId&token=tokenValue

Parameter Description

• room_ip, port, token - are standard parameters, described above

• peerId - identifier of the user whose avatar you want to retrieve

Video Capture Device Presets

Every time a preset is saved using the addPresetFromCurrentVideoCapturer command, a screenshot from the current video capture device is also saved on the HTTP server. The presets are managed with requests sent to /videoCapturerPresets. The HTTP server automatically collects them, and there is no need to manually add, update, or delete them – everything will be handled automatically when working with presets through API commands.

Retrieving Preset Frame

Perform a GET or HEAD request of the format

http://room_ip:port/videoCapturerPresets?presetId=requiredPresetId&token=tokenValue

Parameter Description

• room_ip, port, token – standard parameters, described above

• presetId – the identifier of the preset for which you need to obtain a screenshot

Files

The HTTP server is capable of handling files. This can be necessary for various purposes: file transfer in chat, displaying a slideshow, changing the background, etc. Their management is organized through unique identifiers – fileId. This allows for storage and handling of completely identical files. You can retrieve the list of all available files by executing the API command getFileList.

Receiving a File

Perform a GET request in the following format

http://room_ip:port/files?fileId=requiredFileId&token=tokenValue

Request example

http://192.168.0.100:8766/files?fileId=42488041&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

Parameter Description

• room_ip, port, token – standard parameters, described above

• fileId – identifier of the file to be retrieved

The response will also include the original file name in the headers, for example, Content-Disposition: attachment; filename="Screenshot_20221205_062944.png".

Uploading Files to Web Server

Perform a POST request in the following format

http://room_ip:port/files?token=tokenValue

In this case, in HTML, you will need to specify the multipart/form-data format and provide the file path. When using the curl utility (opens new window), you will need to use the --form key.

Example of file upload using the curl utility (opens new window)

curl --form 'file=@"/home/user/image.png"' http://192.168.0.100:8766/files?token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

Example of a form on an HTML page

<form action="http://192.168.0.100:8766/files?token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130" enctype="multipart/form-data" method="POST">
<div>
   <label for="file">Choose file to upload</label>
   <input type="file" id="file" name="file" multiple>
 </div>
 <div>
   <button>Submit</button>
 </div>
</form>

Parameter Description

• room_ip, port, token - are standard parameters, described above

Upon successful upload, the response will contain the identifier(s) assigned to the file(s) on the HTTP server, which should be used for further operations with them (including in the API).

Access-Control-Expose-Headers: FileId, ErrorMessage, ErrorCode
ErrorCode: 0
ErrorMessage: Success
FileId: 50627163

Access-Control-Expose-Headers: UnpackedFilesId, ErrorMessage, ErrorCode
ErrorCode: 0
ErrorMessage: Success
UnpackedFilesId: 153153427,153154947,153154948,153154949,153154950

Parameter Description

• Access-Control-Expose-Headers - list of additional headers with information about the method execution

• fileId - the file identifier on the server. It is only present if the uploaded file corresponds to a single file on the server.

• UnpackedFilesId - identifiers of files on the server. Present only if the uploaded file is unpacked into several others, for example when uploading slides from a Microsoft PowerPoint presentation file or a presentation file created in TrueConf Client.

Additionally, a POST request can be used to delete files from the HTTP server using the "old format".

URL Request Format

http://room_ip:port/files?fileId=requiredFileId&action=DELETE

Parameter Description

• room_ip, port, token - standard parameters described above
• fileId - the identifier of the file to be deleted
• action=DELETE - indicates that we should delete the file

File Deletion

To delete a file, a DELETE request of the following type needs to be made:

http://room_ip:port/files?fileId=requiredFileId&token=tokenValue

Parameter Description

• fileId – the identifier (ID) of the file that needs to be deleted. You can get a list of all available files and their identifiers by executing the API command getFileList. Also, the ID is returned upon successful file upload using a POST request.

Overlay

Using overlay, you can place an image over the outgoing video stream from .

Receiving a File

Perform a GET or HEAD request of the format

http://room_ip:port/overlay?type=drawing&imageId=someId&token=tokenValue
http://room_ip:port/overlay?type=original_frames&peerId=someId&token=tokenValue

Request example

http://192.168.0.100:8766/overlay?type=drawing&imageId=42488041&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130
http://192.168.0.100:8766/overlay?type=original_frames&peerId=user1@some.server&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

Parameter Description

• imageId – the identifier of the file that needs to be overlaid on the video stream

• peerId – unique identifier of the frame source (conference participants, as well as your own video)

• type – the necessary part of the Overlay functionality

Uploading Files to Web Server

http://room_ip:port/overlay?type=drawing&imageId=someId&token=tokenValue

Request example

http://192.168.0.100:8766/overlay?type=drawing&imageId=42488041&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

Parameter Description

• imageId – the identifier of the file that needs to be overlaid on the video stream

• type – the necessary part of the Overlay functionality

File Deletion

To delete a file, a DELETE request of the following type needs to be made:

http://room_ip:port/overlay?type=drawing&imageId=someId&token=tokenValue

Request example

http://192.168.0.100:8766/overlay?type=drawing&imageId=42488041&token=4*t5rfZVQYzPCMZAcZ*124795274*3730373132354636433231444639353037353935413044303743453246393130

Parameter Description

• imageId – identifier of the file to be deleted

• type – the necessary part of the Overlay functionality

Slideshow

The same functions as when working with files are implemented, but the slides tag is used instead of files in the requests. This is used for preparing a slideshow to be presented during a conference or call.

When uploading a file, it will be checked for compatibility: supported image formats include .jpg, .jpeg, .png, .webp, .gif, as well as Microsoft PowerPoint presentation files .ppt, .pptx and the special .slides format (for how to obtain them, see the client application documentation of TrueConf). If such a file type is not supported, a 422 Unprocessable Entity error will be returned. When uploading a presentation file, it will be unpacked into individual slide files, and the list of these files will be provided in the UnpackedFilesId response header.

Background Replacement

Uploading files to the HTTP server is also required for using the background replacement feature. Before executing the setBackground command, you must add an image in one of the supported formats: .jpg, .jpeg, .png, .svg, as shown above.

Returned Result and HTTP Request Headers

All HTTP requests in the response will return additional headers indicating the result of the execution.

• ErrorCode - a code that indicates the result of execution

• ErrorMessage - textual description of the execution result

• ExtraErrorCode - an additional code indicating the execution result and which reflects the server's internal state in exceptional situations. It can be used for analyzing problems when executing a request.

• ExtraErrorDescription - an additional text description of the execution result, indicating the outcome and reflecting the internal state of the server in exceptional situations. It can be used for troubleshooting issues when executing a request.

ErrorCode and ErrorMessage are issued as related pairs and can take the following values:

• ErrorCode: 0, ErrorMessage: Success - success, no errors occurred

• ErrorCode: 1, ErrorMessage: Token is not present - error. The token was not included in the request.

• ErrorCode: 2, ErrorMessage: Invalid token - error. The token passed in the request is invalid.

• ErrorCode: 3, ErrorMessage: Tag is not present - error. The request did not specify a tag

• ErrorCode: 4, ErrorMessage: This method is not allowed - error. Such request type is not supported on this tag.

• ErrorCode: 5, ErrorMessage: 'peerId' parameter is not present - error. The request is missing the required 'peerId' parameter.

• ErrorCode: 6, ErrorMessage: 'peerId' parameter must be not empty - error. The mandatory parameter 'peerId' is empty in the request.

• ErrorCode: 7, ErrorMessage: Avatar for such peerId was not found - error. Avatar for the specified peerId is missing

• ErrorCode: 8, ErrorMessage: Frame for such peerId was not found - this is an error. The frame for the specified participant is missing.

• ErrorCode: 9, ErrorMessage: 'presetId' parameter is not present - Error. The required parameter 'presetId' is missing in the request.

• ErrorCode: 10, ErrorMessage: 'presetId' parameter must be not empty - error. The mandatory parameter 'presetId' is empty in the request.

• ErrorCode: 11, ErrorMessage: Video capturer presets locking failure - An error. Internal server failure related to retrieving information about presets (unable to obtain the object that manages them).

• ErrorCode: 12, ErrorMessage: An error occurred while getting video capturer preset - error. Internal server failure related to retrieving information about presets (error in fetching a specific preset).

• ErrorCode: 13, ErrorMessage: Video capturer preset doesn't contain preview image - error. Internal server failure related to obtaining information about presets (the received preset does not contain a preview)

• ErrorCode: 14, ErrorMessage: 'fileId' parameter is not present - error. The request is missing the required 'fileId' parameter.

• ErrorCode: 15, ErrorMessage: 'fileId' parameter must be not empty - error. The mandatory 'fileId' parameter is empty in the request.

• ErrorCode: 16, ErrorMessage: An error occurred while getting information about the file by its id - this is an error. It indicates an internal server failure related to retrieving information about the file by its identifier.

• ErrorCode: 17, ErrorMessage: An error occurred while creating response content callback - An internal server error related to processing the request (failed to create the response structure)

• ErrorCode: 18, ErrorMessage: An error occurred while creating Request struct - This error indicates an internal server failure associated with processing the request (failed to create the request structure).

• ErrorCode: 19, ErrorMessage: An error occurred while creating RequestInfo struct - error. Internal server failure related to request processing (failed to create request information structure)

• ErrorCode: 20, ErrorMessage: file.good check failure - error. Internal server failure associated with file system operations (checking file status flags)

• ErrorCode: 21, ErrorMessage: file.tellg check failure - error. An internal server failure related to file system operations (working with the current character position in the input stream).

• ErrorCode: 22, ErrorMessage: An error occurred while creating PostConnectionInfo struct - an error. Internal server failure associated with processing the POST request (failed to create the structure with the request information)

• ErrorCode: 23, ErrorMessage: An error occurred while creating post processor - an error. Internal server failure related to processing the POST request (failed to create the request processing object)

• ErrorCode: 24, ErrorMessage: An error occurred while processing post request - This error indicates an internal server failure associated with processing a POST request (internal library error).

• ErrorCode: 25, ErrorMessage: AfterDownloadFileValidationFunction returned failure - an error occurred. After the download, the file was validated according to the rules and conditions of a specific tag and failed this validation.

• ErrorCode: 26, ErrorMessage: remove_all call failure - error. Internal server failure related to file system operations (error deleting the working temporary directory)

• ErrorCode: 27, ErrorMessage: File key is not present - error. The mandatory parameter 'file' is missing in the request.

• ErrorCode: 28, ErrorMessage: 'fileName' parameter is not present - error. The request is missing the required parameter 'fileName'

• ErrorCode: 29, ErrorMessage: 'fileName' parameter must be not empty - error. The required 'fileName' parameter is empty in the request.

• ErrorCode: 30, ErrorMessage: PreDownloadFileValidationFunctionFailure returned failure - error. Before the download started, the file was validated according to the rules and conditions of the specific tag and failed to pass the check.

• ErrorCode: 31, ErrorMessage: An error occurred while creating path for file - error. This is an internal server failure related to file system operations (an error in creating a directory that is part of the processing logic).

• ErrorCode: 32, ErrorMessage: An error occurred because of unopened file - This is an error. It is an internal server failure associated with file system operations (error in opening the required file).

• ErrorCode: 33, ErrorMessage: 'imageId' parameter is not present - error. The required 'imageId' parameter is missing in the request.

• ErrorCode: 34, ErrorMessage: 'imageId' parameter must be not empty - error. The required 'imageId' parameter is empty in the request.

• ErrorCode: 35, ErrorMessage: An error occurred while loading png for overlay functionality - an internal server failure associated with processing a png file (internal library error)

• ErrorCode: 36, ErrorMessage: Loaded png file for overlay functionality have invalid size - This error indicates that the provided file has an invalid size for the overlay feature.

• ErrorCode: 37, ErrorMessage: An error occurred while adding png file to overlay functionality - error. The object for managing the overlay feature returned an error when adding a new file.

• ErrorCode: 38, ErrorMessage: An error occurred while deleting png file from overlay functionality - this error indicates that an issue was encountered while attempting to delete a file using the Overlay feature.

• ErrorCode: 39, ErrorMessage: Internal error - couldn't lock overlay video processing - error. This is an internal server malfunction related to the overlay feature (unable to acquire the object that manages it).

See also:

Overlay