TrueConf MAUI VideoSDK

# Introduction

This guide describes how to work with the TrueConf MAUI VideoSDK for Desktop on Windows. This component should not be confused with TrueConf Mobile SDK, which also exists under .NET MAUI. TrueConf MAUI VideoSDK is a MAUI control (component) for creating enterprise applications with messenger and video communication TrueConf. It is essentially a wrapper around TrueConf VideoSDK, which implements its main functions.

To develop and use the application, you will need the TrueConf SDK extension in the license for your video conferencing server TrueConf Server or TrueConf Enterprise. For licensing details, please contact TrueConf managers:

Contact the vendor

# Requirements

System requirements for developing applications with TrueConf MAUI VideoSDK:

  1. Windows 10+

  2. .NET 8.0+

  3. IDE MS Visual Studio 2022 with the .NET MAUI extension installed.

  4. The purchased TrueConf SDK extension in the license on the video conferencing server that will be used to create test accounts and connect the application.

# How to start

To develop the application, follow these steps:

  1. Install TrueConf VideoSDK version 5.0 or higher. You don't need to activate TrueConf VideoSDK after installation.

  2. After installing the SDK, restart Visual Studio so that the IDE can detect the new package.

  3. Create a new .NET MAUI project in Visual Studio.

  4. Right-click on your project in Solution Explorer.

  5. Click on Manage NuGet Packages.

  6. In the package manager that opens, select the Browse tab and select Microsoft Visual Studio Offline Packages from the Package source list in the upper right corner.

  7. Find the TrueConf.VideoSDK.MAUI package in the search and click the Install button:

/docs/maui-videosdk/media/add_sdk/en.png

# How to use app created with MAUI SDK

In order for the application you have created to work on other PCs, you need to:

  1. Install TrueConf VideoSDK on the target PC, using the same version that was used for development.

  2. Activate the TrueConf SDK extension in the license on the video conferencing server to which the application will connect.

  3. Run your application.

# Example

We have posted an example application with TrueConf MAUI VideoSDK on GitHub, which demonstrates how to get started with the component: authorization and starting a video call (peer-to-peer session). The application code contains comments, and some explanations are provided below.

Example on GitHub

The application itself consists of one main window. When launched, it connects to the video communication server and authorizes with the specified credentials. The only button, Call, is used to make a video call to the subscriber.

# Authentication

Authorization is shown in Presentation → Views → Pages → MainPage.xaml.cs. For demonstration purposes, the variables for connecting to the server are specified directly in the code. Creating your own authorization window or transferring parameters in another way is left to the discretion of the corporate application programmer:

// Server to connect to
private const string _trueConfServer = "<server.trueconf.com>";
// TrueConf ID of a user in the server
private const string _trueConfId = "<trueconf_id>";
// Password of the user
private const string _password = "<password>";
// TrueConfID of a user to call to
private const string _callTo = "<call to trueconf_id>";

The connection to the server is established immediately after launch using the function _sdk.Methods.connectToServer(_trueConfServer).

After connecting to the server, the control changes its state, which is tracked by subscribing to the event _sdk.OnAppStateChanged. The function checks the new state and, if the connection to the server is successful, calls the function _sdk.Methods.login(_trueConfId, _password) for authorization:

private void OnAppStateChanged(object? sender, AppStateChangedEventArgs e)
{
    switch (e.NewState)
    {
        case 0: // No connection to server
        case 1: // Trying to connect to server
            break;
        case 2: // Connected, need to log in
            _sdk.Methods.login(_trueConfId, _password);
            break;
        case 4: // In waiting (receiving an invite or calling someone)
        case 5: // In conference
            ActionBtn.Text = "Reject";
            break;
        default:
            ActionBtn.Text = "Call";
            break;
    }
}

# Call

The call is triggered when the button is pressed, which invokes the _sdk.Methods.call(_callTo) method. Note that the control state is checked beforehand using _sdk.AppState:

private async void ActionBtn_Clicked(object sender, EventArgs e)
{
    if (_sdk == null)
    {
        // We show an alert this way, because MAUI doesn't allow internal alerts to be configured topmost of all child windows
        var alert = new AlertWindow("Error", "Application must be connected to TrueConf server and login to call.");
        this.Window.AddLogicalChild(alert);
        Application.Current?.OpenWindow(alert);
        return;
    }

    switch (_sdk.AppState)
    {
        case 0: // No connection to server
        case 1: // Trying to connect to server
        case 2: // Connected, need to log in
            var alert = new AlertWindow("Error", "Application must be connected to TrueConf server and login to call.");
            this.Window.AddLogicalChild(alert);
            Application.Current?.OpenWindow(alert);
            break;
        case 3: // Connected and logged in
            _sdk.Methods.call(_callTo);
            break;
        case 4: // In waiting (receiving an invite or calling someone)
            _sdk.Methods.hangUp();
            break;
        case 5: // In conference
            _sdk.Methods.hangUp();
            break;
        default:
            break;
    }
}

Incoming calls are answered automatically if the user is online. To answer a call, the _sdk.Methods.accept() function is called. Receiving a call is tracked by subscribing to the _sdk.Events.On_inviteReceived event. To handle the event, the OnInviteReceived function is called:

private void OnInviteReceived(object? sender, string jsonStr)
{
    // If we are in call or we are not doing anything we reject
    if (_sdk.AppState <= 3 || _sdk.AppState == 5)
    {
        // Reject an incoming call or invitation to a group conference
        _sdk.Methods.reject();
    }

    // Accept an incoming call or invitation to a group conference
    _sdk.Methods.accept(); 
}

# Terminology

# User Identifiers

  • PeerId - a unique identifier of a user (short form of TrueConf ID). It does not include the server address or an instance of the identifier. Its usage assumes operation with the current server to which TrueConf MAUI VideoSDK is connected. For example, if TrueConf MAUI VideoSDK is connected to the current.server, using the identifier user1 will automatically be converted internally to user1@current.server

  • CallId is a unique user identifier (TrueConf ID) with a server address but without an instance. Example: user@some.server

  • InstanceId - a unique identifier for a user (TrueConf ID) that includes the server address and instance. For example, user1@some.server/INSTANCE_ID. It is used for unambiguous identification because, for instance, the same user can be authorized on one server but from different applications: user1@some.server/INSTANCE_ID1, user1@some.server/INSTANCE_ID2

Read more about user roles and conference modes in our documentation:

# Automatic stepping up to the podium with VAD

A group conference with the role based mode may have additional functionality - Automatic access to the podium by VAD. VAD (voice activity detection) refers to the voice volume level. In this mode, each speaker automatically takes the podium until the permitted number of speakers is reached. When a speaker finishes speaking, they leave the podium. In this mode, all commands related to the podium will not work. Additionally, methods for managing the assignment of participants to the podium become available.

# Built-in HTTP server for files

TrueConf MAUI VideoSDK contains HTTP-server which is used for the following functionality:

You need to use .NET standard System.Net.Http namespace to send and receive HTTP-requests. Learn more in the Microsoft .NET documentation (opens new window).

The port for HTTP-server will be chosen automatically, and its value can be retrieved using the API method getHttpServerSettings. This server starts automatically when the application with MAUI SDK component launches.

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:

  • 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 TrueConf MAUI VideoSDK:

Upon changing the state of the HTTP server, a On_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 (On_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 TrueConf MAUI VideoSDK 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 On_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 On_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.

# 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 On_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

# 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

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.

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

Last Updated: 12/05/2025

MAUI component Methods, Events, Properties →