Звонки и голос

Звонки и голосовые каналы передают аудио, видео и демонстрацию экрана напрямую на сервер через собственный порт. На этой странице описана сетевая часть, параметры, которые нужно проверить после установки, а также транскрипция с использованием модели распознавания речи, которую вы запускаете самостоятельно.

Как работают звонки

Звонки обеспечиваются приложением Звонки (id com.mattermost.calls), которое установлено и включено по умолчанию. Голосовые каналы (приложение Голосовые каналы, образ antimatter-next) — это постоянные комнаты для звонков, построенные на базе приложения «Звонки»: для их работы необходимо, чтобы приложение «Звонки» было включено, и они используют те же параметры, порты и серверы.

Приложение «Звонки» запускает медиа-сервер внутри Antimatter. Веб-приложение, настольное приложение и мобильные приложения подключаются к нему с помощью WebRTC:

сигнализация проходит через обычное веб-соединение (ваш HTTPS-прокси);
медиа (аудио, видео, демонстрация экрана) не проходит через него: оно направляется напрямую на сервер через порт для звонков, по умолчанию 8443 UDP и TCP.

Параметры находятся в разделе Системная консоль › Плагины › Звонки. Каждый из них также можно настроить с помощью переменной окружения AM_CALLS_ для сервиса antimatter, которая в этом случае имеет приоритет над Системной консолью и блокирует изменение параметра в ней. Также работают устаревшие имена MM_CALLS_.

Проверьте это после установки

Откройте порт для звонков. Разрешите 8443/udp и 8443/tcp в файрволе сервера и вашего облачного провайдера.
Проверьте тестовый режим. Тестовый режим (DefaultEnabled) по умолчанию выключен, поэтому звонки могут начать все. Включите его (Вкл) в Системная консоль › Плагины › Звонки, чтобы во время проверки работоспособности звонков в каналах их могли начинать только администраторы системы, а затем выключите обратно. Переменная AM_CALLS_DEFAULT_ENABLED: значение true означает, что тестовый режим выключен. Сервер, перенесённый с Mattermost, сохраняет сделанный выбор в своей конфигурации.
Решите вопрос с видео. Видео (EnableVideo, AM_CALLS_ENABLE_VIDEO) включено по умолчанию: участники могут включать камеру там, где доступны звонки, в личных и групповых сообщениях, а также в каналах. Для голосовых каналов это определяет настройка Разрешить видео в голосовых каналах приложения Voice Channels. Если вы её отключите, никто не сможет включить камеру, даже в голосовых каналах.
За NAT задайте публичный адрес (следующий раздел).

Где включены звонки

У каждого сообщества есть тип: Компания или Сообщество (см. Тип новых сообществ). Канал, в котором администраторы не включили и не выключили звонки, следует типу своего сообщества:

в Компании каналы следуют настройке по умолчанию сервера: пока тестовый режим выключен, звонки доступны всем;
в Сообществе звонки в каналах выключены: участники общаются в голосовых каналах. Администраторы канала и сообщества всё равно могут включить звонки в конкретном канале.

Собственная настройка канала всегда имеет приоритет. Личные и групповые сообщения не принадлежат сообществу: пока тестовый режим выключен, звонки в них доступны всем. Изменение типа сообщества применяется к звонкам в течение 30 секунд.

Порты, NAT и STUN

Параметр	Переменная	Значение по умолчанию
Порт RTC-сервера (UDP)	`AM_CALLS_UDP_SERVER_PORT`	`8443`
Порт RTC-сервера (TCP)	`AM_CALLS_TCP_SERVER_PORT`	`8443`
Адрес RTC-сервера (UDP), (TCP)	`AM_CALLS_UDP_SERVER_ADDRESS`, `AM_CALLS_TCP_SERVER_ADDRESS`	пусто: все адреса
Переопределение хоста ICE	`AM_CALLS_ICE_HOST_OVERRIDE`	пусто: определяется через STUN
Переопределение порта хоста ICE	`AM_CALLS_ICE_HOST_PORT_OVERRIDE`	пусто: порт сервера
Конфигурации серверов ICE	`AM_CALLS_ICE_SERVERS_CONFIGS`	`[{"urls":["stun:stun.cloudflare.com:3478"]}]`
(Экспериментально) Включить поддержку IPv6	(Системная консоль)	выключено

Порты должны быть в диапазоне от 80 до 49151. В файле compose сайта измените CALLS_PORT в .env: он задает обе переменные и публикует порт, один и тот же номер на хосте и в контейнере. Клиенты сначала пробуют UDP, а при неудаче переключаются на TCP на том же порту.

Адрес, на который клиенты отправляют медиа

Сервер сообщает каждому клиенту адрес, на который нужно отправлять медиа (его «кандидат хоста»). По умолчанию он определяет свой публичный адрес, запрашивая его у STUN-сервера — публичной службы, которая отвечает адресом и портом, с которых поступил запрос. По умолчанию используется публичный STUN-сервер Cloudflare, stun:stun.cloudflare.com:3478. Сервер — не единственный, кто им пользуется: каждый клиент, присоединяющийся к звонку, тоже запрашивает у него свой публичный адрес. STUN-сервер видит только IP-адреса и порты, но никогда не получает аудио, видео или сообщения из звонка.

Сервер, в Конфигурациях серверов ICE которого по-прежнему сохранен STUN-сервер Mattermost (stun.global.calls.mattermost.com), например после перехода с Mattermost, использует вместо него сервер Cloudflare. Сохраненная настройка не изменяется.

Задать адрес вручную необходимо, если:

сервер находится за NAT или имеет несколько публичных адресов: задайте Переопределение хоста ICE публичным IP-адресом (или именем хоста, которое разрешается в него);
NAT сопоставляет с 8443 другой публичный порт: также задайте Переопределение порта хоста ICE этим публичным портом;
сервер не имеет доступа в Интернет, или вы не хотите, чтобы сервер и клиенты обращались к внешнему STUN-серверу: задайте Переопределение хоста ICE и очистите список STUN с помощью AM_CALLS_ICE_SERVERS_CONFIGS=[]. Если задано Переопределение хоста ICE, сервер больше не запрашивает свой адрес у STUN-сервера; пустой список не дает клиентам делать то же самое.

services:
  antimatter:
    environment:
      AM_CALLS_ICE_HOST_OVERRIDE: 203.0.113.10
      AM_CALLS_ICE_SERVERS_CONFIGS: "[]"

Чтобы использовать STUN без сторонних служб, запустите собственный STUN-сервер (TURN-сервер, например coturn, тоже отвечает на STUN-запросы) и укажите его в Конфигурациях серверов ICE вместо стороннего, как в примере с TURN ниже.

В локальной сети используйте LAN-адрес сервера. После изменения портов, адресов или настроек ICE перезапустите сервер, либо отключите и снова включите приложение Calls: медиа-сервер настраивается при запуске приложения.

TURN для строгих файрволов

Некоторые сети блокируют как UDP, так и исходящие соединения на нестандартные TCP-порты. Пользователям таких сетей нужен сервер TURN, который передаёт медиаданные через порт, к которому у них есть доступ (часто 443). Antimatter не включает такой сервер в свой состав; запустите сервер TURN, например coturn, и добавьте его в ICE Servers Configurations — JSON-список:

[
  {"urls": ["stun:turn.example.com:3478"]},
  {"urls": ["turn:turn.example.com:3478?transport=udp", "turns:turn.example.com:443?transport=tcp"]}
]

При использовании общего секрета (параметр use-auth-secret в coturn) укажите тот же секрет в TURN Static Auth Secret (AM_CALLS_TURN_STATIC_AUTH_SECRET): сервер выдаёт каждому клиенту временные учётные данные, действительные в течение TURN Credentials Expiration (minutes) (по умолчанию 240 минут).
При использовании фиксированных учётных данных добавьте "username" и "credential" в запись TURN.
Server Side TURN (отключено по умолчанию) также использует серверы TURN для соединений, которые инициирует сервер.

Другие параметры звонков

Параметр	Переменная	Значение по умолчанию	Назначение
Max call participants	`AM_CALLS_MAX_CALL_PARTICIPANTS`	0 (без ограничений)	Максимальное количество участников в одном звонке.
Allow screen sharing	(Системная консоль)	вкл	Позволяет участникам демонстрировать свой экран.
Enable call ringing	`AM_CALLS_ENABLE_RINGING`	вкл	Включает сигнал при начале звонка в личном или групповом сообщении.
Enable simulcast for screen sharing (Experimental)	(Системная консоль)	выключено	Передаёт демонстрацию экрана в нескольких качествах.
Enable AV1 codec for screen sharing (Experimental)	(Системная консоль)	выключено	Игнорируется, если включён simulcast.

У приложения «Голосовые каналы» есть два параметра в Системная консоль › Плагины › Голосовые каналы: Присоединяться при открытии голосового канала (включено по умолчанию) и Разрешить видео в голосовых каналах (включено по умолчанию, но см. видео выше). Администраторы сообщества превращают канал в голосовой в его параметрах.

Чтобы полностью отключить звонки, отключите приложение «Звонки» в Системная консоль › Плагины › Управление плагинами или задайте AM_CALLS_DISABLE=true. Голосовые каналы тоже перестанут работать.

Крупные серверы: внешний rtcd

По умолчанию один сервер Antimatter обрабатывает все медиаданные звонков. Для множества одновременных звонков или для разгрузки сервера чата от медиапотока приложение Calls может передавать медиаданные на rtcd — отдельный медиасервер (open-source rtcd от Mattermost, версия 0.17 или новее). Укажите RTCD service URL (AM_CALLS_RTCD_SERVICE_URL), например https://rtcd.example.com: тогда все звонки будут проходить через него, а клиенты будут отправлять свои медиаданные на собственный порт rtcd, а не на порт Antimatter. Учётные данные можно передать с помощью AM_CALLS_RTCD_CLIENT_ID и AM_CALLS_RTCD_AUTH_KEY; если они не заданы, приложение само зарегистрируется в rtcd. Лицензия не требуется. Приложение Calls показывает администраторам предупреждение с рекомендацией использовать rtcd, если на сервере одновременно в звонках находится более 50 человек.

Транскрипция и субтитры в реальном времени

Antimatter может транскрибировать звонки с помощью модели преобразования речи в текст, которую вы запускаете самостоятельно, и показывать субтитры в реальном времени, пока люди говорят. Antimatter поддерживает любой сервер, предоставляющий эндпоинт /v1/audio/transcriptions, совместимый с OpenAI, например сервер Whisper в вашей сети. Дополнительные сервисы от Antimatter не требуются.

Как это работает

Хост звонка запускает транскрипцию с помощью Транскрибировать звонок в элементах управления звонком. Бейдж Идёт транскрипция уведомляет всех участников.
Приложение каждого участника слушает его собственный микрофон, разбивает речь на короткие фрагменты (до 12 секунд, никогда во время заглушения) и отправляет их в Antimatter, который пересылает их на ваш сервер преобразования речи в текст.
Если включены субтитры в реальном времени, текст каждого фрагмента сразу отображается участникам в виде субтитра.
Когда транскрипция останавливается или звонок завершается, бот Calls публикует транскрипт в виде текстового файла и файла субтитров WebVTT в обсуждении звонка (в голосовых каналах — в канале).
Если включён параметр Summarize transcriptions, агент по умолчанию из приложения Agents также публикует краткое содержание в обсуждении (см. AI).

A call's thread: the Calls bot has posted the transcript as a text file, and an AI agent has posted a summary below it. — После звонка: транскрипт и его краткое содержание в обсуждении звонка.

Настройка

Установите следующие параметры для сервиса antimatter:

services:
  antimatter:
    environment:
      AM_CALLS_ENABLE_TRANSCRIPTIONS: "true"
      AM_CALLS_TRANSCRIBE_API: openai
      AM_CALLS_TRANSCRIBE_API_OPEN_AIURL: http://stt.internal:8000/v1
      AM_CALLS_TRANSCRIBE_API_OPEN_AI_MODEL: whisper-1
      AM_CALLS_TRANSCRIBE_API_OPEN_AI_KEY: ""
      AM_CALLS_ENABLE_LIVE_CAPTIONS: "true"
      AM_CALLS_LIVE_CAPTIONS_LANGUAGE: en

Параметр	Переменная	Что указать
Enable call transcriptions (Beta)	`AM_CALLS_ENABLE_TRANSCRIPTIONS`	`true`
Call transcriber API	`AM_CALLS_TRANSCRIBE_API`	`openai` (отображается как "OpenAI-compatible API (no job service)")
Speech-to-text API URL	`AM_CALLS_TRANSCRIBE_API_OPEN_AIURL`	Базовый URL API, включая `/v1`.
Speech-to-text model	`AM_CALLS_TRANSCRIBE_API_OPEN_AI_MODEL`	Имя модели, как его знает API, например `whisper-1`. Обязательное поле.
Speech-to-text API key	`AM_CALLS_TRANSCRIBE_API_OPEN_AI_KEY`	Отправляется как bearer-токен. Оставьте поле пустым, если API не требует ключа.
Включить субтитры в реальном времени (Beta)	`AM_CALLS_ENABLE_LIVE_CAPTIONS`	`true` для субтитров во время звонка.
Язык субтитров в реальном времени	`AM_CALLS_LIVE_CAPTIONS_LANGUAGE`	Говорящий язык в виде двухбуквенного кода (по умолчанию `en`). Он также передается в API распознавания речи для транскрипции, поэтому установите его, даже если субтитры не используются.
Суммаризация транскрипций	`AM_CALLS_SUMMARIZE_TRANSCRIPTIONS`	`true` для AI-резюме после звонка.

В Системной консоли параметры транскрипции появляются только после включения Включить запись звонков, хотя для этого типа транскрипции запись не требуется. Настройка этих параметров с помощью переменных выше позволяет избежать этой проблемы. Не включайте запись одновременно с транскриптором openai: при начале записи будет предпринята попытка запустить транскриптор job-service, что приведет к ошибке.

Аудио всех, кто говорит во время включения транскрипции, передается на сервер распознавания речи, который вы настроили, а транскрипт публикуется там, где его могут прочитать все участники канала. Сообщите об этом пользователям и, если звонки конфиденциальны, размещайте этот сервер в собственной сети.

Запись

Запись звонков (а также их транскрипция с помощью встроенного whisper.cpp или транскрипторов Azure) выполняется в отдельных контейнерах, которые запускаются службой заданий — open-source-решением calls-offloader от Mattermost. Вы разворачиваете её самостоятельно рядом с Antimatter. Настройки: Включить запись звонков (AM_CALLS_ENABLE_RECORDINGS, по умолчанию выключено), URL службы заданий (AM_CALLS_JOB_SERVICE_URL), Максимальная длительность записи звонка (по умолчанию 60 минут, от 15 до 180) и Качество записи звонка (низкое, среднее или высокое; по умолчанию среднее). Лицензия не требуется. Когда запись включена, ведущий звонка начинает и останавливает её с помощью кнопки Записать звонок в элементах управления звонком. Все участники видят, что идёт запись, а когда она останавливается, запись публикуется в обсуждении звонка. У звонков в голосовых каналах нет обсуждений, поэтому их нельзя записать. Если нужны только транскрипты и субтитры, настройка распознавания речи, описанная выше, проще: служба заданий не требуется.