Skip to content

Документация разработчика VideoGrace

Этот раздел описывает архитектуру, протоколы и расширяемые точки VideoGrace для разработчиков, интеграторов и технических партнеров.

Документация помогает понять, как устроены сервер, клиенты, media transport, WebSocket/WSS API и сервисные сценарии вроде записи, воспроизведения файлов и внешних ботов. Она рассчитана на инженеров, которые хотят интегрировать VideoGrace в свою инфраструктуру, написать собственного клиента или доработать существующие компоненты системы.

Что здесь можно найти

  • С чего начать, если вы оцениваете продукт: руководство администратора и основной сайт VideoGrace.
  • Архитектурную карту VideoGrace: сервер, клиенты, сервисы, control/media/storage каналы.
  • Описание WebSocket/WSS API и JSON-команд управляющего протокола.
  • Control v2: общий контракт web/native/KMP, схемы и сценарии проверки для будущего multi-endpoint backend; статус реализации указан отдельно.
  • Модель чатов: отправка, статусы, вложения, offline outbox и постраничная история.
  • Модель конференций, клиентов, устройств и media sessions.
  • WebRTC primary media path, выбор RTC route и WSMedia fallback.
  • Примеры сервисных клиентов на базе FilePlayer и Recorder.
  • Контракт медиаподключения и принципы разработки собственного клиента.
  • Статистику конференций и звонков: сеансы, время присутствия, отзывы и связь с записями и транскриптами.

Границы документации

Это публичная документация интегратора: доступные интерфейсы, протоколы и внешне полезные инварианты. Внутренние проекты архитектуры, отчёты ревизий и тестовых стендов, реализация ядра и инструменты выпуска лицензий в неё не входят.

Главные идеи

  • Управляющий протокол, файлы и медиа разделены на разные каналы: CommandLoop, HTTPS storage, WebRTC primary media, WSMedia fallback.
  • Устройство создаётся и удаляется через control-команды, а media transport только переносит RTP/RTCP.
  • Основной ключ маршрутизации медиа — ssrc.
  • Web client использует WebRTC как основной media path: webrtc_routes_request, rtc_node_id, webrtc_offer, webrtc_answer, webrtc_ice_candidate.
  • WSMedia остается fallback и использует один bidirectional WebSocket на access token/conference с multiplex/demultiplex потоков по ssrc.
  • Для новых native/KMP клиентов целевой media contract — WebRTC; legacy UDP остается совместимым path для старых native-клиентов и сервисов.
  • Наличие внешних media nodes не означает готовой отказоустойчивости управляющего сервера; возможности конкретного релиза проверяются отдельно.
flowchart LR
    Client[Client / Bot / Service]
    Control[CommandLoop JSON]
    Storage[HTTPS storage]
    Blob[BlobChannel legacy]
    RTC[WebRTC primary]
    Media[WSMedia fallback]
    Server[VideoGrace Server]
    Translator[Media Translator]

    Client <-->|commands, auth, conferences, devices| Control
    Client <-->|files, avatars, recordings| Storage
    Client <-->|legacy blob frames| Blob
    Client <-->|ICE/DTLS/SRTP| RTC
    Client <-->|RTP/RTCP frames by SSRC| Media

    Control --> Server
    Storage --> Server
    Blob --> Server
    RTC --> Server
    Media --> Server
    Server <-->|UDP RTP/RTCP| Translator

Как читать

  1. Начать с карты системы и инвариантов.
  2. Затем прочитать WebSocket/WSS API и Конференция и устройства.
  3. Для backend CRM начать со сценария встречи и расшифровки.
  4. Для интеграций читать Как писать клиентов, затем примеры FilePlayer и Recorder.
  5. Для browser media читать контракт WebRTC и WSMedia mux/demux.
  6. Для реализации сообщений читать Чаты и история сообщений.
  7. Для остальных деталей протокола читать Команды, Структуры данных и Сценарии.
  8. Для аналитики читать Статистика конференций и звонков, затем API записей и документацию Recorder/Transcriber.

Правило изменения media path

Новые media-типы, клиенты и боты должны добавлять потоки как новые ssrc внутри существующего media transport. Не нужно создавать отдельный media WebSocket на каждое устройство, если транспорт уже поддерживает multiplexing.