Discussion

Call this method to initialize the service before using AgoraRtcEngineKit.

Discussion

This method is useful for apps that occasionally make voice or video calls, to free up resources for other operations when not making calls.

Once the app calls this method to release the created AgoraRtcEngineKit instance, no other methods in the SDK can be used and no callbacks can occur. To start communications again, initialize sharedEngineWithappId to establish a new AgoraRtcEngineKit instance.

Note:

• Call this method in the subthread.
• This method call is synchronous. The result returns after the AgoraRtcEngineKit object resources are released. The app should not call this interface in the callback generated by the SDK. Otherwise, the SDK must wait for the callback to return before it can reclaim the related object resources, causing a deadlock.

Discussion

The AgoraRtcEngineKit differentiates channel profiles and applies optimization algorithms accordingly. For example, it prioritizes smoothness and low latency for a video call, and prioritizes video quality for a video broadcast.

Note:

• To ensure the quality of real-time communication, we recommend that all users in a channel use the same channel profile.
• Call this method before calling joinChannelByToken. You cannot set the channel profile once you have joined the channel.

Discussion

This method is applicable only to the Live-broadcast profile.

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.

When a user switches user roles after joining a channel, a successful method call triggers the following callback:

• The local client: didClientRoleChanged
• Remote clients: didJoinedOfUid or didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience)

Discussion

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 even if they join the same channel.

You must call the leaveChannel method to exit the current call before entering another channel. This method call is asynchronous; therefore, you can call this method in the main user interface thread.

The SDK uses the iOS’s AVAudioSession shared object for audio recording and playback. Using this object may affect the SDK’s audio functions.

If the joinChannelByToken method call succeeds, the SDK triggersjoinSuccessBlock. If you implement both joinSuccessBlock and didJoinChannel, joinSuccessBlock takes higher priority than didJoinChannel.

We recommend you set joinSuccessBlock as nil to use didJoinChannel.

A successful joinChannel method call triggers the following callbacks:

• The local client: didJoinChannel
• The remote client: didJoinedOfUid, if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile.

When the connection between the client and Agora’s 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 didRejoinChannel callback on the local client.

Note:

• A channel does not accept duplicate UIDs, such as two users with the same uid. If you set uid as 0, the system automatically assigns a uid. If you want to join the same channel on different devices, ensure that different uids are used for each device.
• When joining a channel, the SDK calls setCategory(AVAudioSessionCategoryPlayAndRecord) to set AVAudioSession to PlayAndRecord mode. When AVAudioSession is set to PlayAndRecord mode, the sound played (for example a ringtone) is interrupted. The app should not set AVAudioSession to any other mode.

Discussion

After the user successfully joins the channel, the SDK triggers the following callbacks:

• On the local client: didRegisteredLocalUser and didJoinChannel.
• On the remote client: didJoinedOfUid and didUpdatedUserInfo, if the user joining the channel is in the Communication profile, or is a BROADCASTER in the Live Broadcast profile.

Discussion

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 didRegisteredLocalUser 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:

• Call the registerLocalUserAccount method to create a user account, and then the joinChannelByUserAccount method to join the channel.
• Call the joinChannelByUserAccount method to join the channel.

The difference between the two is that for the former, the time elapsed between calling the joinChannelByUserAccount method and joining the channel is shorter than the latter.

Note:

• Ensure that you set the userAccount parameter. Otherwise, this method does not take effect.
• Ensure that the value of the userAccount parameter is unique in the channel.
• To ensure smooth communication, use the same parameter type to identify the user. For example, if a user joins the channel with a user ID, then ensure that 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.

Discussion

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 (AgoraUserInfo), and triggers the didUpdatedUserInfo callback on the local client.

After receiving the didUpdatedUserInfo 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.

Discussion

After a user joins the channel, the SDK gets the user ID and user account of the remote user, caches them in a mapping table object (AgoraUserInfo), and triggers the didUpdatedUserInfo callback on the local client.

After receiving the didUpdatedUserInfo callback, you can call this method to get the user account of the user from the userInfo object by passing in the user ID.

Discussion

This method allows the audience of a Live-broadcast channel to switch to a different channel.

After the user successfully switches to another channel, the didLeaveChannelWithStats and didJoinChannel callbacks are triggered to indicate that the user has left the original channel and joined a new one.

Discussion

After joining a channel, the user must call the leaveChannel method to end the call before joining another channel.

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 exited the channel when the method call returns.

A successful leaveChannel method call triggers the following callbacks:

• The local client: didLeaveChannelWithStats
• The remote client: didOfflineOfUid(AgoraUserOfflineReasonBecomeAudience), if the user leaving the channel is in the Communication channel, or is a BROADCASTER in the Live Broadcast profile.

Note:

• If you call destroy immediately after leaveChannel, the leaveChannel process interrupts, and the SDK does not trigger the didLeaveChannelWithStats callback.
• If you call this method during CDN live streaming, the SDK triggers the removePublishStreamUrl method.
• When you call this method, the SDK deactivates the audio session on iOS by default, and may affect other apps. If you do not want this default behavior, use setAudioSessionOperationRestriction to set AgoraAudioSessionOperationRestrictionDeactivateSession so that when you call the leaveChannel method, the SDK does not deactivate the audio session.

Discussion

The token expires after a period of time once the token schema is enabled when:

• The SDK triggers the tokenPrivilegeWillExpire callback, or
• connectionChangedToState reports AgoraConnectionChangedTokenExpired(9) in thereason parameter.

Note:

Agora recommends using the rtcEngineRequestToken callback to report the AgoraErrorCodeTokenExpired(-109) error, not using the didOccurError callback.

The app should call this method to get the token. Failure to do so results in the SDK disconnecting from the server.

Discussion

After a successful method call, the SDK triggers the channelMediaRelayStateDidChange and didReceiveChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.

• If the channelMediaRelayStateDidChange callback returns AgoraChannelMediaRelayStateRunning(2) and AgoraChannelMediaRelayStateIdle(0), and the didReceiveChannelMediaRelayEvent callback returns AgoraChannelMediaRelayEventSentToDestinationChannel(4), the SDK starts relaying media streams between the original and the destination channel.
• If the channelMediaRelayStateDidChange callback returns AgoraChannelMediaRelayStateFailure(3), an exception occurs during the media stream relay.

Note

• Call this method after the joinChannel method.
• This method takes effect only when you are a broadcaster in a Live-broadcast channel.
• After a successful method call, if you want to call this method again, ensure that you call the stopChannelMediaRelay method to quit the current relay.
• Contact sales-us@agora.io before implementing this function.
• We do not support string user accounts in this API.

Discussion

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 didReceiveChannelMediaRelayEvent callback with the AgoraChannelMediaRelayEventUpdateDestinationChannel(7) state code.

Note

• Call this method after the startChannelMediaRelay method to update the destination channel.
• This method supports adding at most four destination channels in the relay. If there are already four destination channels in the relay, remove the unnecessary ones with the removeDestinationInfoForChannelName method in channelMediaRelayConfiguration before calling this method.

Discussion

Once the relay stops, the broadcaster quits all the destination channels.

After a successful method call, the SDK triggers the channelMediaRelayStateDidChange callback. If the callback returns AgoraChannelMediaRelayStateIdle(0) and AgoraChannelMediaRelayErrorNone(0), the broadcaster successfully stops the relay.

Discussion

The audio module is enabled by default.

Note:

• This method affects the internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.

• This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the audio engine modules separately:

  • enableLocalAudio: Whether to enable the microphone to create the local audio stream.
  • muteLocalAudioStream: Whether to publish the local audio stream.
  • muteRemoteAudioStream: Whether to subscribe to and play the remote audio stream.
  • muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.

Discussion

Note:

• This method affects the internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.

• This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the audio engine modules separately:

  • enableLocalAudio: Whether to enable the microphone to create the local audio stream.
  • muteLocalAudioStream: Whether to publish the local audio stream.
  • muteRemoteAudioStream: Whether to subscribe to and play the remote audio stream.
  • muteAllRemoteAudioStreams: Whether to subscribe to and play all remote audio streams.

Discussion

Note:

• You must call this method before the joinChannelByToken method.
• In the Communication profile, you can set the profile but not the scenario.
• In the Communication and Live-broadcast profiles, the bitrates may be different from your settings due to network self-adaptation.
• In scenarios requiring high-quality audio, we recommend setting profile as AgoraAudioProfileMusicHighQuality(4) and scenario as AgoraAudioScenarioGameStreaming(3). For example, for music education scenarios.

Discussion

Note

• This method adjusts the playback volume which is mixed volume of all remote users.
• Since v2.3.2, to mute the local audio playback, call both adjustPlaybackSignalVolume and adjustAudioMixingVolume, and set volume as 0.

Discussion

When an app joins a channel, the audio module is enabled by default. This method disables or re-enables the local audio capture, that is, to stop or restart local audio capturing and processing.

This method does not affect receiving or playing the remote audio streams, and enableLocalAudio(NO) 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 didMicrophoneEnabled callback once the local audio module is disabled or re-enabled.

Note:

This method is different from the muteLocalAudioStream method:

• enableLocalAudio: Disables/Re-enables the local audio capturing and processing. If you disable or re-enable local audio recording using the enableLocalAudio method, the local user may hear a pause in the remote audio playback.
• muteLocalAudioStream: Sends/Stops sending the local audio stream.

Discussion

Use this method to stop/start sending the local audio stream. A successful muteLocalAudioStream method call triggers the didAudioMuted callback on the remote client.

Note:

• When mute is set as YES, this method does not disable the microphone and thus does not affect any ongoing recording.
• If you call setChannelProfile after this method, the SDK resets whether or not to mute the local audio according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.

Discussion

Note:

If you call the muteAllRemoteAudioStreams method and set mute as YES to mute all remote audio streams, call the muteAllRemoteAudioStreams method again and set mute as NO before calling this method. The muteAllRemoteAudioStreams method sets all remote streams, while the muteRemoteAudioStream method sets a specified stream.

Discussion

You can call this method either before or after joining a channel. If you call setDefaultMuteAllRemoteAudioStreams (YES) after joining a channel, the remote audio streams of all subsequent users are not received.

Discussion

Since v3.0.0.

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

• Call this method after joining a channel.
• 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.

Discussion

You can call this method either before entering a channel or during a call. If you call this method before entering 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.

A successful enableVideo method call triggers the didVideoEnabled(YES) callback on the remote client.

To disable the video, call the disableVideo method.

Note:

• This method affects the internal engine and can be called after the leaveChannel method.

• This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:

  • enableLocalVideo: Whether to enable the camera to create the local video stream.
  • muteLocalVideoStream: Whether to publish the local video stream.
  • muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
  • muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.

Discussion

You can call this method before entering a channel or during a call. If you call this method before entering a channel, the service starts in the audio mode. If you call this method during a video call, the video mode switches to the audio mode. To enable the video module, call the enableVideo method.

A successful disableVideo method call triggers the didVideoEnabled(NO) callback on the remote client.

Note:

• This method affects the internal engine and can be called after the leaveChannel method.

• This method resets the internal engine and takes some time to take effect. Agora recommends using the following API methods to control the video engine modules separately:

  • enableLocalVideo: Whether to enable the camera to create the local video stream.
  • muteLocalVideoStream: Whether to publish the local video stream.
  • muteRemoteVideoStream: Whether to subscribe to and play the remote video stream.
  • muteAllRemoteVideoStreams: Whether to subscribe to and play all remote video streams.

Discussion

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 unreliable network conditions, the parameters further down the list are considered until a successful configuration is found.

If you do not need to set the video encoder configuration after joining a channel, you can call this method before calling the enableVideo method to reduce the render time of the first video frame.

Note:

From v2.3.0, the following API methods are deprecated:

• setVideoProfile
• setVideoResolution

Discussion

This method initializes the video view of the local stream on the local device. It affects only the video view that the local user sees, not the published local video stream.

Call this method to bind the local video stream to a video view and to set the rendering and mirror modes of the video view. To unbind the view, set the view in AgoraRtcVideoCanvas to nil.

Note

• Call this method before joining a channel.
• To update the rendering or mirror mode of the local video view during a call, use setLocalRenderMode.

Discussion

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.

Call this method to bind the remote video stream to a video view and to set the rendering and mirror modes of the video view.

The app specifies the uid of the remote video in this method call before the user joins a channel.

If the remote uid is unknown to the app, set it after the app receives the userJoinedBlock callback.

If the Video Recording function is enabled, the Video Recording Service joins the channel as a dummy client, causing other clients to also receive the didJoinedOfUid callback. Do not bind the dummy client to the app view because the dummy client does not send any video streams. If your app does not recognize the dummy client, bind the remote user to the view when the SDK triggers the firstRemoteVideoDecodedOfUid callback.

To unbind the remote user from the view, set the view in AgoraRtcVideoCanvas as nil. Once the remote user leaves the channel, the SDK unbinds the remote user.

Discussion

By default, the local preview enables the mirror mode.

Before calling this method, you must:

• Call the setupLocalVideo method to set up the local preview window and configure the attributes.
• Call the enableVideo method to enable video.

Note:

Once you call this method to start the local video preview, if you leave the channel by calling the leaveChannel method, the local video preview remains until you call the stopPreview method to disable it.

Discussion

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(NO) to disable the local video capturer. If you want to re-enable it, call enableLocalVideo(YES).

After the local video capturer is successfully disabled or re-enabled, the SDK triggers the didLocalVideoEnabled callback on the remote client.

Note:

This method enables the internal engine and can be called after calling the leaveChannel method.

Discussion

A successful muteLocalVideoStream method call triggers the didVideoMuted callback on the remote client.

Note:

• When you set mute as YES, this method does not disable the camera, and thus does not affect the retrieval of the local video stream. This method responds faster compared to the enableLocalVideo method which controls the sending of local video streams.
• If you call setChannelProfile after this method, the SDK resets whether or not to mute the local video according to the channel profile and user role. Therefore, we recommend calling this method after the setChannelProfile method.

Discussion

Note:

If you call the muteAllRemoteVideoStreams method and set mute as YES to stop receiving all remote video streams, call the muteAllRemoteVideoStreams method again and set mute as NO before calling this method.

Discussion

You can call this method either before or after joining a channel. If you call setDefaultMuteAllRemoteVideoStreams (YES) after joining a channel, the remote video streams of all subsequent users are not received.

Discussion

Discussion

This method sets whether the received audio is routed to the earpiece or speakerphone by default before joining a channel. If a user does not call this method, the audio is routed to the earpiece by default.

If you need to change the default audio route after joining a channel, call the setEnableSpeakerphone method.

Note:

• This method is applicable only to the Communication profile.
• This method only works in a voice call.
• Call this method before calling the joinChannelByToken method.

The default settings for each profile:

• Communication: Earpiece.
• Live Broadcast: Speakerphone.

Discussion

This method sets whether the audio is routed to the speakerphone. After this method is called, the SDK returns the didAudioRouteChanged callback, indicating that the audio route changes.

Note:

• Ensure that you have successfully called the joinChannelByToken method before calling this method.
• The SDK calls setCategory(AVAudioSessionCategoryPlayAndRecord) with options to configure the headset/speakerphone, so this method applies to all audio playback in the system.

Discussion

v2.4.0 adds the setLocalVoiceReverbPreset method, a more user-friendly method for setting the local voice reverberation. You can use this method to set the local reverberation effect, such as Popular, R&B, Rock, Hip-hop, and more.

Discussion

Sets the local voice changer option.

Note:

Do not use this method together with setLocalVoiceReverbPreset, or the method called earlier does not take effect.

Discussion

Note:

• Do not use this method together with setLocalVoiceReverbOfType.
• Do not use this method together with setLocalVoiceChanger, or the method called earlier does not take effect.

Discussion

If you need to use the setRemoteVoicePosition method, ensure that you call this method before joining a channel to enable stereo panning for remote users.

Discussion

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:

• For this method to work, enable stereo panning for remote users by calling enableSoundPositionIndication before joining a channel. This method requires hardware support.
• For the best effect, we recommend using the following audio output devices:
  • (iOS) A stereo headset.
  • (macOS) A stereo loudspeaker.

Discussion

This method mixes the specified local audio file with the audio stream from the microphone, or replaces the microphone’s audio stream with the specified local audio file. You can choose whether the other user can hear the local audio playback and specify the number of playback loops. This method also supports online music playback.

A successful startAudioMixing method call triggers the localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying) callback on the local client.

When the audio mixing file playback finishes, the SDK triggers the localAudioMixingStateDidChanged(AgoraAudioMixingStateStopped) callback on the local client.

Note:

• To use this method, ensure that the iOS device version is 8.0 and later.
• Call this method when you are in a channel.
• If you want to play an online music file, ensure that the time interval between playing the online music file and calling this method is greater than 100 ms, or the AudioFileOpenTooFrequent(702) warning occurs.
• If the local audio mixing file does not exist, or if the SDK does not support the file format or cannot access the music file URL, the SDK returns AgoraWarningCodeAudioMixingOpenError(701).

Discussion

Call this method when you are in a channel.

Discussion

Call this method when you are in a channel.

Discussion

Call this method when you are in a channel.

Discussion

Call this method when you are in a channel.

Note:

Calling this method does not affect the volume of audio effect file playback invoked by the playEffect method.

Discussion

Call this method when you are in a channel.

Discussion

Call this method when you are in a channel.

Discussion

This method helps troubleshoot audio volume related issues.

Discussion

This method helps troubleshoot audio volume related issues.

Discussion

Call this method when you are in a channel.

Discussion

Call this method when you are in a channel.

Discussion

The value ranges between 0.0 and 100.0.

Discussion

You can use this method to add specific audio effects for specific scenarios, for example, gaming.

With this method, you can set the loop count, pitch, pan, and gain of the audio effect file and whether the remote user can hear the audio effect.

To play multiple audio effect files simultaneously, call this method multiple times with different soundIds and filePaths. We recommend playing no more than three audio effect files at the same time.

When the audio effect file playback is finished, the SDK triggers the rtcEngineDidAudioEffectFinish callback.

Discussion

To ensure smooth communication, limit the size of the audio effect file. Agora recommends using this method to preload the audio effect before calling the joinChannelByToken method.

Supported audio formats: mp3, aac, m4a, 3gp, and wav.

Discussion

The SDK allows recording during a call. After successfully calling this method, you can record the audio of all the users in the channel and get an audio recording file. Supported formats of the recording file are as follows:

• .wav: Large file size with high fidelity.
• .aac: Small file size with low fidelity.

Note

• Ensure that the directory you use to save the recording file exists and is writable.
• This method is usually called after the joinChannelByToken method. The recording automatically stops when you call the leaveChannel method.
• For better recording effects, set quality as AgoraAudioRecordingQualityMedium or AgoraAudioRecordingQualityHigh when sampleRate is 44100 Hz or 48000 Hz.

Discussion

Note:

You can call this method before calling the leaveChannel method, else the recording automatically stops when you call the leaveChannel method.

Discussion

If you enable loopback recording, the output of the sound card is mixed into the audio stream sent to the other end.

Note:

macOS does not support loopback recording 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.

Discussion

The SDK and the app can both configure the audio session by default. The app may occasionally use other apps or third-party components to manipulate the audio session and restrict the SDK from doing so. This method allows the app to restrict the SDK’s manipulation of the audio session.

You can call this method at any time to return the control of the audio sessions to the SDK.

Note:

This method restricts the SDK’s manipulation of the audio session. Any operation to the audio session relies solely on the app, other apps, or third-party components.

Discussion

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:

• Call this method before joining a channel.

• After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, or join a channel.

• In the Live-broadcast profile, only a host can call this method.

Discussion

This method tests the quality of the user’s network connection 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. We do not recommend calling this method together with startLastmileProbeTest.

Call the disableLastmileTest method to disable this test after receiving the lastmileQuality callback, and before the user joins the channel or switches the user role.

Note:

• Do not call any other methods before receiving the lastmileQuality callback. Otherwise, the callback may be interrupted by other methods and may not execute.

• In the Live-broadcast profile, a host should not call this method after joining a channel.

• If you call this method to test the last-mile quality, the SDK consumes the bandwidth of a video stream, whose bitrate corresponds to the bitrate you set in the setVideoEncoderConfiguration method. After you join the channel, whether you have called the disableLastmileTest method or not, the SDK automatically stops consuming the bandwidth.

Discussion

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 round-trip time (RTT).

Call this method to check the uplink network quality before users join a channel or before an audience switches to a host.

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 and is more closely linked to the user experience.
• lastmileProbeResultthe 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.

Note:

• This method consumes extra network traffic and may affect communication quality. We do not recommend calling this method together with enableLastmileTest.
• Do not call other methods before receiving the lastmileQuality and lastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
• In the Live-broadcast profile, a host should not call this method after joining a channel.

Discussion

In real-time communications, the SDK uses the default video input source (the built-in camera) to publish streams. To use an external video source, call AgoraVideoSourceProtocol to set the custom video source and then use this method to add the external video source into the SDK.

Discussion

In real-time communications, the SDK uses the default video renderer to render the video. To use an external video renderer, call AgoraVideoSinkProtocol to set the custom local video renderer and then use this method to add the external renderer into the SDK.

Discussion

This method sets the remote renderer. In real-time communications, the SDK uses the default video renderer to render the video. To use an external video renderer, call AgoraVideoSinkProtocol to set the custom remote video renderer and then use this method to add the external renderer into the SDK.

Discussion

This method applies to scenarios where you want to use external audio data for playback. After enabling the external audio sink, you can call the pullPlaybackAudioFrameRawData / pullPlaybackAudioFrameSampleBufferByLengthInByte method to pull the remote audio data, process it, and play it with the audio effects that you want.

Discussion

Before calling this method, call the enableExternalAudioSink method to enable and set the external audio sink.

After a successful method call, the app pulls the decoded and mixed audio data for playback.

Note

• Once you call the pullPlaybackAudioFrameRawData method successfully, the app will not retrieve any audio data from the onPlaybackAudioFrame callback.
• The difference between the onPlaybackAudioFrame callback and the pullPlaybackAudioFrameRawData method is as follows:
  • onPlaybackAudioFrame: The SDK sends the audio data to the app once every 10 ms. Any delay in processing the audio frames may result in audio jitter.
  • pullPlaybackAudioFrameRawData: The app pulls the remote audio data autonomously. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in the external audio playback.

Discussion

Before calling this method, call the enableExternalAudioSink method to enable and set the external audio sink.

After a successful method call, the app pulls the decoded and mixed audio data for playback.

Note

• Once you call the pullPlaybackAudioFrameSampleBufferByLengthInByte method successfully, the app will not retrieve any audio data from the onPlaybackAudioFrame callback.
• The difference between the onPlaybackAudioFrame callback and the pullPlaybackAudioFrameSampleBufferByLengthInByte method is as follows:
  • onPlaybackAudioFrame: The SDK sends the audio data to the app once every 10 ms. Any delay in processing the audio frames may result in audio jitter.
  • pullPlaybackAudioFrameSampleBufferByLengthInByte: The app pulls the remote audio data. After setting the audio data parameters, the SDK adjusts the frame buffer and avoids problems caused by jitter in the external audio playback.

Discussion

Call this method before joining the channel.

Discussion

If an external video source is used, call this method before the enableVideo or startPreview method.

Discussion

This method pushes the video frame using the AgoraVideoFrame class and passes the video frame to the SDK with the format parameter found in AgoraVideoFrame. Call the setExternalVideoSource method and set the pushMode parameter as YES before calling this method. Otherwise, a failure returns after calling this method.

Note:

In the Communication profile, this method does not support pushing textured video frames.

Discussion

See Raw Audio Data.

Discussion

See Raw Audio Data.

Discussion

See Raw Audio Data.

Discussion

This method adds a PNG watermark image to the local video in a live broadcast. Once the watermark image is added, all the audience in the channel (CDN audience included), and the recording 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 AgoraVideoOutputOrientationModeFixedLandscape, or the landscape mode in AgoraVideoOutputOrientationModeAdaptative, the watermark uses the landscape orientation.
• If the orientation mode of the encoding video is AgoraVideoOutputOrientationModeFixedPortrait, or the portrait mode in AgoraVideoOutputOrientationModeAdaptative, 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.

Note

• Ensure that you have called the enableVideo method to enable the video module before calling this method.
• If you only want to add a watermark image to the local video for the audience in the CDN live broadcast channel to see and capture, you can call this method or the setLiveTranscoding method.
• This method supports adding a watermark image in the PNG file format only. Supported pixel formats of the PNG image are RGBA, RGB, Palette, Gray, and Alpha_gray.
• If the dimensions of the PNG image differ from your settings in this method, the image will be cropped or zoomed to conform to your settings.
• If you have enabled the local video preview by calling the startPreview method, you can use the visibleInPreview member in the WatermarkOptions class to set whether or not the watermark is visible in preview.
• If you have mirrored the local video by calling the setupLocalVideo or setLocalRenderMode method, the watermark image in preview is also mirrored.

Discussion

Use this method with the setRemoteSubscribeFallbackOption method. If the fallback function is enabled for a remote stream, the SDK ensures the high-priority user gets the best possible stream quality.

Note:

The SDK supports setting userPriority as high for one user only.

Discussion

The default setting for option is AgoraStreamFallbackOptionDisabled, where there is no fallback behavior for the locally published video stream when the uplink network conditions are unreliable.

If option is set as AgoraStreamFallbackOptionAudioOnly, the SDK will:

• Disable the upstream video but enable audio only when the network conditions deteriorate and cannot support both video and audio.
• Re-enable the video when the network conditions improve.

When the published video stream falls back to audio only or when the audio-only stream switches back to the video, the SDK triggers the didLocalPublishFallbackToAudioOnly callback.

Note:

Agora does not recommend using this method for CDN live streaming, because the remote CDN live user will have a noticeable lag when the published video stream falls back to audio-only.

Discussion

The default setting for option is AgoraStreamFallbackOptionVideoStreamLow, where the remotely subscribed video stream falls back to the low-stream (low resolution and low bitrate) video under unreliable downlink network conditions.

If option is set as AgoraStreamFallbackOptionAudioOnly, the SDK automatically switches the video from a high stream to a low stream, or disables the video when the downlink network conditions cannot support both audio and video to guarantee the quality of the audio. The SDK monitors the network quality and re-enables the video stream when the network conditions improve. When the remotely subscribed video stream falls back to audio only or when the audio-only stream switches back to the video, the SDK triggers the didRemoteSubscribeFallbackToAudioOnly callback.

Discussion

If dual-stream mode is enabled, the receiver can choose to receive the high-stream (high-resolution high-bitrate) or low-stream (low-resolution low-bitrate) video.

Discussion

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.

• If the remote user enables dual-stream mode by calling the enableDualStreamMode method, the SDK receives the high-stream video by default. You can use this method to switch to the low-stream video.
• If dual-stream mode is not enabled, the SDK receives the high-stream video by default.

The method result returns in the didApiCallExecute callback. The SDK receives the high-stream video by default to save the bandwidth. If needed, users may use this method to switch to the low-stream video.

By default, the aspect ratio of the low-stream video is the same as the high-stream video. Once the resolution of the high-stream video is set, the system automatically sets the resolution, frame rate, and bitrate for the low-stream video.

Discussion

All users in a channel must set the same encryption password. The encryption password is automatically cleared once a user leaves the channel.

If the encryption password is not specified or set to empty, the encryption functionality is disabled.

Note:

• Do not use this method for CDN live streaming.
• For optimal transmission, ensure that the encrypted data size does not exceed the original data size + 16 bytes. 16 bytes is the maximum padding size for AES encryption.

Discussion

The SDK supports built-in encryption, which is set to the "aes-128-xts" mode by default. Call this method to use other encryption modes.

All users in the same channel must use the same encryption mode and password.

Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Note:

• Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.
• Do not use this method for CDN live streaming.

Discussion

The streamPublishedWithUrl callback returns the inject stream status.

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:

• The local client:

  • streamInjectedStatusOfUrl, with the state of the injecting the online stream.
  • didJoinedOfUid(uid: 666), if the method call is successful and the online media stream is injected into the channel.

• The remote client:

  • didJoinedOfUid(uid: 666), if the method call is successful and the online media stream is injected into the channel.

Note:

• Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
• This method applies to the Native SDK v2.4.1 and later.
• This method applies to the Live-Broadcast profile only.
• You can inject only one media stream into the channel at the same time.

Discussion

This method removes the URL address (added by the addInjectStreamUrl method) from a live broadcast.

If this method call is successful, the SDK triggers the didOfflineOfUid callback and returns a stream uid of 666.

Discussion

This method call triggers the rtmpStreamingChangedToState callback on the local client to report the state of adding a local stream to the CDN.

Note:

• This method applies to live-broadcast profile only.
• Ensure that the user joins the channel before calling this method.
• Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
• This method adds only one stream URL each time it is called.

Discussion

This method removes the RTMP URL address added by the addPublishStreamUrl method from a CDN live stream.

This method call triggers the rtmpStreamingChangedToState callback on the local client to report the state of removing an RTMP stream from the CDN.

Note:

• This method applies to live-broadcast profile only.
• This method removes only one URL each time it is called.
• The URL must not contain special characters, such as Chinese language characters.

Discussion

The SDK triggers the rtcEngineTranscodingUpdated callback when you call the setLiveTranscoding method to update the transcoding setting.

Note

• This method applies to live-broadcast profile only.
• Ensure that you enable the RTMP Converter service before using this function. See Prerequisites.
• If you call the setLiveTranscoding method to update the transcoding setting for the first time, the SDK does not trigger the rtcEngineTranscodingUpdated callback.

Discussion

Each user can create up to five data streams during the lifecycle of the AgoraRtcEngineKit.

Note:

Set both the reliable and ordered parameters to YES or NO. Do not set one as YES and the other as NO.

Discussion

The SDK has the following restrictions on this method:

• Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB.
• Each client can send up to 6 kB of data per second.
• Each user can have up to five data streams simultaneously.

A successful sendStreamMessage method call triggers the receiveStreamMessageFromUid callback on the remote client, from which the remote user gets the stream message.

A failed sendStreamMessage method call triggers the didOccurStreamMessageErrorFromUid callback on the remote client.

Note:

This method applies only to the Communication profile or to the hosts in the Live-broadcast profile. If an audience in the Live-broadcast profile calls this method, the audience role may be changed to a host.

Discussion

For a video call or live broadcast, 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:

• If the resolution or frame rate of the captured raw video data is higher than that set by setVideoEncoderConfiguration, processing video frames requires extra CPU and RAM usage and degrades performance. We recommend setting configuration as AgoraCameraCaptureOutputPreferencePerformance(1) to avoid such problems.
• If you do not need local video preview or are willing to sacrifice preview quality, we recommend setting configuration as AgoraCameraCaptureOutputPreferencePerformance(1) to optimize CPU and RAM usage.
• If you want better quality for the local video preview, we recommend setting configuration as AgoraCameraCaptureOutputPreferencePreview(2).

Note:

Call this method before enabling the local camera. That said, you can call this method before calling joinChannel, enableVideo, or enableLocalVideo, depending on which method you use to turn on your local camera.

Discussion

Note:

The app generally enables the front camera by default. If your front camera flash is not supported, this method returns NO. If you want to check if the rear camera flash is supported, call the switchCamera method before calling this method.

Discussion

A successful setCameraFocusPositionInPreview method call triggers the ocameraFocusDidChangedToRect callback on the local client.

Discussion

A successful setCameraExposurePosition method call triggers the cameraExposureDidChangedToRect callback on the local client.

Discussion

A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithm to different types of content.

Discussion

Use this method to monitor the plugging and swapping of external audio/video devices. For example, an external camera.

Discussion

Note:

Do not call this method in the main thread.

This method returns an NSArray object, including all audio/video devices in the system. Your app can use the AgoraRtcDeviceInfo array object to enumerate the devices.

Discussion

This method tests whether the microphone works properly. Once the test starts, the SDK reports the volume information by using the reportAudioVolumeIndicationOfSpeakers callback.

Discussion

This method stops testing the microphone. You must call this method to stop the test after calling the startRecordingDeviceTest method.

Discussion

This method tests whether the audio playback device works properly with a specified playback audio file.

Discussion

This method stops testing the audio playback device. You must call this method to stop the test after calling the startPlaybackDeviceTest method.

Discussion

This method tests whether the video-capture device works properly. Ensure that you call the enableVideo method before calling this method and that the parameter view window is valid.

Discussion

This method stops testing the video-capture device. You must call this method to stop the test after calling the startCaptureDeviceTest method.

Discussion

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. The reportAudioVolumeIndicationOfSpeakers callback returns the local audio volume information at the set interval.

Note:

This method tests the local audio devices and does not report the network conditions.

Discussion

Ensure that you call this method to stop the loopback test after calling the startAudioDeviceLoopbackTest method.

Discussion

You need to implement the AgoraMediaMetadataDataSource protocol and specify the type of metadata in this method.

Use this method with the setMediaMetadataDelegate method to add synchronized metadata in the video stream. You can create more diversified live broadcast interactions, such as sending shopping links, digital coupons, and online quizzes.

Note

• Call this method before the joinChannelByToken method.
• This method applies to the live broadcast channel profile only.

Discussion

You need to implement the AgoraMediaMetadataDelegate protocol and specify the type of metadata in this method.

Note

• Call this method before the joinChannelByToken method.
• This method applies to the live broadcast channel profile only.

Discussion

When a user joins a channel on a client, a callId is generated to identify the call from the client. Feedback methods, such as the rate and complain methods, 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.

Discussion

If disabled, the app should dispatch UI operations to the main queue.

Discussion

This method returns the string of the version number.

Discussion

The log file records all log data for the SDK’s operation. Ensure that the directory to save the log file exists and is writable.

Note:

• The default log file location is as follows:
  • iOS: App Sandbox/Library/caches/agorasdk.log
  • macOS
    • Sandbox enabled: App Sandbox/Library/Logs/agorasdk.log, for example /Users/<username>/Library/Containers/<App Bundle Identifier>/Data/Library/Logs/agorasdk.log.
    • Sandbox disabled: ～/Library/Logs/agorasdk.log.
• Ensure that you call this method immediately after calling the sharedEngineWithAppId method, otherwise the output log might not be complete.

Discussion

You can use one or a combination of the filters. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG. Choose a level to see the logs preceding that level.

For example, if you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Discussion

The SDK has two log files, each with a default size of 512 KB. If you set fileSizeInBytes as 1024 KB, the SDK outputs log files with a total maximum size of 2 MB. If the total size of the log files exceed the set value, the new output log files overwrite the old output log files.

Discussion

This interface is used to get the native C++ handler of the SDK engine used in special scenarios, such as registering the audio and video frame observer.

Discussion

The SDK uses the delegate to inform the app on engine runtime events. All methods defined in the delegate are optional implementation methods.

Discussion

Note:

The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way. Contact support@agora.io for more information.

Discussion

Note:

This method is not public. Contact support@agora.io for more information.

Discussion

DEPRECATED from v3.0.0, use the setupLocalVideo method instead.

This method can be invoked multiple times during a call to change the display mode.

Discussion

DEPRECATED from v3.0.0, use the setupRemoteVideo method instead.

This method can be invoked multiple times during a call to change the display mode.

Discussion

DEPRECATED from v3.0.0, use the setupLocalVideo or setLocalRenderMode method instead.

Use this method before calling the startPreview method, or the mirror mode does not take effect until you re-enable startPreview.

Warning

• Call this method after calling the setupLocalVideo method to initialize the local video view.
• During a call, you can call this method as many times as necessary to update the mirror mode of the local video view.

Note

• iOS: If you use the front camera, the SDK enables the mirror mode by default. If you use the rear camera, the SDK disables the mirror mode by default.
• macOS: The SDK enables the mirror mode by default.

Discussion

DEPRECATED from v3.0.0. As of v3.0.0, the Native SDK automatically enables interoperability with the Web SDK, so you no longer need to call this method.

• This method is applicable to the Live-broadcast profile only. In the Communication profile, the SDK is interoperable with the Web SDK by default.
• If the channel has Web SDK users, ensure that you call this method, or the video of the Native user will be a black screen for the Web user.

Discussion

DEPRECATED from v2.9.1. Use the new addVideoWatermark method.

This method adds a PNG watermark to the local video stream for the recording device, channel audience, or CDN live audience to see and capture.

To add the PNG file onto a CDN live publishing stream only, see the setLiveTranscoding method.

Note:

• The URL descriptions are different for the local video and CDN live streams:
  • In a local video stream, url in AgoraImage refers to the local file path of the added watermark image file in the local video stream.
  • In a CDN live stream, url in AgoraImage refers to the URL address of the added watermark image in the CDN live broadcast.
• The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file is cropped to conform to your settings.
• The SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one.
• If you set orientationMode as Adaptive in the setVideoEncoderConfiguration method, the watermark image rotates with the video frame and rotates around the upper left corner of the watermark image.

Discussion

DEPRECATED from v2.9.1. Use the new startAudioRecording method instead.

This method has a fixed sample rate of 32 kHz.

The SDK allows recording during a call. Supported formats:

• .wav: Large file size with high fidelity.
• .aac: Small file size with low fidelity.

Ensure that the directory to save the recording file exists and is writable. You can call this method after calling the joinChannelByToken method. The recording automatically stops when you call the leaveChannel method.

Discussion

DEPRECATED from v2.4.

This method launches an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

To conduct the test:

• The user speaks and the recording is played back within 10 seconds.
• If the user can hear the recording within 10 seconds, the audio devices and network connection are working properly.

Note:

• After calling this method, always call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, nor can it call the joinChannelByToken method to start a new call.
• In the Live-broadcast profile, only the hosts can call this method. If the user switches from the Communication to Live-broadcast profile, the user must call the setClientRole method to change the user role from an audience (default) to a host before calling this method.

Discussion

DEPRECATED from v2.4.

Under unreliable network connections or the device’s CPU is overloaded, the video quality may be affected. You can use this method to choose the video smoothness (frame rate) over the image quality or vice versa.

Discussion

DEPRECATED from v2.3.

Discussion

DEPRECATED from v2.3

Discussion

DEPRECATED from v2.3

Discussion

Replaced with setAudioProfile.

DEPRECATED from v2.3.

Discussion

DEPRECATED from v2.3.

Discussion

DEPRECATED from v2.4.

Discussion

DEPRECATED from v2.3.

Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by setVideoProfile.

Note:

• Always set the video profile after calling the enableVideo method.
• Always set the video profile before calling the joinChannelByToken or startPreview method.
• If you do not need to set the video profile after joining the channel, call this method before calling the enableVideo method to reduce the render time of the first video frame.

Discussion

DEPRECATED from v2.3.

If you do not need to change the video profile after joining the channel, Agora recommends calling this method before calling the enableVideo method to reduce the render time of the first video frame.

Discussion

DEPRECATED from v2.3.

Discussion

DEPRECATED from v2.3.

Discussion

DEPRECATED from v2.3.

Discussion

DEPRECATED from v1.1.

This callback is disabled by default and can be enabled by the enableAudioVolumeIndication method.

In the returned speakers' array:

• If uid is 0 (the local user is the speaker), the returned volume is totalVolume.
• If uid is not 0 and volume is 0, the specified user did not speak.
• If a uid is found in the previous speakers' array but not in the current speakers' array, the specified user did not speak.