Package io.agora.rtc2

Class RtcEngineEx

java.lang.Object
io.agora.rtc2.RtcEngine
io.agora.rtc2.RtcEngineEx
Direct Known Subclasses:
RtcEngineInternal

public abstract class RtcEngineEx extends RtcEngine
  • Constructor Details

    • RtcEngineEx

      public RtcEngineEx()
  • Method Details

    • muteLocalAudioStreamEx

      public abstract int muteLocalAudioStreamEx(boolean muted, RtcConnection connection)
      Stops or resumes sending the local audio stream with connection.
      Parameters:
      mute - Determines whether to send or stop sending the local audio stream: - true: Stop sending the local audio stream. - false: Send the local audio stream.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • muteLocalVideoStreamEx

      public abstract int muteLocalVideoStreamEx(boolean muted, RtcConnection connection)
      Stops or resumes sending the local video stream with connection.
      Parameters:
      mute - Determines whether to send or stop sending the local video stream: - true: Stop sending the local video stream. - false: Send the local video stream.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • muteAllRemoteAudioStreamsEx

      public abstract int muteAllRemoteAudioStreamsEx(boolean muted, RtcConnection connection)
      Stops or resumes receiving all remote audio stream with connection.
      Parameters:
      mute - Whether to stop receiving remote audio streams: - true: Stop receiving any remote audio stream. - false: Resume receiving all remote audio streams.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • muteAllRemoteVideoStreamsEx

      public abstract int muteAllRemoteVideoStreamsEx(boolean muted, RtcConnection connection)
      Stops or resumes receiving all remote video stream with connection.
      Parameters:
      mute - Whether to stop receiving remote audio streams: - true: Stop receiving any remote audio stream. - false: Resume receiving all remote audio streams.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • muteRemoteAudioStreamEx

      public abstract int muteRemoteAudioStreamEx(int uid, boolean muted, RtcConnection connection)
      Stops or resumes receiving the audio stream of a specified user with specified connection.
      Parameters:
      uid - ID of the specified remote user.
      mute - Determines whether to receive or stop receiving the specified audio stream: - true: Stop receiving the specified audio stream. - false: (Default) Receive the specified audio stream.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • muteRemoteVideoStreamEx

      public abstract int muteRemoteVideoStreamEx(int uid, boolean muted, RtcConnection connection)
      Stops or resumes receiving the video stream of a specified user with specified connection.
      Parameters:
      uid - ID of the specified remote user.
      muted - Determines whether to receive or stop receiving a specified video stream: - true: Stop receiving the specified video stream. - false: (Default) Receive the specified video stream.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setRemoteVideoStreamTypeEx

      public abstract int setRemoteVideoStreamTypeEx(int uid, Constants.VideoStreamType streamType, RtcConnection connection)
      Sets the remote video stream type. If the remote user has enabled the dual-stream mode, by default the SDK receives the high-stream video by Call this method to switch to the low-stream video.
      Parameters:
      uid - ID of the remote user sending the video stream.
      streamType - Sets the video stream type: - 0: High-stream video. - 1: Low-stream video.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setRemoteVideoStreamTypeEx

      @Deprecated public abstract int setRemoteVideoStreamTypeEx(int uid, int streamType, RtcConnection connection)
      Deprecated.
    • setHighPriorityUserListEx

      public abstract int setHighPriorityUserListEx(int[] uidList, int option, RtcConnection connection)
      Sets the high priority user list and related fallback option for the remotely subscribed video stream based on the network conditions in NASA2.
      Parameters:
      uidList - The id list of high priority users.
      option - The remote subscribe fallback option of high priority users.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setSubscribeAudioBlocklistEx

      public abstract int setSubscribeAudioBlocklistEx(int[] uidList, RtcConnection connection)
      Sets the blocklist of subscribe remote stream audio.
      Parameters:
      uidList - The id list of users who do not subscribe to audio.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setSubscribeAudioAllowlistEx

      public abstract int setSubscribeAudioAllowlistEx(int[] uidList, RtcConnection connection)
      Sets the allowlist of subscribe remote stream audio.
      Parameters:
      uidList - The id list of users who do subscribe to audio.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setSubscribeVideoBlocklistEx

      public abstract int setSubscribeVideoBlocklistEx(int[] uidList, RtcConnection connection)
      Sets the blocklist of subscribe remote stream video.
      Parameters:
      uidList - The id list of users who do not subscribe to video.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setSubscribeVideoAllowlistEx

      public abstract int setSubscribeVideoAllowlistEx(int[] uidList, RtcConnection connection)
      Sets the whitelist of subscribe remote stream video.
      Parameters:
      uidList - The id list of users who do subscribe to video.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setRemoteRenderModeEx

      public abstract int setRemoteRenderModeEx(int uid, int renderMode, int mirrorMode, RtcConnection connection)
      Updates the display mode of the video view of a remote user with the specified connection. After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees.
      Parameters:
      uid - ID of the remote user.
      renderMode - Sets the remote display mode: - `RENDER_MODE_HIDDEN(1)`: Uniformly scale the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents. - `RENDER_MODE_FIT(2)`: Uniformly scale the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black.
      mirrorMode - Sets the remote video mirror mode: - `VIDEO_MIRROR_MODE_ENABLED(1)`: Enable the mirror mode. - `VIDEO_MIRROR_MODE_DISABLED(2)`: Disable the mirror mode.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setupRemoteVideoEx

      public abstract int setupRemoteVideoEx(VideoCanvas remote, RtcConnection connection)
      Initializes the video view of a remote user with a specified connection ID. This method initializes the video view of a remote stream on the local device. It affects only the video view that the local user sees. Usually the app should specify the `uid` of the remote video in the method call before the remote user joins the channel. If the remote `uid` is unknown to the app, set it later when the app receives the onUserJoined callback. To unbind the remote user from the view, set `view` in VideoCanvas as `null`.
      Parameters:
      remote - The remote video view settings: VideoCanvas.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setVideoEncoderConfigurationEx

      public abstract int setVideoEncoderConfigurationEx(VideoEncoderConfiguration config, RtcConnection connection)
      Sets the video encoder configuration with specified connection. Each configuration profile corresponds to a set of video parameters, including the resolution, frame rate, and bitrate. The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.
      Parameters:
      config - The local video encoder configuration: VideoEncoderConfiguration.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • updateChannelMediaOptionsEx

      public abstract int updateChannelMediaOptionsEx(ChannelMediaOptions options, RtcConnection connection)
      Updates the media options after joining the channel with specified connection.
      Parameters:
      options - The channel media options: ChannelMediaOptions.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • joinChannelEx

      public abstract int joinChannelEx(String token, RtcConnection connection, ChannelMediaOptions options, IRtcEngineEventHandler eventHandler)
      Joins a channel with the connection ID. You can call this method multiple times to join more than one channels at a time.
      Parameters:
      token - The token for authentication: - In situations not requiring high security: You can use the temporary token generated at Console. For details, see [Get a temporary token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#temptoken). - In situations requiring high security: Set it as the token generated at your server. For details, see [Get a token](https://docs.agora.io/en/Agora%20Platform/token?platform=All%20Platforms#generatetoken).
      connection - RtcConnection is used to control different connection instances * when you join the same channel multiple times
      options - The channel media options: ChannelMediaOptions.
      eventHandler - The pointer to the IRtcEngine event handler: IRtcEngineEventHandler.
      Returns:
      - 0: Success. - < 0: Failure.
    • leaveChannelEx

      public abstract int leaveChannelEx(RtcConnection connection)
      Leaves the channel with the specified connection ID.
      Parameters:
      connection - RtcConnection is used to control different connection instances * when you join the same channel multiple times
      Returns:
      - 0: Success. - < 0: Failure.
    • leaveChannelEx

      public abstract int leaveChannelEx(RtcConnection connection, LeaveChannelOptions options)
      Leaves the channel with the specified connection ID.
      Parameters:
      connection - RtcConnection is used to control different connection instances when you join the same channel multiple times
      options - The options for leaving the channel. See LeaveChannelOptions.
      Returns:
      - 0: Success. - < 0: Failure.
    • leaveChannelWithUserAccountEx

      public abstract int leaveChannelWithUserAccountEx(String channelId, String userAccount)
    • leaveChannelWithUserAccountEx

      public abstract int leaveChannelWithUserAccountEx(String channelId, String userAccount, LeaveChannelOptions options)
      Leaves a channel with the channel ID and user account and sets the options for leaving.
      Parameters:
      channelId - The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. - All numeric characters: 0 to 9. - The space character. - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
      userAccount - The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. - All numeric characters: 0 to 9. - The space character. - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
      options - The options for leaving the channel. See LeaveChannelOptions.
      Returns:
      - 0: Success. - < 0: Failure.
    • enableDualStreamModeEx

      @Deprecated public abstract int enableDualStreamModeEx(boolean enabled, SimulcastStreamConfig streamConfig, RtcConnection connection)
      Deprecated.
      v4.2.0. This method is deprecated. Use setDualStreamModeEx instead. If dual-stream mode is enabled, the subscriber can choose to receive the high-stream (high-resolution high-bitrate video stream) or low-stream (low-resolution low-bitrate video stream) video using setRemoteVideoStreamType.
      Enables or disables the dual video stream mode.
      Parameters:
      enabled - - true: Enable the dual-stream mode. - false: (default) Disable the dual-stream mode.
      streamConfig - - The minor stream config
      connection - - An output parameter which is used to control different connection instances.
    • setDualStreamModeEx

      public abstract int setDualStreamModeEx(Constants.SimulcastStreamMode mode, SimulcastStreamConfig streamConfig, RtcConnection connection)
      Enables, disables or auto enable the dual video stream mode. If dual-stream mode is enabled, the subscriber can choose to receive the high-stream (high-resolution high-bitrate video stream) or low-stream (low-resolution low-bitrate video stream) video using setRemoteVideoStreamType.
      Parameters:
      mode - - The dual-stream mode
      streamConfig - - The minor stream config
    • setSimulcastConfigEx

      public abstract int setSimulcastConfigEx(SimulcastConfig simulcastConfig, RtcConnection connection)
      Set the multi-layer video stream configuration. When users expect the same UID to send multiple streams of different resolutions, they can achieve this by calling setSimulcastConfig. If multi-layer is configed, the subscriber can choose to receive the corresponding layer of video stream using setRemoteVideoStreamType.
      Parameters:
      simulcastConfig - - The configuration for multi-layer video stream. It includes seven layers, ranging from STREAM_LAYER_1 to STREAM_LOW. A maximum of 3 layers can be enabled simultaneously.
      connection - The RtcConnection object.
      Returns:
      - 0: Success. - < 0: Failure.
      Since:
      v4.6.0
    • getConnectionStateEx

      public abstract int getConnectionStateEx(RtcConnection connection)
      Gets the connection state of the SDK.
      Parameters:
      connection - RtcConnection is used to control different connection instances.
      Returns:
      The connection state: - CONNECTION_STATE_DISCONNECTED(1): The SDK is disconnected from Agora's edge server. - CONNECTION_STATE_CONNECTING(2): The SDK is connecting to Agora's edge server. - CONNECTION_STATE_CONNECTED(3): The SDK joined a channel and is connected to Agora's edge server. You can now publish or subscribe to a media stream in the channel. - CONNECTION_STATE_RECONNECTING(4): The SDK keeps rejoining the channel after being disconnected from a joined channel because of network issues. - CONNECTION_STATE_FAILED(5): The SDK fails to join the channel.
    • sendCustomReportMessageEx

      public abstract int sendCustomReportMessageEx(String id, String category, String event, String label, int value, RtcConnection connection)
      Report custom event to argus.
      Parameters:
      id - Custom Event ID
      category - Custom Event category
      event - Custom Event to report
      label - Custom Event label
      value - Custom Event value
      connection - The connection ID.
      Returns:
      - 0: Success. - < 0: Failure.
    • sendStreamMessageEx

      public abstract int sendStreamMessageEx(int streamId, byte[] message, RtcConnection connection)
      Sends data stream messages to all users in a channel. Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB. The API controls the data channel transfer rate. Each client can send up to 6 kB of data per second. Each user can have up to five data channels simultaneously.
      Parameters:
      streamId - Stream ID
      message - Data to be sent.
      connection - Connection ID.
      Returns:
      - 0: Success. - < 0: Failure.
    • sendRdtMessageEx

      public abstract int sendRdtMessageEx(int uid, int type, byte[] message, RtcConnection connection)
      Parameters:
      uid - remote user id.
      type - Reliable Data Transmission tunnel message type.
      message - The sent data.
      connection - Connection ID.
      Returns:
      - 0: Success. - < 0: Failure.
    • sendMediaControlMessageEx

      public abstract int sendMediaControlMessageEx(int uid, byte[] message, RtcConnection connection)
      Parameters:
      uid - remote user id. In particular, if the uid is set to 0, it means broadcasting the message to the entire channel.
      message - The sent data, max 1024 Bytes.
      connection - Connection ID.
      Returns:
      - 0: Success. - < 0: Failure.
    • createDataStreamEx

      public abstract int createDataStreamEx(boolean reliable, boolean ordered, RtcConnection connection)
      Creates a data stream. Each user can only have up to five data channels at the same time.
      Parameters:
      reliable - - True: The recipients will receive data from the sender within 5 seconds. If the recipient does not receive the sent data within 5 seconds, the data channel will report an error to the application. - False: The recipients will not receive any data, and it will not report any error upon data missing.
      ordered - - True: The recipients will receive data in the order of the sender. - False: The recipients will not receive data in the order of the sender.
      Returns:
      - > 0: the Stream ID when the data stream is created. - < 0: an error code when it fails to create the data srteam.
    • createDataStreamEx

      public abstract int createDataStreamEx(DataStreamConfig config, RtcConnection connection)
      Creates a data stream. Each user can create up to five data streams during the lifecycle of the RtcEngine.
      Parameters:
      config - The config of data stream.
      Returns:
      - Returns the stream ID, if the method call is successful. - < 0: Failure. The error code is related to the integer displayed in Error Codes. For example, if it returns -2, then it indicates ERR_INVALID_ARGUMENT(-2) in Error Codes.
    • joinChannelWithUserAccountEx

      public abstract int joinChannelWithUserAccountEx(String token, String channelId, String userAccount, ChannelMediaOptions options, IRtcEngineEventHandler eventHandler)
      Joins the channel with a user account. After the user successfully joins the channel, the SDK triggers the following callbacks: - The local client: \ref agora::rtc::IRtcEngineEventHandler::onLocalUserRegistered "onLocalUserRegistered" and \ref agora::rtc::IRtcEngineEventHandler::onJoinChannelSuccess "onJoinChannelSuccess" . The remote client: \ref agora::rtc::IRtcEngineEventHandler::onUserJoined "onUserJoined" and \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" , if the user joining the channel is in the `COMMUNICATION` profile, or is a host in the `LIVE_BROADCASTING` profile.
      Parameters:
      token - The token generated at your server: - For low-security requirements: You can use the temporary token generated at Console. For details, see [Get a temporary toke](https://docs.agora.io/en/Voice/token?platform=All%20Platforms#get-a-temporary-token). - For high-security requirements: Set it as the token generated at your server. For details, see [Get a token](https://docs.agora.io/en/Voice/token?platform=All%20Platforms#get-a-token).
      channelId - The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. - All numeric characters: 0 to 9. - The space character. - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
      userAccount - The user account. The maximum length of this parameter is 255 bytes. Ensure that you set this parameter and do not set it as null. Supported character scopes are: - All lowercase English letters: a to z. - All uppercase English letters: A to Z. - All numeric characters: 0 to 9. - The space character. - Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ",".
      options - The channel media options: \ref agora::rtc::ChannelMediaOptions::ChannelMediaOptions "ChannelMediaOptions"
      Returns:
      - 0: Success. - < 0: Failure. - #ERR_INVALID_ARGUMENT (-2) - #ERR_NOT_READY (-3) - #ERR_REFUSED (-5)
    • getUserInfoByUserAccountEx

      public abstract int getUserInfoByUserAccountEx(String userAccount, UserInfo userInfo, RtcConnection connection)
      Gets the user information by passing in the user account. After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (`userInfo`), and triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" callback on the local client. After receiving the o\ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" callback, you can call this method to get the user ID of the remote user from the `userInfo` object by passing in the user account.
      Parameters:
      userAccount - The user account of the user. Ensure that you set this parameter.
      userInfo - A userInfo object that identifies the user
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • getUserInfoByUidEx

      public abstract int getUserInfoByUidEx(int uid, UserInfo userInfo, RtcConnection connection)
      Gets the user information by passing in the user ID. After a remote user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (`userInfo`), and triggers the \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" callback on the local client. After receiving the \ref agora::rtc::IRtcEngineEventHandler::onUserInfoUpdated "onUserInfoUpdated" callback, you can call this method to get the user account of the remote user from the `userInfo` object by passing in the user ID.
      Parameters:
      uid - The user ID of the remote user. Ensure that you set this parameter.
      userInfo - A userInfo object that identifies the user
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • adjustRecordingSignalVolumeEx

      public abstract int adjustRecordingSignalVolumeEx(int volume, RtcConnection connection)
      Adjusts the recording volume.
      Parameters:
      volume - The recording volume, which ranges from 0 to 400: - 0 : Mute the recording volume. - 100: The original volume. - 400: (Maximum) Four times the original volume with signal clipping protection.
      connection - The RtcConnection object.
      Returns:
      - 0 : Success. - < 0: Failure.
    • muteRecordingSignalEx

      public abstract int muteRecordingSignalEx(boolean muted, RtcConnection connection)
      Mute or resume recording signal volume.
      Parameters:
      muted - Determines whether to mute or resume the recording signal volume. - true: Mute the recording signal volume. - false: (Default) Resume the recording signal volume.
      connection - The RtcConnection object.
      Returns:
      - 0 : Success. - < 0: Failure.
    • adjustUserPlaybackSignalVolumeEx

      public abstract int adjustUserPlaybackSignalVolumeEx(int uid, int volume, RtcConnection connection)
      Adjust the playback signal volume of a specified remote user. You can call this method as many times as necessary to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user. Note** - The playback volume here refers to the mixed volume of a specified remote user. - This method can only adjust the playback volume of one specified remote user at a time. To adjust the playback volume of different remote users, call the method as many times, once for each remote user.
      Parameters:
      uid - The ID of the remote user.
      volume - The playback volume of the specified remote user. The value ranges between 0 and 400, including the following: - 0: Mute. - 100: (Default) Original volume.
      connection - \ref AgoraRtcConnection by channelId and uid combine
      Returns:
      - 0: Success. - < 0: Failure.
    • setRemoteVoicePositionEx

      public abstract int setRemoteVoicePositionEx(int uid, double pan, double gain, RtcConnection connection)
      Sets the sound position and gain of a remote user. When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.
      Parameters:
      uid - The ID of the remote user.
      pan - The sound position of the remote user. The value ranges from -1.0 to 1.0: - 0.0: the remote sound comes from the front. - -1.0: the remote sound comes from the left. - 1.0: the remote sound comes from the right.
      gain - Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • setRemoteVideoSubscriptionOptionsEx

      public abstract int setRemoteVideoSubscriptionOptionsEx(int uid, VideoSubscriptionOptions options, RtcConnection rtcConnection)
    • setRemoteUserSpatialAudioParamsEx

      public abstract int setRemoteUserSpatialAudioParamsEx(int uid, SpatialAudioParams params, RtcConnection connection)
      Sets the 3D sound position of a remote user.
      Parameters:
      uid - The ID of the remote user.
      azimuth -
      elevation -
      distance -
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • addVideoWatermarkEx

      @Deprecated public abstract int addVideoWatermarkEx(String watermarkUrl, WatermarkOptions options, RtcConnection connection)
      Deprecated.
      From v4.6.0. We recommend using the addVideoWatermark2 method instead. This method adds a PNG watermark image to the local video stream in a live streaming. Once the watermark image is added, all the audience in the channel (CDN audience included), and the sampling device can see and capture it. Agora supports adding only one watermark image onto the local video, and the newly watermark image replaces the previous one. The watermark position depends on the settings in the setVideoEncoderConfiguration method: - If the orientation mode of the encoding video is ORIENTATION_MODE_FIXED_LANDSCAPE, or the landscape mode in ORIENTATION_MODE_ADAPTIVE, the watermark uses the landscape orientation. - If the orientation mode of the encoding video is ORIENTATION_MODE_FIXED_PORTRAIT, or the portrait mode in ORIENTATION_MODE_ADAPTIVE, 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.
      Adds a watermark image to the local video.
      Parameters:
      watermarkUrl - The local file path of the watermark image to be added. This method supports adding a watermark image from either the local file path or the assets file path. If you use the assets file path, you need to start with `/assets/` when filling in this parameter.
      options - The options of the watermark image to be added. See Watermark Options.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
      Since:
      v2.9.1 to replace addVideoWatermark1.
    • addVideoWatermarkEx

      public abstract int addVideoWatermarkEx(WatermarkConfig config, RtcConnection connection)
      Parameters:
      config - The watermark configuration. See WatermarkConfig.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
      Since:
      v4.6.0
    • removeVideoWatermarkEx

      public abstract int removeVideoWatermarkEx(String id, RtcConnection connection)
      Parameters:
      id - The ID of the watermark image to be removed.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
      Since:
      v4.6.0
    • clearVideoWatermarkEx

      public abstract int clearVideoWatermarkEx(RtcConnection connection)
      Removes the watermark image from the video stream added by addVideoWatermarkEx.
      Parameters:
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • enableAudioVolumeIndicationEx

      public abstract int enableAudioVolumeIndicationEx(int interval, int smooth, boolean reportVad, RtcConnection connection)
      Enables the `onAudioVolumeIndication` callback to report on which users are speaking and the speakers' volume. Once the onAudioVolumeIndication callback is enabled, the SDK returns the volume indication in the at the time interval set in `enableAudioVolumeIndication`, regardless of whether any user is speaking in the channel.
      Parameters:
      interval - Sets the time interval between two consecutive volume indications: - <= 0: Disables the volume indication. - > 0: Time interval (ms) between two consecutive volume indications, and should be integral multiple of 200 (less than 200 will be set to 200).
      smooth - The smoothing factor that sets the sensitivity of the audio volume indicator. The value ranges is [0, 10]. The greater the value, the more sensitive the indicator. The recommended value is 3.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • takeSnapshotEx

      public abstract int takeSnapshotEx(RtcConnection connection, int uid, String filePath)
      Takes a snapshot of a video stream. This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path. The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the `onSnapshotTaken` callback to report whether the snapshot is successfully taken, as well as the details for that snapshot.
      Parameters:
      connection - The RtcConnection object.
      uid - The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
      filePath - The local path (including filename extensions) of the snapshot. For example: - Windows: `C:\Users\\AppData\Local\Agora\\example.jpg` - iOS: `/App Sandbox/Library/Caches/example.jpg` - macOS: `~/Library/Logs/example.jpg` - Android: `/storage/emulated/0/Android/data//files/example.jpg` Ensure that the path you specify exists and is writable.
      Returns:
      - 0 : Success. - < 0 : Failure.
    • takeSnapshotEx

      public abstract int takeSnapshotEx(RtcConnection connection, int uid, SnapshotConfig config)
      Takes a snapshot of a video stream. This method takes a snapshot of a video stream from the specified user, generates a JPG image, and saves it to the specified path. The method is asynchronous, and the SDK has not taken the snapshot when the method call returns. After a successful method call, the SDK triggers the `onSnapshotTaken` callback to report whether the snapshot is successfully taken, as well as the details for that snapshot.
      Parameters:
      connection - The RtcConnection object.
      uid - The user ID. Set uid as 0 if you want to take a snapshot of the local user's video.
      config - The configuration for the take snapshot. See SnapshotConfig. Ensure that the path you specify exists and is writable.
      Returns:
      - 0 : Success. - < 0: Failure. - -4: Incorrect observation position. Modify the input observation position according to the reqiurements specified in SnapshotConfig.
    • enableContentInspectEx

      public abstract int enableContentInspectEx(boolean enabled, ContentInspectConfig config, RtcConnection connection)
      Enables video screenshot and upload with the connection ID.
      Parameters:
      enabled - Whether to enable video screenshot and upload: - `true`: Yes. - `false`: No.
      config - The configuration for video screenshot and upload.
      connection - The connection information. See RtcConnection.
      Returns:
      - 0: Success. - < 0: Failure.
    • startRtmpStreamWithoutTranscodingEx

      public abstract int startRtmpStreamWithoutTranscodingEx(String url, RtcConnection connection)
      Publishes the local stream without transcoding to a specified CDN live RTMP address. (CDN live only.)
      Parameters:
      url - The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • startRtmpStreamWithTranscodingEx

      public abstract int startRtmpStreamWithTranscodingEx(String url, LiveTranscoding transcoding, RtcConnection connection)
      Publishes the local stream with transcoding to a specified CDN live RTMP address. (CDN live only.)
      Parameters:
      url - The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes.
      transcoding - Sets the CDN live audio/video transcoding settings. See LiveTranscoding.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • updateRtmpTranscodingEx

      public abstract int updateRtmpTranscodingEx(LiveTranscoding transcoding, RtcConnection connection)
      Update the video layout and audio settings for CDN live. (CDN live only.)
      Parameters:
      transcoding - Sets the CDN live audio/video transcoding settings. See LiveTranscoding.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • stopRtmpStreamEx

      public abstract int stopRtmpStreamEx(String url, RtcConnection connection)
      Stop an RTMP stream with transcoding or without transcoding from the CDN. (CDN live only.)
      Parameters:
      url - The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
    • startOrUpdateChannelMediaRelayEx

      public abstract int startOrUpdateChannelMediaRelayEx(ChannelMediaRelayConfiguration channelMediaRelayConfiguration, RtcConnection connection)
      Starts or update to relay media streams across channels.
      Parameters:
      configuration - The configuration of the media stream relay:ChannelMediaRelayConfiguration.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - -2(ERR_INVALID_ARGUMENT): The argument is invalid. - -5(ERR_REFUSED): The request is rejected. - -8(ERR_INVALID_STATE): The current status is invalid, only allowed to be called when the role is the broadcaster.
      Since:
      v4.2.0
    • stopChannelMediaRelayEx

      public abstract int stopChannelMediaRelayEx(RtcConnection connection)
      Stops the media stream relay. Once the relay stops, the host quits all the destination channels.
      Parameters:
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - -2(ERR_INVALID_ARGUMENT): The argument is invalid. - -5(ERR_REFUSED): The request is rejected. - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.
    • pauseAllChannelMediaRelayEx

      public abstract int pauseAllChannelMediaRelayEx(RtcConnection connection)
      Deprecated.
      This method is deprecated from v4.2.0. Use `startOrUpdateChannelMediaRelayEx` instead.
      Updates the channels for media stream relay
      Parameters:
      configuration - The media stream relay configuration: ChannelMediaRelayConfiguration.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - -2(ERR_INVALID_ARGUMENT): The argument is invalid. - -5(ERR_REFUSED): The request is rejected. - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.
    • resumeAllChannelMediaRelayEx

      public abstract int resumeAllChannelMediaRelayEx(RtcConnection connection)
      resume the channels for media stream relay.
      Parameters:
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure. - -1(ERR_FAILED): A general error occurs (no specified reason). - -2(ERR_INVALID_ARGUMENT): The argument is invalid. - -5(ERR_REFUSED): The request is rejected. - -7(ERR_NOT_INITIALIZED): cross channel media streams are not relayed.
    • startMediaRenderingTracingEx

      public abstract int startMediaRenderingTracingEx(RtcConnection connection)
      Parameters:
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure. - -2(ERR_INVALID_ARGUMENT): The parameter is invalid. Check the channel ID and local uid set by parameter `connection`. - -7(ERR_NOT_INITIALIZED): The SDK is not initialized. Initialize the `RtcEngine` instance before calling this method.
      Since:
      v4.1.1
    • setParametersEx

      public abstract int setParametersEx(String parameters, RtcConnection connection)

      Provides technical preview functionalities or special customizations by configuring the SDK with JSON options.

      The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way.

      Parameters:
      parameters - Parameter to be set as a JSON string in the specified format.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      • 0: Success.
      • <0: Failure.
    • getCallIdEx

      public abstract String getCallIdEx(RtcConnection connection)
      Gets the current call ID. When a user joins a channel on a client, a `callId` is generated to identify the call. After a call ends, you can call `rate` or `complain` to gather feedback from the customer. These methods require a `callId` parameter. To use these feedback methods, call the this method first to retrieve the `callId` during the call, and then pass the value as an argument in the `rate` or `complain` method after the call ends.
      Parameters:
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - NonNull The call ID if the method call is successful. - Null: Failure.
    • addHandlerEx

      public abstract void addHandlerEx(IRtcEngineEventHandler handler, RtcConnection connection)
      Adds the IRtcEngineEventHandler.
      Parameters:
      handler - The IRtcEngineEventHandler instance.
      connection - RtcConnection is used to control different connection instances.
    • removeHandlerEx

      public abstract void removeHandlerEx(IRtcEngineEventHandler handler, RtcConnection connection)
      Removes the IRtcEngineEventHandler.
      Parameters:
      handler - The IRtcEngineEventHandler instance.
      connection - RtcConnection is used to control different connection instances.
    • enableEncryptionEx

      public abstract int enableEncryptionEx(boolean enabled, io.agora.rtc2.internal.EncryptionConfig config, RtcConnection connection)
      Enables/Disables the built-in encryption. In scenarios requiring high security, Agora recommends calling `enableEncryption` to enable the built-in encryption before joining a channel. All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared.
      Parameters:
      enabled - Whether to enable the built-in encryption. - `true`: Enable the built-in encryption. - `false`: Disable the built-in encryption.
      config - Configurations of built-in encryption schemas. See EncryptionConfig.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure. - -2(ERR_INVALID_ARGUMENT): An invalid parameter is used. Set the parameter with a valid value. - -7(ERR_NOT_INITIALIZED: The SDK is not initialized. Initialize the IRtcEngine instance before calling this method. - -4(ERR_NOT_SUPPORTED): The encryption mode is incorrect or the SDK fails to load the external encryption library. Check the enumeration or reload the external encryption library.
    • sendAudioMetadataEx

      public abstract int sendAudioMetadataEx(byte[] metadata, RtcConnection connection)
      Send audio metadata.
      Parameters:
      metadata - Audio Metadata.
      connection - RtcConnection is used to control different connection instances.
      Returns:
      - 0: Success. - < 0: Failure.
      Since:
      v4.3.1
    • preloadEffectEx

      public abstract int preloadEffectEx(RtcConnection connection, int soundId, String filePath)
      Preloads a specified audio effect to a specified channel.
      Parameters:
      connection - The RtcConnection object.
      soundId - The ID of the audio effect.
      filePath - The absolute path of the local audio effect file or the URL of the online audio effect file. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav.
      Returns:
      - 0: Success. - < 0: Failure.
      Since:
      v4.6.0 This method preloads only one specified audio effect into the memory each time it is called. To preload multiple audio effects, call this method multiple times. After preloading, you can call {@link RtcEngine#playEffect() playEffect} to play the preloaded audio effect or call {@link RtcEngine#playAllEffects() playAllEffects} to play all the preloaded audio effects.
    • preloadEffectEx

      public abstract int preloadEffectEx(RtcConnection connection, int soundId, String filePath, int startPos)
      Preloads a specified audio effect to a specified channel.
      Parameters:
      connection - The RtcConnection object.
      soundId - The ID of the audio effect.
      filePath - The absolute path of the local audio effect file or the URL of the online audio effect file. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav.
      startPos - The playback position (ms) of the audio effect file.
      Returns:
      - 0: Success. - < 0: Failure.
      Since:
      v4.6.0 This method preloads only one specified audio effect into the memory each time it is called. To preload multiple audio effects, call this method multiple times. After preloading, you can call {@link RtcEngine#playEffect() playEffect} to play the preloaded audio effect or call {@link RtcEngine#playAllEffects() playAllEffects} to play all the preloaded audio effects.
    • playEffectEx

      public abstract int playEffectEx(RtcConnection connection, int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish)
      Plays a specified audio effect to a specified channel.
      Parameters:
      connection - The RtcConnection object.
      soundId - The ID of the audio effect.
      filePath - The absolute path of the local audio effect file or the URL of the online audio effect file. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav.
      loopCount - The number of times the audio effect loops: - `-1`: Play the audio effect in an indefinite loop until you call stopEffect or stopAllEffects. - `0`: Play the audio effect once. - `1`: Play the audio effect twice.
      pitch - The pitch of the audio effect. The value ranges between 0.5 and 2.0. The default value is 1.0 (original pitch). The lower the value, the lower the pitch.
      pan - The spatial position of the audio effect. The value ranges between -1.0 and 1.0: - `-1.0`: The audio effect shows on the left. - `0.0`: The audio effect shows ahead. - `1.0`: The audio effect shows on the right.
      gain - The volume of the audio effect. The value ranges between 0.0 and 100.0. The default value is 100 (original volume). The lower the value, the lower the volume of the audio effect.
      publish - Sets whether to publish the specified audio effect in a channel: - True: Publish the audio effect in the channel so that remote user can hear it. - False: Do not publish the audio effect in the channel.
      Returns:
      - 0: Success. - < 0: Failure.
      Since:
      v4.6.0 After calling preloadEffect, you can call this method to play the specified audio effect for all users in the channel. This method plays only one specified audio effect each time it is called. To play multiple audio effects, call this method multiple times.
    • playEffectEx

      public abstract int playEffectEx(RtcConnection connection, int soundId, String filePath, int loopCount, double pitch, double pan, double gain, boolean publish, int startPos)
      Plays a specified audio effect to a specified channel.
      Parameters:
      connection - The RtcConnection object.
      soundId - The ID of the audio effect.
      filePath - The absolute path of the local audio effect file or the URL of the online audio effect file. Supported audio formats: mp3, mp4, m4a, aac, 3gp, mkv and wav.
      loopCount - The number of times the audio effect loops: - `-1`: Play the audio effect in an indefinite loop until you call stopEffect or stopAllEffects. - `0`: Play the audio effect once. - `1`: Play the audio effect twice.
      pitch - The pitch of the audio effect. The value ranges between 0.5 and 2.0. The default value is 1.0 (original pitch). The lower the value, the lower the pitch.
      pan - The spatial position of the audio effect. The value ranges between -1.0 and 1.0: - `-1.0`: The audio effect shows on the left. - `0.0`: The audio effect shows ahead. - `1.0`: The audio effect shows on the right.
      gain - The volume of the audio effect. The value ranges between 0.0 and 100.0. The default value is 100 (original volume). The lower the value, the lower the volume of the audio effect.
      publish - Sets whether to publish the specified audio effect in a channel: - True: Publish the audio effect in the channel so that remote user can hear it. - False: Do not publish the audio effect in the channel.
      startPos - The playback position (ms) of the audio effect file.
      Returns:
      - 0: Success. - < 0: Failure.
      Since:
      v4.6.0 After calling preloadEffect, you can call this method to play the specified audio effect for all users in the channel. This method plays only one specified audio effect each time it is called. To play multiple audio effects, call this method multiple times.