@agora-js/media 4.24.2 → 4.24.3-300

package/media.d.ts

@@ -1146,6 +1146,41 @@ export declare interface CustomVideoTrackInitConfig {
      * The maximum bitrate of sending the video track (Kbps).
      */
     bitrateMax?: number;
+    /**
+     * @自从
+     * <br>&emsp;&emsp;&emsp;*4.24.3-300*
+     *
+     * 本地视频发送镜像模式。默认值为 `VIDEO_MIRROR_MODE_DISABLED`。
+     *
+     * > 该参数只作用于上行：开启后，publish 发送的是 Canvas 生成的镜像轨道。
+     * > {@link ILocalVideoTrack.getMediaStreamTrack} 和本地 `play` 预览仍是你传入的
+     * > `mediaStreamTrack`（或 processor 的输出），不受该参数影响；预览方向完全由 `play` 的
+     * > `mirror` 决定。
+     * >
+     * > 自定义视频轨道没有 `encoderConfig` 嵌套，该参数与 `width`、`bitrateMax` 等一样直接
+     * > 平铺在本配置对象上。创建后如需切换，调用
+     * > {@link ILocalVideoTrack.setEncoderConfiguration}——它是整体替换语义，仅切换镜像时
+     * > 请携带当前完整编码配置一起传入。
+     */
+    /** @en
+     * @since
+     * <br>&emsp;&emsp;&emsp;*4.24.3-300*
+     *
+     * The uplink mirror mode for the local video track. The default value is
+     * `VIDEO_MIRROR_MODE_DISABLED`.
+     *
+     * > This option affects the sent video only: when enabled, publish sends the
+     * > Canvas-mirrored track. {@link ILocalVideoTrack.getMediaStreamTrack} and local
+     * > `play` stay on the `mediaStreamTrack` you passed in (or the processor output);
+     * > the preview orientation is determined solely by `mirror` in `play`.
+     * >
+     * > A custom video track has no nested `encoderConfig`, so this option sits directly
+     * > on this configuration object alongside `width` and `bitrateMax`. To toggle it
+     * > after creation, call {@link ILocalVideoTrack.setEncoderConfiguration}, which
+     * > replaces the whole configuration: pass your current encoder configuration along
+     * > with it when you only want to switch mirroring.
+     */
+    mirrorMode?: VideoMirrorModeType;
     /**
      * @自从
      * <br>&emsp;&emsp;&emsp;*4.2.0*
@@ -1294,6 +1329,8 @@ export declare function detectSupportPreSub(store?: SDKStore): boolean;
 
 export declare function detectSupportRestrictOwnAudio(): boolean;
 
+export declare function detectSupportSDPEndpoint(): boolean;
+
 export declare function detectSupportSuppressLocalAudioPlayback(): boolean;
 
 /**
@@ -1758,6 +1795,13 @@ export declare function getElectronScreenStreamByUserSelect(config: ScreenConstr
 
 export declare function getLocalStream(config: GetUserMediaConfig, id: string): Promise<MediaStream>;
 
+/**
+ * 送流点唯一的分叉：未开 mirror 时原样 `_mediaStreamTrack`；仅开启时返回 publish Canvas 轨。
+ * packages/main 所有把轨道交给 RTCPeerConnection（addTransceiver/addTrack/replaceTrack）、
+ * 按轨道认领 sender、以及派生小流的读取点都必须经由本函数，禁止直读 `_mediaStreamTrack`。
+ */
+export declare function getMediaStreamTrackForSender(track: LocalTrack): MediaStreamTrack;
+
 /**
  * 获取新的视频码率
  * @param width
@@ -3755,6 +3799,27 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     private _clearPreviousVideoVisibleStatus;
     _encoderConfig?: Partial<VideoEncoderConfiguration>;
     _scalabilityMode?: SVCConfiguration;
+    /** 发送镜像开关；不碰 `_mediaStreamTrack` 的语义，主工作轨始终是采集/processor 输出。 */
+    protected _videoMirrorMode: VideoMirrorModeType;
+    /** 仅镜像开启时存在的发布腿：输入 = 主工作轨，输出 = publish 专用 Canvas 轨。 */
+    private _uplinkMirror?;
+    /**
+     * 这条 track 建不出发布腿（环境不支持、canvas context 耗尽等），置位后本轨不再重试。
+     * 作用域是 track 生命周期：失败几乎都是环境能力，一次会话内不会自愈，要恢复只能重建 track。
+     */
+    private _uplinkMirrorUnavailable;
+    /** 是否开启发送镜像（main 的送流点仅在 true 时改读 publish 轨）。 */
+    _isUplinkMirrorEnabled(): boolean;
+    /**
+     * 发送用轨。仅当 `_isUplinkMirrorEnabled()` 时由发布路径调用；惰性创建 Canvas 管线。
+     * 管线建不起来时回落成主工作轨：镜像只影响观感，不该让 publish 整个失败。
+     */
+    _getPublishTrack(): MediaStreamTrack;
+    /**
+     * 主工作轨变更（基类 TRACK_UPDATED：切设备 / processor 换轨 / 静态帧）时只更新镜像输入，
+     * 已挂到 sender 上的 publish 轨身份不变。
+     */
+    private _onWorkingTrackUpdated;
     _optimizationMode?: OptimizationMode;
     _saveEncodeBitrateRatio: number;
     private _videoHeight?;
@@ -3774,6 +3839,25 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     protected set processorContext(ctx: VideoProcessorContext);
     get __className__(): string;
     constructor(track: MediaStreamTrack, encoderConfig?: Partial<VideoEncoderConfiguration>, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode, trackId?: string, hints?: TrackHint[]);
+    /**
+     * 惰性创建发布腿；输入永远是当前主工作轨。
+     * 建不起来（UplinkMirror 构造期的能力探测失败、captureStream 异常等）时不抛给上层：
+     * 送流点有二十多处读取，抛出去会让 publish 整体失败，而镜像只影响观感，回落发主工作轨更合理。
+     * 失败后置位不再重试——能力类失败在一次会话里不会自愈，重试只会重复建 DOM 并刷日志。
+     */
+    private _ensureUplinkMirror;
+    /**
+     * 只更新镜像管线状态，不发 NEED_REPLACE（换轨由 setEncoderConfiguration 统一收口发一次）。
+     * @returns 送流轨是否真的换了（而不是 mode 是否变了）
+     */
+    protected _setVideoMirrorMode(mode: VideoMirrorModeType): boolean;
+    /** sender 已切回主工作轨后，拆掉发布腿。 */
+    protected _disposeUplinkMirrorIfDisabled(): void;
+    /**
+     * 送流轨确实换了时才发一次 NEED_REPLACE；成功后再拆 DISABLE 留下的管线。
+     * 失败语义与 replaceTrack()、切设备一致：回退本地模式并抛出，不补偿 sender。
+     */
+    protected _replaceSenderIfMirrorSwitched(switched: boolean, previousMode: VideoMirrorModeType): Promise<void>;
     play(element: HTMLElement | HTMLVideoElement | string, config?: VideoPlayerConfig): void;
     stop(): void;
     setEnabled(enabled: boolean, skipChangeState?: boolean): Promise<void>;
@@ -4395,6 +4479,7 @@ export declare interface RemoteAudioTrackStats {
 export declare class RemoteDataChannel extends DataChannel implements IRemoteDataChannel {
     private _messageListener;
     constructor(config: IDataChannelConfig);
+    _updateDataChannelConfig(config: IDataChannelConfig): void;
     _updateOriginDataChannel(datachannel: RTCDataChannel): void;
     _close(): void;
     private _bandRemoteDataChannelEvents;
@@ -4507,7 +4592,7 @@ export declare class RemoteVideoTrack extends RemoteTrack implements IRemoteVide
     protected processorContext: VideoProcessorContext;
     get isPlaying(): boolean;
     get __className__(): string;
-    constructor(track: MediaStreamTrack, userId: UID, uintId: number, store: SDKStore, player?: AgoraRTCPlayer);
+    constructor(track: MediaStreamTrack, userId: UID, uintId: number, store: SDKStore, player?: AgoraRTCPlayer | VideoPlayer);
     getStats(): RemoteVideoTrackStats;
     play(element: string | HTMLElement | HTMLVideoElement, config?: VideoPlayerConfig): void;
     stop(isKeepLastFrame?: boolean): void;
@@ -5506,6 +5591,36 @@ export declare interface VideoEncoderConfiguration {
      * @ignore
      */
     scaleResolutionDownBy?: number;
+    /**
+     * @自从
+     * <br>&emsp;&emsp;&emsp;*4.24.3-300*
+     *
+     * 本地视频发送镜像模式。默认值为 `VIDEO_MIRROR_MODE_DISABLED`。
+     *
+     * > 该参数只作用于上行：开启后，publish 发送的是 Canvas 生成的镜像轨道。
+     * > {@link ILocalVideoTrack.getMediaStreamTrack} 和本地 `play` 预览仍是采集或
+     * > processor 的输出，不受该参数影响；预览方向完全由 `play` 的 `mirror` 决定。
+     * >
+     * > `setEncoderConfiguration` 是整体替换语义：只传 `{ mirrorMode }` 会把其余编码
+     * > 字段重置为默认值。仅切换镜像时，请携带当前完整编码配置一起传入。
+     */
+    /** @en
+     * @since
+     * <br>&emsp;&emsp;&emsp;*4.24.3-300*
+     *
+     * The uplink mirror mode for the local video track. The default value is
+     * `VIDEO_MIRROR_MODE_DISABLED`.
+     *
+     * > This option affects the sent video only: when enabled, publish sends the
+     * > Canvas-mirrored track. {@link ILocalVideoTrack.getMediaStreamTrack} and local
+     * > `play` stay on the capture or processor output; the preview orientation is
+     * > determined solely by `mirror` in `play`.
+     * >
+     * > `setEncoderConfiguration` replaces the whole configuration: passing
+     * > `{ mirrorMode }` alone resets the other encoding fields to their defaults.
+     * > To toggle mirroring only, pass your current encoder configuration along with it.
+     */
+    mirrorMode?: VideoMirrorModeType;
 }
 
 /**
@@ -5574,10 +5689,41 @@ export declare interface VideoEncoderConfiguration {
  */
 export declare type VideoEncoderConfigurationPreset = keyof typeof SUPPORT_VIDEO_ENCODER_CONFIG_LIST;
 
+/**
+ * @自从
+ * <br>&emsp;&emsp;&emsp;*4.24.3-300*
+ *
+ * 本地视频轨道发送镜像模式。
+ *
+ * @public
+ */
+/** @en
+ * @since
+ * <br>&emsp;&emsp;&emsp;*4.24.3-300*
+ *
+ * The uplink mirror mode for a local video track.
+ */
+export declare enum VideoMirrorModeType {
+    /**
+     * 开启本地视频轨道镜像。
+     */
+    /** @en
+     * Enables mirroring for the local video track.
+     */
+    VIDEO_MIRROR_MODE_ENABLED = "enabled",
+    /**
+     * 关闭本地视频轨道镜像。
+     */
+    /** @en
+     * Disables mirroring for the local video track.
+     */
+    VIDEO_MIRROR_MODE_DISABLED = "disabled"
+}
+
 /**
  * @internal
  */
-declare class VideoPlayer {
+export declare class VideoPlayer {
     trackId: string;
     config: PlayerConfig;
     onFirstVideoFrameDecoded?: () => void;
@@ -5587,6 +5733,7 @@ declare class VideoPlayer {
     freezeTimeCounterList: number[];
     renderFreezeAccTime: number;
     renderFreezeAccTime2: number;
+    totalFreezeTime: number;
     isKeepLastFrame: boolean;
     isDestroyed: boolean;
     /** 计算 500ms 卡顿时间用 */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agora-js/media",
-	"version": "4.24.2",
+	"version": "4.24.3-300",
 	"description": "media module across @agora-js packages",
 	"main": "AgoraRTC_N-media.js",
 	"module": "AgoraRTC_N-media.esm.mjs",
@@ -23,9 +23,9 @@
 	"homepage": "https://api-ref.agora.io/en/voice-sdk/web/4.x/index.html",
 	"peerDependencies": {},
 	"dependencies": {
-		"@agora-js/shared": "4.24.2",
-		"@agora-js/report": "4.24.2",
-		"axios": "^1.13.2",
+		"@agora-js/shared": "4.24.3-300",
+		"@agora-js/report": "4.24.3-300",
+		"axios": "^1.13.6",
 		"agora-rte-extension": "^1.2.4",
 		"webrtc-adapter": "8.2.0"
 	}

package/rtc-sdk-media_en.d.ts

@@ -740,6 +740,25 @@ export declare interface CustomVideoTrackInitConfig {
      * The maximum bitrate of sending the video track (Kbps).
      */
     bitrateMax?: number;
+    /**
+     * @since
+     * <br>&emsp;&emsp;&emsp;*4.24.3-300*
+     *
+     * The uplink mirror mode for the local video track. The default value is
+     * `VIDEO_MIRROR_MODE_DISABLED`.
+     *
+     * > This option affects the sent video only: when enabled, publish sends the
+     * > Canvas-mirrored track. {@link ILocalVideoTrack.getMediaStreamTrack} and local
+     * > `play` stay on the `mediaStreamTrack` you passed in (or the processor output);
+     * > the preview orientation is determined solely by `mirror` in `play`.
+     * >
+     * > A custom video track has no nested `encoderConfig`, so this option sits directly
+     * > on this configuration object alongside `width` and `bitrateMax`. To toggle it
+     * > after creation, call {@link ILocalVideoTrack.setEncoderConfiguration}, which
+     * > replaces the whole configuration: pass your current encoder configuration along
+     * > with it when you only want to switch mirroring.
+     */
+    mirrorMode?: VideoMirrorModeType;
     /**
      * @since
      * <br>&emsp;&emsp;&emsp;*4.2.0*
@@ -845,6 +864,8 @@ export declare function detectSupportPreSub(store?: SDKStore): boolean;
 
 export declare function detectSupportRestrictOwnAudio(): boolean;
 
+export declare function detectSupportSDPEndpoint(): boolean;
+
 export declare function detectSupportSuppressLocalAudioPlayback(): boolean;
 
 /**
@@ -1152,6 +1173,8 @@ export declare function getElectronScreenStreamByUserSelect(config: ScreenConstr
 
 export declare function getLocalStream(config: GetUserMediaConfig, id: string): Promise<MediaStream>;
 
+export declare function getMediaStreamTrackForSender(track: LocalTrack): MediaStreamTrack;
+
 export declare function getNewNearestVideoProfile(width: number, height: number, frameRate: number): any;
 
 export declare function getNewVideoBitrate(width: number, height: number, fps: number): [number, number];
@@ -2313,6 +2336,12 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     private _clearPreviousVideoVisibleStatus;
     _encoderConfig?: Partial<VideoEncoderConfiguration>;
     _scalabilityMode?: SVCConfiguration;
+    protected _videoMirrorMode: VideoMirrorModeType;
+    private _uplinkMirror?;
+    private _uplinkMirrorUnavailable;
+    _isUplinkMirrorEnabled(): boolean;
+    _getPublishTrack(): MediaStreamTrack;
+    private _onWorkingTrackUpdated;
     _optimizationMode?: OptimizationMode;
     _saveEncodeBitrateRatio: number;
     private _videoHeight?;
@@ -2332,6 +2361,10 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     protected set processorContext(ctx: VideoProcessorContext);
     get __className__(): string;
     constructor(track: MediaStreamTrack, encoderConfig?: Partial<VideoEncoderConfiguration>, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode, trackId?: string, hints?: TrackHint[]);
+    private _ensureUplinkMirror;
+    protected _setVideoMirrorMode(mode: VideoMirrorModeType): boolean;
+    protected _disposeUplinkMirrorIfDisabled(): void;
+    protected _replaceSenderIfMirrorSwitched(switched: boolean, previousMode: VideoMirrorModeType): Promise<void>;
     play(element: HTMLElement | HTMLVideoElement | string, config?: VideoPlayerConfig): void;
     stop(): void;
     setEnabled(enabled: boolean, skipChangeState?: boolean): Promise<void>;
@@ -2738,6 +2771,7 @@ export declare interface RemoteAudioTrackStats {
 export declare class RemoteDataChannel extends DataChannel implements IRemoteDataChannel {
     private _messageListener;
     constructor(config: IDataChannelConfig);
+    _updateDataChannelConfig(config: IDataChannelConfig): void;
     _updateOriginDataChannel(datachannel: RTCDataChannel): void;
     _close(): void;
     private _bandRemoteDataChannelEvents;
@@ -2827,7 +2861,7 @@ export declare class RemoteVideoTrack extends RemoteTrack implements IRemoteVide
     protected processorContext: VideoProcessorContext;
     get isPlaying(): boolean;
     get __className__(): string;
-    constructor(track: MediaStreamTrack, userId: UID, uintId: number, store: SDKStore, player?: AgoraRTCPlayer);
+    constructor(track: MediaStreamTrack, userId: UID, uintId: number, store: SDKStore, player?: AgoraRTCPlayer | VideoPlayer);
     getStats(): RemoteVideoTrackStats;
     play(element: string | HTMLElement | HTMLVideoElement, config?: VideoPlayerConfig): void;
     stop(isKeepLastFrame?: boolean): void;
@@ -3405,6 +3439,23 @@ export declare interface VideoEncoderConfiguration {
      * @ignore
      */
     scaleResolutionDownBy?: number;
+    /**
+     * @since
+     * <br>&emsp;&emsp;&emsp;*4.24.3-300*
+     *
+     * The uplink mirror mode for the local video track. The default value is
+     * `VIDEO_MIRROR_MODE_DISABLED`.
+     *
+     * > This option affects the sent video only: when enabled, publish sends the
+     * > Canvas-mirrored track. {@link ILocalVideoTrack.getMediaStreamTrack} and local
+     * > `play` stay on the capture or processor output; the preview orientation is
+     * > determined solely by `mirror` in `play`.
+     * >
+     * > `setEncoderConfiguration` replaces the whole configuration: passing
+     * > `{ mirrorMode }` alone resets the other encoding fields to their defaults.
+     * > To toggle mirroring only, pass your current encoder configuration along with it.
+     */
+    mirrorMode?: VideoMirrorModeType;
 }
 
 /**
@@ -3464,7 +3515,24 @@ export declare interface VideoEncoderConfiguration {
  */
 export declare type VideoEncoderConfigurationPreset = keyof typeof SUPPORT_VIDEO_ENCODER_CONFIG_LIST;
 
-declare class VideoPlayer {
+/**
+ * @since
+ * <br>&emsp;&emsp;&emsp;*4.24.3-300*
+ *
+ * The uplink mirror mode for a local video track.
+ */
+export declare enum VideoMirrorModeType {
+    /**
+     * Enables mirroring for the local video track.
+     */
+    VIDEO_MIRROR_MODE_ENABLED = "enabled",
+    /**
+     * Disables mirroring for the local video track.
+     */
+    VIDEO_MIRROR_MODE_DISABLED = "disabled"
+}
+
+export declare class VideoPlayer {
     trackId: string;
     config: PlayerConfig;
     onFirstVideoFrameDecoded?: () => void;
@@ -3474,6 +3542,7 @@ declare class VideoPlayer {
     freezeTimeCounterList: number[];
     renderFreezeAccTime: number;
     renderFreezeAccTime2: number;
+    totalFreezeTime: number;
     isKeepLastFrame: boolean;
     isDestroyed: boolean;
     private timeUpdatedCount;