@livedigital/client 3.56.1 → 3.57.0-lk-5354-api-reference.1

package/dist/types/media.d.ts

@@ -36,34 +36,59 @@ export interface BaseTrackParams {
     mediaStreamTrack: MediaStreamTrack;
     constraints: MediaStreamConstraints;
 }
+/**
+ * Базовый контракт локального трека, которым управляет SDK.
+ *
+ * Через него приложение может публиковать медиа, ставить его на паузу,
+ * получать техническую статистику и отслеживать состояние публикации.
+ */
 export interface BaseTrack {
+    /** Набор событий трека, на которые можно подписаться из приложения. */
     observer: EnhancedEventEmitter;
     mediaStreamTrack: MediaStreamTrack;
     id: string;
     kind: MediaKind;
+    /** Показывает, опубликован ли трек в канале прямо сейчас. */
     isPublished: boolean;
+    /** Показывает, находится ли трек в paused-состоянии. */
     isPaused: boolean;
     internalEventEmitter: EnhancedEventEmitter<InternalObserverEvents>;
     producerId?: string;
     videoWebRTCStats?: ParsedOutboundVideoStreamStats;
     audioWebRTCStats?: ParsedOutboundAudioStreamStats;
+    /** Текущие MOS-оценки качества для этого трека. */
     connectionScores: MOSScores;
     getLabel: () => TrackLabel;
     setLabel: (label: TrackLabel) => void;
     setEncoderConfig: (encoderConfig: EncoderConfig) => void;
     getEncoderConfig: () => EncoderConfig;
     setProducer: (producer: Producer) => void;
+    /** Управляет тем, будет ли исходный `MediaStreamTrack` остановлен при паузе или закрытии публикации. */
     setStopTrackOnPause: (value: boolean) => void;
     getProducer: () => Producer | undefined;
+    /** Явно останавливает исходный `MediaStreamTrack`, если приложению нужно освободить устройство. */
     stopMediaStreamTrack: () => void;
+    /** Закрывает producer, связанный с треком, без удаления самого объекта трека. */
     closeProducer: (stopTrack?: boolean) => Promise<void>;
+    /** Меняет сетевой приоритет отправки этого трека. */
     setPriority: (priority: RTCPriorityType) => Promise<void>;
+    /**
+     * Низкоуровневый вариант публикации трека с явным контролем параметров кодирования.
+     *
+     * В большинстве сценариев приложению достаточно вызывать `publish()`.
+     */
     produce: ({ encodings, codecOptions, preferredCodec, transformParams, keyFrameRequestDelay, }: TrackProduceParams) => Promise<void>;
+    /** Публикует трек в канале, чтобы он стал доступен другим участникам. */
     publish: () => Promise<void>;
+    /** Снимает трек с публикации. */
     unpublish: (stopTrack?: boolean) => Promise<void>;
+    /** Возобновляет передачу трека после паузы. */
     resume: () => Promise<void>;
+    /** Возвращает сводную информацию о треке в формате, удобном для UI и отладки. */
     getInfo: () => Promise<BaseTrackInfo>;
+    /** Возвращает техническую WebRTC-статистику опубликованного трека. */
     getStats: () => Promise<TrackOutboundStats | undefined>;
+    /** Подменяет исходный `MediaStreamTrack` без пересоздания всего объекта трека. */
     replaceTrack: (track: MediaStreamTrack) => Promise<void>;
 }
 export interface TrackWithEncodings extends BaseTrack {
@@ -74,29 +99,58 @@ export interface TrackWithEncodings extends BaseTrack {
 export interface TrackWithEffects extends BaseTrack {
     isEffectsProcessing: boolean;
 }
+/**
+ * Публичный контракт локального аудиотрека.
+ */
 export interface AudioTrack extends BaseTrack, TrackWithEncodings, TrackWithEffects {
+    /** Подключает пользовательский процессор аудиотрека перед публикацией. */
     setTrackProcessor: (trackProcessor?: AudioTrackProcessor) => void;
+    /** Убирает ранее установленный пользовательский процессор аудио. */
     unsetTrackProcessor: () => void;
+    /** Включает шумоподавление для текущего микрофонного трека. */
     enableNoiseSuppression: () => Promise<void>;
+    /** Отключает шумоподавление для текущего микрофонного трека. */
     disableNoiseSuppression: () => Promise<void>;
+    /** Ставит аудиотрек на паузу без его удаления из SDK. */
     pause: () => Promise<void>;
 }
+/**
+ * Дополнительные параметры публикации видеотрека.
+ */
 export interface VideoTrackPublishParams {
+    /** Задержка перед запросом key frame после публикации или перепубликации трека. */
     keyFrameRequestDelay?: number;
 }
+/**
+ * Публичный контракт локального видеотрека.
+ */
 export interface VideoTrack extends BaseTrack, TrackWithEncodings, TrackWithEffects {
+    /** Публикует видеотрек с дополнительными параметрами управления key frame. */
     publish: (params?: VideoTrackPublishParams) => Promise<void>;
+    /** Обновляет прикладные параметры трансформации видео, например ожидаемый размер кадра. */
     setTransformParams: (transformParams: object) => void;
+    /** Ограничивает максимальный spatial layer для опубликованного видео. */
     setMaxSpatialLayer: (spatialLayer: number) => Promise<void>;
+    /** Возвращает текущий верхний spatial layer, доступный для публикации. */
     getMaxSpatialLayer: () => number | undefined;
+    /** Включает движок видеоэффектов для трека. */
     enableEffects: () => Promise<void>;
+    /** Отключает ранее включённые видеоэффекты. */
     disableEffects: () => Promise<void>;
+    /** Применяет набор визуальных эффектов к текущему видеотреку. */
     applyEffects: (effects: Effects) => Promise<void>;
+    /** Сбрасывает текущие визуальные эффекты к исходному состоянию. */
     resetEffects: () => void;
+    /** Регистрирует callback, который будет вызван после загрузки моделей движка эффектов. */
     setOnLoadModels: (callback: () => void) => void;
+    /** Прогресс загрузки моделей эффекторного движка от `0` до `1`. */
     modelsLoadProgress: number;
+    /** Ставит видеотрек на паузу без его удаления из SDK. */
     pause: () => Promise<void>;
 }
+/**
+ * Универсальный тип локального трека, который может быть аудио- или видеотреком.
+ */
 export type Track = AudioTrack | VideoTrack;
 export type AudioTrackParams = BaseTrackParams;
 export interface MediaTracksFactory {
@@ -114,10 +168,21 @@ export type ProducerAppData = AppData & {
     codec?: RtpCodecCapability;
     keyFrameRequestDelay?: number;
 };
+/**
+ * Параметры предварительной инициализации SDK видеоэффектов.
+ *
+ * Используются, когда приложение хочет подготовить blur, background replacement
+ * и другие эффекты заранее, до первого вызова `videoTrack.enableEffects()`.
+ */
 export interface InitEffectsSDKParams {
+    /** Идентификатор клиента, выданный провайдером эффекторного SDK. */
     customerId?: string;
+    /** Явный URL JavaScript-ресурсов эффекторного SDK. */
     sdk_url?: string;
+    /** Явный URL API эффекторного SDK. */
     api_url?: string;
+    /** Локальный каталог, из которого приложение раздаёт модели и WASM-ресурсы. */
     localDir?: string;
+    /** Версия пакета моделей и runtime-компонентов, которую нужно использовать. */
     version?: string;
 }

package/dist/types/network.d.ts

@@ -1,6 +1,14 @@
 import type { NETWORK_OBSERVER_EVENTS } from '../constants/events';
 export type ExtendedRTCPeerConnectionState = RTCPeerConnectionState | 'reconnected';
 export type TransportDirection = 'send' | 'recv';
+/**
+ * Политика выбора ICE-маршрутов для WebRTC-соединений.
+ *
+ * Значение `all` разрешает использовать все доступные candidate'ы, а `relay`
+ * помогает принудительно уйти в TURN-сценарий, если это требуется для отладки
+ * или обхода сетевых ограничений.
+ */
+export type IceTransportPolicy = 'all' | 'relay';
 export interface TransportStatePayload {
     state: ExtendedRTCPeerConnectionState;
     direction: TransportDirection;

package/dist/types/peerConsumer.d.ts

@@ -0,0 +1,36 @@
+import type { ConsumerData, SpatialLayerParams, TrackInboundStats } from './common';
+/**
+ * Публичная форма consumer-объекта, связанного с удалённым треком.
+ *
+ * SDK создаёт и обновляет consumer самостоятельно, а приложение может читать
+ * его текущее состояние и вызывать публичные операции управления подпиской.
+ */
+export interface PeerConsumer {
+    readonly id: string;
+    readonly kind: 'audio' | 'video';
+    readonly producerId: string;
+    readonly appData: ConsumerData;
+    readonly paused: boolean;
+    readonly isVideo: boolean;
+    readonly isAudio: boolean;
+    readonly spatialLayers: number;
+    readonly temporalLayers: number;
+    readonly currentSpatialLayer: number;
+    readonly currentTemporalLayer: number;
+    readonly requestedSpatialLayer?: number;
+    readonly currentMaxSpatialLayer: number;
+    readonly availableSpatialLayers: SpatialLayerParams[];
+    readonly currentSpatialLayerParams?: SpatialLayerParams;
+    pause: () => void;
+    resume: () => void;
+    close: () => void;
+    setCurrentSpatialLayer: (currentSpatialLayer: number) => void;
+    setCurrentTemporalLayer: (currentTemporalLayer: number) => void;
+    applyLayersUpdate: (payload: {
+        spatialLayer?: number;
+        temporalLayer?: number;
+    }) => void;
+    setRequestedSpatialLayer: (spatialLayer: number | undefined) => void;
+    setCurrentMaxSpatialLayer: (spatialLayer: number) => void;
+    getStats: () => Promise<TrackInboundStats | undefined>;
+}

package/dist/types/peerTrack.d.ts

@@ -0,0 +1,52 @@
+import type { ParsedInboundAudioStreamStats, ParsedInboundVideoStreamStats } from 'webrtc-issue-detector';
+import type EnhancedEventEmitter from '../EnhancedEventEmitter';
+import type { MOSScores } from '../qoe/types';
+import type { PeerTrackInfo, PreferredLayersParams, SpatialLayerParams, TrackLabel } from './common';
+import type { PeerConsumer } from './peerConsumer';
+/**
+ * Карта событий удалённого трека, доступная через `peerTrack.observer`.
+ */
+export interface PeerTrackObserverEvents {
+    'track-start': [PeerTrack];
+    'track-end': [PeerTrack];
+    'track-failed': [PeerTrack];
+    'track-paused': [PeerTrack];
+    'track-resumed': [PeerTrack];
+    'volume-changed': [{
+        value: number;
+    }];
+}
+/**
+ * Публичная форма удалённого трека, который SDK возвращает через `peer.tracks`.
+ *
+ * Экземпляры создаются и управляются самим SDK, а приложение получает их для
+ * управления удалённым медиа, чтения статистики и подписки на события трека.
+ */
+export interface PeerTrack {
+    readonly label: TrackLabel;
+    readonly observer: EnhancedEventEmitter<PeerTrackObserverEvents>;
+    readonly mediaStreamTrack: MediaStreamTrack;
+    readonly kind: 'audio' | 'video';
+    readonly isPaused: boolean;
+    readonly isMuted: boolean;
+    readonly isRemote: boolean;
+    readonly consumerId?: string;
+    readonly currentSpatialLayer: number;
+    readonly volume: number;
+    readonly connectionScores: MOSScores;
+    readonly audioWebRTCStats?: ParsedInboundAudioStreamStats;
+    readonly videoWebRTCStats?: ParsedInboundVideoStreamStats;
+    close: (params?: {
+        closeRemote?: boolean;
+    }) => Promise<void>;
+    mute: () => Promise<void>;
+    unmute: () => Promise<void>;
+    pause: (pauseRemote?: boolean) => Promise<void>;
+    resume: (resumeRemote?: boolean) => Promise<void>;
+    requestVideoPreferredLayers: (params: PreferredLayersParams) => Promise<void>;
+    requestKeyFrame: () => Promise<void>;
+    getVideoAvailableLayers: () => SpatialLayerParams[] | undefined;
+    getInfo: () => Promise<PeerTrackInfo>;
+    readonly consumer: PeerConsumer | undefined;
+    setVolume: (value: number) => void;
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@livedigital/client",
   "author": "vlprojects",
   "license": "MIT",
-  "version": "3.56.1",
+  "version": "3.57.0-lk-5354-api-reference.1",
   "private": false,
   "bugs": {
     "url": "https://github.com/vlprojects/livedigital-sdk/issues"
@@ -25,6 +25,10 @@
     "build-proto": "sh ./build-proto.sh",
     "build": "yarn build-proto && yarn generate-signaling-client && rm -rf dist && rollup -c && tsc --importHelpers && cp src/constants/* dist/constants/",
     "generate-signaling-client": "swagger-typescript-api -p ./api/openapi.yaml -o ./src/engine/signalingApiClient -n api.ts --union-enums --axios --route-types",
+    "api:check": "api-extractor run --config ./api-extractor.json --typescript-compiler-folder ./node_modules/typescript",
+    "api:update": "api-extractor run --local --config ./api-extractor.json --typescript-compiler-folder ./node_modules/typescript",
+    "docs:api": "typedoc --options typedoc.json",
+    "docs:sync": "yarn build && yarn api:update && yarn docs:api",
     "watch": "rollup -c --sourcemap inline --watch --watch.onEnd='tsc --importHelpers && tsc --importHelpers && cp src/constants/* dist/constants/'",
     "lint": "eslint",
     "test": "NODE_ENV=test mocha --config test/utils/runners/mocha/.mocharc.js"
@@ -65,6 +69,7 @@
     "@rollup/plugin-node-resolve": "^13.0.0",
     "@rollup/plugin-replace": "^3.0.0",
     "@rollup/plugin-typescript": "^12.1.2",
+    "@microsoft/api-extractor": "^7.52.13",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.2",
@@ -114,6 +119,9 @@
     "ts-node": "^10.4.0",
     "ts-proto": "^2.7.5",
     "tslib": "^2.3.1",
+    "typedoc": "^0.28.12",
+    "typedoc-docusaurus-theme": "^1.4.2",
+    "typedoc-plugin-markdown": "^4.8.1",
     "typescript": "^5.8.3"
   }
 }