Каждый год — новая полоса препятствий для человечества. И IT не исключение, а полноценный участник этого забега, особенно в нашей стране.    Серьёзные испытания для совместной работы и коммуникаций начались в 2019: коронавирус (он, между прочим, ещё вроде как есть) показал, насколько сложно переходить от офисов и аудиторий к удалённой работе и учёбе. В 2022 иностранные IT-гиганты ушли из России и прихватили с собой известные продукты и сервисы, не раз выручавшие всех нас. Тем не менее, количество пользователей видеосвязи во всём мире постоянно растёт, да и переговорные комнаты никуда не делись вопреки трендам на удалёнку и работу с импровизированных рабочих мест. Так или иначе мы адаптировались под новые условия. А вот адаптировать эти условия под себя — задача не из простых.   Сегодня поговорим о кастомных решениях для видеоконференцсвязи (далее — ВКС) с минимальными затратами человеко-часов и финансов на их создание. Я параноик Брать готовый open-source – меня не устраивает, всем известны случаи встраивания back door в проекты с открытым исходным кодом с целью нанести ущерб пользователям из России. Поэтому за основу берём что-то отечественное с корпоративным уклоном, с открытым API и подходом «без регистрации и смс».  Меня зовут Антон Бааджи и сегодня на примере Python, Vosk и TrueConf VideoSDK я покажу, как можно адаптировать корпоративный продукт под себя. Неважно, чем вы занимаетесь —  администрированием сетей видеосвязи или разработкой ПО, главное, чтобы вас, как и меня, не устраивало текущее положение дел. Поехали! Цель: знакомимся c TrueConf VideoSDK, смотрим как работает и что можно сделать.   VideoSDK – это видео движок для создания кастомных решений для встраиваемых систем (видеокиосков, терминалов самообслуживания), который не имеет своего графического интерфейса для управления. Сам по себе движок не является готовым решением под ключ, но выполняет роль инструмента для интеграции со сторонними приложениями и управления с помощью API. Варианты его применения также включают в себя и переговорные комнаты, и один из примеров ниже это покажет. pyVideoSDK; websocket-client; orjson, просто потому что он быстрее json (тут и тут); queue — для создания очередей; Levenshtein — вычисление сходства строк;  vosk — распознавание речи (speech-to-text);  pyttsx3 — генерация речи из текста для Windows; pyfestival — генерация речи из текста для Linux; sounddevice — захват звука с микрофона и вывода звука на динамики; soundfile — чтение звуковых (WAV) файлов. VideoSDK управляется API по обыкновенной схеме запрос-ответ. Для отправки запросов и получения ответов используется WebSocket, по которому осуществляется обмен сообщениями в формате JSON. Описание запросов и их ответов доступно в документации API TrueConf VideoSDK. Исходя из нее мы будем именовать запросы — командами, а ответы — уведомлениями.  Для выполнения какого-либо действия нужно послать команду (запрос), например: accept – принять вызов; call – позвонить пользователю или послать запрос на участие в групповой конференции; getAbook – получить адресную книгу. Уведомления делятся на два типа: Ответы на запрос.  Уведомления, генерируемые в следствии наступления какого-то события.   Ответ на запрос будет содержать поле method с названием команды и поле result, которое в свою очередь будет содержать true либо, в других случаях, результат выполнения команды. Если произошла ошибка выполнения команды (внутренняя или некорректный запрос), result будет содержать false и дополнительное поле error с текстовым описанием ошибки. Пример ответа: Уведомление будет содержать поле method : "event" и поле event с названием произошедшего события. Пример уведомления: Разработчиками VideoSDK подготовлены библиотеки для взаимодействия с ним на Python (pyVideoSDK) и на С++ (videosdk). То есть вам не понадобится писать свою обертку для отправки/получения с API. Удобно, правда? Все примеры в статье будут показаны на Python.   В @TrueConfSDKPromoBot нужно нажать кнопку Free Accounts. Вам будет выдан один основной аккаунт и два дополнительных. Free Accounts with QR выдаст эти же данные, но с QR-кодом. Его можно показать в камеру VideoSDK и он автоматически авторизуется на тестовом сервере от разработчиков. VideoSDK воспроизведет звуковое уведомление, если считывание и авторизация прошли успешно. Всегда в первую очередь нужно запускать VideoSDK с параметром --pin, а потом уже запускать код. Так происходит, потому что, скрипт подключается (создает сессию) к запущенному экземпляру VideoSDK. В качестве пина можно использовать любую строку. Windows:"C:\Program Files\TrueConf\VideoSDK\VideoSDK.exe" --pin 123 Linux:trueconf-videosdk --pin 123 После этого на экране у вас отобразится окно VideoSDK c данными для подключения  (IP:port).  VideoSDK является клиентом для сервера TrueConf Server, поэтому для работы с ним требуется наличие развернутого сервера. В @TrueConfSDKPromoBot можно получить доступ к развернутому экземпляру TrueConf Server. В своих примерах я использую отдельный файлconfig.pyс настройками подключения и авторизации. Помимо настроек в этом файле есть еще список слов для голосовых команд, словарь для преобразования слов в числа и фразы для обратной связи VideoSDK с пользователем, а также класс для воспроизведения звуковых уведомлений. Пакет pyVideoSDK состоит из нескольких составляющих модулей:    основной модуль init.py. Создает сессию на websocket, устанавливает соединение, производит логирование, регистрирует пользовательские хендлеры.   import pyVideoSDK  мethods.py. В этом модуле все API-команды инкапсулированы в методы класса Methods для удобной работы с ними.   from pyVideoSDK.methods import Methods   consts.py. Здесь описаны все наименования команд и уведомлений, а также их параметры. from pyVideoSDK.consts import EVENT, METHOD_RESPONSE import pyVideoSDK.consts as C Также импортируем конфигурационный модуль: import config Для работы с VideoSDK, создайте экземпляр класса VideoSDK используя функцию open_session из модуля pyVideoSDK: Функция создаст экземпляр, установит соединение, и вернет объект для дальнейшей работы.  Аналогично этому создайте экземпляр класса для работы с командами, передав ему переменную sdk: Такая вот небольшая подготовительная работа. Дальше я покажу, как надо зарегистрировать обработчик (хендлер) событий для уведомлений и команд. Каждая команда после выполнения, а также уведомления присылают ответ в формате JSON. Чтобы отловить конкретное событие из всего потока уведомлений, нужно зарегистрировать хендлер.  Хендлер (обработчик) – это функция, которая вызывается какой-либо программной системой в ответ на наступление какого-либо события. Чтобы зарегистрировать хендлер, нужно обернуть функцию-обработчик декоратором: type_of_response — может содержать только один из двух типов событий:  METHOD_RESPONSE — ответ API, вызванный на выполнение команды; EVENT — уведомление об изменении состояния в работе VideoSDK. C.name_of_response — имя обрабатываемого события. Имена событий отличаются по                                           префиксу, для method_response — M_, а для event-ов — EV_: Декорированная функция всегда должна принимать один позиционный параметр, назовем его response.  После добавления обработчика можно выполнить команду. Для примера приведен код получения информации о мониторах:  Метод run() держит предварительно созданную сессию открытой, пока есть подключение к VideoSDK (см. раздел Инициализация объектов выше). На самом деле здесь все просто. В методе крутится бесконечный цикл и каждую 0,2 секунды проверяет соединение. Итак, мы разобрались как добавлять обработчики и вызывать команды, ниже мы рассмотрим несколько “боевых” примеров. Авторизоваться на сервере можно, если мы к нему подключены. Поэтому нужно отловить уведомление serverConnected, которое возникает только при успешном присоединении к серверу, и выполнить команду login c параметрами login и password.   Предположим, что наша переговорная комната участвует в конференции и один из пользователей показывает контент в отдельном потоке. Тогда, если у нас подключено два экрана, очень удобно выводить окно с показом контента сразу на второй (не занятый окнами из конференции) дисплей. В этом поможет тот факт, что такой контентный поток будет помечен особым тегом "#contentSharing". Для переноса видеоокна подойдет команда moveVideoSlotToMonitor с двумя параметрами: callId – идентификатор слота (окна), который нужно вынести; monitorIndex – числовой индекс монитора. Чтобы перевести слот на второй монитор, нужно узнать какой монитор свободен. Для этого надо: Выполнить команду getMonitorsInfo (ранее рассматривалась в данной статье). Проверить чему равно поле currentMonitor. Вывести слот на противоположный.   Весь код я расписывать не буду, только логику. Для голосового распознавания я использую Vosk API, т.к. он работает оффлайн. Я думаю, все понимают как работает голосовой вызов, например, в том же Google Assistant или Siri. Нам нужно: Получить список абонентов.  Распознать речь и отделить команду Набери от ее параметров Ивана Петрова. Сопоставить введенные ФИО с адресной книгой из VideoSDK. Вызвать найденного абонента по его логину (в терминологии производителя решения TrueConf ID). Для получения списка абонентов я выполнил команду getABook, “словил” уведомление с помощью функции on_getAbook и сохранил полученные данные в словарь Abook в формате ключ (peerDn, отображаемое имя, DisplayName) : значение (peerId, TrueConf ID). on_getAbook Использование глобальных переменных считается плохой практикой, но иногда это оправдано. Выходит, что мне нужно сохранить список абонентов в словарь для дальнейшего использования. Функция, которая выполняет это действие, отдекорирована хендлером, который принимает только один параметр, что в свою очередь накладывает  ограничения – мы не можем вызвать нашу функцию, и передать в нее “кастомные” аргументы. Хендлер работает как коллбек. Было создано событие (getABook) – отработала функция, события нет – функция “спит”.  Поэтому я использую глобальные переменные, чтобы была возможность работать с полученными данными в других функциях.   Структура словаря Аbook: Как было уже написано, я использую Vosk для распознавания речи. Про него достаточно много написано информации, например, тут на Хабре, поэтому сильно углубляться не будем. Но некоторые моменты затрону:  Vosk сильно привередлив к звуку и постороннему шуму. Поэтому в идеале нужно организовать в помещении звукоизоляцию или внедрить шумоподавление для улучшения распознавания голосового ввода. Мы используем русскоязычную облегченную модель, которая подходит для Android/iOS и RPi. Эта модель не требовательна к ресурсам и может работать на устройствах с VideoSDK. Но точность распознавания речи по сравнению с полной моделью может быть снижена. Не популярные имена и фамилии, а также окончания слов распознаются плохо. Т.к. используемая облегченная модель неидеально распознает некоторые окончания в русском языке, то нужно решать и эту проблему. Дополнительная сложность заключалась в том, что я не знал, какие данные могут быть в адресной книге. Метод getABook возвращает отображаемое имя (DisplayName), оно имеет ограничение в 64 символа и по сути может быть любым. Из-за этого нельзя просто проверить, находится ли ключ (ФИО) в словаре и вызвать абонента с таким отображаемым именем по логину (TrueConf ID). Я подумал: “А что если сравнивать строки на схожесть?”. Было принято использовать алгоритм неточного сравнения строк — Сходство Джаро-Винклера. Что это и какие алгоритмы существуют, можно почитать на Хабре. Для Python существует модуль, в котором реализован алгоритм Джаро - Винклера. Он называется Levenshtein и его также надо не забыть импортировать через import Levenshtein. Отображаемое имя может иметь вид:  Иванов Владимир Иванов Владимир Андреевич  999-000 +79081234567 любая другая строка не больше 64 символов.  Vosk числа распознает отлично, но в результате он их записывает строкой, а не цифрами. Например, фразу Набери 123-456-789 он распознает как Набери один два три четыре пять шесть семь восемь девять или как Набери сто двадцать три четыреста пятьдесят шесть семьсот восемьдесят девять, в зависимости от способа произношения фразы. И для алгоритма Джаро-Винклера это имеет значение. Поэтому потребовалось дописать функцию проверки строкового числа и перевода его в цифровое представление.  Далее, в процессе тестирования стало ясно, что некоторые фамилии Vosk делит на части, предполагая, что это разные слова.  Пример распознавания некоторых фамилий: Поэтому пришла мысль конкатенировать все аргументы, которые идут после команды набора (в примере используются ключевые слова "набери" и "позвони"). В итоге получилось так:  Алгоритм Джаро-Винклера рассчитывает минимальное число одно-символьных преобразований, которое необходимо для изменения одного слова на другое, поэтому конкатенация строк повысила точность расчета сходства получившихся в итоге слов.  Результат распознавания Vosk всегда возвращает в нижнем регистре, в свою очередь у отображаемого имени (DispayName) нет каких-либо требований на этот счет. Пользователь может задать себе имя, например, С0нЯ КОшкин@. Конечно, в корпоративной среде так делать никто не будет, но мы пишем универсальный код, который будет работать в разных ситуациях и результат не будет меняться. Смотрим — чувствителен ли алгоритм Джаро-Винклера к регистру? И таки да, чувствителен.  Пример схожести строк в разном регистре: Процент совпадения, как вы видите, меняется аж на целых 12%, и это много. Поэтому нужно к каждое отображаемое имя из адресной книги нужно перевести к нижнему регистру, благо есть функция lower(): После сопоставления входных данных (ФИО) с данными из адресной книги мы получаем словарь со значениями степени совпадения строк. По логике вещей, кандидат на вызов тот, у кого выше степень похожести. И все бы ничего, но и тут снова возник маленький нюанс. Алгоритм Джаро-Винклера для двух строк разного размера, но совпадающих на 6 букв, выдает результат схожести 84%.  Таким образом, мы видим, что нельзя “по логике вещей” брать контакт с максимальным совпадением. Поэтому я добавил дополнительную проверку процента схожести, если совпадение больше 85%, то совершить вызов. Вынес этот параметр в отдельную переменную SIMILARITY_PERCENTAGE в config.py, так его легко можно править при необходимости в зависимости от особенностей формирования адресной книги. В результате вышеизложенного наша функция contact_diff обросла дополнительным функционалом и приобрела такой вид:  Функция возвращает наиболее подходящего абонента для вызова, а именно его DisplayName и процент схожести.   Для вызова абонента надо выполнить команду call с аргументом peerId. peerId - уникальный идентификатор пользователя (TrueConf ID), которому нужно позвонить. Используя QT (PyQT), вы можете разработать собственный брендированный интерфейс для звонков через VideoSDK. Разработчики заботливо подготовили для всех желающих сэмпл с кнопкой для вызова консультанта. Это будет полезно, например, в видеотерминалах или как еще их называют – информационных киосках. Они могут быть размещены на вокзалах, в аэропортах, банках, торговых центрах. А еще в системе "умного города" – скажем, для туриста, который ищет куда бы сходить. Такой терминал решает вопрос удалённой помощи – путешественник при необходимости может получить помощь от консультанта по вопросам посещения культурных мест, заселения в гостиницу и т.п. GIF с наглядным применением сэмпла CallButton: Как запустить этот сэмпл?  Получить авторизационные данные. Запустить VideoSDK c параметром --pin (см. правило запуска). Авторизоваться в VideoSDK. В main.py прописать IP, порт VideoSDK и PIN и TrueConf ID в переменную CALL_ID. Запустить скрипт. Итак, сегодня мы познакомились с VideoSDK и его API, узнали как начать работу с ним и как получить данные для теста. Поэтому,  если у вас есть немного свободного времени, желание и начальные знания программирования, то стоит попробовать. Таким образом можно решить многие бизнес-задачи:  Вызов работника банка с помощью одной кнопки в терминале/банкомате. Вызов консультанта в информационном киоске. Голосовое управление в переговорной комнате.  Внедрить видеосвязь в свое приложение написанное на QT, например, для связи с доктором  в приложение больницы.   Голосовой вызов и автоматический перенос контента на второй экран:https://github.com/TrueConf/pyVideoSDK-VoiceControl CallButton – вызов с помощью кнопки PyQT:https://github.com/TrueConf/CallButton      Технический писатель