@agora-js/media 4.21.0 → 4.22.1

package/rtc-sdk-media_en.d.ts

@@ -536,18 +536,21 @@ export declare interface CameraVideoTrackInitConfig {
     cameraId?: string;
     /**
      * @since
-     * <br>&emsp;&emsp;&emsp;*4.0.0*
+     * <br>&emsp;&emsp;&emsp;*4.2.0*
+     *
+     * Sets the video transmission optimization mode.
+     *
+     * You can call this method during a video call, a live streaming or screen sharing to dynamically change the optimization mode. For example, during the screen sharing, before you change the shared content from text to video, you can change the optimization mode from `"detail"` to `"motion"` to ensure smoothness in poor network conditions.
      *
-     * Transmission optimization mode. Whether to prioritize video quality or smoothness:
+     * > Note: This method supports Chrome only.
+     *
+     * @param mode The video transmission optimization mode:
      * - `"detail"`: Prioritizes video quality.
      *   - The SDK ensures high-quality images by automatically calculating a minimum bitrate based on the capturing resolution and frame rate. No matter how poor the network condition is, the sending bitrate will never be lower than the minimum value.
      *   - In most cases, the SDK does not reduce the sending resolution, but may reduce the frame rate.
-     * -  `"motion"`: Prioritizes video smoothness.
+     * -  `"motion"`: Since 4.21.0, the SDK prioritizes video smoothness.
      *   - 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.
-     * - Empty: Uses the default transmission optimization mode. The SDK may reduce the frame rate or the sending resolution in poor network conditions.
-     *
-     * > Note: This method is only supported on Chrome.
      */
     optimizationMode?: OptimizationMode;
     /**
@@ -575,7 +578,7 @@ export declare function checkTrackState(): (target: any, propertyKey: any, descr
  * Get the visibility of the `<video>` tag through the following methods and events:
  * - [localVideoTrack.on("video-element-visible-status")]{@link ILocalVideoTrack.event_video_element_visible_status}
  * - [localVideoTrack.getVideoElementVisibleStatus]{@link ILocalVideoTrack.getVideoElementVisibleStatus}
- * - [remoteVideoTrack.on("video-element-visible-status")]{@link IRemoteVideoTrack.event_video_element_visible_status}
+ * - [remoteVideoTrack.on("video-element-visible-status")]{@link IRemoteVideoTrack.event_video_element_visible_status_2}
  * - [remoteVideoTrack.getVideoElementVisibleStatus]{@link IRemoteVideoTrack.getVideoElementVisibleStatus}
  *
  * This object contains the following parameters:
@@ -701,18 +704,24 @@ export declare interface CustomVideoTrackInitConfig {
     bitrateMax?: number;
     /**
      * @since
-     * <br>&emsp;&emsp;&emsp;*4.0.0*
+     * <br>&emsp;&emsp;&emsp;*4.2.0*
      *
-     * Transmission optimization mode. Whether to prioritize video quality or smoothness:
+     * Sets the video transmission optimization mode.
+     *
+     * You can call this method during a video call, a live streaming or screen sharing to dynamically change the optimization mode. For example, during the screen sharing, before you change the shared content from text to video, you can change the optimization mode from `"detail"` to `"motion"` to ensure smoothness in poor network conditions.
+     *
+     * > Note: This method supports Chrome only.
+     *
+     * @param mode The video transmission optimization mode:
+     * - `"balanced"`: Uses the default optimization mode.
+     *   - For a screen-sharing video track, the default transmission optimization strategy is to prioritizes clarity.
+     *   - For the other types of video tracks, the SDK may reduce the frame rate or the sending resolution in poor network conditions.
      * - `"detail"`: Prioritizes video quality.
      *   - The SDK ensures high-quality images by automatically calculating a minimum bitrate based on the capturing resolution and frame rate. No matter how poor the network condition is, the sending bitrate will never be lower than the minimum value.
      *   - In most cases, the SDK does not reduce the sending resolution, but may reduce the frame rate.
-     * -  `"motion"`: Prioritizes video smoothness.
+     * -  `"motion"`: Since 4.21.0, the SDK prioritizes video smoothness.
      *   - 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.
-     * - Empty: Uses the default transmission optimization mode. The SDK may reduce the frame rate or the sending resolution in poor network conditions.
-     *
-     * > Note: This method is only supported on Chrome.
      */
     optimizationMode?: "motion" | "detail";
     /**
@@ -731,14 +740,16 @@ export declare interface CustomVideoTrackInitConfig {
 }
 
 export declare abstract class DataChannel extends EventEmitter implements IDataChannel {
+    readonly trackMediaType: TrackMediaType.DATA;
     private _version;
     private _type;
     _config: IDataChannelConfig;
     _originDataChannel?: RTCDataChannel;
     protected _dataStreamPacketHeader: ArrayBuffer;
-    protected _dataStreamPacketHandler: DataStream;
+    protected _dataStreamPacketHandler: IDataStream;
     private _datachannelEventMap;
     constructor(config: IDataChannelConfig, datachannel?: RTCDataChannel);
+    useDataStream(dataStream: IDataStream): void;
     get id(): number;
     get ordered(): boolean;
     get maxRetransmits(): number;
@@ -763,20 +774,6 @@ export declare enum DataChannelEvents {
     ERROR = "error"
 }
 
-declare class DataStream {
-    private _sequence;
-    private _startTime;
-    private isUseOneByte;
-    private get startTime();
-    private get sequence();
-    serialize(payload: ArrayBuffer): ArrayBuffer;
-    deserialize(packet: ArrayBuffer): ArrayBuffer;
-    private serializeExtension;
-    private deserializeExtension;
-    private decompress;
-    private compress;
-}
-
 export declare function decodeAudioData(buffer: ArrayBuffer): Promise<AudioBuffer>;
 
 export declare const DEFAULT_LOCAL_AUDIO_TRACK_STATS: LocalAudioTrackStats;
@@ -1297,6 +1294,11 @@ export declare interface IDataChannelConfig {
     metadata: string;
 }
 
+declare interface IDataStream {
+    serialize: (payload: ArrayBuffer) => ArrayBuffer;
+    deserialize: (packet: ArrayBuffer) => ArrayBuffer;
+}
+
 /**
  * `LocalAudioTrack` is the basic interface for local audio tracks, providing main methods of local audio tracks.
  *
@@ -1601,7 +1603,7 @@ export declare interface ILocalVideoTrack extends ILocalTrack {
      * - `"detail"`: Prioritizes video quality.
      *   - The SDK ensures high-quality images by automatically calculating a minimum bitrate based on the capturing resolution and frame rate. No matter how poor the network condition is, the sending bitrate will never be lower than the minimum value.
      *   - In most cases, the SDK does not reduce the sending resolution, but may reduce the frame rate.
-     * -  `"motion"`: Prioritizes video smoothness.
+     * -  `"motion"`: Since 4.21.0, the SDK prioritizes video smoothness.
      *   - 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.
      */
@@ -1769,7 +1771,7 @@ export declare interface IRemoteAudioTrack extends IRemoteTrack {
      *
      * Sets the audio playback device, for example, the speaker.
      *
-     * > > This method is only supported on desktop Chrome and Edge browsers. If you call it on other browsers, you need to set `RESTRICTION_SET_PLAYBACK_DEVICE` to `false` first, and calling it directly will throw a `NOT_SUPPORTED` error.
+     * > This method supports Chrome and Edge on desktop devices only. Other browsers throw a `NOT_SUPPORTED` error when calling this method.
      * @param deviceId Device ID, which can be retrieved by calling [[getPlaybackDevices]].
      */
     setPlaybackDevice(deviceId: string): Promise<void>;
@@ -2002,6 +2004,8 @@ export { isElectron }
 
 export declare function isLowStreamParameter(streamParameter: any): streamParameter is LowStreamParameter;
 
+export declare function isPlanB(): boolean;
+
 export declare function isScreenSourceType(mediaSource: any): mediaSource is ScreenSourceType;
 
 export declare function isVideoEncoderConfiguration(config: VideoEncoderConfiguration): config is VideoEncoderConfiguration;
@@ -2206,7 +2210,6 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     _player?: AgoraRTCPlayer | VideoPlayer;
     isUseScaleResolutionDownBy: boolean;
     private _videoVisibleTimer;
-    protected _statsTimer: number | null;
     private _previousVideoVisibleStatus;
     private _clearPreviousVideoVisibleStatus;
     _encoderConfig?: Partial<VideoEncoderConfiguration>;
@@ -2256,7 +2259,6 @@ export declare class LocalVideoTrack extends LocalTrack implements ILocalVideoTr
     close(): void;
     clone(config?: VideoEncoderConfiguration | VideoEncoderConfigurationPreset, cloneTrack?: boolean): LocalVideoTrack;
     replaceTrack(track: MediaStreamTrack, stopOldTrack: boolean): Promise<void>;
-    startMonitorStats(): void;
     sendSeiData(sei: Uint8Array): never;
     private bindProcessorDestinationEvents;
     private unbindProcessorDestinationEvents;
@@ -2274,7 +2276,7 @@ export declare interface LocalVideoTrackStats {
      * - `"VP8"`: The video codec is VP8.
      * - `"VP9"`: The video codec is VP9.
      * - `"AV1X"`: Reserved for future use.
-     * - `"AV1"`: Reserved for future use.
+     * - `"AV1"`: The video codec is AV1.
      *
      * > You can not get this property on Firefox.
      */
@@ -2521,7 +2523,7 @@ export declare interface ProcessorUsageStats {
 }
 
 export declare class RemoteAudioTrack extends RemoteTrack implements IRemoteAudioTrack {
-    readonly trackMediaType: "audio" | "video";
+    readonly trackMediaType: TrackMediaType.AUDIO;
     _source: AudioTrackSource | FakeTrackSource;
     _useAudioElement: boolean;
     private _volume;
@@ -2607,6 +2609,10 @@ export declare interface RemoteAudioTrackStats {
      * The total number of lost audio packets that should be received.
      */
     receivePacketsLost: number;
+    /**
+     * The number of packets discarded by the jitter buffer due to early or late arrival.
+     */
+    receivePacketsDiscarded: number;
     /**
      * The packet loss rate of the received audio.
      */
@@ -2653,7 +2659,13 @@ export declare enum RemoteStreamFallbackType {
     /**
      * 2: Subscribe to the low-quality video stream when the network conditions worsen, and subscribe to audio only when the conditions become too poor to support video transmission.
      */
-    AUDIO_ONLY = 2
+    AUDIO_ONLY = 2,
+    HIGH_STREAM_LAYER1 = 3,
+    HIGH_STREAM_LAYER2 = 4,
+    HIGH_STREAM_LAYER3 = 5,
+    HIGH_STREAM_LAYER4 = 6,
+    HIGH_STREAM_LAYER5 = 7,
+    HIGH_STREAM_LAYER6 = 8
 }
 
 /**
@@ -2667,7 +2679,13 @@ export declare enum RemoteStreamType {
     /**
      * 1: Low-quality video stream (low-bitrate, low-resolution).
      */
-    LOW_STREAM = 1
+    LOW_STREAM = 1,
+    HIGH_STREAM_LAYER1 = 4,
+    HIGH_STREAM_LAYER2 = 5,
+    HIGH_STREAM_LAYER3 = 6,
+    HIGH_STREAM_LAYER4 = 7,
+    HIGH_STREAM_LAYER5 = 8,
+    HIGH_STREAM_LAYER6 = 9
 }
 
 export declare abstract class RemoteTrack extends Track implements IRemoteTrack {
@@ -2698,7 +2716,7 @@ export declare class RemoteVideoTrack extends RemoteTrack implements IRemoteVide
     private _videoVisibleTimer;
     private _previousVideoVisibleStatus;
     private _clearPreviousVideoVisibleStatus;
-    readonly trackMediaType: "audio" | "video";
+    readonly trackMediaType: TrackMediaType.VIDEO;
     _videoWidth?: number;
     _videoHeight?: number;
     _player?: AgoraRTCPlayer | VideoPlayer;
@@ -2739,7 +2757,7 @@ export declare interface RemoteVideoTrackStats {
      * - `"VP8"`: The video codec is VP8.
      * - `"VP9"`: The video codec is VP9.
      * - `"AV1X"`: Reserved for future use.
-     * - `"AV1"`: Reserved for future use.
+     * - `"AV1"`: The video codec is AV1.
      *
      * > You can not get this property on Firefox.
      */
@@ -2905,17 +2923,21 @@ export declare interface ScreenVideoTrackInitConfig {
     screenSourceType?: ScreenSourceType;
     /**
      * @since
-     * <br>&emsp;&emsp;&emsp;*4.0.0*
+     * <br>&emsp;&emsp;&emsp;*4.2.0*
      *
-     * Transmission optimization mode. Whether to prioritize video quality or smoothness:
-     * - `"detail"`: (Default) Prioritizes video quality.
+     * Sets the video transmission optimization mode.
+     *
+     * You can call this method during a video call, a live streaming or screen sharing to dynamically change the optimization mode. For example, during the screen sharing, before you change the shared content from text to video, you can change the optimization mode from `"detail"` to `"motion"` to ensure smoothness in poor network conditions.
+     *
+     * > Note: This method supports Chrome only.
+     *
+     * @param mode The video transmission optimization mode:
+     * - `"detail"`: Prioritizes video quality.
      *   - The SDK ensures high-quality images by automatically calculating a minimum bitrate based on the capturing resolution and frame rate. No matter how poor the network condition is, the sending bitrate will never be lower than the minimum value.
      *   - In most cases, the SDK does not reduce the sending resolution, but may reduce the frame rate.
-     * -  `"motion"`: Prioritizes video smoothness.
+     * -  `"motion"`: Since 4.21.0, the SDK prioritizes video smoothness.
      *   - 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.
-     *
-     * > Note: This method is only supported on Chrome.
      */
     optimizationMode?: "motion" | "detail";
     /**
@@ -3114,7 +3136,8 @@ export declare enum TrackEvents {
 export declare enum TrackHint {
     SCREEN_TRACK = "screen_track",
     CUSTOM_TRACK = "custome_track",
-    LOW_STREAM = "low_stream"
+    LOW_STREAM = "low_stream",
+    SCREEN_LOW_TRACK = "screen_low_track"
 }
 
 export declare enum TrackInternalEvent {
@@ -3136,6 +3159,12 @@ export declare enum TrackInternalEvent {
     NEED_UNMUTE_TRACK = "@need_unmute_track"
 }
 
+export declare enum TrackMediaType {
+    AUDIO = "audio",
+    VIDEO = "video",
+    DATA = "data"
+}
+
 export declare function updateAgoraRTCCompatibility(): void;
 
 export declare interface UsageRegistry {