@agora-js/media 4.24.4 → 4.24.6

package/rtc-sdk-media_en.d.ts

@@ -1,12 +1,15 @@
 import { AgoraRTCError } from '@agora-js/shared';
+import type { AudioExtensionConstructor } from 'agora-rte-extension-ng';
 import { CheckVisibleResult } from '@agora-js/shared';
 import { ElectronDesktopCapturerSource } from '@agora-js/shared';
 import { EventEmitter } from '@agora-js/shared';
+import type { IAudioExtension } from 'agora-rte-extension-ng';
 import { IAudioProcessor } from 'agora-rte-extension';
 import type { IAudioProcessorContext } from 'agora-rte-extension';
 import { IBaseProcessor } from 'agora-rte-extension';
 import type { IProcessorContext } from 'agora-rte-extension';
 import { isElectron } from '@agora-js/shared';
+import type { IVideoExtension } from 'agora-rte-extension-ng';
 import type { Kind } from 'agora-rte-extension';
 import type { NetworkQuality } from '@agora-js/shared';
 import type { ProcessorStats } from 'agora-rte-extension';
@@ -16,6 +19,7 @@ import { SDKStore } from '@agora-js/shared';
 import { UID } from '@agora-js/shared';
 import { Usage } from 'agora-rte-extension';
 import type { UsageWithDirection } from 'agora-rte-extension';
+import type { VideoExtensionConstructor } from 'agora-rte-extension-ng';
 
 export declare const __TRACK_LIST__: Track[];
 
@@ -168,6 +172,7 @@ declare class AudioElementPlayCenter {
     private elementStateMap;
     private elementsNeedToResume;
     private sinkIdMap;
+    private elementIdMap;
     constructor();
     setSinkID(trackId: string, deviceID: string): Promise<void>;
     play(track: MediaStreamTrack, trackId: string, volume: number, sessionId?: string): void;
@@ -176,6 +181,7 @@ declare class AudioElementPlayCenter {
     setVolume(trackId: string, volume: number): void;
     getVolume(trackId: string): number;
     stop(trackId: string): void;
+    reuseTrackId(fromId: string, toId: string): void;
     private bindAudioElementEvents;
     getPlayerState(trackId: string): string;
     private autoResumeAudioElement;
@@ -740,6 +746,18 @@ export declare interface CustomVideoTrackInitConfig {
      * The maximum bitrate of sending the video track (Kbps).
      */
     bitrateMax?: number;
+    /**
+     * The minimum width allowed during automatic downscaling.
+     *
+     * When the SDK takes over resolution downscaling, the sending width will not go below this value.
+     */
+    minDownscaleWidth?: number;
+    /**
+     * The minimum height allowed during automatic downscaling.
+     *
+     * When the SDK takes over resolution downscaling, the sending height will not go below this value.
+     */
+    minDownscaleHeight?: number;
     /**
      * @since
      * <br>&emsp;&emsp;&emsp;*4.2.0*
@@ -1159,11 +1177,15 @@ export declare function getNewNearestVideoProfile(width: number, height: number,
 export declare function getNewVideoBitrate(width: number, height: number, fps: number): [number, number];
 
 export declare const getOriginSenderConfig: (track: LocalVideoTrack) => {
+    width: number;
+    height: number;
     frameRate: number;
     bitrateMax: number;
     bitrateMin: number;
     scaleResolutionDownBy: number;
     scale: number;
+    minDownscaleWidth: number;
+    minDownscaleHeight: number;
 };
 
 export declare function getScalabilityConfiguration(profile: SVCConfiguration | SVCConfigurationPreset): SVCConfiguration;
@@ -1473,6 +1495,33 @@ export declare interface ILocalAudioTrack extends ILocalTrack {
      * The destination of the current processing pipeline on the local audio track.
      */
     processorDestination: IAudioProcessor;
+    /**
+     * Creates or reuses an audio extension instance on the current audio track using a class constructor.
+     *
+     * @param extensionCtor The audio extension class constructor.
+     * @param extensionOptions Optional extension initialization parameters.
+     */
+    useExtension<T extends IAudioExtension>(extensionCtor: AudioExtensionConstructor<T>, extensionOptions?: Record<string, unknown>): T;
+    /**
+     * Removes an audio extension from the local audio track.
+     *
+     * @param extension The audio extension instance.
+     * @returns Whether the removal succeeded.
+     */
+    removeExtension(extension: IAudioExtension): boolean;
+    /**
+     * Adds a reference track to the current audio extension pipeline.
+     *
+     * @param track The local or remote audio track used as the reference input.
+     */
+    addReferenceTrack(track: ILocalAudioTrack | IRemoteAudioTrack): void;
+    /**
+     * Removes a reference track from the current audio extension pipeline.
+     *
+     * @param track The reference input track to remove.
+     * @returns Whether the removal succeeded.
+     */
+    removeReferenceTrack(track: ILocalAudioTrack | IRemoteAudioTrack): boolean;
 }
 
 /**
@@ -1713,6 +1762,8 @@ export declare interface ILocalVideoTrack extends ILocalTrack {
      * @since
      * <br>&emsp;&emsp;&emsp;*4.10.0*
      *
+     * @deprecated Legacy v1 pipe-mode API. For new extensions, use `useExtension` and `removeExtension`.
+     *
      * Removes the `Processor` inserted to the local video track.
      */
     unpipe(): void;
@@ -1720,9 +1771,31 @@ export declare interface ILocalVideoTrack extends ILocalTrack {
      * @since
      * <br>&emsp;&emsp;&emsp;*4.10.0*
      *
+     * @deprecated Legacy v1 pipe-mode API. For new extensions, use `useExtension` and `removeExtension`.
+     *
      * The destination of the current processing pipeline on the local video track.
      */
     processorDestination: IBaseProcessor;
+    /**
+     * Creates or reuses a video extension proxy on the current video track using a class constructor.
+     *
+     * The same extension constructor always returns the same instance proxy until it is destroyed.
+     *
+     * @param extensionCtor The video extension class constructor.
+     * @param options Optional extension initialization parameters.
+     */
+    useExtension<T extends VideoExtensionConstructor>(extensionCtor: T, options?: {
+        extensionOptions?: Record<string, unknown>;
+        moduleURL?: string;
+        registrationName?: string;
+    }): InstanceType<T>;
+    /**
+     * Removes a video extension from the local video track.
+     *
+     * @param extension The video extension instance.
+     * @returns Whether the removal succeeded.
+     */
+    removeExtension(extension: IVideoExtension): boolean;
     /**
      * @since
      * <br>&emsp;&emsp;&emsp;*4.17.0*
@@ -1932,6 +2005,32 @@ export declare interface IRemoteAudioTrack extends IRemoteTrack {
      * The destination of the current processing pipeline on the remote audio track.
      */
     processorDestination: IAudioProcessor;
+    /**
+     * Creates or reuses an audio extension instance on the current remote audio track using a class constructor.
+     *
+     * @param extensionCtor The audio extension class constructor.
+     */
+    useExtension<T extends IAudioExtension>(extensionCtor: AudioExtensionConstructor<T>): T;
+    /**
+     * Removes an audio extension from the remote audio track.
+     *
+     * @param extension The audio extension instance.
+     * @returns Whether the removal succeeded.
+     */
+    removeExtension(extension: IAudioExtension): boolean;
+    /**
+     * Adds a reference track to the current audio extension pipeline.
+     *
+     * @param track The local or remote audio track used as the reference input.
+     */
+    addReferenceTrack(track: ILocalAudioTrack | IRemoteAudioTrack): void;
+    /**
+     * Removes a reference track from the current audio extension pipeline.
+     *
+     * @param track The reference input track to remove.
+     * @returns Whether the removal succeeded.
+     */
+    removeReferenceTrack(track: ILocalAudioTrack | IRemoteAudioTrack): boolean;
 }
 
 /**
@@ -2086,6 +2185,24 @@ export declare interface IRemoteVideoTrack extends IRemoteTrack {
      * The destination of the current processing pipeline on the remote video track.
      */
     processorDestination: IBaseProcessor;
+    /**
+     * Creates or reuses a video extension proxy on the current video track using a class constructor.
+     *
+     * @param extensionCtor The video extension class constructor.
+     * @param options Optional extension initialization parameters.
+     */
+    useExtension<T extends VideoExtensionConstructor>(extensionCtor: T, options?: {
+        extensionOptions?: Record<string, unknown>;
+        moduleURL?: string;
+        registrationName?: string;
+    }): InstanceType<T>;
+    /**
+     * Removes a video extension from the remote video track.
+     *
+     * @param extension The video extension instance.
+     * @returns Whether the removal succeeded.
+     */
+    removeExtension(extension: IVideoExtension): boolean;
     /**
      * Stops playing the media track.
      * @param isKeepLastFrame Whether to keep the last frame.
@@ -2181,6 +2298,9 @@ export declare class LocalAudioTrack extends LocalTrack implements ILocalAudioTr
     _processorDestination: AudioProcessorDestination | undefined;
     get processorDestination(): AudioProcessorDestination;
     protected _getOriginVolumeLevel: boolean;
+    private _usePipeMode;
+    private _useExtensionMode;
+    private _extensionManager?;
     get isPlaying(): boolean;
     get __className__(): string;
     constructor(track: MediaStreamTrack, encoderConfig?: AudioEncoderConfiguration, trackId?: string, getOriginVolumeLevel?: boolean);
@@ -2198,6 +2318,11 @@ export declare class LocalAudioTrack extends LocalTrack implements ILocalAudioTr
     protected _updatePlayerSource(updateWebAudioSource?: boolean): void;
     protected _updateOriginMediaStreamTrack(track: MediaStreamTrack, stopOldTrack: boolean): Promise<void>;
     renewMediaStreamTrack(newConstraints?: MediaTrackConstraints): Promise<void>;
+    private _ensureExtensionManager;
+    useExtension<T extends IAudioExtension>(ctor: AudioExtensionConstructor<T>, extensionOptions?: Record<string, unknown>): T;
+    removeExtension(extension: IAudioExtension): boolean;
+    addReferenceTrack(track: LocalAudioTrack | RemoteAudioTrack): void;
+    removeReferenceTrack(track: LocalAudioTrack | RemoteAudioTrack): boolean;
     pipe(processor: IAudioProcessor): IAudioProcessor;
     unpipe(): void;
     private bindProcessorDestinationEvents;
@@ -2330,6 +2455,9 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     protected _processorDestination: VideoProcessorDestination;
     get processorDestination(): VideoProcessorDestination;
     protected _processorContext: VideoProcessorContext;
+    private _usePipeMode;
+    private _useExtensionMode;
+    private _extensionManager?;
     protected get processorContext(): VideoProcessorContext;
     protected set processorContext(ctx: VideoProcessorContext);
     get __className__(): string;
@@ -2358,6 +2486,13 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     updateBitrateFromProfile(): void;
     getVideoElementVisibleStatus(): CheckVideoVisibleResult | undefined;
     renewMediaStreamTrack(newConstraints?: MediaTrackConstraints): Promise<void>;
+    private _ensureVideoExtensionManager;
+    useExtension<T extends VideoExtensionConstructor>(extensionCtor: T, options?: {
+        extensionOptions?: Record<string, unknown>;
+        moduleURL?: string;
+        registrationName?: string;
+    }): InstanceType<T>;
+    removeExtension(extension: IVideoExtension): boolean;
     pipe(processor: IBaseProcessor): IBaseProcessor;
     unpipe(): void;
     close(): void;
@@ -2628,6 +2763,9 @@ export declare class RemoteAudioTrack extends RemoteTrack implements IRemoteAudi
     private _volume;
     protected processorContext: AudioProcessorContext;
     processorDestination: AudioProcessorDestination;
+    private _usePipeMode;
+    private _useExtensionMode;
+    private _extensionManager?;
     private _played;
     private _bypassWebAudio;
     get isPlaying(): boolean;
@@ -2642,9 +2780,15 @@ export declare class RemoteAudioTrack extends RemoteTrack implements IRemoteAudi
     getStats(): RemoteAudioTrackStats;
     play(): void;
     stop(): void;
+    _reusePreAudioElement(tempId: string, isPlaying: boolean): void;
     _destroy(): void;
     _isFreeze(): boolean;
     protected _updatePlayerSource(updateWebAudioSource?: boolean): void;
+    private _ensureAudioExtensionManager;
+    useExtension<T extends IAudioExtension>(ctor: AudioExtensionConstructor<T>): T;
+    removeExtension(extension: IAudioExtension): boolean;
+    addReferenceTrack(track: LocalAudioTrack | RemoteAudioTrack): void;
+    removeReferenceTrack(track: LocalAudioTrack | RemoteAudioTrack): boolean;
     pipe(processor: IAudioProcessor): IAudioProcessor;
     unpipe(): void;
     private bindProcessorDestinationEvents;
@@ -2828,6 +2972,9 @@ export declare class RemoteVideoTrack extends RemoteTrack implements IRemoteVide
     private _prePlayer?;
     processorDestination: VideoProcessorDestination;
     protected processorContext: VideoProcessorContext;
+    private _usePipeMode;
+    private _useExtensionMode;
+    private _extensionManager?;
     get isPlaying(): boolean;
     get __className__(): string;
     constructor(track: MediaStreamTrack, userId: UID, uintId: number, store: SDKStore, player?: AgoraRTCPlayer | VideoPlayer);
@@ -2838,6 +2985,13 @@ export declare class RemoteVideoTrack extends RemoteTrack implements IRemoteVide
     updateMediaStreamTrackResolution(): void;
     protected _updatePlayerSource(): void;
     getVideoElementVisibleStatus(): CheckVideoVisibleResult | undefined;
+    private _ensureVideoExtensionManager;
+    useExtension<T extends VideoExtensionConstructor>(extensionCtor: T, options?: {
+        extensionOptions?: Record<string, unknown>;
+        moduleURL?: string;
+        registrationName?: string;
+    }): InstanceType<T>;
+    removeExtension(extension: IVideoExtension): boolean;
     pipe(processor: IBaseProcessor): IBaseProcessor;
     unpipe(): void;
     private bindProcessorDestinationEvents;
@@ -3408,6 +3562,18 @@ export declare interface VideoEncoderConfiguration {
      * @ignore
      */
     scaleResolutionDownBy?: number;
+    /**
+     * The minimum width allowed during automatic downscaling.
+     *
+     * When the SDK takes over resolution downscaling, the sending width will not go below this value.
+     */
+    minDownscaleWidth?: number;
+    /**
+     * The minimum height allowed during automatic downscaling.
+     *
+     * When the SDK takes over resolution downscaling, the sending height will not go below this value.
+     */
+    minDownscaleHeight?: number;
 }
 
 /**