← Cloudflare Realtime / realtime / sfu / media-transport-adapters

WebSocket-адаптер

Передавайте аудио и видео между дорожками WebRTC и эндпойнтами WebSocket. Поддерживается приём аудио из источников WebSocket и отправка аудио и видео WebRTC потребителям WebSocket. Исходящее видео (egress) передаётся в формате JPEG со скоростью около 1 FPS.

• ИИ-сервисы с WebSocket API для обработки аудио
• Пользовательские конвейеры обработки аудио
• Мосты к устаревшим системам
• Генерация и приём аудио на стороне сервера
• Снимки видео и миниатюры
• Приём данных компьютерного зрения (низкий FPS)

graph LR
    A[External System] -->|Audio Data| B[WebSocket Endpoint]
    B -->|Adapter| C[Realtime SFU]
    C -->|New Session| D[WebRTC Track]
    D -->|WebRTC| E[WebRTC Clients]

graph LR
    A[WebRTC Source] -->|WebRTC| B[Realtime SFU Session]
    B -->|Adapter| C[WebSocket Endpoint]
    C -->|Media Data| D[External System]

POST /v1/apps/{appId}/adapters/websocket/new

{
  "tracks": [
    {
      "location": "local",
      "trackName": "string",
      "endpoint": "wss://...",
      "inputCodec": "pcm",
      "mode": "buffer"
    }
  ]
}

{
  "tracks": [
    {
      "trackName": "string",
      "adapterId": "string",
      "sessionId": "string",    // New session ID generated
      "endpoint": "string"      // Echo of the requested endpoint
    }
  ]
}

{
  "tracks": [
    {
      "location": "remote",
      "sessionId": "string",
      "trackName": "string",
      "endpoint": "wss://...",
      "outputCodec": "pcm"
    }
  ]
}

{
  "tracks": [
    {
      "trackName": "string",
      "adapterId": "string",
      "sessionId": "string",    // Same as request sessionId
      "endpoint": "string"      // Echo of the requested endpoint
    }
  ]
}

POST /v1/apps/{appId}/adapters/websocket/close

{
	"tracks": [
		{
			"adapterId": "string"
		}
	]
}

• Кодек: Opus
• Частота дискретизации: 48 kHz
• Каналы: Стерео

Медиа использует Protocol Buffers. Аудио использует PCM payload, видео использует JPEG payload:

• 16-битный PCM со знаком, little-endian
• частота дискретизации 48 kHz
• Стерео (чередование левого и правого каналов)
• Видео: payload в виде изображения JPEG (один кадр на сообщение)

message Packet {
    uint32 sequenceNumber = 1;  // Used in Stream mode only
    uint32 timestamp = 2;       // Used in Stream mode only
    bytes payload = 5;          // Media data
}

Режим приема (буфер): Только payload поле используется и содержит фрагменты аудиоданных.

Потоковый режим (egress):

• Для аудиокадров:
  • sequenceNumber: Инкрементный счётчик пакетов
  • timestamp: Временная метка для синхронизации
  • payload: Данные отдельного аудиокадра PCM
• Для видеокадров (JPEG):
  • timestamp: Временная метка для синхронизации
  • payload: Данные изображения JPEG (один кадр на сообщение)
  • Примечание: sequenceNumber может быть не задан для видеокадров

• Поддерживаемые входные кодеки WebRTC: H264, H265, VP8, VP9
• Вывод через WebSocket: изображения JPEG со скоростью около 1 FPS

Подключается к вашему эндпойнту WebSocket:

1. Рукопожатие при обновлении до WebSocket
2. Защищённое соединение для wss:// URL-адреса
3. Начинается передача медиапотока

• Двоичные сообщения: Аудиоданные PCM порциями
• Максимальный размер сообщения: 32 КБ на сообщение WebSocket
• Важно: учитывайте накладные расходы на сериализацию при разбиении аудиобуферов на части
• Отправляйте аудио небольшими частыми порциями, а не крупными партиями

• Двоичные сообщения: Отдельные кадры с метаданными (аудио или видео)
• Аудиокадры включают:
  • Информация о временной метке
  • Порядковый номер
  • Данные аудиокадра PCM
• Видеокадры включают:
  • Информация о временной метке
  • Данные изображения в формате JPEG
  • Примечание: для видеокадров порядковый номер может быть не задан
• Кадры отправляются по отдельности по мере поступления из WebRTC-трека
• Видеокадры передаются примерно с частотой 1 FPS

1. Подключается к эндпойнту WebSocket
2. Начинается передача аудиопотока
3. Начинается видеотрансляция (если настроено)
4. При потоковой передаче из WebRTC в WebSocket выполняется несколько кратких попыток переподключения к тому же эндпойнту после разрыва соединения
5. Соединение закрывается при закрытии, ошибке или после исчерпания окна автоматического переподключения

Когда вы используете WebSocket-адаптер в Потоковый режим (egress) чтобы отправлять аудио или видео в реальном времени от SFU на собственный эндпойнт WebSocket (WebRTC → WebSocket), SFU автоматически переподключается после кратковременных отключений или перезапусков конечной точки.

SFU повторяет попытки подключения к тому же WebSocket-эндпойнту в течение до 5 секунд. Изменения в API не требуются. Если по истечении окна переподключения эндпойнт остаётся недоступным, адаптер закрывается, и для возобновления передачи потока приложению нужно создать новый адаптер.

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

• Буферизация аудио: SFU хранит короткий ограниченный буфер аудиокадров. Если прерывание длится дольше, чем позволяет буфер, более старые аудиоданные могут отбрасываться, чтобы восстановление после переподключения оставалось ограниченным по времени.
• Буферизация видео: SFU хранит только последний доступный кадр JPEG. Во время переподключения новые кадры заменяют старые, поэтому видео возобновляется почти в реальном времени, а не воспроизводит устаревшие кадры.
• Поведение доставки: буферизация снижает потерю медиаданных при кратковременных перебоях, но не является механизмом повтора и не гарантирует непрерывную доставку или доставку ровно один раз.

Автоматическое переподключение применяется только при использовании Потоковый режим (egress). Он повторяет попытки только для того же эндпойнта и не поддерживает отказоустойчивое переключение между несколькими эндпойнтами.

В настоящее время находится в бета-версии и доступен бесплатно.

После достижения статуса общей доступности тарификация будет соответствовать стандартным ценам Cloudflare Realtime: $0.05 за ГБ исходящего трафика. Взимается плата только за трафик, идущий от Cloudflare к эндпойнтам WebSocket. Трафик, поступающий от эндпойнтов WebSocket в Cloudflare, не тарифицируется.

Использование учитывается в счёт бесплатного тарифа Cloudflare Realtime на 1000 ГБ.

• Повторное закрытие уже закрытого экземпляра возвращает успешный результат
• Закрывайте по завершении сессий
• При использовании Потоковый режим (egress), обработайте закрытие адаптера после 5-секундного окно автоматического переподключения исчерпан.
• При приёме данных из WebSocket в WebRTC реализуйте в WebSocket-клиенте логику переподключения на случай обрыва соединения.
• Сделайте эндпойнт WebSocket устойчивым к перезапуску, чтобы он мог принимать повторные подключения на тот же URL-адрес во время кратких перезапусков.

• Развертывание WebSocket-эндпойнтов рядом с Cloudflare edge
• Используйте подходящие размеры буфера
• Отслеживайте качество соединения

• Защита эндпойнтов WebSocket с помощью аутентификации
• Используйте wss:// для рабочей среды
• Реализуйте ограничение частоты запросов

• Полезные нагрузки WebSocket: PCM (аудио) для приема и трансляции; JPEG (видео) для трансляции
• Статус беты: API может измениться в будущих версиях
• Поддержка видео: Только Egress (JPEG)
• Частота кадров видео: примерно 1 FPS (бета, не настраивается)
• Переподключения при стриминге: При использовании Потоковый режим (egress), SFU автоматически повторяет попытки подключения к тому же эндпойнту WebSocket только при кратковременных разрывах связи. Переключение на альтернативные эндпойнты не выполняется.
• Восстановление по возможности: короткие переподключения уменьшают потерю медиаданных, но не гарантируют непрерывную доставку или доставку ровно один раз.
• Поведение видео при переподключении: Видео возобновляется с последнего доступного JPEG-кадра, а не воспроизводит более старые кадры.
• Однонаправленный поток: Каждый экземпляр обрабатывает одно направление

• Аудио (PCM через WebSocket): Примеры Cloudflare Realtime: ai-tts-stt ↗
• Видео (исходящий трафик JPEG): Примеры Cloudflare Realtime: video-to-jpeg ↗

1. Замена пользовательской сигнализации вызовами Adapter API
2. Обновление эндпойнтов WebSocket для обработки формата PCM
3. Реализуйте управление жизненным циклом адаптера
4. Удалите пользовательскую конфигурацию STUN/TURN

Вопрос: можно ли использовать один и тот же адаптер для двунаправленного аудио? О: Нет, каждый экземпляр однонаправленный. Создавайте отдельные адаптеры для отправки и для приема.

Вопрос: что происходит при обрыве соединения WebSocket?

О: При использовании Потоковый режим (egress), SFU автоматически повторяет попытки подключения к тому же эндпойнту WebSocket в течение 5 секунд. Если эндпойнт становится доступным в этот промежуток времени, трансляция возобновляется автоматически.

Для аудио используется короткий ограниченный буфер, который уменьшает слышимые потери при кратких прерываниях. Видео возобновляется с последнего доступного JPEG-кадра, а не воспроизводит более старые кадры.

Если эндпойнт остается недоступным по истечении 5-секундного окно автоматического переподключения, адаптер закрывается, и его необходимо создать заново.

При приёме данных из WebSocket в WebRTC WebSocket-клиент должен переподключаться и по необходимости пересоздавать адаптер.

Вопрос: есть ли ограничение на количество одновременных адаптеров? О: Ограничения соответствуют стандартным квотам Cloudflare Realtime. По конкретным требованиям обращайтесь в службу поддержки.

Вопрос: можно ли изменить аудиоформат после создания адаптера? О: Нет, формат аудио фиксируется в момент создания. Для другого формата создайте новый адаптер.