sip-connector 16.2.0 → 17.0.0

package/README.md

@@ -9,16 +9,20 @@
 
 **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**: Автоматическое управление битрейтом для презентаций
@@ -26,21 +30,9 @@
 - **Обработка смены треков**: Автоматическая адаптация балансировки при изменении видеотреков
 - **Улучшенная статистика**: Расширенные возможности сбора и анализа WebRTC статистики
 - **Автоматический перезапуск ICE**: Обработка событий `restart` от сервера с автоматическим вызовом `restartIce`
-
-### 🎯 Основные возможности
-
-SDK предоставляет комплексное решение для:
-
-| Категория                    | Возможности                                                                                |
-| ---------------------------- | ------------------------------------------------------------------------------------------ |
-| **SIP-подключения**          | Регистрация на сервере (SIP REGISTER), управление сессиями                                 |
-| **WebRTC-коммуникации**      | Исходящие/входящие звонки (SIP INVITE/200 OK), медиа-потоки, автоматический перезапуск ICE |
-| **Презентации**              | Отправка второго потока (screen sharing, демонстрация экрана)                              |
-| **Системные сообщения**      | DTMF, SIP INFO, синхронизация медиа-состояния                                              |
-| **Событийная архитектура**   | Подписка на события платформы в реальном времени                                           |
-| **Мониторинг**               | WebRTC-статистика (RTCRtpStats, ICE candidate stats)                                       |
-| **Управление конференциями** | Перемещение участников между ролями (участник/зритель)                                     |
-| **Лицензирование**           | Мониторинг использования лицензий и состояния презентаций                                  |
+- **Управление transceiver'ами**: Новый `TransceiverManager` для отслеживания и управления RTCRtpTransceiver'ами
+- **Автоматическое добавление transceiver'ов**: Умное добавление презентационных transceiver'ов при событиях restart
+  |
 
 ### 🏗️ Архитектура
 
@@ -67,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+    | Сборка и разработка |
-
 ---
 
 ## 🎯 Быстрый старт
@@ -398,11 +373,13 @@ try {
 
 #### Автоматический перезапуск по событию сервера
 
-SDK автоматически обрабатывает события `restart` от сервера и инициирует перезапуск ICE-соединения:
+SDK автоматически обрабатывает события `restart` от сервера и инициирует перезапуск ICE-соединения с интеллектуальным управлением transceiver'ами:
 
 ```typescript
 // SDK автоматически подписывается на события restart от ApiManager
-// и вызывает callManager.restartIce() при получении таких событий
+// и выполняет следующие действия:
+// 1. Проверяет необходимость добавления презентационного transceiver'а
+// 2. Вызывает callManager.restartIce()
 
 // Мониторинг событий restart (опционально)
 sipConnector.on('api:restart', (data) => {
@@ -412,8 +389,14 @@ sipConnector.on('api:restart', (data) => {
     videoTrackCount: data.videoTrackCount,
   });
 
-  // SDK автоматически вызовет restartIce()
+  // SDK автоматически:
+  // - Добавит презентационный transceiver если videoTrackCount === 2
+  // - Вызовет restartIce()
   console.log('ICE будет перезапущен автоматически');
+
+  if (data.videoTrackCount === 2) {
+    console.log('Может быть добавлен презентационный transceiver');
+  }
 });
 ```
 
@@ -429,6 +412,100 @@ sipConnector.on('api:restart', (data) => {
 
 ---
 
+## 🎛️ Управление 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();
+});
+```
+
+---
+
 ## 📡 События и их обработка
 
 ### Архитектура событий
@@ -494,7 +571,7 @@ const roomData = await sipConnector.wait('api:enterRoom');
 console.log('Данные комнаты:', roomData);
 ```
 
-### События балансировки видео (версия 16.0.0+)
+### События балансировки видео
 
 ```typescript
 // Мониторинг автоматической балансировки видео
@@ -644,7 +721,7 @@ monitor.subscribe(videoSender, () => {
 
 ### Автоматическая балансировка
 
-С версии 16.0.0 `VideoSendingBalancer` интегрирован в `SipConnector` и запускается автоматически:
+`VideoSendingBalancer` интегрирован в `SipConnector` и запускается автоматически:
 
 ```typescript
 const sipConnector = new SipConnector(
@@ -753,6 +830,7 @@ import {
   SipConnector, // Низкоуровневый API
   SipConnectorFacade, // Высокоуровневый фасад
   StatsPeerConnection, // Сбор статистики
+  TransceiverManager, // Управление transceiver'ами
   // ... другие экспорты
 } from 'sip-connector';
 ```
@@ -769,6 +847,10 @@ 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);
 ```
@@ -791,6 +873,7 @@ import {
   type TInboundStats, // Входящая статистика
   type TOutboundStats, // Исходящая статистика
   type TRestartData, // Данные события restart
+  type ITransceiverStorage, // Интерфейс хранения transceiver'ов
 } from 'sip-connector';
 ```