sip-connector 16.1.0 → 17.0.0

package/README.md

@@ -9,37 +9,30 @@
 
 **sip-connector** — это TypeScript SDK для интеграции WebRTC-приложений с платформой Vinteo через SIP-протокол. Библиотека построена на базе `@krivega/jssip` и предоставляет высокоуровневый API для создания полнофункциональных видеоконференций.
 
-### 🚨 Breaking Changes в версии 16.0.0
-
-**Важные изменения, требующие обновления кода:**
+### 🎯 Основные возможности
 
-- **VideoSendingBalancer перенесен в SipConnector**: Теперь балансировка видео настраивается через конструктор `SipConnector` с параметром `videoBalancerOptions`
-- **Удален параметр `simulcastEncodings`**: Вместо него используется `sendEncodings` для настройки кодировок
-- **Автоматический запуск балансировки**: VideoSendingBalancer теперь автоматически запускается через 10 секунд после начала звонка
-- **Новые события балансировки**: Добавлены события `video-balancer:*` для мониторинга состояния балансировки
+SDK предоставляет комплексное решение для:
 
-### 🆕 Новые возможности версии 16.0.0
+| Категория                    | Возможности                                                                                                            |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **SIP-подключения**          | Регистрация на сервере (SIP REGISTER), управление сессиями                                                             |
+| **WebRTC-коммуникации**      | Исходящие/входящие звонки (SIP INVITE/200 OK), медиа-потоки, управление transceiver'ами, автоматический перезапуск ICE |
+| **Презентации**              | Отправка второго потока (screen sharing, демонстрация экрана)                                                          |
+| **Системные сообщения**      | DTMF, SIP INFO, синхронизация медиа-состояния                                                                          |
+| **Событийная архитектура**   | Подписка на события платформы в реальном времени                                                                       |
+| **Мониторинг**               | WebRTC-статистика (RTCRtpStats, ICE candidate stats)                                                                   |
+| **Управление конференциями** | Перемещение участников между ролями (участник/зритель)                                                                 |
+| **Лицензирование**           | Мониторинг использования лицензий и состояния презентаций                                                              |
 
 - **Адаптивный polling**: Улучшенная система опроса для мониторинга изменений видеотреков
 - **Поддержка maxBitrate в PresentationManager**: Автоматическое управление битрейтом для презентаций
 - **Предпочтительные кодеки в SipConnector**: Настройка приоритетов кодеков на уровне коннектора
 - **Обработка смены треков**: Автоматическая адаптация балансировки при изменении видеотреков
 - **Улучшенная статистика**: Расширенные возможности сбора и анализа WebRTC статистики
-
-### 🎯 Основные возможности
-
-SDK предоставляет комплексное решение для:
-
-| Категория                    | Возможности                                                   |
-| ---------------------------- | ------------------------------------------------------------- |
-| **SIP-подключения**          | Регистрация на сервере (SIP REGISTER), управление сессиями    |
-| **WebRTC-коммуникации**      | Исходящие/входящие звонки (SIP INVITE/200 OK), медиа-потоки   |
-| **Презентации**              | Отправка второго потока (screen sharing, демонстрация экрана) |
-| **Системные сообщения**      | DTMF, SIP INFO, синхронизация медиа-состояния                 |
-| **Событийная архитектура**   | Подписка на события платформы в реальном времени              |
-| **Мониторинг**               | WebRTC-статистика (RTCRtpStats, ICE candidate stats)          |
-| **Управление конференциями** | Перемещение участников между ролями (участник/зритель)        |
-| **Лицензирование**           | Мониторинг использования лицензий и состояния презентаций     |
+- **Автоматический перезапуск ICE**: Обработка событий `restart` от сервера с автоматическим вызовом `restartIce`
+- **Управление transceiver'ами**: Новый `TransceiverManager` для отслеживания и управления RTCRtpTransceiver'ами
+- **Автоматическое добавление transceiver'ов**: Умное добавление презентационных transceiver'ов при событиях restart
+  |
 
 ### 🏗️ Архитектура
 
@@ -66,23 +59,6 @@ yarn add sip-connector
 pnpm add sip-connector
 ```
 
-### 📋 Системные требования
-
-#### Обязательные зависимости
-
-| Компонент          | Требование           | Описание                       |
-| ------------------ | -------------------- | ------------------------------ |
-| `@krivega/jssip`   | peer dependency      | Для SIP-функциональности       |
-| WebRTC API         | Поддержка в браузере | Стандартные WebRTC возможности |
-| JavaScript runtime | ES2017+              | Современный синтаксис          |
-
-#### Рекомендуемые зависимости
-
-| Компонент  | Версия | Назначение          |
-| ---------- | ------ | ------------------- |
-| TypeScript | 4.5+   | Полная типизация    |
-| Node.js    | 16+    | Сборка и разработка |
-
 ---
 
 ## 🎯 Быстрый старт
@@ -369,6 +345,165 @@ try {
 }
 ```
 
+### Перезапуск ICE-соединения
+
+#### Ручной перезапуск
+
+```typescript
+// Перезапуск ICE для восстановления соединения
+try {
+  const success = await sipConnector.callManager.restartIce({
+    useUpdate: true, // Использовать SIP UPDATE вместо re-INVITE
+    extraHeaders: ['X-Restart-Reason: Connection-Reset'],
+    rtcOfferConstraints: {
+      offerToReceiveAudio: true,
+      offerToReceiveVideo: true,
+    },
+  });
+
+  if (success) {
+    console.log('ICE перезапущен успешно');
+  } else {
+    console.warn('Перезапуск ICE не удался');
+  }
+} catch (error) {
+  console.error('Ошибка перезапуска ICE:', error);
+}
+```
+
+#### Автоматический перезапуск по событию сервера
+
+SDK автоматически обрабатывает события `restart` от сервера и инициирует перезапуск ICE-соединения с интеллектуальным управлением transceiver'ами:
+
+```typescript
+// SDK автоматически подписывается на события restart от ApiManager
+// и выполняет следующие действия:
+// 1. Проверяет необходимость добавления презентационного transceiver'а
+// 2. Вызывает callManager.restartIce()
+
+// Мониторинг событий restart (опционально)
+sipConnector.on('api:restart', (data) => {
+  console.log('Получено событие restart от сервера:', {
+    tracksDirection: data.tracksDirection, // 'incoming', 'outgoing', 'bidirectional'
+    audioTrackCount: data.audioTrackCount,
+    videoTrackCount: data.videoTrackCount,
+  });
+
+  // SDK автоматически:
+  // - Добавит презентационный transceiver если videoTrackCount === 2
+  // - Вызовет restartIce()
+  console.log('ICE будет перезапущен автоматически');
+
+  if (data.videoTrackCount === 2) {
+    console.log('Может быть добавлен презентационный transceiver');
+  }
+});
+```
+
+### Параметры перезапуска ICE
+
+| Параметр                | Тип      | Описание                                 | По умолчанию |
+| ----------------------- | -------- | ---------------------------------------- | ------------ |
+| `useUpdate`             | boolean  | Использовать SIP UPDATE вместо re-INVITE | `false`      |
+| `extraHeaders`          | string[] | Дополнительные SIP заголовки             | `[]`         |
+| `rtcOfferConstraints`   | object   | Ограничения для создания SDP offer       | `{}`         |
+| `sendEncodings`         | array    | Параметры кодирования для видеопотока    | `[]`         |
+| `degradationPreference` | string   | Приоритет при ухудшении качества         | `undefined`  |
+
+---
+
+## 🎛️ Управление RTCRtpTransceiver'ами
+
+### Обзор TransceiverManager
+
+SDK автоматически отслеживает и управляет RTCRtpTransceiver'ами через новый класс `TransceiverManager`:
+
+```typescript
+// Получение текущих transceiver'ов
+const transceivers = sipConnector.callManager.getTransceivers();
+
+console.log('Основной аудио transceiver:', transceivers.mainAudio);
+console.log('Основной видео transceiver:', transceivers.mainVideo);
+console.log('Презентационный видео transceiver:', transceivers.presentationVideo);
+```
+
+### Типы transceiver'ов
+
+SDK автоматически классифицирует transceiver'ы по их `mid` значению:
+
+| Тип transceiver'а   | mid | Назначение                  |
+| ------------------- | --- | --------------------------- |
+| `mainAudio`         | '0' | Основной аудио поток        |
+| `mainVideo`         | '1' | Основной видео поток        |
+| `presentationVideo` | '2' | Презентационный видео поток |
+
+### Автоматическое добавление transceiver'ов
+
+При получении события `restart` с `videoTrackCount === 2`, SDK автоматически добавляет презентационный transceiver если он отсутствует:
+
+```typescript
+// SDK автоматически обрабатывает события restart
+sipConnector.on('api:restart', (data) => {
+  if (data.videoTrackCount === 2) {
+    // SDK проверит наличие presentationVideo transceiver'а
+    // и добавит его автоматически если необходимо
+    console.log('Будет добавлен презентационный transceiver');
+  }
+});
+```
+
+### Ручное управление transceiver'ами
+
+```typescript
+// Добавление нового transceiver'а
+try {
+  const audioTransceiver = await sipConnector.callManager.addTransceiver('audio', {
+    direction: 'sendrecv',
+  });
+
+  const videoTransceiver = await sipConnector.callManager.addTransceiver('video', {
+    direction: 'sendonly',
+    sendEncodings: [
+      { rid: 'low', maxBitrate: 500_000, scaleResolutionDownBy: 4 },
+      { rid: 'high', maxBitrate: 2_000_000, scaleResolutionDownBy: 1 },
+    ],
+  });
+
+  console.log('Transceiver'ы добавлены:', { audioTransceiver, videoTransceiver });
+} catch (error) {
+  console.error('Ошибка добавления transceiver'а:', error);
+}
+```
+
+### Мониторинг transceiver'ов
+
+```typescript
+// Проверка состояния transceiver'ов
+const checkTransceivers = () => {
+  const transceivers = sipConnector.callManager.getTransceivers();
+
+  console.log('Статус transceiver'ов:', {
+    hasAudio: transceivers.mainAudio !== undefined,
+    hasVideo: transceivers.mainVideo !== undefined,
+    hasPresentation: transceivers.presentationVideo !== undefined,
+  });
+
+  // Детальная информация
+  if (transceivers.mainVideo) {
+    console.log('Основное видео:', {
+      mid: transceivers.mainVideo.mid,
+      direction: transceivers.mainVideo.direction,
+      currentDirection: transceivers.mainVideo.currentDirection,
+    });
+  }
+};
+
+// Проверка после установки соединения
+sipConnector.on('call:confirmed', () => {
+  checkTransceivers();
+});
+```
+
 ---
 
 ## 📡 События и их обработка
@@ -381,7 +516,7 @@ SDK использует **событийно-ориентированную а
 | ------------------ | ------------------------ | ----------------------------------------- |
 | `connection:*`     | События подключения      | `connected`, `disconnected`               |
 | `call:*`           | События звонков          | `accepted`, `ended`, `failed`             |
-| `api:*`            | События от сервера       | `enterRoom`, `useLicense`                 |
+| `api:*`            | События от сервера       | `enterRoom`, `useLicense`, `restart`      |
 | `incoming-call:*`  | События входящих звонков | `incomingCall`                            |
 | `presentation:*`   | События презентаций      | `started`, `stopped`                      |
 | `stats:*`          | События статистики       | `collected`                               |
@@ -416,6 +551,10 @@ sipConnector.on('api:enterRoom', ({ room }) => {
 sipConnector.on('api:useLicense', (license) => {
   console.log('Лицензия:', license);
 });
+
+sipConnector.on('api:restart', (data) => {
+  console.log('Событие restart от сервера:', data);
+});
 ```
 
 ### Продвинутые паттерны
@@ -432,7 +571,7 @@ const roomData = await sipConnector.wait('api:enterRoom');
 console.log('Данные комнаты:', roomData);
 ```
 
-### События балансировки видео (версия 16.0.0+)
+### События балансировки видео
 
 ```typescript
 // Мониторинг автоматической балансировки видео
@@ -582,7 +721,7 @@ monitor.subscribe(videoSender, () => {
 
 ### Автоматическая балансировка
 
-С версии 16.0.0 `VideoSendingBalancer` интегрирован в `SipConnector` и запускается автоматически:
+`VideoSendingBalancer` интегрирован в `SipConnector` и запускается автоматически:
 
 ```typescript
 const sipConnector = new SipConnector(
@@ -650,7 +789,7 @@ await connectionQueueManager.register();
 await connectionQueueManager.checkTelephony(params);
 ```
 
-### Принцип работы
+### Механизм работы
 
 - **Очередь операций**: Использует `stack-promises` с `noRunIsNotActual: true`
 - **Предотвращение конфликтов**: Исключает одновременные connect/disconnect операции
@@ -691,10 +830,31 @@ import {
   SipConnector, // Низкоуровневый API
   SipConnectorFacade, // Высокоуровневый фасад
   StatsPeerConnection, // Сбор статистики
+  TransceiverManager, // Управление transceiver'ами
   // ... другие экспорты
 } from 'sip-connector';
 ```
 
+### Методы управления соединением
+
+```typescript
+// SipConnectorFacade методы
+const facade = new SipConnectorFacade(sipConnector);
+
+// Замена медиа-потока
+await facade.replaceMediaStream(mediaStream, options);
+
+// Получение удаленных потоков
+const streams = facade.getRemoteStreams();
+
+// Управление transceiver'ами (низкоуровневый API)
+const transceivers = sipConnector.callManager.getTransceivers();
+await sipConnector.callManager.addTransceiver('video', { direction: 'sendrecv' });
+
+// Перезапуск ICE-соединения (низкоуровневый API)
+await sipConnector.callManager.restartIce(options);
+```
+
 ### Утилиты и типы
 
 ```typescript
@@ -712,6 +872,8 @@ import {
   type TContentHint, // Подсказки для кодирования
   type TInboundStats, // Входящая статистика
   type TOutboundStats, // Исходящая статистика
+  type TRestartData, // Данные события restart
+  type ITransceiverStorage, // Интерфейс хранения transceiver'ов
 } from 'sip-connector';
 ```
 
@@ -768,6 +930,29 @@ try {
 }
 ```
 
+### Восстановление соединения
+
+```typescript
+// Мониторинг качества соединения
+facade.onStats(({ outbound, inbound }) => {
+  // Проверка качества соединения
+  if (outbound.packetsLost > 0.05) {
+    // 5% потерь пакетов
+    console.warn('Высокие потери пакетов, перезапуск ICE');
+
+    // Перезапуск ICE для восстановления соединения
+    sipConnector.callManager
+      .restartIce({
+        useUpdate: true,
+        extraHeaders: ['X-Restart-Reason: High-Packet-Loss'],
+      })
+      .catch((error) => {
+        console.error('Ошибка перезапуска ICE:', error);
+      });
+  }
+});
+```
+
 ### Управление ресурсами
 
 ```typescript
@@ -828,6 +1013,19 @@ console.log('Зарегистрирован:', facade.isRegistered);
 
 // Проверка конфигурации
 console.log('Настроен:', facade.isConfigured());
+
+// Диагностика ICE-соединения
+const checkIceConnection = async () => {
+  try {
+    const success = await sipConnector.callManager.restartIce({
+      useUpdate: true,
+      extraHeaders: ['X-Debug: ICE-Check'],
+    });
+    console.log('ICE соединение:', success ? 'OK' : 'Проблемы');
+  } catch (error) {
+    console.error('ICE недоступен:', error.message);
+  }
+};
 ```
 
 ---
@@ -884,6 +1082,11 @@ if (!navigator.mediaDevices?.getUserMedia) {
 if (!navigator.mediaDevices?.getDisplayMedia) {
   console.warn('Screen sharing не поддерживается');
 }
+
+// Проверка поддержки ICE restart
+if (!RTCPeerConnection.prototype.restartIce) {
+  console.warn('ICE restart не поддерживается в этом браузере');
+}
 ```
 
 ---