@agora-js/media 4.24.4 → 4.24.6

package/media.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[];
 
@@ -260,6 +264,12 @@ declare class AudioElementPlayCenter {
     private elementStateMap;
     private elementsNeedToResume;
     private sinkIdMap;
+    /**
+     * element → 当前 trackId 的可变持有者。
+     * 事件监听闭包读它拿「当前 id」，而不是捕获创建时的 id；
+     * 这样预渲染移交后 reuseTrackId 只改一处，监听器就写到新 id 上（见 reuseTrackId）。
+     */
+    private elementIdMap;
     constructor();
     setSinkID(trackId: string, deviceID: string): Promise<void>;
     play(track: MediaStreamTrack, trackId: string, volume: number, sessionId?: string): void;
@@ -268,6 +278,12 @@ declare class AudioElementPlayCenter {
     setVolume(trackId: string, volume: number): void;
     getVolume(trackId: string): number;
     stop(trackId: string): void;
+    /**
+     * 预渲染移交：把已在播放的 <audio> 从临时 id 迁移到 track 的正式 id（getTrackId()）。
+     * 参照 RemoteVideoTrack 复用 _prePlayer 的思路——渲染层归属 track 自己的身份，
+     * 而不是让 track 长期追着一个临时 id。迁移 3 张 map + 更新事件监听读取的 id 持有者。
+     */
+    reuseTrackId(fromId: string, toId: string): void;
     private bindAudioElementEvents;
     getPlayerState(trackId: string): string;
     /**
@@ -1146,6 +1162,28 @@ export declare interface CustomVideoTrackInitConfig {
      * The maximum bitrate of sending the video track (Kbps).
      */
     bitrateMax?: number;
+    /**
+     * 自动降分辨率时允许降到的最小宽度。
+     *
+     * 当 SDK 接管分辨率降档时，发送宽度不会低于这个值。
+     */
+    /** @en
+     * 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;
+    /**
+     * 自动降分辨率时允许降到的最小高度。
+     *
+     * 当 SDK 接管分辨率降档时，发送高度不会低于这个值。
+     */
+    /** @en
+     * 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;
     /**
      * @自从
      * <br>&emsp;&emsp;&emsp;*4.2.0*
@@ -1786,11 +1824,15 @@ export declare function getNewVideoBitrate(width: number, height: number, fps: n
  * ⚠️：理论上不存在没有分辨率的情况，如果出现不足任何处理
  */
 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;
@@ -2320,6 +2362,56 @@ export declare interface ILocalAudioTrack extends ILocalTrack {
      * The destination of the current processing pipeline on the local audio track.
      */
     processorDestination: IAudioProcessor;
+    /**
+     * 使用类构造器在当前音频轨道上创建或复用一个音频插件实例。
+     *
+     * @param extensionCtor 音频插件类构造器。
+     * @param extensionOptions 可选的插件初始化参数。
+     */
+    /** @en
+     * 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;
+    /**
+     * 从本地音频轨道移除音频插件。
+     *
+     * @param extension 音频插件实例。
+     * @returns 是否成功移除。
+     */
+    /** @en
+     * Removes an audio extension from the local audio track.
+     *
+     * @param extension The audio extension instance.
+     * @returns Whether the removal succeeded.
+     */
+    removeExtension(extension: IAudioExtension): boolean;
+    /**
+     * 向当前音频扩展链路添加参考音轨。
+     *
+     * @param track 作为参考输入的本地或远端音频轨道。
+     */
+    /** @en
+     * 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;
+    /**
+     * 从当前音频扩展链路移除参考音轨。
+     *
+     * @param track 要移除的参考输入轨道。
+     * @returns 是否成功移除。
+     */
+    /** @en
+     * 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;
 }
 
 /** @ignore */
@@ -2762,12 +2854,16 @@ export declare interface ILocalVideoTrack extends ILocalTrack {
      * @自从
      * <br>&emsp;&emsp;&emsp;*4.10.0*
      *
+     * @deprecated 旧版 v1 pipe 模式 API。新插件请使用 `useExtension` 和 `removeExtension`。
+     *
      * 取消本地视频轨道上注入的 `Processor`。
      */
     /** @en
      * @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;
@@ -2775,15 +2871,53 @@ export declare interface ILocalVideoTrack extends ILocalTrack {
      * @自从
      * <br>&emsp;&emsp;&emsp;*4.10.0*
      *
+     * @deprecated 旧版 v1 pipe 模式 API。新插件请使用 `useExtension` 和 `removeExtension`。
+     *
      * 本地视频轨道上当前媒体处理链路的最终节点。
      */
     /** @en
      * @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;
+    /**
+     * 使用类构造器在当前视频轨道上创建或复用一个视频插件代理。
+     *
+     * 同一个插件构造器在 destroy 前会始终返回同一个实例代理。
+     *
+     * @param extensionCtor 视频插件类构造器。
+     * @param options 可选的插件初始化参数。
+     */
+    /** @en
+     * 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>;
+    /**
+     * 从本地视频轨道移除视频插件。
+     *
+     * @param extension 视频插件实例。
+     * @returns 是否成功移除。
+     */
+    /** @en
+     * Removes a video extension from the local video track.
+     *
+     * @param extension The video extension instance.
+     * @returns Whether the removal succeeded.
+     */
+    removeExtension(extension: IVideoExtension): boolean;
     /**
      * @自从
      * <br>&emsp;&emsp;&emsp;*4.17.0*
@@ -3148,6 +3282,54 @@ export declare interface IRemoteAudioTrack extends IRemoteTrack {
      * The destination of the current processing pipeline on the remote audio track.
      */
     processorDestination: IAudioProcessor;
+    /**
+     * 使用类构造器在当前远端音频轨道上创建或复用一个音频插件实例。
+     *
+     * @param extensionCtor 音频插件类构造器。
+     */
+    /** @en
+     * 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;
+    /**
+     * 从远端音频轨道移除音频插件。
+     *
+     * @param extension 音频插件实例。
+     * @returns 是否成功移除。
+     */
+    /** @en
+     * Removes an audio extension from the remote audio track.
+     *
+     * @param extension The audio extension instance.
+     * @returns Whether the removal succeeded.
+     */
+    removeExtension(extension: IAudioExtension): boolean;
+    /**
+     * 向当前音频扩展链路添加参考音轨。
+     *
+     * @param track 作为参考输入的本地或远端音频轨道。
+     */
+    /** @en
+     * 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;
+    /**
+     * 从当前音频扩展链路移除参考音轨。
+     *
+     * @param track 要移除的参考输入轨道。
+     * @returns 是否成功移除。
+     */
+    /** @en
+     * 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;
 }
 
 /** @ignore */
@@ -3422,6 +3604,36 @@ export declare interface IRemoteVideoTrack extends IRemoteTrack {
      * The destination of the current processing pipeline on the remote video track.
      */
     processorDestination: IBaseProcessor;
+    /**
+     * 使用类构造器在当前视频轨道上创建或复用一个视频插件代理。
+     *
+     * @param extensionCtor 视频插件类构造器。
+     * @param options 可选的插件初始化参数。
+     */
+    /** @en
+     * 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>;
+    /**
+     * 从远端视频轨道移除视频插件。
+     *
+     * @param extension 视频插件实例。
+     * @returns 是否成功移除。
+     */
+    /** @en
+     * Removes a video extension from the remote video track.
+     *
+     * @param extension The video extension instance.
+     * @returns Whether the removal succeeded.
+     */
+    removeExtension(extension: IVideoExtension): boolean;
     /**
      * 停止播放。
      * @param isKeepLastFrame 是否保留最后一帧。
@@ -3576,6 +3788,10 @@ export declare class LocalAudioTrack extends LocalTrack implements ILocalAudioTr
     _processorDestination: AudioProcessorDestination | undefined;
     get processorDestination(): AudioProcessorDestination;
     protected _getOriginVolumeLevel: boolean;
+    /** Tracks whether this track is using the new UseExtension mode vs the old pipe mode */
+    private _usePipeMode;
+    private _useExtensionMode;
+    private _extensionManager?;
     get isPlaying(): boolean;
     get __className__(): string;
     constructor(track: MediaStreamTrack, encoderConfig?: AudioEncoderConfiguration, trackId?: string, getOriginVolumeLevel?: boolean);
@@ -3593,6 +3809,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;
@@ -3772,6 +3993,10 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     protected _processorDestination: VideoProcessorDestination;
     get processorDestination(): VideoProcessorDestination;
     protected _processorContext: VideoProcessorContext;
+    /** Tracks whether this track is using the new UseExtension mode vs the old pipe mode */
+    private _usePipeMode;
+    private _useExtensionMode;
+    private _extensionManager?;
     protected get processorContext(): VideoProcessorContext;
     protected set processorContext(ctx: VideoProcessorContext);
     get __className__(): string;
@@ -3800,6 +4025,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;
@@ -4214,6 +4446,10 @@ export declare class RemoteAudioTrack extends RemoteTrack implements IRemoteAudi
     private _volume;
     protected processorContext: AudioProcessorContext;
     processorDestination: AudioProcessorDestination;
+    /** Tracks whether this track is using the new UseExtension mode vs the old pipe mode */
+    private _usePipeMode;
+    private _useExtensionMode;
+    private _extensionManager?;
     private _played;
     private _bypassWebAudio;
     get isPlaying(): boolean;
@@ -4228,9 +4464,22 @@ export declare class RemoteAudioTrack extends RemoteTrack implements IRemoteAudi
     getStats(): RemoteAudioTrackStats;
     play(): void;
     stop(): void;
+    /**
+     * 预渲染移交：join 时（UID 未知）音频已用临时 id 起播，这里把渲染层交给正式构造出来的 track。
+     * 必须按后端分两路——预渲染恒走 <audio>，但本 track 可能配置成 WebAudio：
+     *  - <audio> 后端：把预渲染那个元素 re-key 到 getTrackId()，track 之后一律用自己的 id。
+     *  - WebAudio 后端：预渲染的 <audio> 是「错的后端」，拆掉它、改由 WebAudio source 接管
+     *    （参照 setAmplifiedVolume 的 audio-element→WebAudio 适配：stop 元素 + 启 _source）。
+     */
+    _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;
@@ -4508,6 +4757,10 @@ export declare class RemoteVideoTrack extends RemoteTrack implements IRemoteVide
     private _prePlayer?;
     processorDestination: VideoProcessorDestination;
     protected processorContext: VideoProcessorContext;
+    /** Tracks whether this track is using the new UseExtension mode vs the old pipe mode */
+    private _usePipeMode;
+    private _useExtensionMode;
+    private _extensionManager?;
     get isPlaying(): boolean;
     get __className__(): string;
     constructor(track: MediaStreamTrack, userId: UID, uintId: number, store: SDKStore, player?: AgoraRTCPlayer | VideoPlayer);
@@ -4518,6 +4771,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;
@@ -5509,6 +5769,28 @@ export declare interface VideoEncoderConfiguration {
      * @ignore
      */
     scaleResolutionDownBy?: number;
+    /**
+     * 自动降分辨率时允许降到的最小宽度。
+     *
+     * 当 SDK 接管分辨率降档时，发送宽度不会低于这个值。
+     */
+    /** @en
+     * 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;
+    /**
+     * 自动降分辨率时允许降到的最小高度。
+     *
+     * 当 SDK 接管分辨率降档时，发送高度不会低于这个值。
+     */
+    /** @en
+     * 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;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agora-js/media",
-	"version": "4.24.4",
+	"version": "4.24.6",
 	"description": "media module across @agora-js packages",
 	"main": "AgoraRTC_N-media.js",
 	"module": "AgoraRTC_N-media.esm.mjs",
@@ -23,10 +23,11 @@
 	"homepage": "https://api-ref.agora.io/en/voice-sdk/web/4.x/index.html",
 	"peerDependencies": {},
 	"dependencies": {
-		"@agora-js/shared": "4.24.4",
-		"@agora-js/report": "4.24.4",
+		"@agora-js/shared": "4.24.6",
+		"@agora-js/report": "4.24.6",
 		"axios": "^1.16.1",
 		"agora-rte-extension": "^1.2.4",
+		"agora-rte-extension-ng": "^1.0.3",
 		"webrtc-adapter": "8.2.0"
 	}
 }