Труконф

# Введение

Данная инструкция описывает работу с API TrueConf Room. При этом также данную документацию можно использовать для управления TrueConf VideoSDK с помощью WebSocket команд (например, если у вас Linux и вы не можете использовать .NET MAUI компонент).

При установке TrueConf VideoSDK на ОС Windows в систему добавляется .NET MAUI компонент для добавления видеосвязи TrueConf в корпоративное приложение. Для разработки в этом случае требуется использовать MS Visual Studio.

TrueConf Room — программный терминал для переговорных комнат и конференц-залов любого размера. Устанавливается на ПК на базе ОС Windows или Linux, и предоставляет удобный интерфейс управления с помощью веб-интерфейса или приложения для смартфонов и планшетов на базе Android. Подробнее смотрите в документации к TrueConf Room.

TrueConf VideoSDK — программное решение для создания на его основе корпоративных приложений с интегрированной видеоконференцсвязью TrueConf. Может использоваться для обеспечения видеосвязью в качестве до 4K UltraHD терминалов самообслуживания, видеокиосков, банкоматов и т.п.

Все команды, уведомления и принципы их использования в данном руководстве размещены под разными версиями API: v.1, v.2 и т.д. В более свежих API появляются новые возможности, некоторые параметры могут меняться или добавляться, а также может прекращаться поддержка устаревших функций или уведомлений. Потому важно понимать, какую версию поддерживает ваш TrueConf Room чтобы корректно использовать API.

# Какую версию API использовать

Чем новее версия TrueConf Room, тем более позднюю версию API он поддерживает. Ниже таблица соответствия:

TrueConf Room Поддерживаемые версии API
5.0 v.1, v.2
4.3 v.1

# Сравнение продуктов

Ниже представлена таблица с перечислением функционала каждого решения:

Функционал TrueConf Room TrueConf VideoSDK
Free PRO Free PRO
Веб-интерфейс управления настройками приложения V V V V
Полнофункциональный веб-интерфейс управления видеоконференцсвязью V V
Разграничение прав доступа для администраторов и пользователей V V
Выбор элементов интерфейса для отображения на главном экране V V
Изменение фона главного окна приложения V V
Брендирование: изменение логотипа на главном экране V V
Отсутствие надписи “Free” поверх видео с камеры и в конференциях V V
Наличие API V V V V
Протокол NDI: отправка видео по протоколу NDI V V
Протокол NDI: получение видео по протоколу NDI V V
TrueConf Room Service V V
Поддерживаемые ОС Microsoft Windows 7 SP1 и выше
Debian 10 / 11
Ubuntu 20.04 / 22.04
Astra Linux SE 1.6 / 1.7
Raspberry Pi OS 11

# Принцип работы с API

Интерфейс управления представляет из себя один вебсокет (WebSocket), по которому осуществляется обмен сообщениями в формате JSON.

В каждом запросе для его однозначной идентификации может быть указан параметр requestId. Если он задан, то в JSON ответе на запрос будет содержать такое же значение, иначе будет пустым. Нужен для сопоставления запроса и ответа к нему.

Адрес вебсокета при подключении определяет используемую версию API. Требуемая версия равна значению после /v. Например ws://192.168.0.100:8765/v2 - подключение будет использовать 2 версию; ws://192.168.0.100:8765/v1 - подключение будет использовать 1 версию. Если это не задается, например ws://192.168.0.100:8765 - по умолчанию будет использоваться 1 версия.

# WebSocket порт

# Как получить

Для отправки команд и получения нотификаций (уведомлений) нужно знать номер TCP-порта, который используется TrueConf Room при работе с протоколом WebSocket. Этот порт, как и для встроенного HTTP сервера, задается автоматически и по умолчанию равен 8765. Если такой порт уже занят в ОС, то будет использован ближайший следующий свободный.

Чтобы узнать WebSocket порт:

  1. Убедитесь, что TrueConf Room запущен.

  2. Выполните GET-запрос вида:

http://room_ip:port/public/default/config.json

где:

  • room_ip – ip адрес устройства, где запущен TrueConf Room

  • port – HTTP-порт веб-сервера TrueConf Room

IP и порт задаются при установке TrueConf Room и отображаются на главном экране после запуска:

/docs/videosdk/media/home_screen/ru.png

Тогда в нашем примере надо выполнить запрос:

http://10.140.2.142:88/public/default/config.json

В полученном JSON будет два объекта, содержащие номера портов для HTTP сервера и для управления по WebSocket, например:

{
    "config": {
        "websocket": {
            "hostname": null,
            "port": 8765
        },
        "http": {
            "hostname": null,
            "port": 8766
        }
    }
}

Этот JSON файл пересоздаётся каждый раз при запуске TrueConf Room или обновлении любого из двух портов. Его можно найти на машине с установленным TrueConf Room. Для этого перейдите по пути:

  • C:\ProgramData\TrueConf\VideoSDK\web\default на Windows

  • /opt/trueconf/[product_name]/var/lib/room/default/ на Linux

где [product_name] надо заменить на room в случае TrueConf Room и на videosdk в случае TrueConf VideoSDK.

# Как задать

WebSocket порт можно задать вручную, запустив TrueConf Room с параметром --wsport, например:

C:\Program Files\TrueConf\Room\TrueConfRoom.exe --wsport 568

Если также использовался ключ -t [name] (для запуска копии TrueConf Room со своими настройками), то:

  1. в главном окне TrueConf Room в веб URL добавится параметр cfg=[name];

  2. порты будут храниться в том же файле config.json, но изменится путь:

  • C:\ProgramData\TrueConf\VideoSDK\web\[name] на Windows

  • /opt/trueconf/[product_name]/var/lib/room/[name]/ на Linux

# Проверка запросов в Postman

Для предварительного тестирования тех или иных функций и уведомлений удобно использовать бесплатную утилиту Postman. Она умеет работать с WebScoket, при этом дополнительно предоставляет такие возможности:

  • удобный интерфейс для отслеживания истории запросов и ответов;

  • авторизация в облаке Postman с возможностью синхронизации запросов на любом устройстве пользователя;

  • наличие приложений под различные ОС, а также веб-версии;

  • сохранение списка запросов в виде файлов и пр.

Можно для удобства всё проверять в Postman а потом уже переносить в код на ЯП.

Ниже пример с демонстрацией окна Postman после авторизации и отправки нескольких команд:

/docs/videosdk/media/postman/ru.png Также мы продемонстрировали работу с TrueConf Room API на Демодне 2023:
/docs/videosdk/media/review_preview/ru.jpg

# Пример

Ниже приведен пример html-страницы, где при нажатие на кн. "Call" будет произведен вызов абонента по его TrueConf ID, который указан в текстовом поле.

Важно. Перед открытием страницы в браузере убедитесь в следующем:

  1. TrueConf Room уже запущен локально.

  2. Для управления TrueConf Room используется Незащищенный вход.

<!DOCTYPE html>
<html lang="en">
<script>
    let ws;
    let inputPeerId;
    let submitButton;
    let resultH4;

    window.addEventListener('load', () => {
        inputPeerId = window.document.getElementById('peerIdInput');
        submitButton = window.document.getElementById('submitButton');
        resultH4 = window.document.getElementById('resultH4');

        submitButton.addEventListener('click', ()=> {
            const peerId = inputPeerId.value;
            sendMsg({ method : "call", peerId });
        });

        init();
    })
    
    function init(){
        ws = new WebSocket("ws://localhost:8765/");
        ws.addEventListener('message', onMsg);
        ws.addEventListener('error', onError);
        ws.addEventListener('open', onOpen);
    }
    
    function sendMsg(msg) {
        ws.send(JSON.stringify(msg));
    }
    
    function onMsg(e) {
        const data = JSON.parse(e.data);
        
        // Processing: Commands responses
        switch (data.method) {
            case "auth": {
                data.result ? console.log('authorization done') : console.error('authorization error', data.error);
                
                sendMsg({
                    method: 'login',
                    login: "1@someserver.name",
                    password: "123"
                });
            } 
            break;
        }
        
        // Processing: Events
        switch (data.event) {
            case "conferenceCreated": {
                resultH4.innerHTML = "confID: " + data.confId;
            }
            break;
        }
    }

    function onError(e) {
        console.error(e);
    }
    
    function onOpen(e) {
        sendMsg({
            method: 'setUsedApiVersion',
            requestId: "",
            version: "1"
        });
        
        sendMsg({
            method: 'auth',
            type : "unsecured"
        });
    }
</script>
<body>

<h3>Calling from TrueConf Room to any user by ID</h3>
<input id="peerIdInput" type="text" name="peerId" />
<input id="submitButton" type="submit" value="call" />
<h4 id="resultH4"></h4>

</body>
</html>

# Уровни доступа

Работа с TrueConf Room может осуществляться с разным уровнем доступа: Администратор и Пользователь. Первому доступен абсолютно весь набор методов управления, второму - ограниченный. Сравнение возможностей:

Команда Администратор Пользователь
connectToServer V X
login V X
logout V X
connectToService V X
getHardwareKey V X
activateLicense V X
shutdown V X
rebootSystem V X
shutdownSystem V X
clearTokens V X
setLogo V X
getInfoWodgetsState V X
setDefaultLogo V X
getLogo V X
Все остальные команды V V
Все остальные нотификации V V

# Терминология

# Идентификаторы пользователей


  • PeerId - уникальный идентификатор пользователя (TrueConf ID) в короткой форме. Не содержит адрес сервера и экземпляр идентификатора. При использовании подразумевается работа с текущем сервером, к которому подключен TrueConf Room. Пример - если TrueConf Room подключен к серверу current.server, при использовании идентификатора user1 он будет автоматически сконвертирован внутри в user1@current.server

  • CallId - уникальный идентификатор пользователя (TrueConf ID) с адресом сервера и без экземпляра. Пример - user@some.server

  • InstanceId - уникальный идентификатор пользователя (TrueConf ID) с адресом сервера и экземпляром. Пример - user1@some.server/INSTANCE_ID. Используется для однозначного обозначения, поскольку, например, один и тот же пользователь может быть авторизован на одном сервере, но из-под разных приложений: user1@some.server/INSTANCE_ID1, user1@some.server/INSTANCE_ID2

# Автоматический выход на подиум по VAD


В групповой конференции видеоселектор может быть дополнительный функционал - Автоматический выход на подиум по VAD. Под VAD(voice activity detection) понимается уровень громкости голоса. В этом режиме каждый говорящий автоматически выходит на трибуну, пока их разрешенное количество не кончится. Когда говорящий заканчивает говорить, он уходит с трибуны. В этом режиме все команды, связанные с трибуной, не будут работать. Также дополнительно появляются методы для работы с закреплением участников на трибуне.

Last Updated: 25.07.2025