@livedigital/client 3.60.0 → 3.61.0-encoded-screenshare.1

package/dist/Client.d.ts

@@ -190,7 +190,7 @@ declare class Client {
      * Регистрирует в SDK уже созданный приложением видеотрек, чтобы им можно было управлять и публиковать его.
      * @group Медиа
      */
-    createCustomVideoTrack(options: CreateCustomVideoOptions): Track;
+    createCustomVideoTrack(options: CreateCustomVideoOptions): Promise<Track>;
     /**
      * Удаляет локальный трек из жизненного цикла SDK и освобождает связанные ресурсы.
      * @group Медиа

package/dist/engine/handlers/MediaEventHandler.d.ts

@@ -11,6 +11,7 @@ declare class MediaEventHandler {
     private readonly clientEventEmitter;
     constructor(media: Media, internalEventEmitter: EnhancedEventEmitter, peersStorage: PeersStorage, clientEventEmitter: EnhancedEventEmitter, loggerFactory: (namespace: string) => Logger);
     handleMediaEvent(event: MediaEvent): void;
+    private handleProducerKeyFrameRequested;
     private handleProducerCreated;
     private handleProducerClosed;
     private handleProducerPaused;

package/dist/engine/index.d.ts

@@ -73,7 +73,7 @@ declare class Engine {
     createMicrophoneAudioTrack(options?: CreateMicrophoneAudioTrackOptions): Promise<AudioTrack>;
     createScreenMediaTracks(options?: CreateScreenMediaOptions): Promise<Track[]>;
     createCustomAudioTrack(options: CreateCustomAudioOptions): AudioTrack;
-    createCustomVideoTrack(options: CreateCustomVideoOptions): Track;
+    createCustomVideoTrack(options: CreateCustomVideoOptions): Promise<Track>;
     deleteTrack(tracks: BaseTrack): Promise<void>;
     transportsStats(): TransportsWebRTCStats | undefined;
     setSignalingServerUrl(url: string): void;

package/dist/engine/media/encodedVideo/EncodedVideoSender.d.ts

@@ -0,0 +1,15 @@
+import type { EncodedVideoSenderParams, EncodedVideoStatsSnapshot } from './types';
+/**
+ * Producer-side of the encoded screen share: pulls raw frames from a MediaStreamTrack
+ * (MediaStreamTrackProcessor), encodes them with WebCodecs (VideoEncoder), frames them
+ * and sends them over a mediasoup DataProducer. The server reconstructs a normal RTP
+ * video producer from this stream — no encoder involved on the server.
+ */
+export declare class EncodedVideoSender {
+    #private;
+    constructor(params: EncodedVideoSenderParams);
+    start(): void;
+    requestKeyFrame(): void;
+    stop(): void;
+    getStatsSnapshot(): EncodedVideoStatsSnapshot;
+}

package/dist/engine/media/encodedVideo/EncodedVideoStats.d.ts

@@ -0,0 +1,8 @@
+import type { EncodedVideoStatsSnapshot } from './types';
+export declare class EncodedVideoStats {
+    #private;
+    frameSent(bytes: number, keyFrame: boolean): void;
+    frameDropped(): void;
+    frameShed(): void;
+    snapshot(bufferedAmount: number, readyBufferedAmount: number): EncodedVideoStatsSnapshot;
+}

package/dist/engine/media/encodedVideo/FreshnessGate.d.ts

@@ -0,0 +1,17 @@
+import type { FreshnessGateDecision } from './types';
+/**
+ * "Latest-frame-wins" admission control for the encoded stream. A frame is admitted to the SCTP channel
+ * only when the send queue has drained to ~one frame; otherwise it is already stale and dropped rather
+ * than queued, so the frame rate self-paces to the link and quality is never reduced. Dropping breaks the
+ * encoder's reference chain, so the next admitted frame must be a key frame to re-sync the consumer.
+ *
+ * Pure decision unit (no I/O), mirroring the server-side FrameSequencer.
+ */
+export declare class FreshnessGate {
+    #private;
+    constructor(readyBufferedAmount: number);
+    get chainBroken(): boolean;
+    decide(bufferedAmount: number, isKeyFrame: boolean): FreshnessGateDecision;
+    /** A key frame was actually sent → the decoder re-syncs, so the chain is healed. */
+    onKeyFrameSent(): void;
+}

package/dist/engine/media/encodedVideo/Vp8FrameEncoder.d.ts

@@ -0,0 +1,22 @@
+import type { Vp8FrameEncoderConfig } from './types';
+/**
+ * Thin wrapper around a WebCodecs VideoEncoder for the encoded screen share. Owns encoder creation and
+ * (re)configuration on a resolution change, and forwards output chunks. This is the only WebCodecs/codec
+ * coupling of the sender — the natural seam for a future Worker offload or a VP9/AV1 upgrade.
+ *
+ * Always VBR at the target bitrate: quality is fixed by design; only the frame rate adapts under
+ * backpressure (see FreshnessGate).
+ */
+export declare class Vp8FrameEncoder {
+    #private;
+    constructor(config: Vp8FrameEncoderConfig, onChunk: (chunk: EncodedVideoChunk) => void, onError: (error: unknown) => void);
+    get isConfigured(): boolean;
+    get width(): number;
+    get height(): number;
+    /**
+     * Encodes a frame, (re)configuring for its dimensions first. Returns true if it (re)configured — the
+     * first output after a configure is always a key frame, so the caller can resync its key-frame counter.
+     */
+    encode(frame: VideoFrame, keyFrame: boolean): boolean;
+    close(): void;
+}

package/dist/engine/media/encodedVideo/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const DEFAULT_BITRATE = 2500000;
+export declare const DEFAULT_FRAMERATE = 15;
+export declare const DEFAULT_READY_BUFFERED_AMOUNT = 65536;
+export declare const STATIC_IDLE_THRESHOLD_MS = 200;
+export declare const KEEPALIVE_INTERVAL_MS = 500;
+export declare const MICROSECONDS_PER_SECOND = 1000000;
+export declare const MICROSECONDS_PER_MS = 1000;
+export declare const MS_PER_SECOND = 1000;
+export declare const BITS_PER_BYTE = 8;
+export declare const RTP_TICKS_PER_US = 0.09;
+export declare const VP8_CODEC = "vp8";
+export declare const MIN_WINDOW_MS = 1;

package/dist/engine/media/encodedVideo/encodedVideoFraming.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Encoded-screenshare wire format (FROZEN v1).
+ *
+ * One encoded video frame (compressed codec bitstream, e.g. a VP8 frame from WebCodecs) is split
+ * into one or more SCTP messages. Each message carries a 14-byte big-endian header + a payload slice.
+ * Source of truth: docs/encoded-screenshare-design.md §5.1 (in livedigital-sdk). This module is
+ * duplicated VERBATIM across livedigital-sdk and livedigital-server (no shared TS package);
+ * keep both copies byte-identical and in sync with the design doc.
+ *
+ * Implementation uses Uint8Array + DataView only (no Node Buffer API) so the exact same code runs in
+ * the browser (SDK producer, packFrame) and in Node (server ingest, FrameReassembler).
+ *
+ * Header layout (big-endian):
+ *   0  u8   version = 1
+ *   1  u8   flags   (bit0 = keyframe)
+ *   2  u32  frameId
+ *   6  u32  rtpTimestamp90k
+ *   10 u16  fragIndex
+ *   12 u16  fragCount
+ *   14 ..   payload
+ */
+export declare const ENCODED_VIDEO_FRAMING_VERSION = 1;
+export declare const FRAME_HEADER_SIZE = 14;
+/**
+ * Conservative default SCTP message size (header + payload) for the packer. Well under the mediasoup
+ * router `maxMessageSize` (262144) and classic cross-browser data-channel limits. Tunable per call;
+ * the reassembler is agnostic to fragment size (it relies on fragIndex/fragCount).
+ */
+export declare const DEFAULT_MAX_MESSAGE_BYTES = 65536;
+export interface PackFrameInput {
+    frameId: number;
+    rtpTimestamp90k: number;
+    keyFrame: boolean;
+    /** Compressed codec bitstream for a single frame. */
+    data: Uint8Array;
+}
+export interface CompleteFrame {
+    frameId: number;
+    rtpTimestamp90k: number;
+    keyFrame: boolean;
+    data: Uint8Array;
+}
+/**
+ * Split one encoded frame into wire messages. Returns >= 1 Uint8Array messages, each ready to be sent
+ * over a DataProducer.
+ */
+export declare function packFrame(input: PackFrameInput, maxMessageBytes?: number): Uint8Array[];
+/**
+ * Reassembles wire messages back into complete encoded frames. Stateful (buffers multi-fragment
+ * frames). `push()` returns a CompleteFrame once all fragments of a frame have arrived, else null.
+ *
+ * Single-fragment frames are returned immediately (zero-copy: `data` aliases the input message's
+ * payload). Multi-fragment payloads are copied. `maxPending` bounds memory against never-completing
+ * frames (a lost fragment on an unreliable channel); on reliable-ordered SCTP it should stay ~1.
+ */
+export declare class FrameReassembler {
+    #private;
+    constructor(maxPending?: number);
+    push(message: Uint8Array): CompleteFrame | null;
+}

package/dist/engine/media/encodedVideo/types.d.ts

@@ -0,0 +1,51 @@
+import type { types } from 'mediasoup-client';
+/** Runtime tuning for the encoded-video sender; every field falls back to a default (see constants.ts). */
+export interface EncodedVideoSenderConfig {
+    bitrate?: number;
+    framerate?: number;
+    /** Freshness gate: admit a frame only when the send queue is at/below this many bytes (~one frame). */
+    readyBufferedAmount?: number;
+}
+export interface EncodedVideoSenderParams {
+    track: MediaStreamTrack;
+    dataProducer: types.DataProducer;
+    config?: EncodedVideoSenderConfig;
+    logger?: (message: string, context?: unknown) => void;
+}
+/**
+ * Minimal typed constructor for MediaStreamTrackProcessor: lib.dom's MediaStreamTrackProcessorInit is
+ * incomplete in this TS version (missing `track`), and this shape types `readable` as ReadableStream<VideoFrame>.
+ */
+export type VideoFrameProcessorCtor = new (init: {
+    track: MediaStreamTrack;
+}) => {
+    readable: ReadableStream<VideoFrame>;
+};
+export interface Vp8FrameEncoderConfig {
+    bitrate: number;
+    framerate: number;
+}
+export interface FreshnessGateDecision {
+    /** Admit this chunk to the data channel. */
+    send: boolean;
+    /** The caller must force the next encoded frame to be a key frame (the chain is broken). */
+    needKeyFrame: boolean;
+}
+export interface EncodedVideoStatsSnapshot {
+    /** Frames admitted to the channel, per second. */
+    fps: number;
+    /** Admitted bitrate — what the sender pushed into the queue, kbit/s. */
+    kbps: number;
+    /** Bytes that actually left the send queue, kbit/s — approximates the link throughput. */
+    wireKbps: number;
+    /** Key frames admitted this window. */
+    keyFrames: number;
+    /** Frames dropped by the frame-rate cap, per second. */
+    droppedFps: number;
+    /** Frames dropped by the freshness gate under backpressure, per second. */
+    sheddedFps: number;
+    /** The send queue is above the freshness threshold — the frame rate is being throttled. */
+    gated: boolean;
+    /** Current SCTP send-queue depth, bytes. */
+    bufferedAmount: number;
+}

package/dist/engine/media/index.d.ts

@@ -24,12 +24,13 @@ declare class Media {
     private readonly integrationsService;
     private readonly processorsCache;
     private readonly videoTrackFactory;
+    private readonly encodedVideoTrackFactory;
     private readonly mediaStreamTrackManager;
     private readonly signalingApiClient;
     isDeviceLoaded: boolean;
     private device?;
     private readonly tracks;
-    constructor(config: ConfigService, loggerFactory: (namespace: string) => Logger, audioTrackFactory: AudioTrackFactory, clientEventEmitter: EnhancedEventEmitter, integrationsService: IntegrationsService, processorsCache: ProcessorsCache, videoTrackFactory: VideoTrackFactory, mediaStreamTrackManager: MediaStreamTrackManager, signalingApiClient: SignalingApiClient);
+    constructor(config: ConfigService, loggerFactory: (namespace: string) => Logger, audioTrackFactory: AudioTrackFactory, clientEventEmitter: EnhancedEventEmitter, integrationsService: IntegrationsService, processorsCache: ProcessorsCache, videoTrackFactory: VideoTrackFactory, encodedVideoTrackFactory: VideoTrackFactory, mediaStreamTrackManager: MediaStreamTrackManager, signalingApiClient: SignalingApiClient);
     get mediasoupDevice(): Device;
     get effectsSDKInitialized(): boolean;
     get effectsSDKParams(): InitEffectsSDKParams | null;
@@ -38,8 +39,8 @@ declare class Media {
     getTrackCodec(track: TrackWithEncodings): types.RtpCodecCapability | undefined;
     private createTracks;
     createUserMediaTracks(constraints: MediaStreamConstraints): Promise<BaseTrack[]>;
-    createDisplayMediaTracks(constraints: MediaStreamConstraints): Promise<BaseTrack[]>;
-    createCustomMediaTrack(mediaStreamTrack: MediaStreamTrack, constraints: MediaStreamConstraints): BaseTrack;
+    createDisplayMediaTracks(constraints: MediaStreamConstraints, encoded?: boolean): Promise<BaseTrack[]>;
+    createCustomMediaTrack(mediaStreamTrack: MediaStreamTrack, constraints: MediaStreamConstraints, encoded?: boolean): BaseTrack;
     deleteTrack(track: BaseTrack): Promise<void>;
     getAllTracks(): BaseTrack[];
     publishedTracks(): BaseTrack[];

package/dist/engine/media/tracks/DefaultBaseTrack.d.ts

@@ -5,6 +5,7 @@ import { type BaseTrackInfo, type EncoderConfig, TrackLabel, type TrackLabelStri
 import type { InternalObserverEvents } from '../../../types/engine';
 import type { BaseTrack, BaseTrackDependenciesParams, BaseTrackParams, ProducerAppData } from '../../../types/media';
 import type Logger from '../../Logger';
+import type Network from '../../network';
 import type { MOSScores } from '../../../qoe/types';
 type BaseTrackConstructorParams = BaseTrackParams & BaseTrackDependenciesParams;
 export interface LoggerContext {
@@ -35,6 +36,7 @@ declare class DefaultBaseTrack implements BaseTrack {
     get isPublished(): boolean;
     get isPaused(): boolean;
     get internalEventEmitter(): EnhancedEventEmitter<InternalObserverEvents>;
+    protected get network(): Network;
     getLabel(): TrackLabel;
     setLabel(label: TrackLabel | TrackLabelString): void;
     setEncoderConfig(encoderConfig: EncoderConfig): void;

package/dist/engine/media/tracks/DefaultVideoTrack.d.ts

@@ -4,6 +4,7 @@ import { type VideoCodec, type VideoEncoderConfig } from '../../../types/common'
 import type { ClientObserverEvents } from '../../../types/engine';
 import type { BaseTrackDependenciesParams, BaseTrackParams, VideoTrack, VideoTrackPublishParams } from '../../../types/media';
 import type { Effects } from '../streamEffects/video/esdk/TrackProcessor';
+import type { EncodedVideoStatsSnapshot } from '../encodedVideo/types';
 import DefaultBaseTrack, { type LoggerContext } from './DefaultBaseTrack';
 export type VideoTrackDependenciesParams = BaseTrackDependenciesParams & {
     clientEventEmitter: EnhancedEventEmitter<ClientObserverEvents>;
@@ -26,6 +27,7 @@ declare class DefaultVideoTrack extends DefaultBaseTrack implements VideoTrack {
     setTransformParams(transformParams: object): void;
     setMaxSpatialLayer(spatialLayer: number): Promise<void>;
     getMaxSpatialLayer(): number | undefined;
+    getEncodedVideoStats(): EncodedVideoStatsSnapshot | undefined;
     enableEffects(): Promise<void>;
     disableEffects(restoreOriginalTrack?: boolean): Promise<void>;
     publish(params?: VideoTrackPublishParams): Promise<void>;

package/dist/engine/media/tracks/EncodedVideoTrack.d.ts

@@ -0,0 +1,24 @@
+import type { EncodedVideoStatsSnapshot } from '../encodedVideo/types';
+import DefaultVideoTrack from './DefaultVideoTrack';
+/**
+ * Screen-share video track produced via WebCodecs over a mediasoup DataProducer; the server reconstructs
+ * a normal RTP video producer from the frames. The DataProducer's id equals the server-returned
+ * reconstructed producer id, so it doubles as the producer id for pause/resume signaling and for matching
+ * the server's key-frame-request MediaEvent.
+ */
+export default class EncodedVideoTrack extends DefaultVideoTrack {
+    #private;
+    get producerId(): string | undefined;
+    get isPublished(): boolean;
+    get isPaused(): boolean;
+    publish(): Promise<void>;
+    stopMediaStreamTrack(): void;
+    unpublish(stopTrack?: boolean): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    requestKeyFrame(): void;
+    getEncodedVideoStats(): EncodedVideoStatsSnapshot | undefined;
+    getMaxSpatialLayer(): number | undefined;
+    setMaxSpatialLayer(): Promise<void>;
+    enableEffects(): Promise<void>;
+}

package/dist/engine/signalingApiClient/api.d.ts

@@ -177,7 +177,7 @@ export type TProducerAppData = AppData & {
 };
 export type TConsumerAppData = AppData & object;
 export type DataProducerLabels = "consumers-scores";
-export type PeerDataProducerLabels = "consumers-scores" | "channel-messages-data-producer" | "heart-beater";
+export type PeerDataProducerLabels = "consumers-scores" | "channel-messages-data-producer" | "heart-beater" | "encoded-video";
 export interface RTCIceServer {
     /** List of ICE server URLs (STUN/TURN). */
     urls: string[];

package/dist/helpers/media.d.ts

@@ -7,3 +7,4 @@ export declare const getSupportedCodecsMimeTypes: (device: Device) => string[];
 export declare const isVp9: (codecOrMimeType: string) => boolean;
 export declare const isG711Codec: (codec: AudioCodec) => codec is G711Codec;
 export declare const isTrackLabel: (value: unknown) => value is TrackLabel;
+export declare const supportsEncodedScreenShare: (codec?: string, width?: number, height?: number) => Promise<boolean>;

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { DeviceErrors, TrackLabel, } from './types/common';
 export type { ConsumerData, ActivityConfirmationRequiredPayload, AudioEncoderConfig, AvailableMediaDevices, BaseTrackInfo, MediaDeviceAvailability, MediaDeviceAvailabilityReason, ChannelEvent, CreateCameraVideoTrackOptions, CreateCustomAudioOptions, CreateCustomVideoOptions, CreateMicrophoneAudioTrackOptions, CreateScreenMediaOptions, EncoderConfig, InputKind, JoinChannelParams, PayloadOfPublishedMedia, PayloadOfUnpublishedMedia, ProducerData, PeerGroup, PeerInfo, PeerTrackInfo, Role, SubscribeOptions, TransformParams, TrackTransformParams, TrackForceClosedPayload, TrackInboundStats, TrackLabelString, TrackOutboundStats, TransportsStateInfo, VideoEncoderConfig, VideoCodec, PreferredLayersParams, SpatialLayerParams, } from './types/common';
 export type { ChannelStateInconsistentPayload, ClientObserverEvents, IssuesHandler, NetworkScoresUpdatedHandler, ProducePermissionsChangedPayload, } from './types/engine';
 export type { AudioTrack, BaseTrack, InitEffectsSDKParams, Track, VideoTrack, VideoTrackPublishParams, } from './types/media';
+export type { EncodedVideoStatsSnapshot } from './engine/media/encodedVideo/types';
 export type { IceTransportPolicy } from './types/network';
 export type { PeerConsumer } from './types/peerConsumer';
 export type { PeerTrack, PeerTrackObserverEvents } from './types/peerTrack';