@agora-js/media 4.22.2 → 4.23.1

package/media.d.ts

@@ -363,6 +363,10 @@ export declare interface AudioEncoderConfiguration {
  */
 export declare type AudioEncoderConfigurationPreset = keyof typeof AUDIO_ENCODER_CONFIG_SETTINGS;
 
+export declare interface AudioMetadata {
+    value: Uint8Array;
+}
+
 export declare interface AudioPlaybackOptions {
     /**
      * 控制人声是否要被播放，默认为 `true`
@@ -776,7 +780,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 +887,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 +1179,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 +1684,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 +2645,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*
@@ -2876,11 +2883,21 @@ export declare interface IMicrophoneAudioTrack extends ILocalAudioTrack {
     setEnabled(enabled: boolean): Promise<void>;
 }
 
-export declare function interceptLocalAudioFrame(sender: RTCRtpSender): Promise<void>;
+declare interface InterceptAudioFrameOptions {
+    enableTopn?: boolean;
+    enableMetadata?: boolean;
+    onMetadata?: (metadata: Uint8Array) => void;
+}
+
+declare interface InterceptAudioFrameOptions_2 {
+    metadata?: () => Uint8Array | undefined;
+}
+
+export declare function interceptLocalAudioFrame(sender: RTCRtpSender, options?: InterceptAudioFrameOptions_2): Promise<void>;
 
 export declare function interceptLocalVideoFrame(sender: RTCRtpSender, localVideoTrack: LocalVideoTrack): Promise<void>;
 
-export declare function interceptRemoteAudioFrame(receiver: RTCRtpReceiver): Promise<void>;
+export declare function interceptRemoteAudioFrame(receiver: RTCRtpReceiver, options?: InterceptAudioFrameOptions): Promise<void>;
 
 export declare function interceptRemoteVideoFrame(receiver: RTCRtpReceiver, options?: InterceptVideoFrameOptions): Promise<void>;
 
@@ -3459,6 +3476,7 @@ export declare class LocalAudioTrack extends LocalTrack implements ILocalAudioTr
     readonly trackMediaType: "audio" | "video";
     _encoderConfig?: AudioEncoderConfiguration;
     _trackSource: AudioTrackSource | FakeTrackSource;
+    metadata: AudioMetadata[];
     /**
      * @description This method is used to init WebAudio, if you're sure you don't want to use WebAudio, call _trackSource
      */
@@ -3655,7 +3673,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 +3690,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 +3704,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 +4068,9 @@ export declare class MixingAudioTrack extends LocalAudioTrack {
  * - `"motion"`: 自 4.21.0 开始，浏览器默认开启流畅优先模式。
  *   - 浏览器不会启用最小码率策略。遭遇网络波动时，发送端会降低码率来确保接收端的视频画面不会出现中断和卡顿。
  *   - 大部分情况下，浏览器不会降低帧率，但是可能会降低发送分辨率。
+ * - `"balanced"`: 默认的传输优化模式。
+ *   - 对于屏幕共享视频流，SDK 默认的优化策略为清晰优先。
+ *   - 对于其他视频流，SDK 默认的优化策略为坚固清晰合流畅，弱网条件下，帧率和分辨率都会被调整。
  * @public
  */
 /** @en
@@ -4060,8 +4081,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 +4266,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 +4545,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 +4587,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 +4657,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 +4798,9 @@ export declare interface ScreenVideoTrackInitConfig {
      * - `"motion"`: 自 4.21.0 开始，浏览器默认开启流畅优先模式。
      *   - 浏览器不会启用最小码率策略。遭遇网络波动时，发送端会降低码率来确保接收端的视频画面不会出现中断和卡顿。
      *   - 大部分情况下，浏览器不会降低帧率，但是可能会降低发送分辨率。
+     * - `"balanced"`: 默认的传输优化模式。
+     *   - 对于屏幕共享视频流，SDK 默认的优化策略为清晰优先。
+     *   - 对于其他视频流，SDK 默认的优化策略为坚固清晰合流畅，弱网条件下，帧率和分辨率都会被调整。
      */
     /** @en
      * @since
@@ -4791,7 +4820,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 +4947,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.1",
 	"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.1",
+		"@agora-js/report": "4.23.1",
 		"axios": "^1.7.7",
 		"agora-rte-extension": "^1.2.4",
 		"webrtc-adapter": "8.2.0"

package/rtc-sdk-media_en.d.ts

@@ -229,6 +229,10 @@ export declare interface AudioEncoderConfiguration {
  */
 export declare type AudioEncoderConfigurationPreset = keyof typeof AUDIO_ENCODER_CONFIG_SETTINGS;
 
+export declare interface AudioMetadata {
+    value: Uint8Array;
+}
+
 export declare interface AudioPlaybackOptions {
     origin?: boolean;
     mixing?: boolean;
@@ -513,7 +517,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 +579,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 +754,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 +1095,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 +1642,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*
@@ -1763,11 +1770,21 @@ export declare interface IMicrophoneAudioTrack extends ILocalAudioTrack {
     setEnabled(enabled: boolean): Promise<void>;
 }
 
-export declare function interceptLocalAudioFrame(sender: RTCRtpSender): Promise<void>;
+declare interface InterceptAudioFrameOptions {
+    enableTopn?: boolean;
+    enableMetadata?: boolean;
+    onMetadata?: (metadata: Uint8Array) => void;
+}
+
+declare interface InterceptAudioFrameOptions_2 {
+    metadata?: () => Uint8Array | undefined;
+}
+
+export declare function interceptLocalAudioFrame(sender: RTCRtpSender, options?: InterceptAudioFrameOptions_2): Promise<void>;
 
 export declare function interceptLocalVideoFrame(sender: RTCRtpSender, localVideoTrack: LocalVideoTrack): Promise<void>;
 
-export declare function interceptRemoteAudioFrame(receiver: RTCRtpReceiver): Promise<void>;
+export declare function interceptRemoteAudioFrame(receiver: RTCRtpReceiver, options?: InterceptAudioFrameOptions): Promise<void>;
 
 export declare function interceptRemoteVideoFrame(receiver: RTCRtpReceiver, options?: InterceptVideoFrameOptions): Promise<void>;
 
@@ -2096,6 +2113,7 @@ export declare class LocalAudioTrack extends LocalTrack implements ILocalAudioTr
     readonly trackMediaType: "audio" | "video";
     _encoderConfig?: AudioEncoderConfiguration;
     _trackSource: AudioTrackSource | FakeTrackSource;
+    metadata: AudioMetadata[];
     get _source(): AudioTrackSource;
     set _source(source: AudioTrackSource | FakeTrackSource);
     _enabled: boolean;
@@ -2242,7 +2260,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 +2277,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 +2291,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 +2532,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 +2654,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 +2844,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 +2868,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 +2901,7 @@ export declare interface ScreenConstraintsWithElectron extends MediaTrackConstra
     selfBrowserSurface?: "include" | "exclude";
     surfaceSwitching?: "include" | "exclude";
     systemAudio?: "include" | "exclude";
+    preferCurrentTab?: boolean;
 }
 
 /**
@@ -2963,7 +2985,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 +3053,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 = {