agora-electron-sdk 4.5.2-dev.2 → 4.5.40-rc.1

package/CHANGELOG.md

@@ -1,18 +1,21 @@
 
 
-## [4.5.2-dev.2](https://github.com/AgoraIO-Extensions/Electron-SDK/compare/v4.5.2-dev.1...v4.5.2-dev.2) (2025-03-14)
+## [4.5.40-rc.1](https://github.com/AgoraIO-Extensions/Electron-SDK/compare/v4.5.2-build.131-rc.1...v4.5.40-rc.1) (2025-09-28)
 
-## [4.5.2-dev.1](https://github.com/AgoraIO-Extensions/Electron-SDK/compare/v0.0.0-dev.1...v4.5.2-dev.1) (2025-03-12)
 
-# [0.0.0-dev.1](https://github.com/AgoraIO-Extensions/Electron-SDK/compare/v4.5.2...v0.0.0-dev.1) (2025-03-12)
+### Features
+
+* support linux ([e8a8b08](https://github.com/AgoraIO-Extensions/Electron-SDK/commit/e8a8b08bc7cae8b1fa44404d3a310b562e39821b))
+* support linux for 4.5.40 ([30dc852](https://github.com/AgoraIO-Extensions/Electron-SDK/commit/30dc85218e4232357dde488e546a364d573f4789))
+
+## [4.5.2-build.131-rc.1](https://github.com/AgoraIO-Extensions/Electron-SDK/compare/v4.5.1-build.132-rc.1...v4.5.2-build.131-rc.1) (2025-04-27)
+
+## [4.5.1-build.132-rc.1](https://github.com/AgoraIO-Extensions/Electron-SDK/compare/v4.5.2...v4.5.1-build.132-rc.1) (2025-04-23)
 
 
 ### Features
 
-* downlaod.js ([7e49fa6](https://github.com/AgoraIO-Extensions/Electron-SDK/commit/7e49fa659c11f219e3d333112c9ae515651ee8f4))
-* remove pwd ([37e5d44](https://github.com/AgoraIO-Extensions/Electron-SDK/commit/37e5d446542a42509f87e571142da93082751df2))
-* roll back example ([b0e7948](https://github.com/AgoraIO-Extensions/Electron-SDK/commit/b0e79486d51629228465ad81c0e66ee65d3f3bdb))
-* update dependencies ([33cf7f6](https://github.com/AgoraIO-Extensions/Electron-SDK/commit/33cf7f683e437484c67a0835222f37bf324f0f0e))
+* support 4.5.1.132 ([#1287](https://github.com/AgoraIO-Extensions/Electron-SDK/issues/1287)) ([54b9e83](https://github.com/AgoraIO-Extensions/Electron-SDK/commit/54b9e830e3f1268f2fbe2f59e354333fdade1262)), closes [#1285](https://github.com/AgoraIO-Extensions/Electron-SDK/issues/1285) [#1286](https://github.com/AgoraIO-Extensions/Electron-SDK/issues/1286)
 
 ## [4.5.2](https://github.com/AgoraIO-Extensions/Electron-SDK/compare/v4.5.1...v4.5.2) (2025-03-11)
 

package/js/AgoraSdk.js

@@ -41,7 +41,7 @@ const instance = new RtcEngineExInternal_1.RtcEngineExInternal();
  * Currently, the Agora RTC SDK v4.x supports creating only one IRtcEngineEx object for each app.
  *
  * @returns
- * One IRtcEngineEx object.
+ * IRtcEngineEx object.
  */
 function createAgoraRtcEngine(options) {
     Object.assign(Utils_1.AgoraEnv, options);

package/js/Private/AgoraBase.js

@@ -1082,11 +1082,11 @@ var H264PacketizeMode;
 var VideoStreamType;
 (function (VideoStreamType) {
     /**
-     * 0: High-quality video stream.
+     * 0: High-quality video stream, that is, a video stream with the highest resolution and bitrate.
      */
     VideoStreamType[VideoStreamType["VideoStreamHigh"] = 0] = "VideoStreamHigh";
     /**
-     * 1: Low-quality video stream.
+     * 1: Low-quality video stream, that is, a video stream with the lowest resolution and bitrate.
      */
     VideoStreamType[VideoStreamType["VideoStreamLow"] = 1] = "VideoStreamLow";
     /**
@@ -1409,7 +1409,9 @@ class WatermarkRatio {
 }
 exports.WatermarkRatio = WatermarkRatio;
 /**
- * Configurations of the watermark image.
+ * Watermark image configurations.
+ *
+ * Configuration options for setting the watermark image to be added.
  */
 class WatermarkOptions {
 }
@@ -1682,7 +1684,7 @@ var VideoApplicationScenarioType;
      */
     VideoApplicationScenarioType[VideoApplicationScenarioType["ApplicationScenarioMeeting"] = 1] = "ApplicationScenarioMeeting";
     /**
-     * ApplicationScenario1v1 (2) This is applicable to the scenario. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. 2: 1v1 video call scenario.
+     * ApplicationScenario1v1 (2) This is applicable to the scenario. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. This enumeration value is only applicable to the broadcaster vs. broadcaster scenario. 2: 1v1 video call scenario.
      */
     VideoApplicationScenarioType[VideoApplicationScenarioType["ApplicationScenario1v1"] = 2] = "ApplicationScenario1v1";
     /**
@@ -1947,7 +1949,7 @@ var LocalVideoStreamReason;
      */
     LocalVideoStreamReason[LocalVideoStreamReason["LocalVideoStreamReasonScreenCaptureNoPermission"] = 22] = "LocalVideoStreamReasonScreenCaptureNoPermission";
     /**
-     * 24: (Windows only) An unexpected error occurred during screen sharing (possibly due to window blocking failure), resulting in decreased performance, but the screen sharing process itself was not affected.
+     * 24: (Windows only) An unexpected error occurred during screen sharing (possibly due to window blocking failure), resulting in decreased performance, but the screen sharing process itself was not affected. During screen sharing, if blocking a specific window fails due to device driver issues, the SDK will report this event and automatically fall back to sharing the entire screen. If your use case requires masking specific windows to protect privacy, we recommend listening for this event and implementing additional privacy protection mechanisms when it is triggered.
      */
     LocalVideoStreamReason[LocalVideoStreamReason["LocalVideoStreamReasonScreenCaptureAutoFallback"] = 24] = "LocalVideoStreamReasonScreenCaptureAutoFallback";
     /**
@@ -2795,7 +2797,7 @@ var VideoViewSetupMode;
      */
     VideoViewSetupMode[VideoViewSetupMode["VideoViewSetupAdd"] = 1] = "VideoViewSetupAdd";
     /**
-     * 2: Deletes a view.
+     * 2: Deletes a view. When you no longer need to use a certain view, it is recommended to delete the view by setting setupMode to VideoViewSetupRemove, otherwise it may lead to leak of rendering resources.
      */
     VideoViewSetupMode[VideoViewSetupMode["VideoViewSetupRemove"] = 2] = "VideoViewSetupRemove";
 })(VideoViewSetupMode = exports.VideoViewSetupMode || (exports.VideoViewSetupMode = {}));

package/js/Private/AgoraMediaPlayerTypes.js

@@ -245,6 +245,10 @@ var MediaPlayerEvent;
      * @ignore
      */
     MediaPlayerEvent[MediaPlayerEvent["PlayerEventTryOpenFailed"] = 18] = "PlayerEventTryOpenFailed";
+    /**
+     * @ignore
+     */
+    MediaPlayerEvent[MediaPlayerEvent["PlayerEventHttpRedirect"] = 19] = "PlayerEventHttpRedirect";
 })(MediaPlayerEvent = exports.MediaPlayerEvent || (exports.MediaPlayerEvent = {}));
 /**
  * Events that occur when media resources are preloaded.

package/js/Renderer/RendererCache.js

@@ -11,7 +11,7 @@ class RendererCache extends IRendererCache_1.IRendererCache {
             yBuffer: Buffer.alloc(0),
             uBuffer: Buffer.alloc(0),
             vBuffer: Buffer.alloc(0),
-            alphaBuffer: Utils_1.AgoraEnv.encodeAlpha ? Buffer.alloc(0) : undefined,
+            alphaBuffer: Buffer.alloc(0),
             width: 0,
             height: 0,
             yStride: 0,
@@ -74,7 +74,16 @@ class RendererCache extends IRendererCache_1.IRendererCache {
                 return;
         }
         if (!Utils_1.AgoraEnv.encodeAlpha) {
-            this.videoFrame.alphaBuffer = undefined;
+            if (this.videoFrame.alphaBuffer &&
+                this.videoFrame.alphaBuffer.length > 0) {
+                this.videoFrame.alphaBuffer = Buffer.alloc(0);
+            }
+        }
+        else {
+            if (!this.videoFrame.alphaBuffer ||
+                this.videoFrame.alphaBuffer.length === 0) {
+                this.videoFrame.alphaBuffer = Buffer.alloc(this.videoFrame.width * this.videoFrame.height);
+            }
         }
         if (isNewFrame) {
             this.renderers.forEach((renderer) => {

package/js/Renderer/WebGLRenderer/index.js

@@ -188,7 +188,7 @@ class WebGLRenderer extends IRenderer_1.IRenderer {
                 pixels: vBuffer,
             },
         };
-        if (alphaBuffer) {
+        if (alphaBuffer && alphaBuffer.length > 0) {
             textures[this.gl.TEXTURE3] = {
                 texture: this.aTexture,
                 stride: width,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agora-electron-sdk",
-  "version": "4.5.2-dev.2",
+  "version": "4.5.40-rc.1",
   "description": "agora-electron-sdk",
   "main": "js/AgoraSdk",
   "types": "types/AgoraSdk.d.ts",
@@ -33,8 +33,8 @@
     "build_windows_win32_release": "cmake-js rebuild --arch=ia32 --CDCMAKE_OSX_ARCHITECTURES=\"i386\" --CDCMAKE_BUILD_TYPE=Release",
     "build_windows_x64_debug": "cmake-js rebuild --arch=x64 --CDCMAKE_OSX_ARCHITECTURES=\"x86_64\" --CDCMAKE_BUILD_TYPE=Debug -G \"Visual Studio 16 2019\"",
     "build_windows_x64_release": "cmake-js rebuild --arch=x64 --CDCMAKE_OSX_ARCHITECTURES=\"x86_64\" --CDCMAKE_BUILD_TYPE=Release",
-    "build_linux_debug": "cmake-js rebuild --arch=x64 --CDCMAKE_BUILD_TYPE=Debug -G \"Unix Makefiles\"",
-    "build_linux_release": "cmake-js rebuild --arch=x64 --CDCMAKE_BUILD_TYPE=Release -G \"Unix Makefiles\"",
+    "build_linux_debug": "cmake-js rebuild --arch=x64 --CDCMAKE_OSX_ARCHITECTURES=\"x86_64\" --CDCMAKE_BUILD_TYPE=Debug -G \"Unix Makefiles\"",
+    "build_linux_release": "cmake-js rebuild --arch=x64 --CDCMAKE_OSX_ARCHITECTURES=\"x86_64\" --CDCMAKE_BUILD_TYPE=Release -G \"Unix Makefiles\"",
     "test": "jest",
     "typecheck": "tsc --noEmit",
     "lint": "eslint \"**/*.{js,ts,tsx}\"",
@@ -159,9 +159,11 @@
     "pify": "^4.0.1"
   },
   "agora_electron": {
-    "iris_sdk_win": "https://download.agora.io/sdk/release/iris_4.5.1-build.1_DCG_Windows_Video_Standalone_20250305_1103_622.zip",
-    "iris_sdk_mac": "https://download.agora.io/sdk/release/iris_4.5.1-build.1_DCG_Mac_Video_Standalone_20250305_1105_590.zip",
-    "native_sdk_win": "https://download.agora.io/sdk/release/Agora_Native_SDK_for_Windows_v4.5.1_FULL.zip",
-    "native_sdk_mac": "https://download.agora.io/sdk/release/Agora_Native_SDK_for_Mac_v4.5.1_FULL.zip"
+    "iris_sdk_win": "https://download.agora.io/sdk/release/iris_4.5.40-build.1_DCG_Windows_Video_Standalone_20250924_0622_31777.zip",
+    "iris_sdk_mac": "https://download.agora.io/sdk/release/iris_4.5.40-build.1_DCG_Mac_Video_Standalone_20250924_0622_32713.zip",
+    "native_sdk_win": "https://download.agora.io/sdk/release/Agora_Native_SDK_for_Windows_rel.v4.5.40_30192_FULL_20250923_1742_897771.zip",
+    "native_sdk_mac": "https://download.agora.io/sdk/release/Agora_Native_SDK_for_Mac_rel.v4.5.40_25593_FULL_20250923_1743_897773.zip",
+    "iris_sdk_linux": "https://download.agora.io/sdk/release/iris_4.5.40-build.1_DCG_Linux_Video_Standalone_20250924_0622_3524.zip",
+    "native_sdk_linux": "https://download.agora.io/sdk/release/Agora_Native_SDK_for_Linux_rel.v4.5.40_26488_FULL_20250922_1709_896225_external.zip"
   }
 }

package/scripts/build.js

@@ -23,6 +23,9 @@ const build = async (cb) => {
           : 'build_windows_win32_release';
       }
       break;
+    case 'linux':
+      scriptStr = debug ? 'build_linux_debug' : 'build_linux_release';
+      break;
     default:
       break;
   }

package/scripts/download.js

@@ -67,7 +67,9 @@ module.exports = (uri, output, opts) => {
     rejectUnauthorized: process.env.npm_config_strict_ssl !== 'false',
   };
 
-  const stream = got.stream(uri);
+  const stream = got.stream(uri, {
+    headers: opts.headers,
+  });
 
   const promise = pEvent(stream, 'response')
     .then((res) => {

package/scripts/synclib.js

@@ -9,7 +9,26 @@ const { getOS, moveFile, getIrisStandAlone } = require('./util');
 
 const config = getConfig();
 
-const { iris_sdk_mac, iris_sdk_win, native_sdk_mac, native_sdk_win } = config;
+const {
+  iris_sdk_mac,
+  iris_sdk_win,
+  native_sdk_mac,
+  native_sdk_win,
+  iris_sdk_linux,
+  native_sdk_linux,
+} = config;
+
+const IRIS_SDK_URLS = {
+  mac: iris_sdk_mac,
+  win32: iris_sdk_win,
+  linux: iris_sdk_linux,
+};
+
+const NATIVE_SDK_URLS = {
+  mac: native_sdk_mac,
+  win32: native_sdk_win,
+  linux: native_sdk_linux,
+};
 
 const downloadSDK = async ({
   preHook,
@@ -21,6 +40,9 @@ const downloadSDK = async ({
   logger.info(`Downloading:${sdkURL}`);
   await preHook();
   await download(sdkURL, destDir, {
+    headers: {
+      'X-JFrog-Art-Api': process.env.JFROG_API_KEY || '',
+    },
     strip: strip,
     extract: true,
     //https://github.com/kevva/decompress/issues/68
@@ -47,7 +69,7 @@ const syncLib = async (cb) => {
         cleanDir(destNativeSDKDir);
       }
     },
-    sdkURL: os === 'mac' ? iris_sdk_mac : iris_sdk_win,
+    sdkURL: IRIS_SDK_URLS[os],
     destDir: destIrisSDKDir,
   });
   if (irisStandAlone) {
@@ -56,7 +78,7 @@ const syncLib = async (cb) => {
         cleanDir(destNativeSDKDir);
       },
       strip: 0,
-      sdkURL: os === 'mac' ? native_sdk_mac : native_sdk_win,
+      sdkURL: NATIVE_SDK_URLS[os],
       destDir: destNativeSDKDir,
     });
   } else {

package/scripts/util.js

@@ -28,7 +28,7 @@ exports.moveFile = (sp, tp) => {
 };
 
 exports.getIrisStandAlone = () => {
-  const { iris_sdk_mac, iris_sdk_win } = getConfig();
+  const { iris_sdk_mac, iris_sdk_win, iris_sdk_linux } = getConfig();
   const os = this.getOS();
   if (
     (os === 'mac' &&
@@ -36,7 +36,10 @@ exports.getIrisStandAlone = () => {
       iris_sdk_mac.toLowerCase().indexOf('standalone') !== -1) ||
     (os === 'win32' &&
       iris_sdk_win &&
-      iris_sdk_win.toLowerCase().indexOf('standalone') !== -1)
+      iris_sdk_win.toLowerCase().indexOf('standalone') !== -1) ||
+    (os === 'linux' &&
+      iris_sdk_linux &&
+      iris_sdk_linux.toLowerCase().indexOf('standalone') !== -1)
   ) {
     logger.info('iris use standalone package');
     return true;

package/ts/AgoraSdk.ts

@@ -30,7 +30,7 @@ const instance = new RtcEngineExInternal();
  * Currently, the Agora RTC SDK v4.x supports creating only one IRtcEngineEx object for each app.
  *
  * @returns
- * One IRtcEngineEx object.
+ * IRtcEngineEx object.
  */
 export function createAgoraRtcEngine(options?: AgoraEnvOptions): IRtcEngineEx {
   Object.assign(AgoraEnv, options);

package/ts/Private/AgoraBase.ts

@@ -1154,11 +1154,11 @@ export enum H264PacketizeMode {
  */
 export enum VideoStreamType {
   /**
-   * 0: High-quality video stream.
+   * 0: High-quality video stream, that is, a video stream with the highest resolution and bitrate.
    */
   VideoStreamHigh = 0,
   /**
-   * 1: Low-quality video stream.
+   * 1: Low-quality video stream, that is, a video stream with the lowest resolution and bitrate.
    */
   VideoStreamLow = 1,
   /**
@@ -1558,7 +1558,7 @@ export class SimulcastStreamConfig {
    */
   dimensions?: VideoDimensions;
   /**
-   * Video receive bitrate (Kbps), represented by an instantaneous value. This parameter does not need to be set. The SDK automatically matches the most suitable bitrate based on the video resolution and frame rate you set.
+   * Video bitrate (Kbps). The default value is -1. This parameter does not need to be set. The SDK automatically matches the most suitable bitrate based on the video resolution and frame rate you set.
    */
   kBitrate?: number;
   /**
@@ -1678,7 +1678,9 @@ export class WatermarkRatio {
 }
 
 /**
- * Configurations of the watermark image.
+ * Watermark image configurations.
+ *
+ * Configuration options for setting the watermark image to be added.
  */
 export class WatermarkOptions {
   /**
@@ -2120,7 +2122,7 @@ export enum VideoApplicationScenarioType {
    */
   ApplicationScenarioMeeting = 1,
   /**
-   * ApplicationScenario1v1 (2) This is applicable to the scenario. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. 2: 1v1 video call scenario.
+   * ApplicationScenario1v1 (2) This is applicable to the scenario. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. This enumeration value is only applicable to the broadcaster vs. broadcaster scenario. 2: 1v1 video call scenario.
    */
   ApplicationScenario1v1 = 2,
   /**
@@ -2385,7 +2387,7 @@ export enum LocalVideoStreamReason {
    */
   LocalVideoStreamReasonScreenCaptureNoPermission = 22,
   /**
-   * 24: (Windows only) An unexpected error occurred during screen sharing (possibly due to window blocking failure), resulting in decreased performance, but the screen sharing process itself was not affected.
+   * 24: (Windows only) An unexpected error occurred during screen sharing (possibly due to window blocking failure), resulting in decreased performance, but the screen sharing process itself was not affected. During screen sharing, if blocking a specific window fails due to device driver issues, the SDK will report this event and automatically fall back to sharing the entire screen. If your use case requires masking specific windows to protect privacy, we recommend listening for this event and implementing additional privacy protection mechanisms when it is triggered.
    */
   LocalVideoStreamReasonScreenCaptureAutoFallback = 24,
   /**
@@ -3664,7 +3666,7 @@ export enum VideoViewSetupMode {
    */
   VideoViewSetupAdd = 1,
   /**
-   * 2: Deletes a view.
+   * 2: Deletes a view. When you no longer need to use a certain view, it is recommended to delete the view by setting setupMode to VideoViewSetupRemove, otherwise it may lead to leak of rendering resources.
    */
   VideoViewSetupRemove = 2,
 }
@@ -3686,7 +3688,7 @@ export class VideoCanvas {
    */
   view?: any;
   /**
-   * The background color of the video canvas in RGBA format. The default value is 0x00000000, which represents completely transparent black.
+   * The background color of the video canvas in RGBA format. The default value is 0x00000000, which represents black.
    */
   backgroundColor?: number;
   /**

package/ts/Private/AgoraMediaBase.ts

@@ -429,6 +429,10 @@ export class AudioPcmFrame {
    * The number of audio channels.
    */
   num_channels_?: number;
+  /**
+   * @ignore
+   */
+  audio_track_number_?: number;
   /**
    * The number of bytes per sample.
    */

package/ts/Private/AgoraMediaPlayerTypes.ts

@@ -242,6 +242,10 @@ export enum MediaPlayerEvent {
    * @ignore
    */
   PlayerEventTryOpenFailed = 18,
+  /**
+   * @ignore
+   */
+  PlayerEventHttpRedirect = 19,
 }
 
 /**

package/ts/Private/IAgoraMediaEngine.ts

@@ -235,14 +235,14 @@ export abstract class IMediaEngine {
    * Pushes the external raw video frame to the SDK through video tracks.
    *
    * To publish a custom video source, see the following steps:
-   *  Call createCustomVideoTrack to create a video track and get the video track ID.
+   *  Call createCustomVideoTrack to create a video track and get the video track ID. If you only need to push one custom video source to the channel, you can directly call the setExternalVideoSource method and the SDK will automatically create a video track with the videoTrackId set to 0.
    *  Call joinChannel to join the channel. In ChannelMediaOptions, set customVideoTrackId to the video track ID that you want to publish, and set publishCustomVideoTrack to true.
    *  Call this method and specify videoTrackId as the video track ID set in step 2. You can then publish the corresponding custom video source in the channel. After calling this method, even if you stop pushing external video frames to the SDK, the custom video stream will still be counted as the video duration usage and incur charges. Agora recommends that you take appropriate measures based on the actual situation to avoid such video billing.
    *  If you no longer need to capture external video data, you can call destroyCustomVideoTrack to destroy the custom video track.
    *  If you only want to use the external video data for local preview and not publish it in the channel, you can call muteLocalVideoStream to cancel sending video stream or call updateChannelMediaOptions to set publishCustomVideoTrack to false.
    *
    * @param frame The external raw video frame to be pushed. See ExternalVideoFrame.
-   * @param videoTrackId The video track ID returned by calling the createCustomVideoTrack method. The default value is 0.
+   * @param videoTrackId The video track ID returned by calling the createCustomVideoTrack method. If you only need to push one custom video source, set videoTrackId to 0.
    *
    * @returns
    * 0: Success.

package/ts/Private/IAgoraMediaPlayer.ts

@@ -154,7 +154,7 @@ export abstract class IMediaPlayer {
    * @param index The index of the media stream. This parameter must be less than the return value of getStreamCount.
    *
    * @returns
-   * If the call succeeds, returns the detailed information of the media stream. See PlayerStreamInfo. null, if the method call fails.
+   * If the call succeeds, returns the detailed information of the media stream. See PlayerStreamInfo. null is returned, if the method call fails.
    */
   abstract getStreamInfo(index: number): PlayerStreamInfo;
 

package/ts/Private/IAgoraRtcEngine.ts

@@ -1488,7 +1488,7 @@ export interface IRtcEngineEventHandler {
    *
    * This callback occurs when the local audio effect file finishes playing.
    *
-   * @param soundId The ID of the audio effect. The ID of each audio effect file is unique.
+   * @param soundId The ID of the audio effect. The unique ID of each audio effect file.
    */
   onAudioEffectFinished?(soundId: number): void;
 
@@ -2970,7 +2970,7 @@ export abstract class IRtcEngine {
    * Gets the SDK version.
    *
    * @returns
-   * One SDKBuildInfo object.
+   * SDKBuildInfo object.
    */
   abstract getVersion(): SDKBuildInfo;
 
@@ -3146,7 +3146,7 @@ export abstract class IRtcEngine {
   /**
    * Renews the token.
    *
-   * You can call this method to pass a new token to the SDK. A token will expire after a certain period of time, at which point the SDK will be unable to establish a connection with the server.
+   * This method is used to update the token. After successfully calling this method, the SDK will trigger the callback. A token will expire after a certain period of time, at which point the SDK will be unable to establish a connection with the server.
    *
    * @param token The new token.
    *
@@ -3457,6 +3457,7 @@ export abstract class IRtcEngine {
    * Enables/Disables the virtual background.
    *
    * The virtual background feature enables the local user to replace their original background with a static image, dynamic video, blurred background, or portrait-background segmentation to achieve picture-in-picture effect. Once the virtual background feature is enabled, all users in the channel can see the custom background. Call this method after calling enableVideo or startPreview.
+   *  Using a video as a your virtual background will lead to continuous increase in memory usage, which may cause issues such as app crashes. Therefore,it is recommended to reduce the resolution and frame rate of the video when using it.
    *  This feature has high requirements on device performance. When calling this method, the SDK automatically checks the capabilities of the current device. Agora recommends you use virtual background on devices with the following processors:
    *  Devices with an i5 CPU and better
    *  Agora recommends that you use this feature in scenarios that meet the following conditions:
@@ -3529,7 +3530,7 @@ export abstract class IRtcEngine {
    *  If someone subscribes to the low-quality stream, the SDK enables the low-quality stream and resets it to the SimulcastStreamConfig configuration used in the most recent calling of setDualStreamMode. If no configuration has been set by the user previously, the following values are used:
    *  Resolution: 480 × 272
    *  Frame rate: 15 fps
-   *  Bitrate: 500 Kbps ApplicationScenario1v1 (2) This is applicable to the scenario. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. ApplicationScenarioLiveshow (3) This is applicable to the scenario. In this scenario, fast video rendering and high image quality are crucial. The SDK implements several performance optimizations, including automatically enabling accelerated audio and video frame rendering to minimize first-frame latency (no need to call enableInstantMediaRendering), and B-frame encoding to achieve better image quality and bandwidth efficiency. The SDK also provides enhanced video quality and smooth playback, even in poor network conditions or on lower-end devices.
+   *  Bitrate: 500 Kbps ApplicationScenario1v1 (2) This is applicable to the scenario. To meet the requirements for low latency and high-quality video in this scenario, the SDK optimizes its strategies, improving performance in terms of video quality, first frame rendering, latency on mid-to-low-end devices, and smoothness under weak network conditions. This enumeration value is only applicable to the broadcaster vs. broadcaster scenario. ApplicationScenarioLiveshow (3) This is applicable to the scenario. In this scenario, fast video rendering and high image quality are crucial. The SDK implements several performance optimizations, including automatically enabling accelerated audio and video frame rendering to minimize first-frame latency (no need to call enableInstantMediaRendering), and B-frame encoding to achieve better image quality and bandwidth efficiency. The SDK also provides enhanced video quality and smooth playback, even in poor network conditions or on lower-end devices.
    *
    * @returns
    * 0: Success.
@@ -3661,7 +3662,7 @@ export abstract class IRtcEngine {
    * Enables/Disables the local video capture.
    *
    * This method disables or re-enables the local video capture, and does not affect receiving the remote video stream. After calling enableVideo, the local video capture is enabled by default. If you call enableLocalVideo (false) to disable local video capture within the channel, it also simultaneously stops publishing the video stream within the channel. If you want to restart video catpure, you can call enableLocalVideo (true) and then call updateChannelMediaOptions to set the options parameter to publish the locally captured video stream in the channel. After the local video capturer is successfully disabled or re-enabled, the SDK triggers the onRemoteVideoStateChanged callback on the remote client.
-   *  You can call this method either before or after joining a channel.
+   *  You can call this method either before or after joining a channel. However, if you call it before joining, the settings will only take effect once you have joined the channel.
    *  This method enables the internal engine and is valid after leaving the channel.
    *
    * @param enabled Whether to enable the local video capture. true : (Default) Enable the local video capture. false : Disable the local video capture. Once the local video is disabled, the remote users cannot receive the video stream of the local user, while the local user can still receive the video streams of remote users. When set to false, this method does not require a local camera.
@@ -3912,7 +3913,7 @@ export abstract class IRtcEngine {
   /**
    * Destroys the media player instance.
    *
-   * @param mediaPlayer One IMediaPlayer object.
+   * @param mediaPlayer IMediaPlayer object.
    *
    * @returns
    * ≥ 0: Success. Returns the ID of media player instance.
@@ -4277,7 +4278,7 @@ export abstract class IRtcEngine {
   /**
    * Gets the volume of a specified audio effect file.
    *
-   * @param soundId The ID of the audio effect. The ID of each audio effect file is unique.
+   * @param soundId The ID of the audio effect. The unique ID of each audio effect file.
    * @param volume The playback volume. The value range is [0, 100]. The default value is 100, which represents the original volume.
    *
    * @returns
@@ -6059,7 +6060,7 @@ export abstract class IRtcEngine {
    *  Each client within the channel can have up to 5 data channels simultaneously, with a total shared packet bitrate limit of 30 KB/s for all data channels.
    *  Each data channel can send up to 60 packets per second, with each packet being a maximum of 1 KB. A successful method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message. A failed method call triggers the onStreamMessageError callback on the remote client.
    *  This method needs to be called after createDataStream and joining the channel.
-   *  In live streaming scenarios, this method only applies to hosts.
+   *  This method applies to broadcasters only.
    *
    * @param streamId The data stream ID. You can get the data stream ID by calling createDataStream.
    * @param data The message to be sent.
@@ -6078,7 +6079,7 @@ export abstract class IRtcEngine {
   /**
    * Adds a watermark image to the local video.
    *
-   * This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one. The watermark coordinates are dependent on the settings in the setVideoEncoderConfiguration method:
+   * This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. The Agora SDK supports adding only one watermark image onto a live video stream. The newly added watermark image replaces the previous one. The watermark coordinates are dependent on the settings in the setVideoEncoderConfiguration method:
    *  If the orientation mode of the encoding video (OrientationMode) is fixed landscape mode or the adaptive landscape mode, the watermark uses the landscape orientation.
    *  If the orientation mode of the encoding video (OrientationMode) is fixed portrait mode or the adaptive portrait mode, the watermark uses the portrait orientation.
    *  When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfiguration method; otherwise, the watermark image will be cropped.
@@ -6226,6 +6227,7 @@ export abstract class IRtcEngine {
    * Once registered, the user account can be used to identify the local user when the user joins the channel. After the registration is successful, the user account can identify the identity of the local user, and the user can use it to join the channel. This method is optional. If you want to join a channel using a user account, you can choose one of the following methods:
    *  Call the registerLocalUserAccount method to register a user account, and then call the joinChannelWithUserAccount method to join a channel, which can shorten the time it takes to enter the channel.
    *  Call the joinChannelWithUserAccount method to join a channel.
+   *  Starting from v4.6.0, the SDK will no longer automatically map Int UID to the String userAccount used when registering a User Account. If you want to join a channel with the original String userAccount used during registration, call the joinChannelWithUserAccount method to join the channel, instead of calling joinChannel and pass in the Int UID obtained through this method
    *  Ensure that the userAccount is unique in the channel.
    *  To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a UID, then ensure all the other users use the UID too. The same applies to the user account. If a user joins the channel with the Agora Web SDK, ensure that the ID of the user is set to the same parameter type.
    *
@@ -6680,8 +6682,8 @@ export abstract class IRtcEngine {
    * Enables tracing the video frame rendering process.
    *
    * The SDK starts tracing the rendering status of the video frames in the channel from the moment this method is successfully called and reports information about the event through the onVideoRenderingTracingResult callback.
-   *  The SDK automatically starts tracking the rendering events of the video from the moment that you call joinChannel to join the channel. You can call this method at an appropriate time according to the actual application scenario to customize the tracing process.
-   *  After the local user leaves the current channel, the SDK automatically resets the time point to the next time when the user successfully joins the channel.
+   *  If you have not called this method, the SDK tracks the rendering events of the video frames from the moment you call joinChannel to join the channel. You can call this method at an appropriate time according to the actual application scenario to set the starting position for tracking video rendering events.
+   *  After the local user leaves the current channel, the SDK automatically tracks the video rendering events from the moment you join a channel.
    *
    * @returns
    * 0: Success.

package/ts/Private/IAgoraRtcEngineEx.ts

@@ -202,9 +202,7 @@ export abstract class IRtcEngineEx extends IRtcEngine {
    * The SDK will dynamically adjust the size of the corresponding video stream based on the size of the video window to save bandwidth and computing resources. The default aspect ratio of the low-quality video stream is the same as that of the high-quality video stream. According to the current aspect ratio of the high-quality video stream, the system will automatically allocate the resolution, frame rate, and bitrate of the low-quality video stream. Depending on the default behavior of the sender and the specific settings when calling setDualStreamMode, the scenarios for the receiver calling this method are as follows:
    *  The SDK enables low-quality video stream adaptive mode (AutoSimulcastStream) on the sender side by default, meaning only the high-quality video stream is transmitted. Only the receiver with the role of the host can call this method to initiate a low-quality video stream request. Once the sender receives the request, it starts automatically sending the low-quality video stream. At this point, all users in the channel can call this method to switch to low-quality video stream subscription mode.
    *  If the sender calls setDualStreamMode and sets mode to DisableSimulcastStream (never send low-quality video stream), then calling this method will have no effect.
-   *  If the sender calls setDualStreamMode and sets mode to EnableSimulcastStream (always send low-quality video stream), both the host and audience receivers can call this method to switch to low-quality video stream subscription mode.
-   *  If the publisher has already called setDualStreamModeEx and set mode to DisableSimulcastStream (never send low-quality video stream), calling this method will not take effect, you should call setDualStreamModeEx again on the sending end and adjust the settings.
-   *  Calling this method on the receiving end of the audience role will not take effect.
+   *  If the sender calls setDualStreamMode and sets mode to EnableSimulcastStream (always send low-quality video stream), both the host and audience receivers can call this method to switch to low-quality video stream subscription mode. If the publisher has already called setDualStreamModeEx and set mode to DisableSimulcastStream (never send low-quality video stream), calling this method will not take effect, you should call setDualStreamModeEx again on the sending end and adjust the settings.
    *
    * @param uid The user ID.
    * @param streamType The video stream type, see VideoStreamType.
@@ -572,7 +570,6 @@ export abstract class IRtcEngineEx extends IRtcEngine {
    *  Each data channel can send up to 60 packets per second, with each packet being a maximum of 1 KB. After calling createDataStreamEx, you can call this method to send data stream messages to all users in the channel.
    *  Call this method after joinChannelEx.
    *  Ensure that you call createDataStreamEx to create a data channel before calling this method.
-   *  This method applies only to the COMMUNICATION profile or to the hosts in the LIVE_BROADCASTING profile. If an audience in the LIVE_BROADCASTING profile calls this method, the audience may be switched to a host.
    *
    * @param streamId The data stream ID. You can get the data stream ID by calling createDataStreamEx.
    * @param data The message to be sent.
@@ -593,7 +590,7 @@ export abstract class IRtcEngineEx extends IRtcEngine {
   /**
    * Adds a watermark image to the local video.
    *
-   * This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one. The watermark coordinates are dependent on the settings in the setVideoEncoderConfigurationEx method:
+   * This method adds a PNG watermark image to the local video in the live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the capturing device can see and capture it. The Agora SDK supports adding only one watermark image onto a live video stream. The newly added watermark image replaces the previous one. The watermark coordinates are dependent on the settings in the setVideoEncoderConfigurationEx method:
    *  If the orientation mode of the encoding video (OrientationMode) is fixed landscape mode or the adaptive landscape mode, the watermark uses the landscape orientation.
    *  If the orientation mode of the encoding video (OrientationMode) is fixed portrait mode or the adaptive portrait mode, the watermark uses the portrait orientation.
    *  When setting the watermark position, the region must be less than the dimensions set in the setVideoEncoderConfigurationEx method; otherwise, the watermark image will be cropped.
@@ -930,8 +927,8 @@ export abstract class IRtcEngineEx extends IRtcEngine {
   /**
    * Enables tracing the video frame rendering process.
    *
-   * The SDK automatically starts tracking the rendering events of the video from the moment that you call joinChannel to join the channel. You can call this method at an appropriate time according to the actual application scenario to customize the tracing process.
-   *  After the local user leaves the current channel, the SDK automatically resets the time point to the next time when the user successfully joins the channel. The SDK starts tracing the rendering status of the video frames in the channel from the moment this method is successfully called and reports information about the event through the onVideoRenderingTracingResult callback.
+   * If you have not called this method, the SDK tracks the rendering events of the video frames from the moment you call joinChannel to join the channel. You can call this method at an appropriate time according to the actual application scenario to set the starting position for tracking video rendering events.
+   *  After the local user leaves the current channel, the SDK automatically tracks the video rendering events from the moment you join a channel. The SDK starts tracing the rendering status of the video frames in the channel from the moment this method is successfully called and reports information about the event through the onVideoRenderingTracingResult callback.
    *
    * @param connection The connection information. See RtcConnection.
    *

package/ts/Renderer/RendererCache.ts

@@ -17,7 +17,7 @@ export class RendererCache extends IRendererCache {
       yBuffer: Buffer.alloc(0),
       uBuffer: Buffer.alloc(0),
       vBuffer: Buffer.alloc(0),
-      alphaBuffer: AgoraEnv.encodeAlpha ? Buffer.alloc(0) : undefined,
+      alphaBuffer: Buffer.alloc(0),
       width: 0,
       height: 0,
       yStride: 0,
@@ -95,7 +95,21 @@ export class RendererCache extends IRendererCache {
     }
 
     if (!AgoraEnv.encodeAlpha) {
-      this.videoFrame.alphaBuffer = undefined;
+      if (
+        this.videoFrame.alphaBuffer &&
+        this.videoFrame.alphaBuffer.length > 0
+      ) {
+        this.videoFrame.alphaBuffer = Buffer.alloc(0);
+      }
+    } else {
+      if (
+        !this.videoFrame.alphaBuffer ||
+        this.videoFrame.alphaBuffer.length === 0
+      ) {
+        this.videoFrame.alphaBuffer = Buffer.alloc(
+          this.videoFrame.width! * this.videoFrame.height!
+        );
+      }
     }
 
     if (isNewFrame) {

package/ts/Renderer/WebGLRenderer/index.ts

@@ -273,7 +273,7 @@ export class WebGLRenderer extends IRenderer {
         pixels: vBuffer!,
       },
     };
-    if (alphaBuffer) {
+    if (alphaBuffer && alphaBuffer.length > 0) {
       textures[this.gl.TEXTURE3] = {
         texture: this.aTexture,
         stride: width!,

package/types/AgoraSdk.d.ts

@@ -24,7 +24,7 @@ export * from './Utils';
  * Currently, the Agora RTC SDK v4.x supports creating only one IRtcEngineEx object for each app.
  *
  * @returns
- * One IRtcEngineEx object.
+ * IRtcEngineEx object.
  */
 export declare function createAgoraRtcEngine(options?: AgoraEnvOptions): IRtcEngineEx;
 /**