@livedigital/client 3.62.1 → 3.63.0-lk-7808-network-quality.1

package/dist/Client.d.ts

@@ -2,6 +2,7 @@ import 'reflect-metadata';
 import type { ClientMetaPayload } from './ClientMetaProvider';
 import type Peer from './engine/Peer';
 import type { TransportsWebRTCStats } from './engine/WebRTCStats/types';
+import type { NetworkQuality } from './qoe/networkQuality.types';
 import EnhancedEventEmitter from './EnhancedEventEmitter';
 import type { ClientParams } from './types/client';
 import type { AvailableMediaDevices, CreateCameraVideoTrackOptions, CreateCustomAudioOptions, CreateCustomVideoOptions, CreateMicrophoneAudioTrackOptions, CreateScreenMediaOptions, JoinChannelParams, TransportsStateInfo } from './types/common';
@@ -250,6 +251,17 @@ declare class Client {
      * @group Диагностика
      */
     restartIce(): Promise<void>;
+    /**
+     * Состояние своей сети и устройства по отдельности: приём, отдача, ресурсы
+     * устройства. В отличие от MOS-оценок отвечает на вопрос «на чьей стороне
+     * проблема», а не «насколько плохо выглядит поток».
+     *
+     * Снимок на момент вызова; об изменениях уровня сообщает событие
+     * `network-quality-updated` через `client.observer`. При `disableWid: true`
+     * статистика не собирается, и сетевые направления остаются в `unknown`.
+     * @group Диагностика
+     */
+    networkQuality(): NetworkQuality;
     /**
      * Возвращает агрегированную транспортную статистику WebRTC для мониторинга качества соединения.
      * @group Диагностика

package/dist/constants/events.d.ts

@@ -48,6 +48,7 @@ export declare const CLIENT_EVENTS: {
     readonly effectsDisabled: "effects-disabled";
     readonly effectsFailed: "effects-failed";
     readonly networkScoresUpdated: "network-scores-updated";
+    readonly networkQualityUpdated: "network-quality-updated";
 };
 export declare const TRACK_EVENTS: {
     readonly volumeChanged: "volume-changed";

package/dist/constants/events.ts

@@ -49,6 +49,7 @@ export const CLIENT_EVENTS = {
   effectsDisabled: 'effects-disabled',
   effectsFailed: 'effects-failed',
   networkScoresUpdated: 'network-scores-updated',
+  networkQualityUpdated: 'network-quality-updated',
 } as const;
 
 export const TRACK_EVENTS = {

package/dist/engine/WebRTCStats/NetworkQualityMonitor.d.ts

@@ -0,0 +1,61 @@
+import type { StatsReportItem } from 'webrtc-issue-detector';
+import { DevicePressureMonitor } from '../../qoe/DevicePressureMonitor';
+import { NetworkQualityCalculator } from '../../qoe/NetworkQualityCalculator';
+import { NetworkQuality } from '../../qoe/networkQuality.types';
+export interface NetworkQualityMonitorParams {
+    /** Идентификаторы транспортов: по ним отчёты разводятся по направлениям. */
+    sendTransportId: string;
+    receiveTransportId: string;
+    /** Интервал сбора статистики: от него считается порог протухания трафика. */
+    statsIntervalMs: number;
+    /** Вызывается после гистерезиса, а не на каждый тик статистики. */
+    onLevelChange?: (quality: NetworkQuality) => void;
+    /** Единый источник времени: тесты управляют им целиком. */
+    now?: () => number;
+}
+/**
+ * Считает состояние своей сети и устройства по потоку WebRTC-статистики.
+ *
+ * Отвечает за всё, что зависит от времени: приращения счётчиков, гистерезис
+ * и уход в `unknown` при отсутствии трафика. Формула «метрики → уровень»
+ * живёт в {@link NetworkQualityCalculator} и состояния не имеет.
+ *
+ * Отчёты приходят по одному на каждый `RTCPeerConnection`, а у mediasoup их два:
+ * отправляющий и принимающий. Складывать их нельзя — получится ровно та же
+ * смесь своего и чужого, ради ухода от которой всё и затевалось.
+ */
+export default class NetworkQualityMonitor {
+    #private;
+    private readonly calculator;
+    private readonly devicePressure;
+    constructor(calculator: NetworkQualityCalculator, devicePressure: DevicePressureMonitor);
+    init({ sendTransportId, receiveTransportId, statsIntervalMs, onLevelChange, now, }: NetworkQualityMonitorParams): void;
+    clear(): void;
+    get quality(): NetworkQuality;
+    /** Вызывается из {@link StatsHandler} на каждый отчёт. */
+    handleReport({ id, stats }: StatsReportItem): void;
+    private resolveReportDirection;
+    private applySample;
+    /**
+     * Асимметричный гистерезис: ухудшение подтверждается быстро, улучшение —
+     * долго. Так значок не мигает на одном плохом тике и не возвращается
+     * в зелёное от случайной паузы в потерях.
+     */
+    private updateShownLevel;
+    /**
+     * Единственная точка оповещения: событие уходит только на реальную смену
+     * уровней. Отчёт приходит на каждый транспорт отдельно, так что за один тик
+     * статистики событий может быть два.
+     *
+     * Если поток отчётов встанет совсем, протухание заметит только геттер:
+     * таймеров ради событий без входящих данных мы не заводим.
+     */
+    private notifyIfChanged;
+    private resolveDirection;
+    /**
+     * Устройство: показание Compute Pressure API, а где его нет — догадка по
+     * метрикам отдачи. Потребитель эти два случая не различает; если разница
+     * понадобится, её придётся вынести в отдельное поле.
+     */
+    private resolveDevice;
+}

package/dist/engine/WebRTCStats/StatsHandler.d.ts

@@ -3,6 +3,8 @@ import type { ParsedInboundAudioStreamCompositeStats, ParsedInboundVideoStreamCo
 export default class StatsHandler {
     #private;
     handle(payload: StatsReportItem[]): void;
+    addAggregateHandler(handler: (report: StatsReportItem) => void): void;
+    removeAggregateHandler(handler: (report: StatsReportItem) => void): void;
     addConnectionHandler(id: string, handler: (stats: ParsedConnectionStats) => void): void;
     addInboundVideoHandler(id: string, handler: (stats: ParsedInboundVideoStreamCompositeStats) => void): void;
     addInboundAudioHandler(id: string, handler: (stats: ParsedInboundAudioStreamCompositeStats) => void): void;

package/dist/engine/WebRTCStats/TransportsStatsProvider.d.ts

@@ -1,10 +1,21 @@
 import { TransportsStatsProviderParams, TransportsWebRTCStats } from './types';
+import type ConfigService from '../../config/ConfigService';
 import type { LoggerFactory } from '../../types/container';
 import type { ScoresCalculator } from '../../qoe/ScoresCalculator';
+import NetworkQualityMonitor from './NetworkQualityMonitor';
+import StatsHandler from './StatsHandler';
+import EnhancedEventEmitter from '../../EnhancedEventEmitter';
+import type { ClientObserverEvents } from '../../types/engine';
+import type { NetworkQuality } from '../../qoe/networkQuality.types';
 export default class TransportsStatsProvider {
     #private;
-    constructor(loggerFactory: LoggerFactory, scoresCalculator: ScoresCalculator);
-    init({ sendTransportConnectionManager, receiveTransportConnectionManager, media, peers, }: TransportsStatsProviderParams): void;
+    private readonly networkQualityMonitor;
+    private readonly statsHandler;
+    private readonly clientEventEmitter;
+    private readonly config;
+    constructor(loggerFactory: LoggerFactory, scoresCalculator: ScoresCalculator, networkQualityMonitor: NetworkQualityMonitor, statsHandler: StatsHandler, clientEventEmitter: EnhancedEventEmitter<ClientObserverEvents>, config: ConfigService);
+    init({ sendTransportConnectionManager, receiveTransportConnectionManager, sendTransportId, receiveTransportId, media, peers, }: TransportsStatsProviderParams): void;
+    get networkQuality(): NetworkQuality;
     getStats(): TransportsWebRTCStats;
     clear(): void;
     private doGetStats;

package/dist/engine/WebRTCStats/types.d.ts

@@ -5,6 +5,8 @@ import type ConnectionStatManager from './ConnectionStatsManager';
 export interface TransportsStatsProviderParams {
     sendTransportConnectionManager: ConnectionStatManager;
     receiveTransportConnectionManager: ConnectionStatManager;
+    sendTransportId: string;
+    receiveTransportId: string;
     media: Media;
     peers: IPeersService;
 }

package/dist/engine/index.d.ts

@@ -25,6 +25,7 @@ import SignalingApiClient from './signalingApiClient/SignalingApiClient';
 import System from './system';
 import StatsHandler from './WebRTCStats/StatsHandler';
 import TransportsStatsProvider from './WebRTCStats/TransportsStatsProvider';
+import type { NetworkQuality } from '../qoe/networkQuality.types';
 import { TransportsWebRTCStats } from './WebRTCStats/types';
 import PeersStorage from './PeersStorage';
 import { ScoresCalculator } from '../qoe/ScoresCalculator';
@@ -76,6 +77,7 @@ declare class Engine {
     createCustomVideoTrack(options: CreateCustomVideoOptions): Promise<Track>;
     deleteTrack(tracks: BaseTrack): Promise<void>;
     transportsStats(): TransportsWebRTCStats | undefined;
+    networkQuality(): NetworkQuality;
     setSignalingServerUrl(url: string): void;
     private cleanup;
     private watchInternalEvents;

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { default as EnhancedEventEmitter } from './EnhancedEventEmitter';
 export { default as Peer } from './engine/Peer';
 export { default as PeerProducer } from './engine/PeerProducer';
 export { ScoresCalculator } from './qoe/ScoresCalculator';
+export { NetworkQualityDirection, NetworkQualityLevel, NetworkQualityReason, } from './qoe/networkQuality.types';
+export type { DirectionQuality, NetworkQuality, } from './qoe/networkQuality.types';
 export type { ClientMetaPayload } from './ClientMetaProvider';
 export type { PeerObserverEvents } from './engine/Peer';
 export type { TransportsWebRTCStats, LDTransportWebRTCStats } from './engine/WebRTCStats/types';