@agora-js/media 4.22.2 → 4.23.0

package/media.d.ts

@@ -776,7 +776,7 @@ export declare class CameraVideoTrack extends LocalVideoTrack implements ICamera
     _enabled: boolean;
     _deviceName: string;
     get __className__(): string;
-    constructor(track: MediaStreamTrack, config: CameraVideoTrackInitConfig, constraints: MediaTrackConstraints, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode | "balanced", trackId?: string);
+    constructor(track: MediaStreamTrack, config: CameraVideoTrackInitConfig, constraints: MediaTrackConstraints, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode, trackId?: string);
     setDevice(deviceId: string | RequiredOnlyOneOf<{
         facingMode: VideoFacingModeEnum;
         deviceId: string;
@@ -883,6 +883,9 @@ export declare interface CameraVideoTrackInitConfig {
      * -  `"motion"`: Since v4.21.0, the browser prioritizes video smoothness.
      *   - In poor network conditions, the browser reduces the sending bitrate to minimize video freezes.
      *   - In most cases, the browser does not reduce the frame rate, but may reduce the sending resolution.
+     * - `"balanced"`: The default optimization mode.
+     *   - For screen sharing video streams, the SDK default optimization strategy is quality-first.
+     *   - For other video streams, the SDK default optimization strategy is balanced between quality and smoothness. Under poor network conditions, both the frame rate and resolution will be adjusted.
      */
     optimizationMode?: OptimizationMode;
     /**
@@ -1172,7 +1175,7 @@ export declare interface CustomVideoTrackInitConfig {
      *   - In poor network conditions, the SDK reduces the sending bitrate to minimize video freezes.
      *   - In most cases, the SDK does not reduce the frame rate, but may reduce the sending resolution.
      */
-    optimizationMode?: "motion" | "detail";
+    optimizationMode?: OptimizationMode;
     /**
      * @ignore
      * @自从
@@ -1677,7 +1680,7 @@ declare class FakeTrackSource extends EventEmitter {
     createMediaStreamSourceNode(): undefined;
 }
 
-export declare const frameData2CryptoBuffer: (imageData: ImageTypedData, appid: string, channelName: string) => Promise<Uint8Array>;
+export declare const frameData2CryptoBuffer: (imageData: ImageTypedData, appid: string, channelName: string) => Promise<Uint8Array<ArrayBufferLike>>;
 
 export declare function getAudioContext(): AudioContext;
 
@@ -2638,7 +2641,7 @@ export declare interface ILocalVideoTrack extends ILocalTrack {
      *   - In poor network conditions, the browser reduces the sending bitrate to minimize video freezes.
      *   - In most cases, the browser does not reduce the frame rate, but may reduce the sending resolution.
      */
-    setOptimizationMode(mode: "balanced" | "motion" | "detail"): Promise<void>;
+    setOptimizationMode(mode: OptimizationMode): Promise<void>;
     /**
      * * @自从
      * <br>&emsp;&emsp;&emsp;*4.8.0*
@@ -3655,7 +3658,7 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     private _clearPreviousVideoVisibleStatus;
     _encoderConfig?: Partial<VideoEncoderConfiguration>;
     _scalabilityMode?: SVCConfiguration;
-    _optimizationMode?: OptimizationMode | "balanced";
+    _optimizationMode?: OptimizationMode;
     private _videoHeight?;
     private _videoWidth?;
     get videoHeight(): number | undefined;
@@ -3672,7 +3675,7 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     protected get processorContext(): VideoProcessorContext;
     protected set processorContext(ctx: VideoProcessorContext);
     get __className__(): string;
-    constructor(track: MediaStreamTrack, encoderConfig?: Partial<VideoEncoderConfiguration>, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode | "balanced", trackId?: string, hints?: TrackHint[]);
+    constructor(track: MediaStreamTrack, encoderConfig?: Partial<VideoEncoderConfiguration>, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode, trackId?: string, hints?: TrackHint[]);
     play(element: HTMLElement | HTMLVideoElement | string, config?: VideoPlayerConfig): void;
     stop(): void;
     setEnabled(enabled: boolean, skipChangeState?: boolean): Promise<void>;
@@ -3686,7 +3689,7 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
         max_bitrate: number;
         min_bitrate: number;
     }): Promise<void>;
-    setOptimizationMode(mode: OptimizationMode | "balanced"): Promise<void>;
+    setOptimizationMode(mode: OptimizationMode): Promise<void>;
     setScalabiltyMode(mode: SVCConfiguration): void;
     updateMediaStreamTrackResolution(): void;
     protected _updatePlayerSource(): void;
@@ -4050,6 +4053,9 @@ export declare class MixingAudioTrack extends LocalAudioTrack {
  * - `"motion"`: 自 4.21.0 开始，浏览器默认开启流畅优先模式。
  *   - 浏览器不会启用最小码率策略。遭遇网络波动时，发送端会降低码率来确保接收端的视频画面不会出现中断和卡顿。
  *   - 大部分情况下，浏览器不会降低帧率，但是可能会降低发送分辨率。
+ * - `"balanced"`: 默认的传输优化模式。
+ *   - 对于屏幕共享视频流，SDK 默认的优化策略为清晰优先。
+ *   - 对于其他视频流，SDK 默认的优化策略为坚固清晰合流畅，弱网条件下，帧率和分辨率都会被调整。
  * @public
  */
 /** @en
@@ -4060,8 +4066,11 @@ export declare class MixingAudioTrack extends LocalAudioTrack {
  * -  `"motion"`: Since v4.21.0, the browser prioritizes video smoothness.
  *   - In poor network conditions, the browser reduces the sending bitrate to minimize video freezes.
  *   - In most cases, the browser does not reduce the frame rate, but may reduce the sending resolution.
+ * - `"balanced"`: The default optimization mode.
+ *   - For screen sharing video streams, the SDK default optimization strategy is quality-first.
+ *   - For other video streams, the SDK default optimization strategy is balanced between quality and smoothness. Under poor network conditions, both the frame rate and resolution will be adjusted.
  */
-export declare type OptimizationMode = "motion" | "detail";
+export declare type OptimizationMode = "motion" | "detail" | "balanced";
 
 /**
  * @internal
@@ -4242,14 +4251,14 @@ export declare interface RemoteAudioTrackStats {
      * 接收的音频总丢包率。
      */
     /** @en
-     * The packet loss rate of the received audio.
+     * The total packet loss rate of the received audio.
      */
     packetLossRate: number;
     /**
-     * 接收的音频400ms内的丢包率。
+     * 接收的音频在 400ms 内的丢包率。
      */
     /** @en
-     * The packet loss rate of the received audio.
+     * The packet loss rate of the received audio in 400ms.
      */
     currentPacketLossRate: number;
     /**
@@ -4521,17 +4530,17 @@ export declare interface RemoteVideoTrackStats {
      */
     receivePacketsLost: number;
     /**
-     * 接收的视频丢包率。
+     * 接收的视频总丢包率。
      */
     /** @en
-     * The packet loss rate of the received video.
+     * The total packet loss rate of the received video.
      */
     packetLossRate: number;
     /**
-     * 接收的视频在400ms内的丢包率。
+     * 接收的视频在 400ms 内的丢包率。
      */
     /** @en
-     * The packet loss rate of the received video.
+     * The packet loss rate of the received video in 400ms.
      */
     currentPacketLossRate: number;
     /**
@@ -4563,10 +4572,10 @@ export declare interface RemoteVideoTrackStats {
      */
     totalFreezeTime: number;
     /**
-     * 接收的视频卡顿率。
+     * 最近一秒接收视频的卡顿率。取值范围为 [0.0,1.0]，代表最近一秒内视频卡顿百分比。
      */
     /** @en
-     * The freeze rate of the received video.
+     * The freeze rate of the remote video in the last second. The value range is [0.0,1.0], representing the percentage of video freezes in the last second.
      */
     freezeRate: number;
     /**
@@ -4633,6 +4642,8 @@ export declare interface ScreenConstraintsWithElectron extends MediaTrackConstra
     surfaceSwitching?: "include" | "exclude";
     /** 是否开启系统音频，默认开启include, Chrome 105以上, Opera 91以上 */
     systemAudio?: "include" | "exclude";
+    /** 是否默认分享当前页面，默认为false, Chrome 94以上, Opera 80以上 */
+    preferCurrentTab?: boolean;
 }
 
 /**
@@ -4772,6 +4783,9 @@ export declare interface ScreenVideoTrackInitConfig {
      * - `"motion"`: 自 4.21.0 开始，浏览器默认开启流畅优先模式。
      *   - 浏览器不会启用最小码率策略。遭遇网络波动时，发送端会降低码率来确保接收端的视频画面不会出现中断和卡顿。
      *   - 大部分情况下，浏览器不会降低帧率，但是可能会降低发送分辨率。
+     * - `"balanced"`: 默认的传输优化模式。
+     *   - 对于屏幕共享视频流，SDK 默认的优化策略为清晰优先。
+     *   - 对于其他视频流，SDK 默认的优化策略为坚固清晰合流畅，弱网条件下，帧率和分辨率都会被调整。
      */
     /** @en
      * @since
@@ -4791,7 +4805,7 @@ export declare interface ScreenVideoTrackInitConfig {
      *   - In poor network conditions, the browser reduces the sending bitrate to minimize video freezes.
      *   - In most cases, the browser does not reduce the frame rate, but may reduce the sending resolution.
      */
-    optimizationMode?: "motion" | "detail";
+    optimizationMode?: OptimizationMode;
     /**
      * @ignore
      *
@@ -4918,6 +4932,28 @@ export declare interface ScreenVideoTrackInitConfig {
      * > Note: This property is supported on Chrome 105 and later (Windows only), as well as Edge 105 and later (Windows only).
      */
     systemAudio?: "include" | "exclude";
+    /**
+     * @自从
+     * <br>&emsp;&emsp;&emsp;*4.23.0*
+     *
+     * 是否默认共享当前页面。
+     * - `true`: 是。
+     * - `false`: （默认）否。
+     *
+     * > 注意事项: 该属性仅支持 Chrome 94 及以上版本、Opera 80 及以上版本。
+     */
+    /** @en
+     *
+     * @since
+     * <br>&emsp;&emsp;&emsp;*4.23.0*
+     *
+     * Whether to share the current tab by default.
+     * - `true`: Yes.
+     * - `false`: (Default) No.
+     *
+     * > Note: This property is only supported in Chrome 94 and above, and Opera 80 and above..
+     */
+    preferCurrentTab?: boolean;
 }
 
 export declare type SenderConfig = {

package/package.json

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

package/rtc-sdk-media_en.d.ts

@@ -513,7 +513,7 @@ export declare class CameraVideoTrack extends LocalVideoTrack implements ICamera
     _enabled: boolean;
     _deviceName: string;
     get __className__(): string;
-    constructor(track: MediaStreamTrack, config: CameraVideoTrackInitConfig, constraints: MediaTrackConstraints, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode | "balanced", trackId?: string);
+    constructor(track: MediaStreamTrack, config: CameraVideoTrackInitConfig, constraints: MediaTrackConstraints, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode, trackId?: string);
     setDevice(deviceId: string | RequiredOnlyOneOf<{
         facingMode: VideoFacingModeEnum;
         deviceId: string;
@@ -575,6 +575,9 @@ export declare interface CameraVideoTrackInitConfig {
      * -  `"motion"`: Since v4.21.0, the browser prioritizes video smoothness.
      *   - In poor network conditions, the browser reduces the sending bitrate to minimize video freezes.
      *   - In most cases, the browser does not reduce the frame rate, but may reduce the sending resolution.
+     * - `"balanced"`: The default optimization mode.
+     *   - For screen sharing video streams, the SDK default optimization strategy is quality-first.
+     *   - For other video streams, the SDK default optimization strategy is balanced between quality and smoothness. Under poor network conditions, both the frame rate and resolution will be adjusted.
      */
     optimizationMode?: OptimizationMode;
     /**
@@ -747,7 +750,7 @@ export declare interface CustomVideoTrackInitConfig {
      *   - In poor network conditions, the SDK reduces the sending bitrate to minimize video freezes.
      *   - In most cases, the SDK does not reduce the frame rate, but may reduce the sending resolution.
      */
-    optimizationMode?: "motion" | "detail";
+    optimizationMode?: OptimizationMode;
     /**
      * @ignore
      *
@@ -1088,7 +1091,7 @@ declare class FakeTrackSource extends EventEmitter {
     createMediaStreamSourceNode(): undefined;
 }
 
-export declare const frameData2CryptoBuffer: (imageData: ImageTypedData, appid: string, channelName: string) => Promise<Uint8Array>;
+export declare const frameData2CryptoBuffer: (imageData: ImageTypedData, appid: string, channelName: string) => Promise<Uint8Array<ArrayBufferLike>>;
 
 export declare function getAudioContext(): AudioContext;
 
@@ -1635,7 +1638,7 @@ export declare interface ILocalVideoTrack extends ILocalTrack {
      *   - In poor network conditions, the browser reduces the sending bitrate to minimize video freezes.
      *   - In most cases, the browser does not reduce the frame rate, but may reduce the sending resolution.
      */
-    setOptimizationMode(mode: "balanced" | "motion" | "detail"): Promise<void>;
+    setOptimizationMode(mode: OptimizationMode): Promise<void>;
     /**
      * @since
      * <br>&emsp;&emsp;&emsp;*4.8.0*
@@ -2242,7 +2245,7 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     private _clearPreviousVideoVisibleStatus;
     _encoderConfig?: Partial<VideoEncoderConfiguration>;
     _scalabilityMode?: SVCConfiguration;
-    _optimizationMode?: OptimizationMode | "balanced";
+    _optimizationMode?: OptimizationMode;
     private _videoHeight?;
     private _videoWidth?;
     get videoHeight(): number | undefined;
@@ -2259,7 +2262,7 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     protected get processorContext(): VideoProcessorContext;
     protected set processorContext(ctx: VideoProcessorContext);
     get __className__(): string;
-    constructor(track: MediaStreamTrack, encoderConfig?: Partial<VideoEncoderConfiguration>, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode | "balanced", trackId?: string, hints?: TrackHint[]);
+    constructor(track: MediaStreamTrack, encoderConfig?: Partial<VideoEncoderConfiguration>, scalabilityConfig?: SVCConfiguration, optimizationMode?: OptimizationMode, trackId?: string, hints?: TrackHint[]);
     play(element: HTMLElement | HTMLVideoElement | string, config?: VideoPlayerConfig): void;
     stop(): void;
     setEnabled(enabled: boolean, skipChangeState?: boolean): Promise<void>;
@@ -2273,7 +2276,7 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
         max_bitrate: number;
         min_bitrate: number;
     }): Promise<void>;
-    setOptimizationMode(mode: OptimizationMode | "balanced"): Promise<void>;
+    setOptimizationMode(mode: OptimizationMode): Promise<void>;
     setScalabiltyMode(mode: SVCConfiguration): void;
     updateMediaStreamTrackResolution(): void;
     protected _updatePlayerSource(): void;
@@ -2514,8 +2517,11 @@ export declare class MixingAudioTrack extends LocalAudioTrack {
  * -  `"motion"`: Since v4.21.0, the browser prioritizes video smoothness.
  *   - In poor network conditions, the browser reduces the sending bitrate to minimize video freezes.
  *   - In most cases, the browser does not reduce the frame rate, but may reduce the sending resolution.
+ * - `"balanced"`: The default optimization mode.
+ *   - For screen sharing video streams, the SDK default optimization strategy is quality-first.
+ *   - For other video streams, the SDK default optimization strategy is balanced between quality and smoothness. Under poor network conditions, both the frame rate and resolution will be adjusted.
  */
-export declare type OptimizationMode = "motion" | "detail";
+export declare type OptimizationMode = "motion" | "detail" | "balanced";
 
 export declare interface PlayerConfig extends VideoPlayerConfig {
     trackId: string;
@@ -2633,11 +2639,11 @@ export declare interface RemoteAudioTrackStats {
      */
     receivePacketsDiscarded: number;
     /**
-     * The packet loss rate of the received audio.
+     * The total packet loss rate of the received audio.
      */
     packetLossRate: number;
     /**
-     * The packet loss rate of the received audio.
+     * The packet loss rate of the received audio in 400ms.
      */
     currentPacketLossRate: number;
     /**
@@ -2823,11 +2829,11 @@ export declare interface RemoteVideoTrackStats {
      */
     receivePacketsLost: number;
     /**
-     * The packet loss rate of the received video.
+     * The total packet loss rate of the received video.
      */
     packetLossRate: number;
     /**
-     * The packet loss rate of the received video.
+     * The packet loss rate of the received video in 400ms.
      */
     currentPacketLossRate: number;
     /**
@@ -2847,7 +2853,7 @@ export declare interface RemoteVideoTrackStats {
      */
     totalFreezeTime: number;
     /**
-     * The freeze rate of the received video.
+     * The freeze rate of the remote video in the last second. The value range is [0.0,1.0], representing the percentage of video freezes in the last second.
      */
     freezeRate: number;
     publishDuration: number;
@@ -2880,6 +2886,7 @@ export declare interface ScreenConstraintsWithElectron extends MediaTrackConstra
     selfBrowserSurface?: "include" | "exclude";
     surfaceSwitching?: "include" | "exclude";
     systemAudio?: "include" | "exclude";
+    preferCurrentTab?: boolean;
 }
 
 /**
@@ -2963,7 +2970,7 @@ export declare interface ScreenVideoTrackInitConfig {
      *   - In poor network conditions, the browser reduces the sending bitrate to minimize video freezes.
      *   - In most cases, the browser does not reduce the frame rate, but may reduce the sending resolution.
      */
-    optimizationMode?: "motion" | "detail";
+    optimizationMode?: OptimizationMode;
     /**
      * @ignore
      *
@@ -3031,6 +3038,18 @@ export declare interface ScreenVideoTrackInitConfig {
      * > Note: This property is supported on Chrome 105 and later (Windows only), as well as Edge 105 and later (Windows only).
      */
     systemAudio?: "include" | "exclude";
+    /**
+     *
+     * @since
+     * <br>&emsp;&emsp;&emsp;*4.23.0*
+     *
+     * Whether to share the current tab by default.
+     * - `true`: Yes.
+     * - `false`: (Default) No.
+     *
+     * > Note: This property is only supported in Chrome 94 and above, and Opera 80 and above..
+     */
+    preferCurrentTab?: boolean;
 }
 
 export declare type SenderConfig = {