Adds a voice or video stream HTTP/HTTPS URL address to a live streaming.
This method applies to the Native SDK v2.4.1 and later.
If this method call is successful, the server pulls the voice or video stream and injects it into a live channel. This is applicable to scenarios where all audience members in the channel can watch a live show and interact with each other.
The addInjectStreamUrl method call triggers the following
callbacks:
userJoined (uid: 666), if the method call is successful and
the online media stream is injected into the channel.
userJoined (uid: 666), if the method call is successful and
the online media stream is injected into the channel.
The HTTP/HTTPS URL address to be added to the ongoing live streaming. Valid protocols are RTMP, HLS, and FLV.
The InjectStreamConfig object which contains the configuration information for the added voice or video stream.
ERR_INVALID_ARGUMENT (2): The injected URL does not exist.
Call this method again to inject the stream and ensure that the URL is
valid.
ERR_NOT_READY (3): The user is not in the channel.ERR_NOT_SUPPORTED (4): The channel profile is not Live
streaming. Call the
setChannelProfile
method and set the channel profile to Live streaming before calling this
method.
ERR_NOT_INITIALIZED (7): The SDK is not initialized. Ensure
that the AgoraRtcEngine object is initialized before using
this method.
Publishes the local stream to a specified CDN live RTMP address.
The SDK returns the result of this method call in the streamPublished callback.
The CDN streaming URL in the RTMP format. The maximum length of this parameter is 1024 bytes. The RTMP URL address must not contain special characters, such as Chinese language characters.
Sets whether transcoding is enabled/disabled:
true, you should call the
setLiveTranscoding
method before this method.
Adds a video stream to the high frame rate stream. Streams added to the high frame rate stream will be controlled by the setVideoRenderHighFPS method.
The User ID.
The local file path of the watermark image to be added. This method supports adding a watermark image from the local absolute or relative file path.
The watermark's options. See WatermarkOptions
Adjusts the audio mixing volume for local playback.
Audio mixing volume for local playback. The value ranges between 0 and 100 (default). 100 is the original volume.
Adjusts the audio mixing volume for publishing (sending to other users).
Audio mixing volume for publishing. The value ranges between 0 and 100 (default). 100 is the original volume.
Adjusts the volume of audio mixing.
Call this API when you are in a channel.
Audio mixing volume. The value ranges between 0 and 100 (default). 100 is the original volume.
Adjusts the volume of the signal captured by the sound card.
The volume of the signal captured by the sound card. The range is 0 to 100. The default value is 100, which represents the unadjusted volume.
Adjusts the playback signal volume of all remote users.
The playback volume. The range is 0 to 400. The default value is 100, which represents the original volume.
Adjusts the volume of the signal captured by the microphone.
The volume of the signal captured by the microphone. The range is 0 to 400. The default value is 100, which represents the original volume.
Adjusts the playback 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.
The ID of the remote user.
The playback volume of the specified remote user. The value ranges from 0 to 100:
Removes the watermark image from the video stream added by the addVideoWatermark method.
Allows a user to complain about the call quality after a call ends.
Call ID retrieved from the getCallId method.
(Optional) The description of the complaint, with a string length of less than 800 bytes.
Creates and gets an AgoraRtcChannel object.
To join more than one channel, call this method multiple times to create as
many AgoraRtcChannel objects as needed, and call the
joinChannel method of each
created AgoraRtcChannel object.
After joining multiple channels, you can simultaneously subscribe to streams of all the channels, but publish a stream in only one channel at one time.
The unique channel name for an Agora RTC session. It must be in the string format and not exceed 64 bytes in length. Supported character scopes are:
AgoraRtcChannel object.
ERR_REFUSED (5).
Creates a data stream.
Each user can create up to five data streams during the lifecycle of the AgoraRtcEngine.
Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
Sets whether or not the recipients receive the data stream in the sent order:
Creates a data stream.
The configurations for the data stream.
Destroys the renderer.
Key for the map that store the renderers, e.g, uid or
videosource or local.
The error callback for the {@link destroyRenderer} method.
Disables the audio module.
Note:
This method disables the network connection quality test.
Disables the video module.
You can call this method before joining a channel or during a call. If you call this method before joining a channel, the service starts in audio mode. If you call this method during a video call, the video mode switches to the audio mode.
To enable the video mode, call the enableVideo method.
Note:
Enables the audio module.
The audio module is enabled by default.
Note:
Enables the groupAudioVolumeIndication callback at a set time
interval to report on which users are speaking and the speakers' volume.
Once this method is enabled, the SDK returns the volume indication in the groupAudioVolumeIndication callback at the set time interval, regardless of whether any user is speaking in the channel.
Sets the time interval between two consecutive volume indications:
The smoothing factor sets the sensitivity of the audio volume indicator. The value ranges between 0 and 10. The greater the value, the more sensitive the indicator. The recommended value is 3.
true: Enable the voice activity detection of the local
user. Once it is enabled, vad in the
groupAudioVolumeIndication callback reports the voice
activity status of the local user.
false: (Default) Disables the voice activity detection of
the local user. Once it is disabled, vad in the
groupAudioVolumeIndication callback does not report the
voice activity status of the local user, except for scenarios where the
engine automatically detects the voice activity of the local user.
Enables or disables deep-learning noise reduction.
Enables/Disables the dual video stream mode.
If dual-stream mode is enabled, the receiver can choose to receive the high stream (high-resolution high-bitrate video stream) or low stream (low-resolution low-bitrate video stream) video.
Sets the stream mode:
Enables/Disables the built-in encryption.
Whether to enable the built-in encryption:
Configurations of built-in encryption schemas. See EncryptionConfig.
Enables the network connection quality test.
This method tests the quality of the users' network connections and is disabled by default.
Before users join a channel or before an audience switches to a host, call this method to check the uplink network quality.
This method consumes additional network traffic, which may affect the communication quality.
Call the disableLastmileTest method to disable this test after receiving the lastMileQuality callback, and before the user joins a channel or switches the user role.
Enables/Disables the local audio capture.
The audio function is enabled by default. This method disables/re-enables the local audio function, that is, to stop or restart local audio capture and processing.
This method does not affect receiving or playing the remote audio streams, and enableLocalAudio(false) is applicable to scenarios where the user wants to receive remote audio streams without sending any audio stream to other users in the channel.
The SDK triggers the microphoneEnabled callback once the local audio function is disabled or re-enabled.
Sets whether to disable/re-enable the local audio function:
Disables/Re-enables the local video capture.
This method disables or re-enables the local video capturer, and does not affect receiving the remote video stream.
After you call the enableVideo method, the local video capturer is enabled by default. You can call enableLocalVideo(false) to disable the local video capturer. If you want to re-enable it, call enableLocalVideo(true).
After the local video capturer is successfully disabled or re-enabled, the SDK triggers the userEnableVideo callback on the remote client.
Sets whether to disable/re-enable the local video, including the capturer, renderer, and sender:
Enables reporting the voice pitch of the local user.
Sets the time interval at which the SDK triggers the
localVoicePitchInHz callback:
localVoicePitchInHz callback.localVoicePitchInHz callback. The value must be greater
than or equal to 10. If the value is less than 10, the SDK automatically
changes it to 10.
Enables loopback audio capturing.
If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end.
Sets whether to enable/disable loopback capturing.
The device name of the sound card. The default value is NULL (the default sound card). Note: macOS does not support loopback capturing of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName parameter. Agora has tested and recommends using soundflower.
Enables/Disables stereo panning for remote users.
Ensure that you call this method before joinChannel to enable stereo panning for remote users so that the local user can track the position of a remote user by calling setRemoteVoicePosition.
Sets whether or not to enable stereo panning for remote users:
Enables the video module.
You can call this method either before joining a channel or during a call. If you call this method before joining a channel, the service starts in the video mode. If you call this method during an audio call, the audio mode switches to the video mode.
To disable the video, call the disableVideo method.
Note:
Enables/Disables the virtual background. (beta function)
Sets whether to enable the virtual background:
The custom background image. See VirtualBackgroundSource.
Note: To adapt the resolution of the custom background image to the resolution of the SDK capturing video, the SDK scales and crops the custom background image while ensuring that the content of the custom background image is not distorted.
Sets whether to enable/disable interoperability with the Agora Web SDK:
Sets the audio playback device used by the SDK to follow the system default audio playback device.
Whether to follow the system default audio playback device:
Sets the audio recording device used by the SDK to follow the system default audio recording device.
Whether to follow the system default audio recording device:
Gets the information of a specified audio file.
The file path:
C:\music\audio.mp4.
/assets/. You might encounter permission issues
if you use an absolute path to access a local file, so Agora recommends
using a URI address instead. For example:
content://com.android.providers.media.documents/document/audio%3A14441.
/var/mobile/Containers/Data/audio.mp4.
Gets the playback position (ms) of the music file.
Call this API when you are in a channel.
Gets the duration (ms) of the music file.
Adjusts the audio mixing volume for publishing (for remote users).
Call this API when you are in a channel.
Retrieves the audio mixing volume for publishing.
Call this API when you are in a channel.
check whether selected audio playback device is muted
muted/unmuted
Retrieves the audio playback device associated with the device ID.
The array of the audio playback device.
Retrieves the volume of the audio playback device.
The audio playback device volume.
Retrieves the mute status of the audio playback device.
Whether to mute/unmute the audio playback device:
Retrieves the audio recording device associated with the device ID.
The array of the audio recording device.
Retrieves the volume of the microphone.
The microphone volume. The volume value ranges between 0 (lowest volume) and 255 (highest volume).
Gets the audio track index of the current music file.
Retrieves the current call ID. When a user joins a channel on a client, a
callId is generated to identify the call from the client.
Feedback methods, such as rate and
complain, must be called after
the call ends to submit feedback to the SDK.
The rate and
complain methods require the
callId parameter retrieved from the
getCallId method during a call.
callId is passed as an argument into the
rate and
complain methods after the call
ends.
The current call ID.
return sdk config object
Gets the connection state of the SDK.
Connect states. See {@link ConnectionState}.
Gets the current audio playback device.
The current audio playback device.
Gets the current audio recording device.
The audio recording device.
Gets the current video device.
The video device.
Gets the default audio playback device of the system.
Gets the default audio recording device of the system.
Gets the playback position of the audio effect file.
Audio effect ID. Ensure that this parameter is set to the same value as in
playEffect.
-22: Cannot find the audio effect file. Please set a correct
soundId.
Gets the duration of the audio effect file.
The absolute path or URL address (including the filename extensions) of
the music file. For example: C:\music\audio.mp4. Supported
audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. For more
information, see
Supported Media Formats in Media Foundation.
-22: Cannot find the audio effect file. Please set a correct
filePath.
Retrieves the volume of the audio effects.
The value ranges between 0.0 and 100.0.
Retrieves the error description.
The error code.
The error description.
Retrieves the audio playback device information associated with the device ID and device name.
The device ID of the audio playback device.
The device name of the audio playback device.
Retrieves the audio recording device information associated with the device ID and device name.
The device ID of the recording audio device.
The device name of the recording audio device.
Gets a list of shareable screens and windows.
The target size of the screen or window thumbnail. The width and height
are in pixels. See SIZE. The SDK scales the original image to make the
length of the longest side of the image the same as that of the target
size without distorting the original image. For example, if the original
image is 400 × 300 and thumbSize is 100 × 100, the actual
size of the thumbnail is 100 × 75. If the target size is larger than the
original size, the thumbnail is the original image and the SDK does not
scale it.
The target size of the icon corresponding to the application program. The
width and height are in pixels. See SIZE. The SDK scales the original
image to make the length of the longest side of the image the same as that
of the target size without distorting the original image. For example, if
the original image is 400 × 300 and iconSize is 100 × 100,
the actual size of the icon is 100 × 75. If the target size is larger than
the original size, the icon is the original image and the SDK does not
scale it.
Whether the SDK returns screen information in addition to window information:
Array of ScreenCaptureSources objects
Gets the display ID when using the video source.
This method gets the ID of the whole display and relevant inforamtion. You can share the whole or part of a display by specifying the display ID.
The callback that returns a list of DisplayInfo.
Gets the window ID when using the video source.
This method gets the ID of the whole window and relevant inforamtion. You can share the whole or part of a window by specifying the window ID.
The callback that returns a list of WindowInfo.
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 userInfoUpdated callback on the local client. After receiving the 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.
The user ID. Ensure that you set this parameter.
Returns the version and the build information of the current SDK.
The version of the current SDK.
Gets the list of the video devices.
The array of the video devices.
Initializes the renderer.
Key for the map that store the renderers, e.g, uid or
videosource or local.
The Dom elements to render the video.
Initializes the Agora service.
The App ID issued to you by Agora. See
How to get the App ID. Only users in apps with the same App ID can join the same channel and
communicate with each other. Use an App ID to create only one
AgoraRtcEngine. To change your App ID, call
release to destroy the current
AgoraRtcEngine and then call initialize to
create AgoraRtcEngine with the new App ID.
The region for connection. This advanced feature applies to scenarios that have regional restrictions. For the regions that Agora supports, see AREA_CODE. After specifying the region, the SDK connects to the Agora servers within that region.
The configuration of the log files that the SDK outputs. See
LogConfig. By default, the SDK
outputs five log files, agorasdk.log,
agorasdk_1.log, agorasdk_2.log,
agorasdk_3.log, agorasdk_4.log, each with a
default size of 1024 KB. These log files are encoded in UTF-8. The SDK
writes the latest logs in agorasdk.log. When
agorasdk.log is full, the SDK deletes the log file with the
earliest modification time among the other four, renames
agorasdk.log to the name of the deleted log file, and creates
a new agorasdk.log to record latest logs.
Joins a channel with the user ID, and configures whether to automatically subscribe to the audio or video streams.
Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.
You must call the leaveChannel method to exit the current call before entering another channel.
A successful joinChannel method call triggers the following
callbacks:
joinChannelSuccess.userJoined, if the user joining the channel
is in the 0 (communication) profile, or is a host in the
1 (live streaming) profile.
When the connection between the client and the Agora server is interrupted due to poor network conditions, the SDK tries reconnecting to the server.
When the local client successfully rejoins the channel, the SDK triggers the
rejoinChannelSuccess callback on the local client.
The token generated at your server. For details, see Generate a token.
The unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:
(Optional) Reserved for future use.
(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1
to 232-1. The @p uid must be unique. If a @p uid is not
assigned (or set to 0), the SDK assigns and returns a @p uid in the
joinChannelSuccess callback. Your application must record and
maintain the returned uid, because the SDK does not do so.
Note: The ID of each user in the channel should be
unique. If you want to join the same channel from different devices,
ensure that the user IDs in all devices are different.
The channel media options. See ChannelMediaOptions.
-2: The parameter is invalid.-3: The SDK fails to be initialized. You can try
re-initializing the SDK.
AgoraRtcChannel object with the same
channel name.
AgoraRtcChannel object. When you join a channel created
by the AgoraRtcEngine object, the SDK publishes the local
audio and video streams to that channel by default. Because the SDK
does not support publishing a local stream to more than one channel
simultaneously, an error occurs in this occasion.
-7: The SDK is not initialized before calling this method.
Joins the channel with a user account.
After the user successfully joins the channel, the SDK triggers the following callbacks:
0) profile, or is a host in the
1 (live streaming) profile.
The token generated at your server. For details, see Generate a token.
The channel name. The maximum length of this parameter is 64 bytes. Supported character scopes are:
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:
The channel media options. See ChannelMediaOptions.
-2-3-5-7Allows a user to leave a channel.
Allows a user to leave a channel, such as hanging up or exiting a call. The user must call the method to end the call before joining another channel after call the joinChannel method. This method returns 0 if the user leaves the channel and releases all resources related to the call. This method call is asynchronous, and the user has not left the channel when the method call returns.
Once the user leaves the channel, the SDK triggers the leavechannel callback.
A successful leavechannel method call triggers the removeStream callback for
the remote client when the user leaving the channel is in the Communication
channel, or is a host in the 1 (live streaming) profile.
Stops or resumes subscribing to the audio streams of all remote users.
As of v3.3.1, after successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users.
Sets whether to stop subscribing to the audio streams of all remote users.
Stops or resumes subscribing to the video streams of all remote users.
As of v3.3.1, after successfully calling this method, the local user stops or resumes subscribing to the video streams of all remote users, including all subsequent users.
Sets whether to stop subscribing to the video streams of all remote users.
Stops or resumes publishing the local audio stream.
A successful
muteLocalAudioStream
method call triggers the userMuteAudio callback on the remote
client.
Sets whether to stop publishing the local audio stream.
Stops or resumes publishing the local video stream.
A successful
muteLocalVideoStream
method call triggers the userMuteVideo callback on the remote
client.
Sets whether to stop publishing the local video stream.
Stops or resumes subscribing to the audio stream of a specified user.
Sets whether to stop subscribing to the audio stream of a specified user.
Stops or resumes subscribing to the video stream of a specified user.
Sets whether to stop subscribing to the video stream of a specified user.
Occurs when an API method is executed.
api: The method executed by the SDK.
err: Error code that the SDK returns when the method call fails.
Reports a warning during SDK runtime.
Warning code.
The warning message.
Reports an error during SDK runtime.
Error code.
The error message.
Occurs when a user joins a specified channel.
The channel name.
User ID of the user joining the channel.
Time elapsed (ms) from the user calling the joinChannel method until the SDK triggers this callback.
Occurs when a user rejoins the channel after disconnection due to network problems. When a user loses connection with the server because of network problems, the SDK automatically tries to reconnect and triggers this callback upon reconnection.
The channel name.
User ID of the user joining the channel.
Time elapsed (ms) from the user calling the joinChannel method until the SDK triggers this callback.
Reports which users are speaking, the speakers' volume and whether the local user is speaking.
This callback reports the IDs and volumes of the loudest speakers (at most 3 users) at the moment in the channel, and whether the local user is speaking.
By default, this callback is disabled. You can enable it by calling the enableAudioVolumeIndication method.
The SDK triggers two independent
groupudioVolumeIndication callbacks at one time, which separately
report the volume information of the local user and all the remote speakers.
For more information, see the detailed parameter descriptions.
The speakers' information:
uid: 0.volume: The volume of the local speaker.
vad: The voice activity status of the local
user.
uid: The ID of the remote user.volume: The sum of the voice volume and
audio-mixing volume of each remote speaker.
vad: 0.Total number of speakers. The value range is [0, 3].
Total volume after audio mixing. The value ranges between 0 (lowest volume) and 255 (highest volume).
Occurs when the user leaves the channel. When the app calls the leaveChannel method, the SDK uses this callback to notify the app when the user leaves the channel.
Reports the statistics of the AgoraRtcEngine once every two seconds.
Reports the statistics of the local video streams.
Note:
If you have called the enableDualStreamMode method, the localVideoStats callback reports the statistics of the high-video stream (high bitrate, and high-resolution video stream).
Reports the statistics of the local audio streams.
The SDK triggers this callback once every two seconds.
Reports the statistics of the video stream from each remote user/host.
Statistics of the received remote video streams. See RemoteVideoState.
Reports the statistics of the audio stream from each remote user/host.
Statistics of the received remote audio streams. See RemoteAudioStats.
The transport-layer statistics. See RemoteAudioTransportStats.
Occurs when the audio device state changes.
The device ID.
The device type. See MediaDeviceType.
The device state:
Occurs when the state of the local user's music file changes.
The current music file playback state:
710: The music file is playing. This state
comes with reason 720,
721, 722, or 726.
711: The music file pauses playing. This state
comes with reason 725.
713: The music file stops playing. This state
comes with reason 723 or
724.
714: An exception occurs during the playback of
the music file. This state comes with
reason 701, 702,
or 703.
The reason for the change of the music file playback state.
701: The SDK cannot open the music file.
Possible causes include the local music file does not exist,
the SDK does not support the file format, or the SDK cannot
access the music file URL.
702: The SDK opens the music file too
frequently. If you need to call
startAudioMixing
multiple times, ensure that the call interval is longer than
500 ms.
703: The music file playback is interrupted.
720: Successfully calls
startAudioMixing
to play a music file.
721: The music file completes a loop playback.
722: The music file starts a new loop playback.
723: The music file completes all loop
playback.
724: Successfully calls
stopAudioMixing
to stop playing the music file.
725: Successfully calls
pauseAudioMixing
to pause playing the music file.
726: Successfully calls
resumeAudioMixing
to resume playing the music file.
Occurs when a remote user starts audio mixing. When a remote user calls startAudioMixing to play the background music, the SDK reports this callback.
Occurs when a remote user finishes audio mixing.
Occurs when the local audio effect playback finishes.
Occurs when the video device state changes.
The device ID.
The device type. See MediaDeviceType.
The device state:
Reports the last mile network quality of each user in the channel once every two seconds.
Last mile refers to the connection between the local device and Agora's edge server.
User ID. The network quality of the user with this uid is reported. If uid is 0, the local network quality is reported.
Uplink transmission quality rating of the user in terms of the transmission bitrate, packet loss rate, average RTT (Round-Trip Time), and jitter of the uplink network. See AgoraNetworkQuality.
Downlink network quality rating of the user in terms of the packet loss rate, average RTT, and jitter of the downlink network. See AgoraNetworkQuality.
Reports the last mile network quality of the local user once every two seconds before the user joins the channel.
Last mile refers to the connection between the local device and Agora's edge server. After the application calls the enableLastmileTest method, this callback reports once every two seconds the uplink and downlink last mile network conditions of the local user before the user joins the channel.
Reports the last-mile network probe result.
The SDK triggers this callback within 30 seconds after the app calls the startLastmileProbeTest method.
Occurs when the first local video frame is displayed/rendered on the local video view.
Occurs when the video size or rotation of a specified user changes.
User ID of the remote user or local user (0) whose video size or rotation changes.
New width (pixels) of the video.
New height (pixels) of the video.
User ID of the remote user sending the video stream.
Width (pixels) of the video frame.
Height (pixels) of the video stream.
Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Occurs when the first remote video frame is decoded. The SDK triggers this callback when the first frame of the remote video is decoded.
Occurs when a user or host joins the channel.
The SDK triggers this callback under one of the following circumstances:
User ID of the user or host joining the channel.
Time delay (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Occurs when a remote user (Communication)/host (Live streaming) leaves the channel.
There are two reasons for users to become offline:
ID of the user or host who leaves the channel or goes offline.
Reason why the user goes offline:
Occurs when a remote user's video stream playback pauses/resumes.
The SDK triggers this callback when the remote user stops or resumes sending the video stream by calling the muteLocalVideoStream method.
Note: This callback returns invalid when the number of users in a channel exceeds 20.
Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted.
The SDK triggers this callback when it cannot connect to the server 10 seconds after calling the joinChannel method, whether or not it is in the channel.
Occurs when the local user receives the data stream from the remote user within five seconds.
The SDK triggers this callback when the local user receives the stream message that the remote user sends by calling the sendStreamMessage method.
User ID of the remote user sending the message.
Stream ID.
The data received bt the local user.
Length of the data in bytes.
Occurs when the local user does not receive the data stream from the remote user within five seconds.
The SDK triggers this callback when the local user fails to receive the stream message that the remote user sends by calling the sendStreamMessage method.
User ID of the remote user sending the message.
Stream ID.
Number of the lost messages.
Number of incoming cached messages when the data stream is interrupted.
Occurs when the media engine call starts.
Occurs when the token expires.
After a token(channel key) is specified by calling the joinChannel method, if the SDK losses connection with the Agora server due to network issues, the token may expire after a certain period of time and a new token may be required to reconnect to the server.
This callback notifies the application to generate a new token. Call the renewToken method to renew the token
Occurs when the engine sends the first local audio frame.
User ID of the remote user sending the audio stream.
The time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Reports which user is the loudest speaker.
This callback returns the user ID of the user with the highest voice volume during a period of time, instead of at the moment.
User ID of the active speaker. If the user enables the audio volume indication by calling the enableAudioVolumeIndication method, this callback returns the uid of the active speaker detected by the audio volume detection module of the SDK.
Occurs when the user role switches in a live streaming.
For example, from a host to an audience or vice versa.
This callback notifies the application of a user role switch when the application calls the setClientRole method.
The old role, see {@link ClientRoleType}
The new role, see {@link ClientRoleType}
Occurs when the volume of the playback device, microphone, or application changes.
Device type. See {@link AgoraRtcEngine.MediaDeviceType MediaDeviceType}.
Volume of the device. The value ranges between 0 and 255.
Occurs when the local video source joins the channel.
The User ID.
Occurs when the token expires.
Occurs when the video source leaves the channel.
Occurs when screencapture fail to filter window
Reports the statistics of the audio stream of the local video source.
The SDK triggers this callback once every two seconds.
The statistics of the local audio stream.
Reports the statistics of the video stream of the local video source.
The SDK triggers this callback once every two seconds for each user/host. If there are multiple users/hosts in the channel, the SDK triggers this callback as many times.
Statistics of the local video stream.
Occurs when the video size or rotation of the video source changes.
User ID of the remote video source or local video source
(0) whose video size or rotation changes.
New width (pixels) of the video.
New height (pixels) of the video.
New rotation of the video [0 to 360).
Occurs when the local video state of the video source changes.
This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur.
The SDK triggers the
videoSourceLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED,
LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)
callback in the following situations:
When the camera outputs the captured video frames, if all the video frames are
the same for 15 consecutive frames, the SDK triggers the
videoSourceLocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING,
LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)
callback. Note that the video frame duplication detection is only available
for video frames with a resolution greater than 200 × 200, a frame rate
greater than or equal to 10 fps, and a bitrate less than 20 Kbps.
The local video state.
The detailed error information of the local video.
Occurs when the local audio state of the video source changes.
This callback indicates the state change of the local audio stream, including the state of the audio recording and encoding, and allows you to troubleshoot issues when exceptions occur.
State of the local audio.
The error information of the local audio.
Occurs when the remote video state changes.
ID of the user whose video state changes.
State of the remote video. See RemoteVideoState.
The reason of the remote video state change. See RemoteVideoStateReason
Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Occurs when the camera focus area changes.
Occurs when the camera exposure area changes.
Occurs when the token expires in 30 seconds.
The user becomes offline if the token used in the joinChannel method expires. The SDK triggers this callback 30 seconds before the token expires to remind the application to get a new token. Upon receiving this callback, generate a new token on the server and call the renewToken method to pass the new token to the SDK.
The token that expires in 30 seconds.
Occurs when the state of Media Push changes.
The SDK triggers this callback to report the result of the local user calling the addPublishStreamUrl and removePublishStreamUrl method.
This callback indicates the state of Media Push. When exceptions occur, you
can troubleshoot issues by referring to the detailed error descriptions in the
code parameter.
The RTMP URL address.
Media Push state:
0: Media Push has not started or has ended.
This state is also triggered after you remove an RTMP
address from the CDN by calling
removePublishStreamUrl.
1: The SDK is connecting to Agora's
streaming server and the RTMP server. This state is
triggered after you call the
addPublishStreamUrl
method.
2: Media Push publishes. The SDK successfully
publishes the Media Push stream and returns this state.
3: Media Push is recovering. When exceptions
occur to the CDN, or the streaming is interrupted, the SDK
tries to resume Media Push and returns this state.
2 returns.
4 returns. You can
also reconnect to the server by calling the
removePublishStreamUrl
and then
addPublishStreamUrl
method.
4: Media Push fails. See the
code parameter for the detailed error
information. You can also call the
addPublishStreamUrl
method to publish Media Push again.
5: The SDK is disconnecting from the Agora
streaming server and CDN. When you call remove or stop to
stop the streaming normally, the SDK reports the streaming
state as DISCONNECTING, IDLE in
sequence.
The detailed error information:
0: Media Push publishes successfully.1: Invalid argument used.2: The RTMP streams is encrypted and cannot be
published.
3: Timeout for Media Push. Call the
addPublishStreamUrl
to publish the stream again.
4: An error occurs in Agora's streaming
server. Call the
addPublishStreamUrl
to publish the stream again.
5: An error occurs in the RTMP server.6: Media Push publishes too frequently.7: The host publishes more than 10 URLs. Delete
the unnecessary URLs before adding new ones.
8: The host manipulates other hosts' URLs.
Check your app logic.
9: Agora's server fails to find the RTMP
stream.
10: The format of the stream's URL address
is not supported. Check whether the URL format is correct.
11: The user role is not host, so the user
cannot use the CDN live streaming function. Check your
application code logic.
13: The updateRtmpTranscoding or
setLiveTranscoding method is called to update
the transcoding configuration in a scenario where there is
streaming without transcoding. Check your application code
logic.
14: Errors occurred in the host's network.
15: Your App ID does not have permission to use
the CDN live streaming function. Refer to
Prerequisites
to enable the CDN live streaming permission.
100: The streaming has been stopped normally.
After you call
removePublishStreamUrl
to stop streaming, the SDK returns this value.
Occurs when the publisher's transcoding is updated.
When the LiveTranscoding class in the setLiveTranscoding method updates, the SDK triggers the transcodingUpdated callback to report the update information to the local host.
Note: If you call the setLiveTranscoding method to set the LiveTranscoding class for the first time, the SDK does not trigger the transcodingUpdated callback.
Occurs when a voice or video stream URL address is added to a live broadcast.
Occurs when the locally published media stream falls back to an audio-only stream due to poor network conditions or switches back to the video after the network conditions improve.
If you call setLocalPublishFallbackOption and set option as AUDIO_ONLY(2), the SDK triggers this callback when the locally published stream falls back to audio-only mode due to poor uplink conditions, or when the audio stream switches back to the video after the uplink network condition improves.
Occurs when the remote media stream falls back to audio-only stream due to poor network conditions or switches back to the video stream after the network conditions improve.
If you call setRemoteSubscribeFallbackOption and set option as AUDIO_ONLY(2), the SDK triggers this callback when the remotely subscribed media stream falls back to audio-only mode due to poor uplink conditions, or when the remotely subscribed media stream switches back to the video after the uplink network condition improves.
ID of the remote user sending the stream.
Whether the remote media stream falls back to audio-only or switches back to the video:
true: The remote media stream falls back to
audio-only due to poor network conditions.
false: The remote media stream switches back to
the video stream after the network conditions improved.
Occurs when the connection state between the SDK and the server changes.
The connection state, see {@link ConnectionState}.
The connection reason, see {@link ConnectionState}.
Occurs when the local network type changes.
When the network connection is interrupted, this callback indicates whether the interruption is caused by a network type change or poor network conditions.
The network type, see NETWORK_TYPE.
Occurs when the local user successfully registers a user account by calling the registerLocalUserAccount method. This callback reports the user ID and user account of the local user.
Occurs when the SDK gets the user ID and user account of the remote user.
After a remote user joins the channel, the SDK gets the UID and user account of the remote user, caches them in a mapping table object (UserInfo), and triggers this callback on the local client.
Occurs when the local video state changes.
This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur.
The SDK triggers the
LocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_FAILED,
LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)
callback in the following situations:
When the camera outputs the captured video frames, if all the video frames are
the same for 15 consecutive frames, the SDK triggers the
LocalVideoStateChanged(LOCAL_VIDEO_STREAM_STATE_CAPTURING,
LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE)
callback. Note that the video frame duplication detection is only available
for video frames with a resolution greater than 200 × 200, a frame rate
greater than or equal to 10 fps, and a bitrate less than 20 Kbps.
The local video state.
The detailed error information of the local video.
Occurs when the local audio state changes.
This callback indicates the state change of the local audio stream, including the state of the audio recording and encoding, and allows you to troubleshoot issues when exceptions occur.
State of the local audio.
The error information of the local audio.
Occurs when the remote audio state changes.
This callback indicates the state change of the remote audio stream.
ID of the remote user whose audio state changes.
State of the remote audio: RemoteAudioState.
The reason of the remote audio state change: RemoteAudioStateReason.
Time elapsed (ms) from the local user calling the joinChannel method until the SDK triggers this callback.
Occurs when the state of the media stream relay changes.
The SDK reports the state of the current media relay and possible error messages in this callback.
The state code. See ChannelMediaRelayState.
The error code. See ChannelMediaRelayError.
Reports events during the media stream relay.
The event code. See ChannelMediaRelayEvent.
Receives the media metadata.
After the sender sends the media metadata by calling the sendMetadata method and the receiver receives the media metadata, the SDK triggers this callback and reports the metadata to the receiver.
The media metadata.
Sends the media metadata successfully.
After the sender sends the media metadata successfully by calling the sendMetadata method, the SDK triggers this calback to reports the media metadata to the sender.
The media metadata.
Occurs when the first audio frame is published.
The time elapsed (ms) from the local client calling joinChannel until the SDK triggers this callback.
Occurs when the first video frame is published.
The time elapsed (ms) from the local client calling joinChannel until the SDK triggers this callback.
Reports events during the RTMP or RTMPS streaming.
The RTMP or RTMPS streaming URL.
The event code.
Occurs when the audio publishing state changes.
The channel name.
The previous publishing state.
The current publishing state.
The time elapsed (ms) from the previous state to the current state.
Occurs when the video publishing state changes.
The channel name.
The previous publishing state.
The current publishing state.
The time elapsed (ms) from the previous state to the current state.
Occurs when the audio subscribing state changes.
The channel name.
The ID of the remote user.
The previous subscribing state.
The current subscribing state.
The time elapsed (ms) from the previous state to the current state.
Occurs when the video subscribing state changes.
The channel name.
The ID of the remote user.
The previous subscribing state.
The current subscribing state.
The time elapsed (ms) from the previous state to the current state.
Reserved callback.
Reports whether the virtual background is successfully enabled. (beta function)
Whether the virtual background is successfully enabled:
The reason why the virtual background is not successfully enabled or the message that confirms success. See VIRTUAL_BACKGROUND_SOURCE_STATE_REASON.
Reports the voice pitch of the local user.
The voice pitch (Hz) of the local user.
Occurs when the user role switch fails in the interactive live streaming.
The reason for the user role switch failure. See CLIENT_ROLE_CHANGE_FAILED_REASON.
The current user role. See CLIENT_ROLE_TYPE.
Reports the proxy connection state.
The channel name.
The user ID.
The proxy type connected. See PROXY_TYPE.
Reserved for future use.
The time elapsed (ms) from the user calling
joinChannel until this callback is triggered.
Pauses the media stream relay to all destination channels.
Pauses all the audio effects.
Pauses playing and mixing the music file.
Call this API when you are in a channel.
Pauses a specified audio effect.
ID of the audio effect. Each audio effect has a unique ID.
Plays a specified local or online audio effect file.
To play multiple audio effect files at the same time, call this method
multiple times with different soundId and
filePath values. For the best user experience, Agora recommends
playing no more than three audio effect files at the same time.
After completing playing an audio effect file, the SDK triggers the
audioEffectFinished callback.
Audio effect ID. The ID of each audio effect file is unique. If you
preloaded an audio effect into memory by calling
preloadEffect, ensure that
this parameter is set to the same value as in preloadEffect.
The absolute path or URL address (including the filename extensions) of
the music file. For example: C:\music\audio.mp4. Supported
audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. For more
information, see
Supported Media Formats in Media Foundation. If you preloaded an audio effect into memory by calling
preloadEffect, ensure that
this parameter is set to the same value as in preloadEffect.
The number of times the audio effect loops:
1 means loop one
time, which means play the audio effect two times in total.
-1: Play the audio effect in an indefinite loop.The pitch of the audio effect. The range is 0.5 to 2.0. The default value is 1.0, which means the original pitch. The lower the value, the lower the pitch.
The spatial position of the audio effect. The range is
-1.0 to 1.0. For example:
-1.0: The audio effect occurs on the left.0.0: The audio effect occurs in the front.1.0: The audio effect occurs on the right.The volume of the audio effect. The range is 0.0 to 100.0. The default value is 100.0, which means the original volume. The smaller the value, the less the gain.
Whether to publish the audio effect to the remote users:
The playback position (ms) of the audio effect file.
Preloads a specified audio effect file into the memory.
To ensure smooth communication, limit the size of the audio effect file. We recommend using this method to preload the audio effect before calling the joinChannel method.
Supported audio formats: mp3, aac, m4a, 3gp, and wav.
Note: This method does not support online audio effect files.
ID of the audio effect. Each audio effect has a unique ID.
The absolute path of the audio effect file.
Allows a user to rate a call after the call ends.
The ID of the call, retrieved from the getCallId method.
Rating of the call. The value is between 1 (lowest score) and 5 (highest score).
(Optional) The description of the rating, with a string length of less than 800 bytes.
Registers a user account. Once registered, the user account can be used to identify the local user when the user joins the channel. After the user successfully registers a user account, the SDK triggers the onLocalUserRegistered callback on the local client, reporting the user ID and user account of the local user.
To join a channel with a user account, you can choose either of the following:
The difference between the two is that for the former, the time elapsed between calling the joinChannelWithUserAccount method and joining the channel is shorter than the latter.
To ensure smooth communication, use the same parameter type to identify the
user. For example, if a user joins the channel with a user ID, then ensure all
the other users use the user ID too. The same applies to the user account. If
a user joins the channel with the Agora Web SDK, ensure that the
uid of the user is set to the same parameter type.
Note:
userAccount parameter. Otherwise, this
method does not take effect.
userAccount parameter is unique in
the channel.
The App ID of your project.
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. Ensure that you set this parameter and do not set it as null. Supported character scopes are:
Registers a media metadata observer.
Releases the AgoraRtcEngine instance.
Once the App calls this method to release the created AgoraRtcEngine instance, no other methods in the SDK can be used and no callbacks can occur. To start it again, initialize initialize to establish a new AgoraRtcEngine instance.
Note: Call this method in the subthread.
Removes the injected online media stream from a live streaming.
HTTP/HTTPS URL address of the added stream to be removed.
Removes an RTMP stream from the CDN.
The RTMP URL address to be removed. The maximum length of this parameter is 1024 bytes.
Removes a stream from the high frame rate stream. Streams removed from the high frame rate stream will be controlled by the setVideoRenderFPS method.
The User ID.
Renews the token when the current token expires.
The key expires after a certain period of time once the Token schema is enabled when:
The app should retrieve a new token from the server and then call this method to renew it. Failure to do so results in the SDK disconnecting from the server.
The new token.
Resizes the renderer.
When the size of the view changes, this method refresh the zoom level so that video is sized appropriately while waiting for the next video frame to arrive.
Calling this method prevents a view discontinutity.
Key for the map that store the renderers, e.g, uid or
videosource or local.
Resumes the media stream relay to all destination channels.
Resumes playing all audio effects.
Resumes playing and mixing the music file.
Call this API when you are in a channel.
Resumes playing a specified audio effect.
sound id
Specifies the playback track of the current music file.
The specified playback track. This parameter must be less than or equal to the return value of getAudioTrackCount.
Agora supports reporting and analyzing customized messages.
Sends the media metadata.
After calling the
registerMediaMetadataObserver
method, you can call the setMetadata method to send the media
metadata.
If it is a successful sending, the sender receives the
sendMetadataSuccess callback, and the receiver receives the
receiveMetadata callback.
The media metadata.
Sends data stream messages to all users in a channel.
The SDK has the following restrictions on this method:
A successful sendStreamMessage method call triggers the streamMessage callback on the remote client, from which the remote user gets the stream message.
A failed sendStreamMessage method call triggers the streamMessageError callback on the remote client.
ID of the sent data stream, returned in the createDataStream method.
Data to be sent.
Specifies an SDK output log file.
The log file records all log data for the SDK’s operation. Ensure that the directory for the log file exists and is writable.
File path of the log file. The string of the log file is in UTF-8.
Sets parameters for SDK preset audio effects.
The options for SDK preset audio effects:
ROOM_ACOUSTICS_3D_VOICE.
profile parameter to
3
or 5 before setting this enumerator; otherwise, the
enumerator setting does not take effect.
PITCH_CORRECTION. To achieve
better audio effect quality, Agora recommends calling
setAudioProfile and
setting the profile parameter to 4 or
5 before setting this enumerator.
preset to ROOM_ACOUSTICS_3D_VOICE,
the param1 sets the cycle period of the 3D voice effect.
The value range is [1,60] and the unit is a second. The default value is
10 seconds, indicating that the voice moves around you every 10 seconds.
preset to PITCH_CORRECTION,
param1 sets the basic mode of the pitch correction effect:
1: (Default) Natural major scale.2: Natural minor scale.3: Japanese pentatonic scale.preset to ROOM_ACOUSTICS_3D_VOICE,
you need to set param2 to 0.
preset to PITCH_CORRECTION,
param2 sets the tonic pitch of the pitch correction effect:
1: A2: A#3: B4: (Default) C5: C#6: D7: D#8: E9: F10: F#11: G12: G#Sets an SDK preset audio effect.
The options for SDK preset audio effects.
Sets the channel mode of the current music file.
The channel mode. See AUDIO_MIXING_DUAL_MONO_MODE.
Sets the pitch of the local music file.
Sets the pitch of the local music file by chromatic scale. The default value is 0, which means keeping the original pitch. The value ranges from -12 to 12, and the pitch value between consecutive values is a chromatic value. The greater the absolute value of this parameter, the higher or lower the pitch of the local music file.
Sets the playback speed of the current music file.
The playback speed. Agora recommends that you limit this value to between 50 and 400, defined as follows:
Sets the playback position of the music file to a different starting position.
This method drags the playback progress bar of the audio mixing file to where you want to play instead of playing it from the beginning.
The playback starting position (ms) of the music file.
Sets the audio playback device using the device ID.
The device ID of the audio playback device.
Mutes the audio playback device.
Sets whether to mute/unmute the audio playback device:
Sets the volume of the audio playback device.
Sets the volume of the audio playback device. The value ranges between 0 (lowest volume) and 255 (highest volume).
Sets audio parameters and application scenarios.
Note:
0) and 1 (live streaming)
profiles, the bitrate may be different from your settings due to network
self-adaptation.
4 and scenario as
3.
Sets the sample rate, bitrate, encoding mode, and the number of channels.
1 (live streaming) profile: A sample rate of 48
KHz, music encoding, mono, and a bitrate of up to 64 Kbps.
0) profile:
Sets the audio application scenario.
Under different audio scenarios, the device uses different volume types. For details, see What is the difference between the in-call volume and the media volume?.
Sets the audio recording device using the device ID.
The device ID of the audio recording device.
Mutes/Unmutes the microphone.
Sets whether to mute/unmute the audio playback device:
Sets the volume of the microphone.
Sets the volume of the microphone. The value ranges between 0 (lowest volume) and 255 (highest volume).
Enables/Disables image enhancement and sets the options.
Sets whether or not to enable image enhancement:
The image enhancement options. It contains the following parameters:
Sets the camera capturer configuration.
For a video call or live streaming, generally the SDK controls the camera output parameters. When the default camera capture settings do not meet special requirements or cause performance problems, we recommend using this method to set the camera capture preference:
CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1) to optimize CPU and
RAM usage.
CAPTURER_OUTPUT_PREFERENCE_MANUAL(3).
The camera capturer configuration. See CameraCapturerConfiguration.
Sets the channel profile.
The AgoraRtcEngine applies different optimization according to the app scenario.
Note:
The channel profile:
Sets the role of a user (live streaming only).
This method sets the role of a user, such as a host or an audience (default), before joining a channel.
This method can be used to switch the user role after a user joins a channel.
In the 1 (live streaming)profile, when a user switches user roles
after joining a channel, a successful
setClientRole method call
triggers the following callbacks:
The client role:
Sets the role of a user in interactive live streaming.
The role of a user in interactive live streaming.
The detailed options of a user, including user level.
Sets the Agora cloud proxy service.
The cloud proxy type, see CLOUD_PROXY_TYPE. This parameter is required, and the SDK reports an error if you do not pass in a value.
-2: The parameter is invalid.-7: The SDK is not initialized.Sets color enhancement.
Sets whether to enable color enhancement:
true: Enable.false: (Default) Disable.The color enhancement options. See ColorEnhanceOptions.
Use this method to set custom Renderer when set renderMode in the setRenderMode method to 3. CustomRender should be a class.
Customizes the video renderer.
Stops or resumes subscribing to the audio streams of all remote users by default.
Sets whether to stop subscribing to the audio streams of all remote users by default.
Stops or resumes subscribing to the video streams of all remote users by default.
Sets whether to stop subscribing to the video streams of all remote users by default.
Sets the playback position of an audio effect file.
Audio effect ID. Ensure that this parameter is set to the same value as in
playEffect.
The playback position (ms) of the audio effect file.
-22: Cannot find the audio effect file. Please set a correct
soundId.
Sets the volume of the audio effects.
Sets the volume of the audio effects. The value ranges between 0 and 100 (default).
Sets the built-in encryption mode.
Sets the encryption mode:
Encryption Password
Sets whether to enable/disable full-band codec (48-kHz sample rate).
Sets whether to enable/disable stereo codec.
Sets whether to enable/disable high-bitrate mode.
Sets the video layout and audio settings for CDN live. (CDN live only)
The SDK triggers the otranscodingUpdated callback when you call the setLiveTranscoding method to update the LiveTranscoding class.
Sets the CDN live audio/video transcoding settings. See TranscodingConfig.
Sets the fallback option for the locally published video stream based on the network conditions.
The default setting for option is
STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), where there is no fallback
for the locally published video stream when the uplink network conditions are
poor. If option is set to
STREAM_FALLBACK_OPTION_AUDIO_ONLY (2), the SDK will:
localPublishFallbackToAudioOnly callback
is triggered.
Sets the fallback option for the locally published video stream.
STREAM_FALLBACK_OPTION_DISABLED (0): (Default) No fallback
behavior for the local/remote video stream when the uplink/downlink
network conditions are poor. The quality of the stream is not
guaranteed.
STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1): (Default) The
remote video stream falls back to the low-stream video when the downlink
network condition worsens. This option works not for the
setLocalPublishFallbackOption
method.
STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): Under poor uplink
network conditions, the locally published video stream falls back to
audio only.
The local voice changer option. See VoiceChangerPreset.
Sets the local voice equalization effect.
Sets the index of the band center frequency. The value ranges between 0 and 9, representing the respective band center frequencies of the voice effects including 31, 62, 125, 500, 1k, 2k, 4k, 8k, and 16kHz.
Sets the gain (dB) of each band. The value ranges between -15 and 15. The default value is 0.
Changes the voice pitch of the local speaker.
The value ranges between 0.5 and 2.0. The lower the value, the lower the voice pitch. The default value is 1.0 (no change to the local voice pitch).
Sets the local voice reverberation.
Sets the audio reverberation key.
0: Level (dB) of the dry signal. The value ranges between
-20 and 10.
1: Level (dB) of the early reflection signal (wet signal).
The value ranges between -20 and 10.
2: Room size of the reflection. A larger room size means a
stronger reverbration. The value ranges between 0 and
100.
3: Length (ms) of the initial delay of the wet signal. The
value ranges between 0 and 200.
4: The reverberation strength. The value ranges between 0
and 100.
Sets the effect of the reverberation key. See reverbKey for
the value range.
The local voice reverberation preset. See AudioReverbPreset.
Specifies an SDK output log file.
File path of the log file. The string of the log file is in UTF-8.
Sets the size of a log file that the SDK outputs.
The size (KB) of a log file. The default value is 1024 KB. If you set
size to 1024 KB, the SDK outputs at most 5 MB log files; if
you set it to less than 1024 KB, the maximum size of a log file is still
1024 KB.
Sets the output log level of the SDK.
Sets the filter level:
0: Do not output any log.0x080f: Output all the API logs. Set your log filter as
DEBUG if you want to get the most complete log file.
0x000f: Output logs of the CRITICAL, ERROR, WARNING and
INFO level. We recommend setting your log filter as this level.
0x000e: Output logs of the CRITICAL, ERROR and WARNING
level.
0x000c: Output logs of the CRITICAL and ERROR level.0x0008: Output logs of the CRITICAL level.Sets low-light enhancement.
Sets whether to enable low-light enhancement:
true: Enable.false: (Default) Disable.The low-light enhancement options. See LowLightEnhanceOptions.
Sets the maximum size of the media metadata.
After calling the
registerMediaMetadataObserver
method, you can call the setMaxMetadataSize method to set the
maximum size.
The maximum size of your metadata.
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.
The parameter as a JSON string in the specified format.
Sets the default video-stream type of the remotely subscribed video stream when the remote user sends dual streams.
Sets the video stream type:
Sets the fallback option for the remote video stream based on the network conditions.
If option is set as
STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1) or
STREAM_FALLBACK_OPTION_AUDIO_ONLY (2):
When the remote video stream falls back to audio only or when the audio-only
stream switches back to the video stream, the SDK triggers the
remoteSubscribeFallbackToAudioOnly callback.
Sets the fallback option for the remote stream.
STREAM_FALLBACK_OPTION_DISABLED (0): No fallback behavior
for the local/remote video stream when the uplink/downlink network
conditions are poor. The quality of the stream is not guaranteed.
STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1): (Default) The
remote video stream falls back to the low-stream video when the downlink
network condition worsens. This option works only for this method and
not for the
setLocalPublishFallbackOption
method.
STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): Under poor downlink
network conditions, the remote video stream first falls back to the
low-stream video; and then to an audio-only stream if the network
condition worsens.
Sets the priority of a remote user's media stream.
Use this method with the setRemoteSubscribeFallbackOption method. If the fallback function is enabled for a subscribed stream, the SDK ensures the high-priority user gets the best possible stream quality.
Note: The Agora SDK supports setting userPriority as high for one user only.
The ID of the remote user.
The priority of the remote user. See Priority.
Sets the stream type of the remote video.
Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode(false), the receiver can choose to receive either the high-video stream (the high resolution, and high bitrate video stream) or the low-video stream (the low resolution, and low bitrate video stream).
By default, users receive the high-video stream. Call this method if you want to switch to the low-video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources.
The aspect ratio of the low-video stream is the same as the high-video stream.
Once the resolution of the high-video stream is set, the system automatically
sets the resolution, frame rate, and bitrate of the low-video stream. The SDK
reports the result of calling this method in the
apiCallExecuted callback.
ID of the remote user sending the video stream.
Sets the video stream type:
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.
Note:
The ID of the remote user.
The sound position of the remote user. The value ranges from -1.0 to 1.0:
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.
Decide whether to use webgl/software/custom rendering.
Sets the content hint for screen sharing.
A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithm to different types of content.
The content hint for screen sharing. See VideoContentHint
Sets the screen sharing scenario.
The screen sharing scenario. See SCREEN_SCENARIO_TYPE.
Sets video noise reduction.
Sets whether to enable video noise reduction:
true: Enable.false: (Default) Disable.The video noise reduction options. See VideoDenoiserOptions.
Sets the video device using the device Id.
The device Id.
Sets the video encoder configuration.
Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation. 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.
If you do not set the video encoder configuration after joining the channel, you can call this method before calling the enableVideo method to reduce the render time of the first video frame.
The local video encoder configuration. See VideoEncoderConfiguration.
The video profile. See VIDEO_PROFILE_TYPE.
Sets the video quality preference:
Sets the renderer dimension of video.
This method ONLY affects size of data sent to js layer, while native video size is determined by setVideoEncoderConfiguration.
The renderer type:
The user ID of the targeted user.
The target width.
The target height.
Sets the global renderer frame rate (fps).
This method is mainly used to improve the performance of js rendering once set, the video data will be sent with this frame rate. This can reduce the CPU consumption of js rendering. This applies to ALL views except the ones added to the high frame rate stream.
The renderer frame rate (fps).
Sets renderer frame rate for the high stream.
The high stream here has nothing to do with the dual stream. It means the stream that is added to the high frame rate stream by calling the addVideoRenderToHighFPS method.
This is often used when we want to set the low frame rate for most of views, but high frame rate for one or two special views, e.g. screen sharing.
The renderer high frame rate (fps).
Sets parameters for SDK preset voice beautifier effects.
The options for SDK preset voice beautifier effects:
SINGING_BEAUTIFIER: Singing beautifier effect.The gender characteristics options for the singing voice:
1: A male-sounding voice.2: A female-sounding voice.The reverberation effects options:
1: The reverberation effect sounds like singing in a small
room.
2: The reverberation effect sounds like singing in a large
room.
3: The reverberation effect sounds like singing in a hall.
Sets an SDK preset voice beautifier effect.
The options for SDK preset voice beautifier effects.
Sets an SDK preset voice conversion effect.
The options for SDK preset voice conversion effects. See VOICE_CONVERSION_PRESET.
Sets the volume of a specified audio effect.
ID of the audio effect. Each audio effect has a unique ID.
Sets the volume of the specified audio effect. The value ranges between 0.0 and 100.0 (default).
Sets the local video view and the corresponding renderer.
The Dom element where you initialize your view.
Sets the video renderer for video source.
The dom element where video source should be displayed.
Sets the remote video view and the corresponding renderer.
The user ID
The Dom element where the remote view is initialized.
Sets the view content mode.
The user ID for operating streams. When setting up the view content of the remote user's stream, make sure you have subscribed to that stream by calling the subscribe method.
The view content mode:
Starts the audio device loopback test.
This method tests whether the local audio devices are working properly. After calling this method, the microphone captures the local audio and plays it through the speaker.
Note: This method tests the local audio devices and does not report the network conditions.
The time interval (ms).
Starts playing and mixing the music file.
This method supports mixing or replacing local or online music file and audio
collected by a microphone. After successfully playing the music file, the SDK
triggers the audioMixingStateChanged(710,720) callback. After
completing playing the music file, the SDK triggers
audioMixingStateChanged(713,723).
The absolute path or URL address (including the filename extensions) of
the music file. For example: C:\music\audio.mp4. Supported
audio formats include MP3, AAC, M4A, MP4, WAV, and 3GP. For more
information, see
Supported Media Formats in Media Foundation. When you access a local file on Android, Agora recommends passing a URI
address or the path starts with /assets/ in this parameter.
Whether to only play the music file on the local client:
true: Only play the music file on the local client so that
only the local user can hear the music.
false: Publish the music file to remote clients so that
both the local user and remote users can hear the music.
Whether to replace the audio collected by the microphone with a music file:
true: Replace. Users can only hear music.false: Do not replace. Users can hear both music and audio
collected by the microphone.
The number of times the music file plays.
0 means
that the SDK does not play the music file, while 1 means
that the SDK plays the music file once.
-1: Play the music in an indefinite loop.The playback position (ms) of the music file.
Starts the audio playback device test.
This method tests if the playback device works properly. In the test, the SDK plays an audio file specified by the user. If the user can hear the audio, the playback device works properly.
The path of the audio file for the audio playback device test in UTF-8:
The absolute file path of the recording file. The string of the file name
is in UTF-8, such as c:/music/audio.aac for Windows and
/var/mobile/Containers/Data/audio.aac for macOS.
Starts the microphone test.
This method checks whether the microphone works properly.
The interval period (ms).
Starts an audio recording on the client.
Recording configuration. See AudioRecordingConfiguration.
-160: The client is already recording audio. To start a new
recording, call
stopAudioRecording to
stop the current recording first, and then call
startAudioRecording.
Starts to relay media streams across channels.
After a successful method call, the SDK triggers the channelMediaRelayState and channelMediaRelayEvent callbacks, and these callbacks report the states and events of the media stream relay.
1 and the error code 0, and the and the
channelMediaRelayEvent
callback reports the event code 4 in
ChannelMediaRelayEvent,
the SDK starts relaying media streams between the original and the
destination channel.
3 in
ChannelMediaRelayState,
an exception occurs during the media stream relay.
The configuration of the media stream relay: ChannelMediaRelayConfiguration.
Starts an audio and video call loop test.
The configuration of the audio and video call loop test. See EchoTestConfiguration.
Starts an audio call test.
This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.
In the audio call test, you record your voice. If the recording plays back within the set time interval, the audio devices and the network connection are working properly.
Note:
1 (live streaming) profile, only hosts can call this
method.
The time interval (s) between when you speak and when the recording plays back.
Starts the last-mile network probe test before joining a channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and average round-trip time (RTT).
Once this method is enabled, the SDK returns the following callbacks:
lastMileQuality: the SDK triggers this callback within two
seconds depending on the network conditions. This callback rates the network
conditions with a score and is more closely linked to the user experience.
lastmileProbeResult: the SDK triggers this callback within 30
seconds depending on the network conditions. This callback returns the
real-time statistics of the network conditions and is more objective.
Call this method to check the uplink network quality before users join a channel or before an audience switches to a host.
The configurations of the last-mile network probe test. See LastmileProbeConfig.
Starts the local video preview before joining a channel.
Before starting the preview, always call setupLocalVideo to set up the preview window and configure the attributes, and also call the enableVideo method to enable video.
If startPreview is called to start the local video preview before calling joinChannel to join a channel, the local preview remains after after you call leaveChannel to leave the channel. Call stopPreview to disable the local preview.
Starts pushing media streams to a CDN and sets the transcoding configuration.
The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
The transcoding configuration for Media Push. See LiveTranscoding.
ERR_INVALID_ARGUMENT(-2): url is null or the string length is
0.
ERR_NOT_INITIALIZED(-7): The SDK is not initialized before
calling this method.
Starts pushing media streams to a CDN without transcoding.
The address of Media Push. The format is RTMP. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
ERR_INVALID_ARGUMENT(-2): url is null or the string length is
0.
ERR_NOT_INITIALIZED(-7): The SDK is not initialized before
calling this method.
Starts the screen sharing.
(Mandatory) The captured frame rate. The value ranges between 1 fps and 15 fps.
Specifies the screen sharing region. rect is valid when
wndid is set as 0. When rect is set as NULL, the
whole screen is shared.
The captured bitrate.
(Mandatory) The captured frame rate. The value ranges between 1 fps and 15 fps.
Specifies the video source region. rect is valid when
wndid is set as 0. When rect is set as NULL, the
whole screen is shared.
The captured bitrate.
Shares the whole or part of a screen by specifying the screen symbol.
The screen symbol. See ScreenSymbol.
(Optional) The relative location of the region to the screen. NULL means sharing the whole screen. See CaptureRect. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
The screen sharing encoding parameters. See CaptureParam
Shares the whole or part of a window by specifying the window symbol.
The symbol of the windows to be shared.
(Optional) The relative location of the region to the window. NULL/NIL means sharing the whole window. See CaptureRect. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window.
Window sharing encoding parameters. See CaptureParam
Starts the local video preview when using the video source.
Starts a video-capture device test.
Note: This method tests whether the video-capture device works properly. Ensure that you call the enableVideo method before calling this method and that the HWND window handle of the incoming parameter is valid.
Stops playing all audio effects.
Stops the audio device loopback test.
Note: Ensure that you call this method to stop the loopback test after calling the startAudioDeviceLoopbackTest method.
Stops playing or mixing the music file.
Call this API when you are in a channel.
Stops the audio playback device test.
This method stops testing the audio playback device. You must call this method to stop the test after calling the startAudioPlaybackDeviceTest method.
Stops an audio recording on the client.
You can call this method before calling the leaveChannel method else to stop the recording automatically.
Stops the microphone test.
Note: This method stops the microphone test. You must call this method to stop the test after calling the startAudioRecordingDeviceTest method.
Stops the media stream relay.
Once the relay stops, the host quits all the destination channels.
After a successful method call, the SDK triggers the channelMediaRelayState
callback. If the callback reports the state code 0 and the error
code 1, the host successfully stops the relay.
Note: If the method call fails, the SDK triggers the
channelMediaRelayState callback with the error code 2 and
8 in
ChannelMediaRelayError. You
can leave the channel by calling the
leaveChannel method, and the
media stream relay automatically stops.
Stops the audio call test.
Stops playing a specified audio effect.
ID of the audio effect to stop playing. Each audio effect has a unique ID.
Stops the last-mile network probe test.
Stops the local video preview and closes the video.
Stops pushing media streams to a CDN.
The address of Media Push. The format is RTMP or RTMPS. The character length cannot exceed 1024 bytes. Special characters such as Chinese characters are not supported.
Stops screen sharing.
Stops the screen sharing when using the video source.
Stops the local video preview when using the video source.
Stops the video-capture device test.
Note: This method stops testing the video-capture device. You must call this method to stop the test after calling the startVideoDeviceTest method.
Subscribes to a remote user and initializes the corresponding renderer.
The user ID of the remote user.
The Dom where to initialize the renderer.
Switches to a different channel, and configures whether to automatically subscribe to audio or video streams in the target channel.
This method allows the audience of a 1 (live streaming) channel
to switch to a different channel.
After the user successfully switches to another channel, the
leaveChannel and joinChannelSuccess callbacks are
triggered to indicate that the user has left the original channel and joined a
new one.
The token generated at your server. For details, see Generate a token.
The unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:
The channel media options. See ChannelMediaOptions.
-1: A general error occurs (no specified reason).-2: The parameter is invalid.-5: The request is rejected, probably because the user is not
an audience.
-7: The SDK is not initialized.-102: The channel name is invalid.-113: The user is not in the channel.Takes a snapshot of a video stream.
The channel name.
The user ID of the user. Set uid as 0 if you want to take a
snapshot of the local user's video.
The local path (including the filename extensions) of the snapshot. For
example,
C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg
on Windows, /App Sandbox/Library/Caches/example.jpg on iOS,
～/Library/Logs/example.jpg on macOS, and
/storage/emulated/0/Android/data/<package
name>/files/example.jpg
on Android. Ensure that the path you specify exists and is writable.
Unregisters a media metadata observer.
Releases a specified preloaded audio effect from the memory.
ID of the audio effect. Each audio effect has a unique ID.
Updates the channels for media stream relay.
After the channel media relay starts, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.
After a successful method call, the SDK triggers the channelMediaRelayState
callback with the state code 7 in
ChannelMediaRelayEvent.
Note:
Call this method after the startChannelMediaRelay method to update the destination channel.
The media stream relay configuration: ChannelMediaRelayConfiguration.
Updates the transcoding configuration.
The transcoding configuration for Media Push. See LiveTranscoding.
Updates the screen sharing parameters.
The screen sharing encoding parameters. See CaptureParam
Updates the screen capture region.
(relative distance from the left-top corner of the screen)
meeting
Enables the audio module.
The audio module is disabled by default.
Note:
Enables/Disables the built-in encryption.
Whether to enable the built-in encryption:
Configurations of built-in encryption schemas.
Enables loopback audio capturing.
If you enable loopback audio capturing, the output of the sound card is mixed into the audio stream sent to the other end.
The device name of the sound card. The default value is NULL (the default sound card). Note: macOS does not support loopback capturing of the default sound card. If you need to use this method, please use a virtual sound card and pass its name to the deviceName parameter. Agora has tested and recommends using soundflower.
Set whether or not to enable the web interoperability of the video source.
Initializes agora real-time-communicating video source with the app Id.
The app ID issued to you by Agora.
optional groupId of your application, you will need to specify this field in order to start a process in MacOS Sandbox.
optional bundleId of your application, you will need to specify this field in order to start a process in MacOS Sandbox
ERR_INVALID_APP_ID (101): The app ID is invalid. Check if it
is in the correct format.
Allows a user to join a channel when using the video source.
The token generated at your server:
(Required) The unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:
Additional information about the channel. This parameter can be set to NULL or contain channel related information. Other users in the channel will not receive this message.
The User ID. The same user ID cannot appear in a channel. Ensure that the
user ID of the videoSource here is different from the
uid used by the user when calling the
joinChannel method.
Allows a user to leave a channe when using the video source.
Note: You must call this method after calling the videoSourceJoin method.
Releases the video source object.
Gets a new token for a user using the video source when the current token expires after a period of time.
The application should call this method to get the new token.
Failure to do so will result in the SDK disconnecting from the server.
The new token.
Sets the channel profile when using the video source.
Sets the channel profile:
Enables built-in encryption with an encryption password before users join a channel.
The encryption password.
Specifies an SDK output log file for the video source object.
Note: Call this method after the videoSourceInitialize method.
filepath of log. The string of the log file is in UTF-8.
Sets the video source parameters.
Sets the video source encoding parameters.
Updates the video source parameters.
Sets the content hint for the video source.
Sets the video profile for the video captured by the camera device.
The video profile. See VIDEO_PROFILE_TYPE.
Shares the whole or part of a screen by specifying the screen rect.
The display ID：
Sets the relative location of the region to the screen.
Sets the video source encoding parameters.
Shares the whole or part of a window by specifying the window ID.
The ID of the window to be shared.
The ID of the window to be shared.
Sets the video source encoding parameters.
Updates the video source parameters.
Sets the video source encoding parameters.
Updates the screen capture region for the video source.
(relative distance from the left-top corner of the screen)
The AgoraRtcEngine class. The AgoraRtcEngine interface.