WebSocket/WSS API

VideoGrace использует WebSocket для трех разных каналов. Формально это один endpoint сервера, но смысл соединения задается connect_request.channel_type.

ChannelType	Значение	Формат frames	Назначение
`CommandLoop`	`0`	text JSON	Логин, конференции, устройства, звонки, сообщения.
`WSMedia`	`1`	text JSON на логине, затем binary WSM media frames	RTP/RTCP media.
`BlobChannel`	`2`	text JSON на логине, затем binary WSM blob frames	Файлы, изображения, voice blobs, speed-test.

ClientType:

ClientType	Значение	Назначение
`Ordinal`	`0`	Обычный пользовательский клиент или простой сервис, публикующий media.
`MediaProcessor`	`1`	Media-processing service.
`Connector`	`2`	Интеграционный коннектор.
`Recorder`	`3`	Сервис записи.

Клиент открывает ws://host:port или wss://host:port и первым сообщением отправляет JSON:

{
  "connect_request": {
    "client_type": 0,
    "channel_type": 0,
    "client_version": 100,
    "system": "Web",
    "login": "user@example.com",
    "password": "secret"
  }
}

Ответ:

{
  "connect_response": {
    "result": 1,
    "server_version": 100,
    "id": 223900001,
    "connection_id": 1,
    "access_token": "opaque-token",
    "name": "User",
    "secure_key": "base64-or-empty",
    "server_name": "VideoGrace",
    "options": 0,
    "grants": 0,
    "max_output_bitrate": 4096
  }
}

result=1 означает OK. Остальные значения описаны в Engine/Proto/CmdConnectResponse.h.

sequenceDiagram
    participant Client
    participant WS as CommandLoop WS
    participant Server

    Client->>WS: open ws/wss
    Client->>Server: connect_request(channel_type=0, login, password)
    Server-->>Client: connect_response(result=OK, access_token)
    Server-->>Client: conferences_list / contact_list / group_list

Дополнительные каналы по access_token

WSMedia и BlobChannel не передают логин/пароль. Они используют token из CommandLoop.

{
  "connect_request": {
    "channel_type": 1,
    "access_token": "opaque-token"
  }
}

Для BlobChannel используется channel_type: 2.

Основной control lifecycle конференции

sequenceDiagram
    participant Client
    participant Server
    participant Others as Other members

    Client->>Server: connect_to_conference_request(tag, connect_members, has_camera, has_microphone)
    Server-->>Client: change_member_state(existing members)
    Server-->>Client: connect_to_conference_response(result=OK)
    Server-->>Client: device_connect(existing remote devices)
    Server-->>Others: change_member_state(new member)

Пример:

{
  "connect_to_conference_request": {
    "tag": "default",
    "connect_members": 1,
    "has_camera": 1,
    "has_microphone": 1
  }
}

Создание локального устройства

Публикация mic/cam/screen начинается в control plane:

{
  "device_params": {
    "id": 0,
    "ssrc": 0,
    "device_type": 1,
    "ord": 0,
    "name": "Camera",
    "metadata": "",
    "resolution": 31457920,
    "color_space": 0
  }
}

Сервер отвечает device_connect для автора и рассылает remote device_connect другим участникам:

{
  "device_connect": {
    "connect_type": 1,
    "device_type": 1,
    "device_id": 1001,
    "client_id": 223900001,
    "metadata": "",
    "receiver_ssrc": 0,
    "author_ssrc": 1208,
    "address": "",
    "port": 5061,
    "name": "Camera",
    "resolution": 31457920,
    "color_space": 0,
    "video_codec": 0,
    "audio_codec": 0,
    "my": 1,
    "secure_key": "..."
  }
}

DeviceType:

DeviceType	Значение
`Camera`	`1`
`Demonstration`	`2`
`Avatar`	`3`
`Microphone`	`4`
`VideoRenderer`	`5`
`AudioRenderer`	`6`

ConnectType:

ConnectType	Значение
`CreatedDevice`	`1`
`ConnectRenderer`	`2`

Media over WSMedia

После connect_response на WSMedia клиент отправляет binary frames:

packet-beta
    0-7: "msg_type=1"
    8-15: "flags=0"
    16-47: "ssrc"
    48-63: "port"
    64-79: "media_type"
    80-127: "RTP/RTCP payload..."

Правила:

ssrc выбирает media route внутри WSMServer;
port указывает порт внутреннего media translator;
media_type=1 для RTP, media_type=2 для RTCP;
RTP payload types в текущем browser path: VP8 96, Opus 111; H.264 должен стать предпочтительным video codec для mobile/native compatibility;
один WSMedia может переносить много SSRC.

RequestMediaAddresses

Native клиенты и тестеры могут запросить media адреса:

{ "request_media_addresses": {} }

Ответ содержит rtp://host:port адреса translator pool и ws://host:port fallback endpoint.

Ошибки и reconnect

Ситуация	Ожидаемое поведение
Control WS закрыт	Клиент теряет источник state, должен перелогиниться и пересобрать конференцию.
WSMedia закрыт	Media transport reconnect, затем повтор RTP init/ForceKeyFrame по зарегистрированным SSRC.
BlobChannel закрыт	Reconnect/retry конкретной blob операции.
`device_disconnect`	Удалить устройство и SSRC handler, но не закрывать общий media transport.