Release Notes
This page provides the release notes for the Agora Video SDK for iOS.
Known issues and limitations
Compatibility with iOS 15
As of v3.4.6, the SDK supports iOS 15. For the SDK versions between v3.2.0 and v3.4.5 inclusive, crashes occur on iOS 15. To fix this issue, upgrade the SDK to v3.4.6 or later.
v3.7.1
v3.7.1 was released on August 4, 2022.
Improvements
1. Super resolution (beta)
This release deprecates the previous enableRemoteSuperResolution
method, and adds a method with the same name to support super resolution. If the original resolution of a remote user's video is a × b, the local user's device can render the remote video at a resolution of 2a × 2b after you enable this feature.
Compared to the deprecated method, the new enableRemoteSuperResolution
method adds a parameter mode
that can be set as either of following values:
AgoraVideoSRModeManual(0)
: Enables super resolution for the remote user you specify.AgoraVideoSRModeAuto(1)
: Enables super resolution for the remote user corresponding to the largest rendering window in the channel.
Before using super resolution, ensure that you have integrated the AgoraSuperResolutionExtension.xcframework
dynamical library. For other requirements, see the enableRemoteSuperResolution documentation.
2. Co-hosting across channels
This release enhances the connection mechanism between the SDK and the server of co-hosting across channels and therefore reduces the failure rate.
Fixed issues
This release fixed the following issues:
- Occasional crashes occurred.
- The video received by the user appeared to change from dark to bright.
- The local user received the
remoteAudioStateChangedOfUid(2,6)
callback after disconnecting from and reconnecting to a network even though the remote user had not changed the audio state. - Occasionally, screen sharing ended unexpectedly.
gatewayRtt
reported by thereportRtcStats
callback was inaccurate when the network latency was too high or the router did not respond to ICMP packets.- Occasional crashes occurred when you called
playEffect
orstartAudioMixing
to play 8-bit PCM-encoded audio in the WAV format. - The uplink network quality reported by the
networkQuality
callback was inaccurate for the user who was sharing a screen. - The local audio error reason reported by the
localAudioStateChange
callback after a user denied microphone permission was inaccurate. - Occasionally, it took users longer than normal to join a channel for the first time.
- When the local user shared audio played by a third-party app using the screen sharing feature, remote users heard echoes.
API changes
Added
enableRemoteSuperResolution
setCameraCaptureRotation
AgoraSRStateReasonInsufficientPerformance(4)
inAgoraSuperResolutionStateReason
AgoraVBSStateReasonInsufficientPerformance(4)
inAgoraVirtualBackgroundSourceStateReason
Deprecated
enableRemoteSuperResolution
v3.7.0.2
v3.7.0.2 was released on June 6, 2022.
This release fixed the issue where native clients saw video freeze on web clients when web clients published H.264 video streams.
v3.7.0
v3.7.0 was released on April 11, 2022.
Compatibility changes
1. JND library integration change
As of v3.7.0, the JND library is statically compiled in the SDK by default and no longer provided as an extension library. If you have integrated the JND library, remove the JND extension library from your project dependencies and recompile your project when upgrading to v3.7.0. For the description of the JND library, see extension libraries.
2. Optimized integration with Swift API
Swift developers automatically convert the Objective-C API provided by the Agora SDK to the Swift API by using Xcode for integration development. To avoid API semantic confusion due to automatic conversion, this release uses the NS_SWIFT_NAME
macro to explicitly define the name of the Swift API for each Objective-C API in the header files.
When you use the Swift API, note that the following Swift API names defined by Agora do not match the Swift API names automatically converted by Xcode:
Agora Objective-C API | Swift API defined by Agora | Swift API automatically converted by Xcode |
---|---|---|
- (int)updateScreenCaptureParameters:(AgoraScreenCaptureParameters* _Nonnull)captureParams; in the AgoraRtcEngineKit class | updateScreenCaptureParameters() | update() |
- (int)setScreenCaptureContentHint:(AgoraVideoContentHint)contentHint; in the AgoraRtcEngineKit class | setScreenCaptureContentHint() | setScreenCapture() |
- (BOOL)onRecordAudioFrame:(AgoraAudioFrame* _Nonnull)frame; in the AgoraAudioDataFrameProtocol protocol | func onRecordAudioFrame(_ frame: AgoraAudioFrame) -> Bool | func onRecord(_ frame: AgoraAudioFrame) -> Bool |
+ (instancetype _Nonnull)screenCaptureWithId:(NSUInteger)displayId rect:(CGRect)rect dimensions:(CGSize)dimensions frameRate:(NSInteger)frameRate bitrate:(NSInteger)bitrate captureMouseCursor:(BOOL)captureMouseCursor; in the AgoraRtcScreenCapture interface | screenCapture(withId: rect: dimensions: frameRate: bitrate: captureMouseCursor:) | init(id: rect: dimensions: frameRate: bitrate: captureMouseCursor:) |
New features
1. Spatial audio effect
This release adds the feature of spatial audio effect, which can add a sense of space to remote users' audio and simulate the audio transmission process in the real world. This enables the local user to hear remote users with the spatial audio effect.
To use this feature, contact support@agora.io.
2. Screen sharing
This release supports screen sharing on this platform and provides the startScreenCapture
, stopScreenCapture
, and updateScreenCapture
methods for this purpose. For the implementation method, See Share the Screen.
3. Local voice pitch
This release adds the enableLocalVoicePitchCallback
method and the reportLocalVoicePitchFrequency
callback, to allow the SDK to report the voice pitch of the local user at the set time interval to the app.
4. Reporting the first remote video frame rendered
This release adds the firstRemoteVideoFrameOfUid
callback to the AgoraRtcChannelDelegate
class to report to the local user that the first video frame of the remote user has been rendered in a multichannel scenario. You can also get the remote user ID, the width and height (in pixels) of the video, and the time (in milliseconds) to render the first video frame from this callback.
5. Reporting the user role switch failure
This release adds the didClientRoleChangeFailed
callback to report the reason for a user role switch failure and the current user role in the interactive live streaming.
6. Reasons for connection state changes
To help users better understand the cause of connection state changes, this release adds the following enumerators in AgoraConnectionChangedReason
:
AgoraConnectionChangedSameUidLogin(19)
: Join the same channel from different devices using the same user ID.AgoraConnectionChangedTooManyBroadcasters(20)
: The number of hosts in the channel reaches the upper limit. This enumerator is reported only after the support for 128 hosts is enabled.
Improvements
1. Channel capacity improvement
As of this release, a single channel can support up to 128 concurrent online hosts, who can publish audio and video streams at the same time. The number of audience members in a channel is unlimited. Each host or audience member can subscribe to a maximum of 50 hosts at the same time.
To experience this improvement, contact support@agora.io.
2. Virtual background
Test results and user feedback show that the effect of the virtual background feature significantly improves when a user is against a complex background and and adopts a more casual pose. As a result, virtual background is converted from a beta feature to an official feature as of v3.7.0.
3. A new version of deep-learning noise reduction
Agora has added the option of using a new version of deep-learning noise reduction to further improve audio quality. To experience this feature, contact support@agora.io
4. playEffect improvements
This release improves the internal implementation logic of playEffect
to avoid blocking and reduce freezing when playing an audio effect file.
5. Audio experience optimization
This release reduces audio stuttering under network conditions with burst jitter and high packet loss.
6. Transmission upgrade
This release upgrades transmission protocols and algorithms to enhance the SDK‘s ability to counter poor network conditions. At the same time, this release optimizes the scalable video coding capability for multi-user video scenarios to improve user video experience.
Issues fixed
This release fixed an issue where the app occasionally failed to rejoin a channel after a user left a channel and put the app in the background for a period of time.
API changes
Added
startScreenCapture
stopScreenCapture
updateScreenCapture
enableLocalVoicePitchCallback
reportLocalVoicePitchFrequency
firstRemoteVideoFrameOfUid
in theAgoraRtcChannelDelegate
classdidClientRoleChangeFailed
AgoraConnectionChangedSameUidLogin(19)
andAgoraConnectionChangedTooManyBroadcasters(20)
inAgoraConnectionChangedReason
- The following constants in
AgoraLocalVideoStreamError
:AgoraLocalVideoStreamErrorExtensionCaptureStarted(13)
AgoraLocalVideoStreamErrorExtensionCaptureStoped(14)
AgoraLocalVideoStreamErrorExtensionCaptureDisconnected(15)
Deprecated
- Warning code
AgoraWarningCodeSetClientRoleNotAuthorized(119)
, useAgoraClientRoleChangeFailedReason
instead.
v3.6.2
v3.6.2 was released on February 22, 2022.
New features
1. Removing extension libraries when using CocoaPods
Extension libraries are dynamic libraries that can be optionally integrated into a project. As of v3.6.2, when you integrate the iOS SDK with CocoaPods, Agora supports reducing the size of your app after integrating the SDK by using the subspecs
field in the Podfile to specify the desired dynamic libraries and exclude unnecessary extension libraries. For details about the sample code and the subspecs
fields, see Reduce App Size.
2. Video enhancement
In addition to the image enhancement feature, Agora adds support for more video enhancement features:
- Video noise reduction: This feature reduces video noise and improves video quality. You can use the
setVideoDenoiserOptions
method to enable/disable video noise reduction and set the options of the video noise reduction effect. - Low-light enhancement: This feature adaptively adjusts the brightness value of the video captured in situations with low or uneven lighting, such as backlit, cloudy, or dark scenes. It restores or highlights the image details and improves the overall visual effect of the video. You can use the
setLowLightEnhanceOptions
method to enable/disable low-light enhancement and set the options of the low-light enhancement effect. - Color enhancement: This feature intelligently adjusts video characteristics such as saturation and contrast to enhance the video color richness and color reproduction, making the video more vivid. You can use the
setColorEnhanceOptions
method to enable/disable color enhancement and set the options of the color enhancement effect.
AgoraVideoProcessExtension.xcframework
dynamical library is integrated.Improvements
1. Cloud proxy
To enrich application scenarios of the Agora Cloud Proxy, this release updates the cloud proxy types (proxyType
) as follows:
- Changes the meaning of
AgoraNoneProxy(0)
from "Do not use the cloud proxy" to "Automatic mode". In this mode, the SDK attempts a direct connection to SD-RTN™ and automatically switches to TLS 443 if the attempt fails. As of v3.6.2, the SDK has this mode enabled by default. - Adds
AgoraTcpProxy(2)
, which is the TCP (encrypted) mode. In this mode, the SDK always transmits data over TLS 443.
In addition, this release adds the didProxyConnected
callback to report the proxy connection state. For example, when a user calls setCloudProxy
and joins a channel successfully, the SDK triggers this callback to report the user ID, the proxy type connected, and the time elapsed from the user calling joinChannelByToken
until this callback is triggered.
2. Audio recording
This release extends startAudioRecordingWithConfig
with support for setting recording with dual channels and higher audio quality.
- By adding
recordingChannel
toAgoraAudioRecordingConfiguration
, it enables you to set the recorded audio channel to be mono or dual. Because the actual recorded audio channel is related to the captured audio channel and the integration scheme affects the final recorded audio channel, contact technical support for assistance with stereo recording usingstartAudioRecordingWithConfig
. - By adding
AgoraAudioRecordingQualityUltraHigh(3)
toAgoraAudioRecordingConfiguration.recordingQuality
, it enables you to set the recorded audio quality to ultra-high. Ultra-high quality is the highest quality available inrecordingQuality
. When you record a 10-minute AAC audio file at a sample rate of 32,000 Hz and ultra-high quality, the file size is approximately 7.5 MB.
3. Music file playback
This release optimizes the experience of calling startAudioMixing
to play music files as follows:
- Reduces issues of audio freezes or no audio when playing music files.
- Increases the accuracy of the audio duration reported by
getAudioFileInfo
. - Supports more audio file formats. See Which audio file formats does the Agora RTC SDK support.
If you want to experience these improvements, ensure that you have integrated the AgoraFullAudioFormatExtension.xcframework
dynamic library. Given the large size of this library, if you have limitations on app size and do not need these improvements, you can remove this dynamic library when integrating the SDK. For more instructions, see Reduce App Size.
4. Audio file formats
This release adds support for playing audio files in the following formats:
- Mono-track online files in MP4 format.
- Multi-track online files in M4A and MP4 formats.
For online MP4 and M4A files, the MOOV atom must be before the MDAT atom.
5. Audio device errors
To convey the impact of a system call on the audio sampling, this release adds AgoraAudioLocalErrorInterrupted(8)
in AgoraAudioLocalError
, which reports that the audio sampling is interrupted by a system call.
Fixed issues
This release fixed the following issues:
- Under certain circumstances, local users could see a blurry screen for remote users after switching back to the app from the home screen.
- When playing a specific audio file in the WAV format with the
startAudioMixing
method, there was no sound after a certain period of playback. - Audio stuttered under high jitter networks.
- Under poor network conditions, you could receive the
localAudioMixingStateDidChanged
callback only after a three-second delay after a successful call tostartAudioMixing
. - When adding a watermark with the
addVideoWatermark
method, under certain circumstances, the watermark color was different from the original color. - Occasional crashes.
API changes
Added
setVideoDenoiserOptions
setLowLightEnhanceOptions
setColorEnhanceOptions
enableWirelessAccelerate
wlAccStats
wlAccMessage
enableContentInspect
contentInspectResult
recordingChannel
inAgoraAudioRecordingConfiguration
AgoraAudioRecordingQualityUltraHigh(3)
inAgoraAudioRecordingConfiguration.recordingQuality
didProxyConnected
AgoraTcpProxy(2)
inAgoraCloudProxyType
AgoraAudioLocalErrorInterrupted(8)
inAgoraAudioLocalError
Modified
- The behavior of
AgoraNoneProxy(0)
inAgoraCloudProxyType
.
v3.6.1.1
v3.6.1.1 was released on January 16, 2022.
This release fixed the following audio issue:
When an end user muted and unmuted audio from an application using the Agora Web SDK, end users using an application with Native SDK version 3.6.0 might not hear audio from this end user.
v3.6.1
v3.6.1 was released on January 14, 2022.
Improvements
This release provides the following improvements:
- After a remote user using a Mac device leaves a channel due to the
leaveChannel
method call, network interruption, or other reasons, the local user sees the remote view stay on the last video frame instead of the remote view directly disappearing as in previous versions. - Optimizes video rendering methods, which improves compatibility.
Fixed issues
This release fixed the following issues:
- The CDN live streaming failed because of the abnormal resolution of the RTMP streaming URL with a port number.
- After you enabled Bitcode settings in Xcode and integrated the
AgoraVideoProcessExtension.xcframework
dynamic library, errors occurred when you uploaded the app to the Apple App Store. - Occasionally failed to start the camera and video capture due to a system issue that prevented the SDK from getting the device name of the camera.
- Occasional crashes occurred.
- The
startAudioMixing
method call failed to play local iTunes music files starting with"ipod-library://"
.
v3.6.0.1
v3.6.0.1 was released on December 10, 2021.
This release fixed the issue that v3.6.0 incorrectly renamed the dynamic library Agorafdkaac.xcframework
to AgoraFDKAACExtension.xcframework
.
v3.6.0
v3.6.0 was released on December 7, 2021.
Compatibility changes
Media Push
To reduce the difficulty of integrating Media Push, this release optimizes the API design of Media Push and improves the handling of network issues within Media Push clients and servers. You can experience the optimized Media Push functionality with the following new methods:
startRtmpStreamWithoutTranscoding
: Starts pushing media streams to a CDN without transcoding. This method works the same as the old methodaddPublishStreamUrl(NO)
.startRtmpStreamWithTranscoding
: Starts pushing media streams to a CDN and sets the transcoding configuration. This method works the same as calling the old methodssetLiveTranscoding
andaddPublishStreamUrl(YES)
in sequence.updateRtmpTranscoding
: Updates the transcoding configuration. This method works the same as the non-first call to the old methodsetLiveTranscoding
.stopRtmpStream
: Stops pushing media streams to a CDN. This method works the same as the old methodremovePublishStreamUrl
.
This release deprecates three old methods for Media Push: addPublishStreamUrl
, setLiveTranscoding
, and removePublishStreamUrl
. Agora recommends that you use the new methods for Media Push and update your code logic by referring to Media Push.
Also, as of this release, whether you use the new or old methods for Media Push, you can experience the following improvements:
-
Reporting streaming states, errors, and events:
- In the
AgoraRtmpStreamingState
state code, addingAgoraRtmpStreamingStateDisconnecting(5)
: The SDK is disconnecting from the Agora streaming server and CDN. When you callremove
orstop
to stop the streaming normally, the SDK reports the streaming state asDisconnecting
,Idle
in sequence. - Adding the following to the
AgoraRtmpStreamingErrorCode
error code:AgoraRtmpStreamPublishErrorNotBroadcaster(11)
: The user role is not host, so the user cannot use the Media Push function. Check your application code logic.AgoraRtmpStreamPublishErrorTranscodingNoMixStream(13)
: Theupdate
orsetLiveTranscoding
method is called to update the transcoding configuration in a scenario where there is streaming without transcoding. Check your application code logic.AgoraRtmpStreamPublishErrorNetDown(14)
: Errors occurred in the host's network.AgoraRtmpStreamPublishErrorInvalidAppId(15)
: Your App ID does not have permission to use the Media Push function. Refer to Prerequisites to enable the Media Push permission.
- Adding the following to the
AgoraRtmpStreamingEvent
event code:AgoraRtmpStreamingEventAdvancedFeatureNotSupport(3)
: The feature is not supported.AgoraRtmpStreamingEventRequestTooOften(4)
: Reserved.
To ensure the quality of the Media Push, make sure to handle the business logic according to the state code, error code, and event code. - In the
-
Adding multiple watermarks and background images during streaming with transcoding: This is achieved by adding
watermarkArray
andbackgroundImageArray
to theAgoraLiveTranscoding
class. -
Setting the layer number and transparency of each watermark and background image during streaming with transcoding: This is achieved by adding
zOrder
andalpha
to theAgoraImage
class. -
Using the HE-AAC v2 audio codec during streaming with transcoding: This is achieved by adding
AgoraAudioCodecProfileHEAACv2
toAgoraAudioCodecProfileType
.
Improvements
1. Image enhancement
This release updates the Agora image enhancement algorithm to improve the image enhancement effects that you can enable by calling setBeautyEffectOptions
. To balance these image enhancement effects, this release changes the default value of lighteningLevel
from 0.7 to 0.6 and adds sharpnessLevel
to the BeautyOptions
structure to support setting the sharpness level.
As of this release, ensure that you have integrated the AgoraVideoProcessExtension.framework
dynamic library before calling setBeautyEffectOptions
; otherwise, you cannot experience the optimized image enhancement effects and sharpness adjustment brought out by the updated Agora image enhancement algorithm, but only the image enhancement effects brought out by the older Agora image enhancement algorithm.
2. Rendering of the first remote video frame
This release speeds up rendering of the first remote video frame under poor network conditions to enhance user video experience.
Fixed issues
This release fixed the following issues:
- When the host in the channel switched their role to
AgoraClientRoleAudience
and then back toAgoraClientRoleBroadcaster
, the audience heard the host's voice with a voice change effect. - Occasionally, the video received by remote users froze after you enabled media stream encryption.
- After a user played music with a third-party music player and set the audio scenario to
AgoraAudioScenarioChatRoomGaming
, joining a channel could interrupt the music played by the third-party music player. - When you were playing an original song, calling
setAudioMixingPitch
to adjust the pitch caused the played song to switch to accompaniment. - Remote users could not see the shared screen video during the local user's screen sharing.
- Remote users saw the screen shared by the local user flicker.
API changes
Added
-
AgoraRtmpStreamingStateDisconnecting(5)
inAgoraRtmpStreamingState
-
The following enumerators in
AgoraRtmpStreamingErrorCode
:AgoraRtmpStreamPublishErrorNotBroadcaster(11)
AgoraRtmpStreamPublishErrorTranscodingNoMixStream(13)
AgoraRtmpStreamPublishErrorNetDown(14)
AgoraRtmpStreamPublishErrorInvalidAppId(15)
-
The following enumerators in
AgoraRtmpStreamingEvent
:RTMP_STREAMING_EVENT_ADVANCED_FEATURE_NOT_SUPPORT(3)
RTMP_STREAMING_EVENT_REQUEST_TOO_OFTEN(4)
-
watermarkArray
andbackgroundImageArray
in theAgoraLiveTranscoding
class -
zOrder
andalpha
inAgoraImage
-
AgoraAudioCodecProfileHEAACv2
in theAgoraAudioCodecProfileType
class -
sharpnessLevel
in theAgoraBeautyOptions
class
Modified
Changed the default value of lighteningLevel
from 0.7 to 0.6
v3.5.2
v3.5.2 was released on November 25, 2021.
Compatibility changes
1. Error codes returned when the request to join a channel is rejected
To more accurately report the reason for the failure to join a channel, as of this release, the SDK returns the error code -17(AgoraErrorCodeJoinChannelRejected)
in the return value of the joining channel method in the following situations:
- When a user who has already joined an
AgoraRtcEngineKit
channel calls the joining channel method of theAgoraRtcEngineKit
class with a valid channel name. - When a user who has already joined an
AgoraRtcChannel
channel calls the joining channel method of thisAgoraRtcChannel
object.
In the SDK earlier than v3.5.2, when the above errors occur, the SDK might report the error code 17
through the didOccurError
callback, or return the error code -5(AgoraErrorCodeRefused)
in the return value of the joining channel method.
2. Selecting Bluetooth profiles
To ensure connectivity with Bluetooth headsets, as of this release, when a user in the communication profile or a host in the interactive live streaming profile uses a Bluetooth headset, the SDK checks whether the device supports the Hands-Free Profile (HFP), and selects the Bluetooth profile based on the result as follows:
- On a device that supports HFP, the SDK uses HFP, where the audio is captured and played through the Bluetooth headset.
- On a device that does not support HFP, the SDK changes to the Advanced Audio Distribution Profile (A2DP), where the audio is captured through device's microphone and played through the Bluetooth headset.
New features
1. Audio and video recording on the client
To enable users to record local audio and video on their client, this release adds the AgoraMediaRecorder
class, which supports recording the following content:
- The audio captured by the local microphone and encoded in AAC format by the SDK.
- The video captured by the local camera and encoded by the SDK.
The generated recording files are saved in the local path specified by the user.
After successfully initializing the AgoraRtcEngineKit
object, you can call the following methods and callbacks in the AgoraMediaRecorder
class to implement the local audio and video recording function:
sharedMediaRecorderWithRtcEngine
: Creates theAgoraMediaRecorder
instance.startRecording
: Sets the recording content, duration, format of generated files, and callback interval, and enables the local audio and video recording.stopRecording
: Stops recording the local audio and video.destroy
: Destroys theAgoraMediaRecorder
instance.stateDidChanged
: Occurs when the recording state changes.informationDidUpdated
: Occurs when the recording information is updated.
COMMUNICATION
channel profile, this function is incompatible with versions of the SDK earlier than v3.0.0.2. Video snapshot
This release adds the takeSnapshot
method for taking a snapshot of a video stream from the specified user, generating a JPG image, and saving it to the specified path. After a successful method call, the SDK triggers the snapshotTaken
callback to report whether the snapshot is successfully taken as well as the details of the snapshot taken.
3. Testing audio and video call loop
To check whether the local audio device, video device, and network conditions can guarantee the proper sending and receiving of audio and video streams, this release adds the startEchoTestWithConfig
method. You can call this method before joining a channel to test whether the loop of a user's audio and video devices and network conditions are working properly.
Compared to startEchoTestWithInterval
, startEchoTestWithConfig
can test video devices and secure the test, but cannot support setting the time interval for reporting test results.
Improvements
1. Performance improvements
This release slightly reduces CPU usage in video scenarios by optimizing the FEC (Forward Error Correction) codec.
2. Experience improvements
This release improves video sharpness and smoothness under poor network conditions by optimizing the congestion control algorithm.
Fixed issues
This release fixed the following issues:
- The video bitrate failed to climb when a user joined a channel in poor network conditions with high packet loss.
- The video sharpness and smoothness degraded significantly due to a cliff-like drop in video bitrate under certain poor network conditions.
- Remote users heard slightly unsynchronized voice and music when a user called
startAudioMixing
on some Android devices. - After a local user called
enableDualStreamMode(NO)
, a dual stream (high-quality and low-quality video stream) was nevertheless sent when the user switched from custom video capture usingsetVideoSource
with the custom video source in theScreen
type to SDK capture.
API changes
This release adds the following APIs:
startEchoTestWithConfig
sharedMediaRecorderWithRtcEngine
stateDidChanged
informationDidUpdated
startRecording
stopRecording
destroy
takeSnapshot
snapshotTaken
v3.5.1
v3.5.1 was released on October 14, 2021.
New features
1. Super resolution (beta)
To effectively boost the resolution of a remote user's video seen by the local user, this release adds support for the super resolution feature. You can call enableRemoteSuperResolution
to enable super resolution. The SDK triggers the superResolutionEnabledOfUid
callback to report whether this feature has been successfully enabled. If it is not enabled successfully, use the reason
code to troubleshoot issues.
2. Background blurring
To enrich the virtual background effects, this release adds support for setting background blur when a user enables the virtual background function by calling enableVirtualBackground
. You need to set the type of the custom background image as AgoraVirtualBackgroundBlur
and set blur_degree
according to the degree of blurring that the user desires.
3. Enabling device flash
To support calling the C++ APIs to enable the flash of a device on Android and iOS platforms, this release adds the following APIs to C++:
isCameraTorchSupported
: Determine whether the device supports enabling the flash.setCameraTorchOn
: Set whether to enable the flash.
4. Pausing and resuming the media stream relay across channels
In order to enable the host to quickly pause or resume a cross-channel media stream relay, this release adds the following methods and event code:
pauseAllChannelMediaRelay
: Pauses the media stream relay to all destination channels.resumeAllChannelMediaRelay
: Resumes the media stream relay to all destination channels.AgoraChannelMediaRelayEventPauseSendPacketToDestChannelSuccess
(12): The SDK successfully pauses relaying the media stream to destination channels.AgoraChannelMediaRelayEventPauseSendPacketToDestChannelFailed
(13): The SDK fails to pause relaying the media stream to destination channels.AgoraChannelMediaRelayEventResumeSendPacketToDestChannelSuccess
(14): The SDK successfully resumes relaying the media stream to destination channels.AgoraChannelMediaRelayEventResumeSendPacketToDestChannelFailed
(15): The SDK fails to resume relaying the media stream to destination channels.
After a successful method call of pauseAllChannelMediaRelay
or resumeAllChannelMediaRelay
, the SDK triggers the didReceiveChannelMediaRelayEvent
callback to report whether the media stream relay is successfully paused or resumed.
5. Pushing the external audio frame to a specified position
To meet the different processing requirements of external audio frames in different scenarios, this release deprecates pushExternalAudioFrameRawData
[1/2] and pushExternalAudioFrameSampleBuffer
[1/2], and adds pushExternalAudioFrameRawData
[2/2] and pushExternalAudioFrameSampleBuffer
[2/2] with sourcePos
instead. You can push the external audio frame to one of three positions: after audio capture, before audio encoding, or before local playback. For example, in the KTV scenario, you can push the singing voice to after audio capture, and push the accompaniment to before audio encoding, so that the singing voice is processed by the SDK audio module, but the accompaniment is not affected by the SDK audio module.
This release also adds setExternalAudioSourceVolume
, which enables you to set the volume of external audio frames at a specified position.
6. Advanced settings of the music file
To set the playback speed, audio track, and channel mode of a music file, this release adds the following methods:
setAudioMixingPlaybackSpeed
: Sets the playback speed of the current music file. Agora recommends a value range of [50,400], where 100 represents the original speed.getAudioTrackCount
: Gets the number of audio tracks of the current music file.selectAudioTrack
: Specifies the playback audio track of the current music file. The range of index is [0, getAudioTrackCount()).setAudioMixingDualMonoMode
: Sets the channel mode of the current music file to original mode, left channel mode, right channel mode, or mixed channel mode.
7. Getting audio file information
To get the information of any audio file, this release deprecates getAudioMixingDuration
and adds getAudioFileInfo
instead. After joining a channel, you can call getAudioFileInfo
and get information such as duration for the specified audio file in didRequestAudioFileInfo
.
Improvements
1. Identification and quality testing for 5G mobile networks
This release adds identification and connection quality testing for 5G mobile networks:
- Adds
AgoraNetworkTypeMobile5G (6)
toAgoraNetworkType
. When the local network changes to 5G, the SDK triggers thenetworkTypeChangedToType
callback to report this network connection type. - Supports calling
enableLastmileTest
orstartLastmileProbeTest
to test the connection quality of the 5G mobile network.
2. Other improvements
This release also provides the following improvements:
- Adds continuous optimization of the portrait edge effect of the virtual background.
- After enabling deep-learning noise reduction, the audio experience is improved when using some Bluetooth headsets.
Fixed issues
This release has fixed the following issues:
- In the
AgoraAudioScenarioGameStreaming
scenario, occasional echo or noise that was caused by inaccurate music detection occurred. - The local user occasionally saw the remote user with a short black screen after the remote user called
enableLocalVideo(NO)
,enableLocalVideo(YES)
to disable and enable local video capture or calledmuteLocalVideoStream(YES)
,muteLocalVideoStream(NO)
to stop and resume sending local video in sequence within a few seconds. - When
pauseAudioMixing
was called before playing an audio file, and thenstartAudioMixing
was called to play the audio file, playback failed. - When the local user called
muteAllRemoteAudioStreams
and receivedonRemoteAudioStateChanged (AgoraAudioRemoteReasonLocalMuted)
,onRemoteAudioStateChanged (AgoraAudioRemoteReasonRemoteMuted)
was incorrectly received after 15 seconds. - Crashes occasionally occurred in audio scenarios.
- On some low-end iOS devices, after switching to the background during screen sharing, the app was forcibly closed by the system because it took up more memory than the limit.
- The local user occasionally could not hear remote users after calling
setAudioSessionOperationRestriction
. - As of v3.4.5, the return value was inaccurate when you called
joinChannelByToken
multiple times in a row. - When the host used a specific low-end device under certain circumstances, the audience watching the host's video occasionally experience lag.
- Under certain circumstances, when the sender used certain Xiaomi or Redmi devices, the receiver occasionally saw a mosaic square on the received video.
- When the sender used certain Android emulators, the local video or the video received by the receiver was abnormal.
- The method call of
enableExternalAudioSourceWithSampleRate
before joining the channel did not take effect. - The SDK additionally triggered the
localAudioStateChange
callback to reportAgoraAudioLocalStateRecording(1)
when you calledenableLocalAudio(NO)
after joining a channel.
API changes
Added
enableRemoteSuperResolution
superResolutionEnabledOfUid
blur_degree
andAgoraBlurDegree
inAgoraVirtualBackgroundSource
AgoraVirtualBackgroundBlur
in theAgoraVirtualBackgroundSourceType
isCameraTorchSupported
(C++)setCameraTorchOn
(C++)pauseAllChannelMediaRelay
resumeAllChannelMediaRelay
- The following enumerators in
AgoraChannelMediaRelayEvent
:AgoraChannelMediaRelayEventPauseSendPacketToDestChannelSuccess
AgoraChannelMediaRelayEventPauseSendPacketToDestChannelFailed
AgoraChannelMediaRelayEventResumeSendPacketToDestChannelSuccess
AgoraChannelMediaRelayEventResumeSendPacketToDestChannelFailed
pushExternalAudioFrameRawData
[2/2]pushExternalAudioFrameSampleBuffer
[2/2]setExternalAudioSourceVolume
setAudioMixingPlaybackSpeed
getAudioTrackCount
selectAudioTrack
setAudioMixingDualMonoMode
getAudioFileInfo
didRequestAudioFileInfo
AgoraNetworkTypeMobile5G
inAgoraNetworkType
Deprecated
pushExternalAudioFrameRawData
[1/2]pushExternalAudioFrameSampleBuffer
[1/2]getAudioMixingDuration
v3.5.0.4
v3.5.0.4 was released on September 26, 2021.
Improvements
To improve audio quality when a user uses a Bluetooth headset, this release optimizes the logic for selecting Bluetooth profiles and volume types.
-
Bluetooth profile: As of this release, the Bluetooth profile used by the SDK is only affected by the user role.
- If a user in the communication profile or a host in the interactive live streaming profile uses a Bluetooth headset, the Bluetooth headset captures and plays audio through the Hands-Free Profile (HFP).
- If an audience member in the interactive live streaming profile uses a Bluetooth headset, the Bluetooth headset plays audio through the Advanced Audio Distribution Profile (A2DP).
-
Volume type: This release regulates the volume type. When a user uses a Bluetooth headset, the SDK uses the following volume type:
Audio scenario User in the communication profile/Host in the interactive live streaming profile Audience in the interactive live streaming profile Default
In-call volume Media volume ChatRoomGaming
In-call volume In-call volume GameStreaming
Media volume Media volume ChatRoomEntertainment
In-call volume In-call volume Education
In-call volume Media volume ShowRoom
In-call volume Media volume Meeting
Media volume Media volume
Fixed issues
This release fixed the following issues:
- On some devices, when you captured video at 353 × 288 resolution using the front camera, the captured video was stretched and distorted.
- When you used raw video data, the SDK incorrectly triggered the
onRenderVideoFrame
andonRenderVideoFrameEx
callbacks when capturing a local video frame to be rendered. - Occasional crashes occurred when you used raw video data.
- Repeated declaration of the
didAudioMuted
,didVideoEnabled
,didLocalVideoEnabled
, andfirstRemoteVideoDecodedOfUid
functions occurred in the header file. - After you successfully registered the raw video data observer, the app implemented time-consuming tasks in the
onCaptureVideoFrame
callback and caused video freezes for remote users. - When you called
setAudioMixingPosition
multiple times to set the playback position of the music file after you calledstartAudioMixing
to successfully play music, the music file would most likely be played from the beginning. - Enabling video mirror mode occasionally caused crashes.
- After you successfully registered the raw video data observer and set the return value of
getObservedFramePosition
asAgoraVideoFramePositionPreEncoder (1 << 2)
, the SDK incorrectly triggered aonCaptureVideoFrame
callback that did not match the set observation position. - In the
AgoraAudioScenarioChatRoomGaming
audio scenario, the moment a user in the channel switched the role fromAgoraClientRoleAudience
toAgoraClientRoleBroadcaster
, that user heard a zipping noise.
v3.5.0.3
v3.5.0.3 was released on September 6, 2021.
This release fixed the following issues:
- Occasional crashes.
- A naming conflict existed in the
AgoraReachability
class between the Agora RTC SDK and Agora RTM SDK. - When
orientationMode
was set asFixedPortrait
, the width and height of the video resolution was reversed, which caused the human face in video to be scaled up.
v3.5.0.2
v3.5.0.2 was released on August 11, 2021.
This release fixed black screen issues that occurred when setupLocalVideo
or setupRemoteVideo
was called under certain circumstances, such as the following:
setupLocalVideo(nil)
orsetupRemoteVideo(nil)
was called to disable the local or remote video view, and thensetupLocalVideo
orsetupRemoteVideo
was called to initialize the local or remote video view.setupRemoteVideo
was called in theremoteVideoStateChangedOfUid
callback to initialize the remote video view.
v3.5.0.1
v3.5.0.1 was released on August 4, 2021.
This release fixed the following issues:
- Due to the strong reference to
AgoraRtcEngineDelegate
byAgoraRtcEngineKit
, theAgoraRtcEngineDelegate
object was released only whenAgoraRtcEngineKit
was destroyed, which caused a memory leak. - The user could not receive the
onRenderVideoFrame
callback from the registered raw video data observer when thesetupLocalVideo
andsetupRemoteVideo
methods were not called.
v3.5.0
AgoraRtcEngineKit
strongly references AgoraRtcEngineDelegate
. If you set the strong reference to AgoraRtcEngineDelegate
by AgoraRtcEngineKit
, Agora recommends that you upgrade the SDK to v3.5.0.2. For details, see v3.5.0.2.v3.5.0 was released on July 20, 2021.
New features
1. Virtual background (beta)
This release adds the enableVirtualBackground
method, with which you can enable and set a virtual background for users as either a solid color or an image in PNG or JPG format. You can use the virtualBackgroundSourceEnabled
callback to learn whether the virtual background is successfully enabled or the reason for an error.
2. Raw audio data from multiple channels
In order to get the audio data from multiple channels in a multi-channel scenario, this release adds the following callbacks in AgoraAudioFrame.h
:
isMultipleChannelFrameWanted
onPlaybackAudioFrameBeforeMixingEx
After you successfully register the audio frame observer, if you set the return value of isMultipleChannelFrameWanted
as YES
and the return value of getObservedAudioFramePosition
as AgoraAudioFramePositionBeforeMixing (1 << 3)
, the SDK triggers the onPlaybackAudioFrameBeforeMixingEx
callbacks to send you the audio data of remote users from multiple channels.
Improvements
1. Video quality
The following improvements have been made to the quality of captured and received video in this release:
- Automatically enable the best video-capture strategy to optimize the quality of captured video (including resolution, frame rate, and color range). This improvement only applies to certain video with a capture resolution no higher than 1080P.
- Enable camera autofocus by default, and dynamically adjust the capture behavior to moderate overexposure. If you want to disable autofocus, call
setCameraAutoFocusFaceModeEnabled(NO)
. - Enhance the video contrast of captured and received video by adapting the color range to moderate the video whiteness.
- Enhance the color richness of captured and received video by adapting the color space to further restore video colors.
2. Additional improvements
This release also improves the following:
- In scenarios where the AGC is enabled, the convergence time for noise reduction is shortened, which reduces noise fluctuations.
- The smoothness of output frames in the custom video rendering scenario is improved.
Fixed issues
This release fixed the following issues:
- After a remote user called
enableLoopbackRecording
, occasionally the local user heard an echo of their own audio. - In the meeting scenario, after a remote user enabled local audio capturing in the channel, occasionally the local user heard an echo of the remote user’s audio.
- After calling
muteLocalAudioStream(YES)
to stop publishing a local audio stream, the local user could hear remote users when the local user joined a channel for the first time. After leaving the channel and joining another channel, occasionally the local user could not hear remote users. - When the local network quality was poor, the downlink network quality rating (
rxQuality
) of remote users reported by the SDK was not accurate. - The value of
memoryTotalUsageRatio
reported by thereportRtcStats
callback was not accurate.
API changes
Added
enableVirtualBackground
virtualBackgroundSourceEnabled
isMultipleChannelFrameWanted
onPlaybackAudioFrameBeforeMixingEx
v3.4.6
AgoraRtcEngineKit
strongly references AgoraRtcEngineDelegate
. If you set the strong reference to AgoraRtcEngineDelegate
by AgoraRtcEngineKit
, Agora recommends that you upgrade the SDK to v3.5.0.2. For details, see v3.5.0.2.v3.4.6 was released on July 15, 2021.
Improvements
To improve the accuracy of face detection results, as of this release, the SDK triggers the facePositionDidChangeWidth
callback immediately after detecting the disappearance of the human face.
Fixed issues
This release fixed the following issues:
- Occasional crash during SDK initialization under certain circumstances.
- The missing
nonnull
and_Nullable
modifiers in Objective-C header files caused warnings when the project was run. - When
startAudioMixing
was called and a percent-encoding URL was passed in this method, the SDK failed to play the corresponding online audio file.
v3.4.5
AgoraRtcEngineKit
strongly references AgoraRtcEngineDelegate
. If you set the strong reference to AgoraRtcEngineDelegate
by AgoraRtcEngineKit
, Agora recommends that you upgrade the SDK to v3.5.0.2. For details, see v3.5.0.2.v3.4.5 was released on June 22, 2021.
Compatibility changes
1. Support for GCM2 encryption
To further improve the security during real-time audio and video transmission process, this release adds the following:
AgoraEncryptionModeAES128GCM2 (7)
andAgoraEncryptionModeAES256GCM2 (8)
encryption modes inAgoraEncryptionMode
. The new GCM encryption modes use a more secure KDF (Key Derivation Function) and support setting the key and salt.- The
encryptionKdfSalt
inAgoraEncryptionConfig
to add the salt for theAgoraEncryptionModeAES128GCM2 (7)
andAgoraEncryptionModeAES256GCM2 (8)
encryption modes.
This release also changes the default encryption mode from AgoraEncryptionModeAES128XTS (1)
to AgoraEncryptionModeAES128GCM2 (7)
. If you use the default encryption mode in earlier versions, after upgrading the SDK to v3.4.5, ensure that you call enableEncryption
and set AgoraEncryptionMode
to AgoraEncryptionModeAES128XTS (1)
.
2. Media stream publishing behavior changes
To flexibly control the publishing state in multiple channels, this release optimizes the AgoraRtcChannel
class as follows:
- Deprecates the
publish
andunpublish
methods, and addsmuteLocalAudioStream
andmuteLocalVideoStream
instead. You can set the publishing state of the audio stream and video stream separately. - Adds the
publishLocalAudio
andpublishLocalVideo
members inAgoraRtcChannelMediaOptions
. The default value isYES
. You can set the publishing state when joining a channel. If a user publishes streams in a channel, regardless of whether the user is a host or an audience member, you need to setpublishLocalAudio
andpublishLocalVideo
toNO
when the user joins other channels; otherwise, the user fails to join the channel. - After calling
setClientRole(AgoraClientRoleBroadcaster)
, the local user publishes audio and video streams by default. You no longer need to callpublish
.
publishLocalAudio = NO
serves the same function asmuteLocalAudioStream(YES)
.publishLocalVideo = NO
serves the same function asmuteLocalVideoStream(YES)
.
The above improvements bring the following changes in the AgoraRtcEngineKit
class:
muteLocalAudioStream
andmuteLocalVideoStream
ofAgoraRtcEngineKit
do not take effect for channels created by theAgoraRtcChannel
class, so you need to use themuteLocalAudioStream
andmuteLocalVideoStream
of theAgoraRtcChannel
class instead.- When a user joins a channel by using
joinChannelByToken
with theoptions
parameter, you can set the publishing state. - If a user joins a channel by calling
joinChannelByToken
with theoptions
parameter,muteLocalAudioStream
ormuteLocalVideoStream
only takes effect when it is called afterjoinChannelByToken
.
If you upgrade the SDK to v3.4.5 or later, to avoid affecting your service, Agora recommends modifying the implementation of muteLocalAudioStream
, muteLocalVideoStream
, publish
, and unpublish
.
See Set the Publishing State and Join Multiple Channels.
3. Raw audio data
The raw audio data function enables you to implement custom audio pre- and post-processing functions, such as audio recording and audio mixing. To reduce the development difficulty and support the accurate observation of audio data at a specific node, this release optimizes the raw audio data APIs as follows:
- To align with the raw video data API names, changes the name of
setAudioFrameDelegate
tosetAudioDataFrame
, and the name ofAgoraAudioFrameDelegate
toAgoraAudioDataFrameProtocol
. - Adds the following callbacks in
AgoraAudioDataFrameProtocol
for you to get the raw audio data at different audio transmission stages and in your expected format:getObservedAudioFramePosition
: Sets the audio observation positions.getRecordAudioParams
: Sets the audio recording format for theonRecordFrame
callback.getPlaybackAudioParams
: Sets the audio playback format for theonPlaybackFrame
callback.getMixedAudioParams
: Sets the audio mixing format for theonMixedFrame
callback.
If you upgrade the SDK to v3.4.5 or later, to avoid affecting your service, ensure that you modify the implementation of setAudioFrameDelegate
and AgoraAudioFrameDelegate
.
4. startAudioMixing changes
To avoid blocking, this release changes the startAudioMixing
from a synchronous call to an asynchronous call.
New features
Raw video data and local encoded video data
To reduce system-resource consumption on devices and the development difficulty of using C++ APIs across platforms, this release adds the following APIs to the Android/iOS platform for you to implement a raw video data observer and a local encoded video data observer. You can use them to implement custom functions, such as recording video, taking screenshots, and image enhancement.
-
Raw video data observer:
setVideoDataFrame
: Registers a raw video data observer.onCaptureVideoFrame
: Gets the video data captured by the local camera.onPreEncodedVideoFrame
: Gets the local pre-encoded video data.onRenderVideoFrame
: Gets the incoming remote video data.getVideoFormatPreference
: Sets the format of the raw video data output by the SDK.getRotationApplied
: Sets whether to rotate the raw video data output by the SDK.getMirrorApplied
: Sets whether to mirror the raw video data output by the SDK.getObservedFramePosition
: Sets the video observation position.isMultipleChannelFrameWanted
: Sets whether the SDK outputs remote video data received in multiple channels.onRenderVideoFrameEx
: Gets the remote video data received in multiple channels.
-
Local encoded video data observer:
setVideoEncodedFrame
: Registers a local encoded video data observer.onVideoEncodedFrame
: Gets the local encoded video data.
Improvements
1. Media Push
To be more transparent to users about errors and events in Media Push, this release adds the following codes:
- To
rtmpStreamingChangedToState
: Error codeAgoraRtmpStreamingErrorCodeUnpublishOK (100)
, which reports that the streaming has been stopped normally. After you callremovePublishStreamUrl
to stop streaming, the SDK returns this error code and state codeAgoraRtmpStreamingStateIdle (0)
. - To
rtmpStreamingEventWithUrl
: Event codeAgoraRtmpStreamingEventUrlAlreadyInUse (2)
, which reports that the streaming URL is already being used for Media Push. If you want to start new streaming, use a new streaming URL.
2. App running on an M1 Mac
This release supports running apps that integrate the Agora iOS SDK on a physical M1 Mac. Due to hardware differences between M1 Mac, iPhone, and iPad, the Agora iOS SDK does not support iPhone- and iPad-specific hardware behaviors on an M1 Mac. For example, it does not support switching the audio route to the earpiece and does not support a rear camera.
3. Music file state
When you call startAudioMixing
after pauseAudioMixing
, this release adds the localAudioMixingStateDidChanged(AgoraAudioMixingStateStopped, AgoraAudioMixingReasonStoppedByUser)
state, which indicates the music file is stopped, before reporting localAudioMixingStateDidChanged(AgoraAudioMixingStatePlaying, AgoraAudioMixingReasonStartedByUser)
.
Fixed issues
This release fixed the following issues:
- Under poor network conditions, when you called
startAudioMixing
to play an online music file, occasionally the SDK response time was too long and caused a freeze. - Under poor network conditions, users were occasionally unable to switch roles.
- Occasionally, the user's view was upside down when the application was running on an M1 chip device.
API changes
Added
AgoraRtmpStreamingErrorCodeUnpublishOK (100)
inAgoraRtmpStreamingErrorCode
AgoraRtmpStreamingEventUrlAlreadyInUse (2)
inAgoraRtmpStreamingEvent
AgoraEncryptionModeAES128GCM2 (7)
andAgoraEncryptionModeAES256GCM2 (8)
inAgoraEncryptionMode
encryptionKdfSalt
inAgoraEncryptionConfig
muteLocalAudioStream
andmuteLocalVideoStream
inAgoraRtcChannel
publishLocalAudio
andpublishLocalVideo
inAgoraRtcChannelMediaOptions
setVideoDataFrame
onCaptureVideoFrame
onPreEncodeVideoFrame
onRenderVideoFrame
getVideoFormatPreference
getRotationApplied
getMirrorApplied
getObservedFramePosition
isMultipleChannelFrameWanted
onRenderVideoFrameEx
setVideoEncodedFrame
onVideoEncodedFrame
- The following callbacks in
AgoraAudioDataFrameProtocol
:
Modified
setAudioFrameDelegate
tosetAudioDataFrame
AgoraAudioFrameDelegate
toAgoraAudioDataFrameProtocol
startAudioMixing
Deprecated
publish
andunpublish
inAgoraRtcChannel
v3.4.4
v3.4.4 was released on June 18, 2021. This release supports iOS 15.
v3.4.3
v3.4.3 was released on June 16, 2021. This release fixed the following issues:
- The missing
nonnull
and_Nullable
modifiers in Objective-C header files caused warnings when you run the project. - The
startAudioMixing
method could not play the MP3 local music files with the.m4a
filename extension. - After a user of the SDK v3.0.0+ left a communication channel that had any user of the SDK versions earlier than 3.0.0 and switched the channel profile to live streaming, the user of the SDK v3.0.0+ set user role to host before joining the next channel, but the client role setting did not take effect.
- Under certain circumstances, an audio delay occasionally occurred 10 minutes after a user joined the channel.
v3.4.2
v3.4.2 was released on May 12, 2021. This release fixed the following issues:
- Interoperability issues between v3.4.0 or v3.4.1 and versions earlier than v3.0.0:
- With the
Communication
channel profile, users of the v3.4.0 or v3.4.1 Native SDK experienced video freezes if they subscribed to videos from users of the Native SDK with versions earlier than v3.0.0. - With the
LiveBroadcasting
channel profile, users of the v3.4.0 or v3.4.1 Native SDK experienced video freezes if they subscribed to videos from users of the Windows or macOS SDK with versions earlier than v3.0.0.
- With the
- Occasional crashes.
v3.4.1
v3.4.1 was released on April 22, 2021. This release fixed the following issues:
- Crashes occurred in a certain voice conversion scenario.
Non-public API usage
error, which occurred only in v3.4.0, when you uploaded your app to the Apple App Store.- Under extremely poor network conditions, the host's video sent from the Web clients was corrupted on the Native clients.
v3.4.0
v3.4.0 was released on April 16, 2021.
Compatibility changes
Integration changes
To reduce the app size after integrating the SDK, this release packages some features as extension libraries (with the Extension
suffix). For details, see Extension libraries. If you do not need to use the related features, you can remove the corresponding extension libraries and recompile the project.
Behavior changes
To monitor the reason why the playback state of a music file changes, this release modifies the localAudioMixingStateDidChanged
callback as follows:
- Replaces the
errorCode
parameter with thereason
parameter. - Deprecates
AgoraAudioMixingErrorCode
and replaces it withAgoraAudioMixingReasonCode
instead. UsingAgoraAudioMixingReasonCode
, you can get the reason for the change of the playback state, such as start, pause, stop or fail. - Modifies some logic of reporting
AgoraAudioMixingStateCode
. For example, as of this release, when looping music, the SDK triggers theAgoraAudioMixingStatePlaying
state when each loop is completed or starts.
If you upgrade the SDK to v3.4.0 or later, to avoid affecting your service, Agora recommends that you modify the implementation of localAudioMixingStateDidChanged
.
New features
1. Virtual metronome
To meet the needs of online teaching scenarios that would benefit from a metronome, this release adds the following methods:
startRhythmPlayer
: Enables the virtual metronome.stopRhythmPlayer
: Disables the virtual metronome.configRhythmPlayer
: Reconfigures the virtual metronome after it is enabled.
2. Playback progress of audio effect files
To control the playback progress of audio effect files, this release adds the following methods:
playEffect
3: Sets the playback position when starting playback of an audio effect file by using thestartPos
parameter.setEffectPosition
: Sets the playback position after starting playback of an audio effect file.getEffectDuration
: Gets the duration of a local audio effect file.getEffectCurrentPosition
: Gets current playback progress of an audio effect file.
Also, this release deprecates the playEffect
2 method. You can use playEffect
3 instead.
Improvements
1. Video encoding
The Agora SDK allows you to use degradationPreference
to set the degradation preference of local video encoding under limited bandwidth, for example, reducing the video frame rate while maintaining video quality, or reducing the video quality while maintaining the video frame rate. As of this release, degradationPreference
can be set as AgoraDegradationBalanced
, which reduces the video frame rate and video quality simultaneously to strike a balance between smoothness and video quality. AgoraDegradationBalanced
is suitable for scenarios where both smoothness and video quality are a priority, such as one-to-one calls, one-to-one online teaching, and multi-user online meetings.
2. Raw video data (C++)
The getRotationApplied
and getMirrorApplied
callbacks can rotate and mirror the raw video data. To improve the user experience, this release expands the video-data formats supported by these callback functions from RGBA to RGBA and YUV 420.
3. Playback progress of music files
To control the playback progress of music files, this release deprecates the startAudioMixing
method and adds a new method with the same name in its place. The new startAudioMixing
method allows you to set the playback position when starting playback of a music file by using the startPos
parameter.
4. AirPlay callback
This release adds support for reporting AgoraAudioOutputRoutingAirPlay
in the didAudioRouteChanged
callback on iOS devices. When you use Apple AirPlay to play audio on an iOS device, the SDK triggers the didAudioRouteChanged
callback and reports AgoraAudioOutputRoutingAirPlay
.
5. Audio recording
To set the recording configuration during audio recording, this release adds the startAudioRecordingWithConfig
method and deprecates startAudioRecording
2. The config
parameter of the startAudioRecordingWithConfig
method allows you to set the audio recording quality, content, sample rate, and storage path of the recording file.
This release also adds a new error code: AgoraErrorCodeAlreadyInRecording(160)
. If you call the startAudioRecordingWithConfig
method again before the current recording ends, the SDK reports this error code.
6. Media device errors
To help users better understand the cause of local video errors, this release adds a new error code to AgoraLocalVideoStreamError
: AgoraLocalVideoStreamErrorCaptureNoDeviceFound(8)
, which indicates that the SDK cannot find the local video-capture device.
Fixed issues
This release fixed the following issues:
- The video was upside down after you used
getMirrorApplied
to set the mirror mode under certain circumstances. - You could not get the video data in the RGBA format from
onPreEncodeVideoFrame
. - You could not use
getMirrorApplied
andgetRotationApplied
to process the local video data before encoding. - The
reportAudioVolumeIndicationOfSpeakers
callback returned incorrect volume information after you calledenableSoundPositionIndication(YES)
. - The local user would see the remote video upside down for an instant when the remote user switched between the front and rear cameras.
- The user interface of the application got stuck when you called
destroy
or theget
method such asgetCallId
orgetSdkVersion
after callingsetupLocalVideo
orsetupRemoteVideo
.
API changes
Added
startRhythmPlayer
stopRhythmPlayer
configRhythmPlayer
playEffect
3getEffectDuration
setEffectPosition
getEffectCurrentPosition
startAudioMixing
2startAudioRecordingWithConfig
3AgoraLocalVideoStreamErrorCaptureNoDeviceFound(8)
inAgoraLocalVideoStreamError
- Error Code:
AgoraErrorCodeAlreadyInRecording(160)
Modified
Deprecated
startAudioRecording
2playEffect
2startAudioMixing
1AgoraAudioMixingErrorCode
v3.3.2
v3.3.2 was released on March 29, 2021. This release fixed the following issues:
- Joining the channel occasionally failed when a user switched back to the app after keeping it in the background for a long time.
- Remote users saw a distorted image when the local user minimized the shared screen with the genie effect on Mac devices.
v3.3.1
v3.3.1 was released on March 4, 2021.
New features
Voice Conversion
This release adds the setVoiceConversionPreset
method to set a voice conversion effect (to disguise a user's voice). You can use this method to make a male-sounding voice sound steady or deep, and a female-sounding voice sound gender-neutral or sweet. See Set the Voice Effect.
Improvements
1. AES-GCM encryption mode
For scenarios requiring high security, to guarantee the confidentiality, integrity, and authenticity of data, and to improve the computational efficiency of data encryption, this release adds the following enumerators in AgoraEncryptionMode
:
AgoraEncryptionModeAES128GCM
: 128-bit AES encryption, GCM mode.AgoraEncryptionModeAES256GCM
: 256-bit AES encryption, GCM mode.
2. Remote audio statistics
To monitor quality of experience (QoE) of the local user when receiving a remote audio stream, this release adds mosValue
to remoteAudioStats
, which reports the quality of the remote audio stream as determined by the Agora real-time audio MOS (Mean Opinion Score) measurement system.
Issues fixed
This release fixed the following issues:
- After enabling the sound position indication, you could not get the remote user's volume by the
reportAudioVolumeIndicationOfSpeakers
callback. - Occasional crashes when you called
enableLocalVideo(NO)
while the application window was switching to Slide Over, Split View, or Picture in Picture mode.
API changes
This release adds the following APIs:
setVoiceConversionPreset
AgoraEncryptionModeAES128GCM
andAgoraEncryptionModeAES256GCM
inAgoraEncryptionMode
mosValue
inAgoraRtcRemoteAudioStats
v3.3.0
v3.3.0 was released on January 22, 2021.
Compatibility changes
1. Integration change
To meet Apple's requirements for using a simulator to run a project, this release changes the SDK package as follows:
- The format of all dynamic libraries changes from Framework to XCFramework. A dynamic library in XCFramework format supports running a project on both physical devices and simulators.
- The
ALL_ARCHITECTURE
folder is removed.
This release also adds AgoraCore.xcframework
, the Agora basic calculation framework.
To integrate the SDK into your project, see Integrate the SDK.
2. Changes to subscribing behavior
This release deprecates setDefaultMuteAllRemoteAudioStreams
and setDefaultMuteAllRemoteVideoStreams
and changes the behavior of mute
-related methods as follows:
mute
-related methods must be called after joining or switching to a channel; otherwise, the method call does not take effect.- Methods with the prefix
muteAll
are no longer the master switch, and eachmute
-related method independently controls the user's subscribing state. When you call methods with the prefixesmuteAll
andmuteRemote
together, the method that is called later takes effect. - Methods with the prefix
muteAll
set whether to subscribe to the audio or video streams of all remote users, including all subsequent users, which means methods with the prefixmuteAll
contain the function of methods with the prefixsetDefaultMute
. Agora recommends not calling methods with the prefixesmuteAll
andsetDefaultMute
together; otherwise, the setting may not take effect.
See details in Set the Subscribing State.
3. Changes to voice activity behavior
In the remote users' reportAudioVolumeIndicationOfSpeakers
callback, this release changes the value of the vad
member from always 0 to always 1.
New features
1. Channel media options
To help developers control media subscription more flexibly, this release adds the joinChannelByToken
2 and switchChannelByToken
2 methods to set whether users subscribe to all remote audio or video streams in a channel when joining and switching channels.
2. Cloud proxy
To improve the usability of the Agora Cloud Proxy, this release adds the setCloudProxy
method to set the cloud proxy and allows you to select a cloud proxy that uses the UDP protocol. For details, see Cloud Proxy.
3. Deep-learning noise reduction
To eliminate non-stationary noise based on traditional noise reduction, this release adds enableDeepLearningDenoise
to enable deep-learning noise reduction.
Before enabling deep-learning noise reduction, integrate the AgoraAIDenoiseExtension.xcframework
dynamic library into your project files.
4. Singing beautifier
To beautify the voice and add reverberation effects in a singing scenario, this release adds the setVoiceBeautifierParameters
method and adds the AgoraSingingBeautifier
constant to AgoraVoiceBeautifierPreset
.
You can call setVoiceBeautifierPreset(AgoraSingingBeautifier)
to beautify the male voice and add the reverberation effect for a voice in a small room. For more settings, you can call setVoiceBeautifierParameters(AgoraSingingBeautifier, param1, param2)
to beautify male or female voices and add reverberation effects for a voice in a small room, large room, or hall.
5. Log files
To ensure the integrity of log content, this release adds the logConfig
property to AgoraRtcEngineConfig
. You can use logConfig
to set the log files output by the Agora SDK when you initialize AgoraRtcEngineKit
. See How can I set the log file? for details.
As of v3.3.0, Agora does not recommend using the setLogFile
, setLogFileSize
, or setLogFilter
methods to set the log files.
6. Quality of captured video
To control the quality of video captured by the local camera, this release adds support for customizing the capture resolution and listening for abnormalities.
- Customize the capture resolution: Call the
setCameraCapturerConfiguration
method to set the capture preference toAgoraCameraCaptureOutputPreferenceManual(3)
and set the width and height of the captured video image. - Listen for abnormalities:
- The abnormal brightness level of captured video images: Use
captureBrightnessLevel
in thelocalVideoStats
callback. - The camera fails to output the captured video: Use the
localVideoStateChange(AgoraLocalVideoStreamStateFailed, AgoraLocalVideoStreamErrorCaptureFailure)
callback. - The camera repeatedly outputs the captured video: Use the
localVideoStateChange(AgoraLocalVideoStreamStateCapturing, AgoraLocalVideoStreamErrorCaptureFailure)
callback.
- The abnormal brightness level of captured video images: Use
To improve the user experience, this release adds the following reasons for local video capture errors in the localVideoStateChange
callback:
AgoraLocalVideoStreamErrorCaptureInBackGround(6)
: The application is running in the background.AgoraLocalVideoStreamErrorCaptureMultipleForegroundApps(7)
: The application is running in Slide Over, Split View, or Picture in Picture mode.
7. Data streams
To support scenarios such as lyrics synchronization and courseware synchronization, this release deprecates the previous createDataStream
method and replaces it with a new method of the same name. You can use this new method to create a data stream and set whether to synchronize the data stream with the audio stream sent to the Agora channel and whether the received data is ordered.
Improvements
1. Raw audio data
This release adds raw audio data APIs for the iOS platform. Once you obtain raw audio data through the following APIs, you can pre-process or post-process it for desired playback effects:
setAudioFrameDelegate
onRecordAudioFrame
onPlaybackAudioFrame
onMixedAudioFrame
onPlaybackAudioFrameBeforeMixing
2. Remote audio statistics
To monitor quality of experience (QoE) of the local user when receiving a remote audio stream, this release adds qoeQuality
and qualityChangedReason
to AgoraRtcRemoteAudioStats
, which report QoE of the local user and the reason for poor QoE, respectively.
API changes
Added
setVoiceBeautifierParameters
AgoraSingingBeautifier
in theAgoraVoiceBeautifierPreset
constantenableDeepLearningDenoise
joinChannelByToken
2switchChannelByToken
2createDataStream
- The
logConfig
property in theAgoraRtcEngineConfig
class setAudioFrameDelegate
onRecordAudioFrame
onPlaybackAudioFrame
onMixedAudioFrame
onPlaybackAudioFrameBeforeMixing
- The
qoeQuality
andqualityChangedReason
properties in theAgoraRtcRemoteAudioStats
class setCloudProxy
- The
captureBrightnessLevel
property in theAgoraRtcLocalVideoStats
class - The
captureWidth
andcaptureHeight
properties in theAgoraCameraCapturerConfiguration
class AgoraCameraCaptureOutputPreferenceManual(3)
in theAgoraCameraCaptureOutputPreference
constantAgoraLocalVideoStreamErrorCaptureInBackGround(6)
andAgoraLocalVideoStreamErrorCaptureMultipleForegroundApps(7)
in theAgoraLocalVideoStreamError
constant- Error code:
AgoraErrorCodeModuleNotFound(157)
Deprecated
setDefaultMuteAllRemoteVideoStreams
setDefaultMuteAllRemoteAudioStreams
setLogFile
setLogFileSize
setLogFilter
createDataStream
v3.2.1
v3.2.1 was released on December 17, 2020. This release fixed the following issues:
- Crashes occurred when using IPv6.
- After you called
enableEncryption
, the SDK did not trigger thefirstLocalVideoFramePublished
callback.
v3.2.0
v3.2.0 was released on November 30, 2020.
Compatibility changes
1. Integration change
Since v3.2.0, the following files have been added to the SDK package:
Agorafdkaac.framework
: The Fraunhofer FDK AAC dynamic library.AgoraSoundTouch.framework
: The SoundTouch dynamic library.Agoraffmpeg.framework
: The FFmpeg dynamic library.
If you upgrade the SDK to v3.2.0 or later, refer to the following steps to add the above dynamic libraries when integrating the SDK:
- Copy the above files to the folder where the
AgoraRtcKit.framework
file is located. - Open Xcode, go to TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content menu, click +, then click Add Other… to add
Agorafdkaac.framework
,AgoraSoundTouch.framework
, andAgoraffmpeg.framework
. Ensure the status of these dynamic libraries is Embed & Sign.
This release also merges AgoraRtcCryptoLoader.framework
into AgoraRtcKit.framework
. After integrating AgoraRtcKit.framework
, you can use built-in encryption directly.
2. Cloud proxy This release optimizes the Agora cloud proxy architecture. If you are already using cloud proxy, to avoid compatibility issues between the new SDK and the old cloud proxy, please contact support@agora.io before upgrading the SDK. See Cloud Proxy.
3. Security and compliance
Agora has passed ISO 27001, ISO 27017, and ISO 27018 international certifications, providing safe and reliable real-time interactive cloud services for users worldwide. See ISO Certificates.
This release supports transport layer encryption by adding TLS (Transport Layer Security) and UDP (User Datagram Protocol) encryption methods.
New features
Interactive Live Streaming Standard
This release adds setClientRole
for setting the latency level of an audience member. You can use this method to switch between Interactive Live Streaming Premium and Interactive Live Streaming Standard as follows:
- Set the latency level as ultra low latency to use Interactive Live Streaming Premium.
- Set the latency level as low latency to use Interactive Live Streaming Standard.
For details, see the product overview of Interactive Live Streaming Standard.
Improvements
1. Local video quality
This release improves the quality of the video captured by the local camera:
- This release optimizes the autofocus function of the rear camera.
- For video with a resolution not lower than 960 × 540 pixels, this release improves the local overexposure of the image under strong light by enabling the HDR attribute of the camera by default.
2. Meeting scenario
To improve the audio experience for multi-person meetings, this release adds AgoraAudioScenarioMeeting(8)
in setAudioProfile
.
3. Voice beautifier and audio effects
To improve the usability of the APIs related to voice beautifier and audio effects, this release deprecates setLocalVoiceChanger
and setLocalVoiceReverbPreset
, and adds the following methods instead:
setVoiceBeautifierPreset
: Compared withsetLocalVoiceChanger
, this method deletes audio effects such as a little boy’s voice and a more spatially resonant voice.setAudioEffectPreset
: Compared withsetLocalVoiceReverbPreset
, this method adds audio effects such as the 3D voice, the pitch correction, a little boy’s voice and a more spatially resonant voice.setAudioEffectParameters
: This method sets detailed parameters for a specified audio effect. In this release, the supported audio effects are the 3D voice and pitch correction.
4. Media Push with transcoding
This release adds the videoCodecType
member to the AgoraLiveTranscoding
class for setting the codec type of the transcoded video stream to H.264 or H.265.
5. Interactive streaming delay
This release reduces the latency on the audience's client during an interactive live streaming by about 500 ms.
Issues fixed
This release fixed the following issues:
- On iPhone 5s and iPhone 6, after the user enabled the basic image enhancement function, the screen flickered when users switched between apps.
- The
stopChannelMediaRelay
method did not take effect. - The SDK mistakenly returned the
AgoraErrorCodeAdmStartRecording(1012)
error.
API changes
Added
setClientRole
setAudioEffectPreset
setVoiceBeautifierPreset
setAudioEffectParameters
AgoraAudioScenarioMeeting(8)
inAgoraAudioScenario
Deprecated
setLocalVoiceChanger
setLocalVoiceReverbPreset
getSmoothRenderingEnabled
(C++)
v3.1.2
v3.1.2 was released on September 14, 2020.
Compatibility changes
To improve user experience, this version disables the local network connection quality report by default, to prevent the prompt to find local network devices from popping up when an end user launches the app on an iOS 14.0 device. The gatewayRtt
parameter in the reportRtcStats
callback is disabled by default. Do not use gatewayRtt
to obtain the round-trip delay between the client and the local router. See the FAQ for details.
If you do not mind the prompt, and want to enable the gatewayRtt
parameter, please contact Agora technical support via support@agora.io.
Issues fixed
This release fixed the following issues:
- When you use MediaIO to switch to a different video source, the screen gets frozen.
- When a remote user leaves the channel, the view of the remote user becomes black.
- The
firstLocalVideoFrameWithSize
andfirstRemoteVideoFrameOfUid
callbacks are not triggered at the right time.
v3.1.1
v3.1.1 was released on August 27, 2020.
Compatibility changes
This release changes the AgoraAreaCode
for regional connection. The latest area codes are as follows:
AgoraAreaCodeCN
: Mainland China.AgoraAreaCodeNA
: North America.AgoraAreaCodeEU
: Europe.AgoraAreaCodeAS
: Asia, excluding Mainland China.AgoraAreaCodeJP
: Japan.AgoraAreaCodeIN
: India.AgoraAreaCodeGLOB
: (Default) Global.
If you have specified a region for connection when calling sharedEngineWithConfig
, ensure that you use the latest area code when migrating from an earlier SDK version.
v3.1.0
v3.1.0 was released on August 11, 2020.
New features
1. Publishing and subscription states
This release adds the following callbacks to report the current publishing and subscribing states:
didAudioPublishStateChange
: Reports the change of the audio publishing state.didVideoPublishStateChange
: Reports the change of the video publishing state.didAudioSubscribeStateChange
: Reports the change of the audio subscribing state.didVideoSubscribeStateChange
: Reports the change of the video subscribing state.
2. First local frame published callback
This release adds the firstLocalAudioFramePublished
and firstLocalVideoFramePublished
callbacks to report that the first audio or video frame is published. The firstLocalAudioFrame
callback is deprecated from v3.1.0.
3. Custom data report
This release adds the sendCustomReportMessage
method for reporting customized messages. To try out this function, contact support@agora.io and discuss the format of customized messages with us.
Improvement
1. Regional connection
This release adds the following regions for regional connection. After you specify the region for connection, your app that integrates the Agora SDK connects to the Agora servers within that region.
AgoraIpAreaCode_JAPAN
: Japan.AgoraIpAreaCode_INDIA
: India.
2. Advanced screen sharing
This release adds the following callbacks to the AgoraVideoSourceProtocol
protocol for screen sharing:
captureType
: Get the capture type of the custom video source.contentHint
: Get the content hint of the custom video source
3. Media Push
This release adds the rtmpStreamingEventWithUrl
callback to report events during Media Push, such as failure to add a background image or watermark image.
4. Encryption
This release adds the enableEncryption
method for enabling built-in encryption, and deprecates the following methods:
setEncryptionSecret
setEncryptionMode
5. More in-call statistics
This release adds the following attributes to provide more in-call statistics:
- Adds
txPacketLossRate
inAgoraRtcLocalAudioStats
, which represents the audio packet loss rate (%) from the local client to the Agora edge server before applying anti-packet loss strategies. - Adds the following attributes in
AgoraRtcLocalVideoStats
:txPacketLossRate
: The video packet loss rate (%) from the local client to the Agora edge server before applying anti-packet loss strategies.captureFrameRate
: The capture frame rate (fps) of the local video.
- Adds
publishDuration
inAgoraRtcRemoteAudioStats
andAgoraRtcRemoteVideoStats
, which represents the total publish duration (ms) of the remote media stream.
6. Audio profile
To improve audio performance, this release adjusts the maximum audio bitrate of each audio profile as follows:
Profile | v3.1.0 | Earlier than v3.1.0 |
---|---|---|
AgoraAudioProfileDefault | ||
AgoraAudioProfileSpeechStandard | 18 Kbps | 18 Kbps |
AgoraAudioProfileMusicStandard | 64 Kbps | 48 Kbps |
AgoraAudioProfileMusicStandardStereo | 80 Kbps | 56 Kbps |
AgoraAudioProfileMusicHighQuality | 96 Kbps | 128 Kbps |
AgoraAudioProfileMusicHighQualityStereo | 128 Kbps | 192 Kbps |
7. Log files
This release increases the default number of log files that the Agora SDK outputs from 2 to 5, and increases the default size of each log file from 512 KB to 1024 KB. By default, the SDK outputs five log files, agorasdk.log
, agorasdk_1.log
, agorasdk_2.log
, agorasdk_3.log
, agorasdk_4.log
. 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 create a new agorasdk.log
to record the latest logs.
8. Video experience under poor network conditions
- Starting with this release, the SDK automatically reduces video resolution under poor network conditions in order to improve the smoothness of the video.
- This release improves video quality by ensuring that the video does not become blurry due to changing network conditions.
9. Others
- This release improves the performance of some iOS models (using Apple A10 and below chips), reducing CPU utilization and memory footprint.
- This release reduces the playback time of the first remote audio frame.
Issues fixed
This release fixed the following issues:
setAudioMixingPitch
did not work when setting thepitch
parameter to certain values.- Occasional audio freeze when disconnecting from a Bluetooth device.
- The app did not receive the
setMediaMetadataDataSource
callback. - Occasional crashes when the user left the channel after talking in multiple channels.
API changes
Added
didAudioPublishStateChange
didVideoPublishStateChange
didAudioSubscribeStateChange
didVideoSubscribeStateChange
firstLocalAudioFramePublished
firstLocalVideoFramePublished
enableEncryption
txPacketLossRate
inAgoraRtcLocalAudioStats
classtxPacketLossRate
andcaptureFrameRate
inAgoraRtcLocalVideoStats
classpublishDuration
inAgoraRtcRemoteAudioStats
andAgoraRtcRemoteVideoStats
classcaptureType
andcontentHint
inAgoraVideoSourceProtocol
protocolrtmpStreamingEventWithUrl
- Warning code:
AgoraWarningCodeAdmCategoryNotPlayAndRecord(1029)
andAgoraWarningCodeApmResidualEcho(1053)
- Error code:
AgoraErrorCodeNoServerResources(103)
Deprecated
setEncryptionSecret
setEncryptionMode
firstLocalAudioFrame
Deleted
- Warning code:
AgoraWarningCodeAdmImproperSettings(1053)
v3.0.1.1
v3.0.1.1 was released on Jun 18, 2020. This release fixed the following issues:
- Crashes after calling
registerVideoRenderFactory
(deprecated). - The image enhancement feature does not work.
v3.0.1
v3.0.1 was released on May 27, 2020.
Compatibility changes
1. Dynamic library
This release replaces the static library with a dynamic library for the following reasons:
- Improving overall security.
- Avoiding incompatibility issues with other third-party libraries.
- Making it easier to upload the app to the App Store.
To upgrade the RTC Native SDK, you must re-integrate the dynamic library, AgoraRtcKit.framework
.
2. Frame position for the video observer (C++)
As of this release, to get the video frame from the onPreEncodeVideoFrame
callback, you must set POSITION_PRE_ENCODER(1<<2)
in getObservedFramePosition
as the frame position to observe, as well as implementing the onPreEncodeVideoFrame
callback.
New features
1. Audio mixing pitch
To set the pitch of the local music file during audio mixing, this release adds setAudioMixingPitch
. You can set the pitch
parameter to increase or decrease the pitch of the music file. This method sets the pitch of the local music file only. It does not affect the pitch of a human voice.
2. Voice enhancement
To improve the audio quality, this release adds the following enumerate elements in setLocalVoiceChanger
and setLocalVoiceReverbPreset
:
AgoraAudioVoiceChanger
adds several elements that have the prefixesAgoraAudioVoiceBeauty
andAgoraAudioGeneralBeautyVoice
. TheAgoraAudioVoiceBeauty
elements enhance the local voice, and theAgoraAudioGeneralBeautyVoice
enumerations add gender-based enhancement effects.AgoraAudioReverbPreset
adds the enumerationAgoraAudioReverbPresetVirtualStereo
and several enumerations that have the prefixAgoraAudioReverbPresetFx
. TheAgoraAudioReverbPresetVirtualStereo
enumeration implements reverberation in the virtual stereo, and theAgoraAudioReverbPresetFx
enumerations implement additional enhanced reverberation effects.
See Set the Voice Changer and Reverberation Effects for more information.
3. Face detection
This release enables local face detection. After you call enableFaceDetection
to enable this function, the SDK triggers the facePositionDidChangeWidth
callback in real time to report the detection results, including the distance between the human face and the device screen. This function can remind users to keep a certain distance from the screen.
4. Fill mode
To improve the user experience of watching videos, this release adds a video display mode AgoraVideoRenderModeFill(4)
. This mode zooms and stretches the video to fill the display window. You can select this mode when calling the following methods:
setupLocalVideo
setupRemoteVideo
setLocalRenderMode
setRemoteRenderMode
5. Remote video renderer in multiple channels
This release adds setRemoteVideoRenderer
and remoteVideoRendererOfUserId
in the AgoraRtcChannel
class to enable users who join the channel using the AgoraRtcChannel
object to customize the remote video renderer.
6. Data post-processing in multiple channels (C++)
This release adds support for post-processing remote audio and video data in a multi-channel scenario by adding the following C++ methods:
- The
IAudioFrameObserver
class:isMultipleChannelFrameWanted
andonPlaybackAudioFrameBeforeMixingEx
. - The
IVideoFrameObserver
class:isMultipleChannelFrameWanted
andonRenderVideoFrameEx
.
After successfully registering the audio or video observer, if you set the return value of isMultipleChannelFrameWanted
as true
, you can get the corresponding audio or video data from onPlaybackAudioFrameBeforeMixingEx
or onRenderVideoFrameEx
. In a multi-channel scenario, Agora recommends setting the return value as true
.
Improvements
Frame position (C++)
After successfully registering the video observer, you can observe and get the video frame at each node of video processing. To conserve power consumption, this release enables customizing the frame position for the video observer. Set the return value of the getObservedFramePosition
callback to set the position to observe:
- The position after capturing the video frame.
- The position before receiving the remote video frame.
- The position before encoding the frame.
Others
- Improves in-call audio quality. When multiple users speak at the same time, the SDK does not decrease volume of any speaker.
- Reduces overall CPU usage of the device.
Fixed issues
- This release fixed issues with inaccurate report of the
didRemoteAudioStateChanged
callback, no audio, audio mixing and audio freezing. - This release fixed issues that failure to end a call, and inaccurate report of the
didClientRoleChanged
callback.
API changes
This release adds the following APIs:
setAudioMixingPitch
- Several elements that have the prefixes
AgoraAudioVoiceBeauty
andAgoraAudioGeneralBeautyVoice
in theAgoraAudioVoiceChanger
enumeration AgoraAudioReverbPresetVirtualStereo
and several elements that have the prefixesAgoraAudioReverbPresetFx
in theAgoraAudioReverbPreset
enumerationenableFaceDetection
facePositionDidChangeWidth
AgoraVideoRenderModeFill
in theAgoraVideoRenderMode
enumerationsetRemoteVideoRenderer
andremoteVideoRendererOfUserId
in theAgoraRtcChannel
classtotalActiveTime
in theAgoraRtcRemoteAudioStats
classtotalActiveTime
in theAgoraRtcRemoteVideoStats
class
v3.0.0.2
v3.0.0.2 was released on Apr 22, 2020.
New features
Specifying the area of connection
This release adds sharedEngineWithConfig
for specifying the area of connection when creating an AgoraRtcEngineKit
instance. This advanced feature applies to scenarios that have regional restrictions. You can choose from areas including Mainland China, North America, Europe, Asia (excluding Mainland China), and global (default).
After specifying the area of connection:
- When the app that integrates the Agora SDK is used within the specified area, it connects to the Agora servers within the specified area under normal circumstances.
- When the app that integrates the Agora SDK is used out of the specified area, it connects to the Agora servers either in the specified area or in the area where the SDK is located.
Issues fixed
This release fixed the occasional failure to connect to a Bluetooth headset.
API changes
Added
v3.0.0
v3.0.0 was released on Mar 4, 2020.
On Mar 24, 2020, we fixed occasional issues relating to no audio, audio mixing, multiple didClientRoleChanged
callbacks, and SDK crashes.
In this release, Agora improves the user experience under poor network conditions for both the Communication
and LiveBroadcasting
profiles through the following measures:
- Adopting a new architecture for the
Communication
profile. - Upgrading the last-mile network strategy for both the
Communication
andLiveBroadcasting
profiles, which enhances the SDK's anti-packet-loss capacity by maximizing the net bitrate when the uplink and downlink bandwidth are insufficient.
To deal with any incompatibility issues caused by the architecture change, Agora uses the fallback mechanism to ensure that users of different versions of the SDKs can communicate with each other: if a user joins the channel from a client using a previous version, all clients using v3.0.0 automatically fall back to the older version. This has the effect that none of the users in the channel can enjoy the improved experience. Therefore we strongly recommend upgrading all your clients to v3.0.0.
We also upgrade the On-premise Recording SDK to v3.0.0. Ensure that you upgrade your On-premise Recording SDK to v3.0.0 so that all users can enjoy the improvements brought by the new architecture and network strategy.
Compatibility changes
1. Renaming the static library and adding support for dynamic library
To unify the library names across platforms, this release renames the library from AgoraRtcEngineKit.framework
to AgoraRtcKit.framework
. If you upgrade your SDK to v3.0.0, you must re-import the AgoraRtcKit
class. For details, see Import the class in the Quickstart.
To improve your development experience, this release also adds support for the dynamic library. You can integrate either the static or the dynamic library in your project, and the name of the dynamic library package is Agora_Native_SDK_for_iOS_v3_0_0_FULL_Dynamic.
Integrating the dynamic library has the following advantages:
- The overall security level is improved.
- Incompatibility issues with other third-party libraries are avoided.
- Uploading the app onto App Store is easier.
If you prefer the dynamic library, you need to re-integrate the SDK and re-import the AgoraRtcKit
class. This process should take no more than five minutes. See Integrate the SDK and Import the class in the Quickstart.
Library type | ipa size (M) | Decompressed ipa size (M) | Frameworks folder size (M) | Binary file size (M) | Total size of frameworks folder + binary file (M) |
Dynamic library | 31.1 | 65 | 51.47 | 2.4 | 53.87 |
Static library | 30.6 | 63.7 | 30.1 | 22.5 | 52.6 |
The dynamic library is located in the framework folder as an independent library. Note that the corresponding binary file size does not include the SDK size. Overall, this decreases the binary file size by 20.1 M and increases the framework folder size by 21.37 M.
2. Dual-stream mode not enabled in the Communication profile
As of v3.0.0, the native SDK does not enable the dual-stream mode by default in the Communication
profile. Call the enableDualStreamMode (YES)
method after joining the channel to enable it. In video scenarios with multiple users, we recommend enabling the dual-stream mode.
New features
1. Multiple channel management
To enable a user to join an unlimited number of channels at a time, this release adds the AgoraRtcChannel
and AgoraRtcChannelDelegate
classes. By creating multiple AgoraRtcChannel
objects, a user can join the corresponding channels at the same time.
After joining multiple channels, users can receive the audio and video streams of all the channels, but publish one stream to only one channel at a time. This feature applies to scenarios where users need to receive streams from multiple channels, or frequently switch between channels to publish streams. See Join multiple channels for details.
2. Raw video data
Adds the following C++ callbacks to the IVideoFrameObserver
class to provide raw video data at different video transmission stages, and to accommodate more scenarios.
onPreEncodeVideo
: Gets the video data after pre-processing and prior to encoding. This method applies to the scenarios where you need to pre-process the video data.getSmoothRenderingEnabled
: Sets whether to smooth the acquired video frames. The smoothed video frames are more evenly spaced, providing a better rendering experience.
3. Adjusting the playback volume of the specified remote user
Adds adjustUserPlaybackSignalVolume
for adjusting the playback volume of a specified remote user. You can call this method as many times as necessary in a call or interactive live streaming to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.
4. Agora Mediaplayer Kit
To enrich the playability of the interactive live streaming, Agora releases the Mediaplayer Kit plug-in, which supports the host playing local or online media resources and sharing them with all users in the channel during the interactive live streaming. See Mediaplayer Kit release notes for details.
Improvements
1. Audio profiles
To meet the need for higher audio quality, this release adjusts the corresponding audio profile of AgoraAudioProfileDefault(0)
in the LiveBroadcasting
profile.
SDK | AgoraAudioProfileDefault(0) |
---|---|
v3.0.0 | A sample rate of 48 KHz, music encoding, mono, and a bitrate of up to 52 Kbps. |
Earlier than v3.0.0 | A sample rate of 32 KHz, music encoding, mono, and a bitrate of up to 52 Kbps. |
2. Mirror mode
The mirror mode determines how the SDK mirrors the video in different stages of transmission. This release supports setting the video mirror mode when encoding and rendering the video:
- Setting a mirror mode for the stream to be encoded: This release adds the
mirrorMode
member to theAgoraVideoEncoderConfiguration
struct struct for setting a mirror effect for the stream to be encoded and transmitted. - Setting a mirror mode for the streams to be rendered:
- We add the
mirrorMode
member to theAgoraRtcVideoCanvas
struct. You can usesetupLocalVideo
, to set a mirror effect for the local view, or usesetupRemoteVideo
to set a mirror effect for the remote view on the local device. - This release also adds the
setLocalRenderMode
andsetRemoteRenderMode
methods, both of which take an extramirrorMode
parameter. During a call, you can usesetLocalRenderMode
to update the mirror effect of the local view orsetRemoteRenderMode
to update the mirror effect of the remote view on the local device.
- We add the
3. Quality statistics
Adds the following members in the AgoraChannelStats
class for providing more in-call statistics, making it easier to monitor the call quality and memory usage in real time:
gatewayRtt
memoryAppUsageRatio
memoryTotalUsageRatio
memoryAppUsageInKbytes
4. Others
This release enables interoperability between the Native SDK and the Web SDK by default, and deprecates the enableWebSdkInteroperability
method.
Issues fixed
- Audio issues concerning audio mixing, audio encoding, and echo.
- Video issues concerning the watermark, video aspect ratio, video sharpness, full-screen video, and black outline during the screen share.
- Other issues related to app crashes, log file, and unstable service when pushing streams to the CDN.
API changes
Behavior change
Calling enableLocalAudio (NO)
does not change the in-call volume to media volume.
Added
setLocalRenderMode
setRemoteRenderMode
- The
mirrorMode
parameter in theAgoraVideoEncoderConfiguration
struct - The
mirrorMode
andchannelId
parameter in theAgoraRtcVideoCanvas
struct - The
channelId
parameter in theAgoraRtcAudioVolumeInfo
struct createRtcChannel
AgoraRtcChannel
classAgoraRtcChannelDelegate
class- The
gatewayRtt
,memoryAppUsageRatio
,memoryTotalUsageRatio
andmemoryAppUsageInKbytes
members in theAgoraChannelStats
class
Deprecated
enableWebSdkInteroperability
setLocalRenderMode
¹. Use the newsetLocalRenderMode
method instead.setRemoteRenderMode
¹. Use the newsetRemoteRenderMode
method instead.setLocalVideoMirrorMode
. Use themirrorMode
parameter in thesetupLocalVideo
andsetLocalRenderMode
methods instead.firstRemoteAudioFrameDecodedOfUid
andfirstRemoteAudioFrameOfUid
. Use theremoteAudioStateChangedOfUid
callback instead.streamPublishedWithUrl
andstreamUnpublishedWithUrl
. Use thertmpStreamingChangedToState
callback instead.
v2.9.3
v2.9.3 was released on Feb 10, 2020.
This release fixed the following issues:
- The
setRemoteSubscribeFallbackOption method
, which should work in theLiveBroadcasting
profile only, also works in theCommunication
profile. - In some one-to-one communication, the downlink media stream falls back to audio-only under poor network conditions.
- In scenarios involving custom video source, the resolution of the received video frame changes as the app switches between the foreground and the background.
v2.9.1
v2.9.1 is released on Sep 19, 2019.
New features
1. Detecting local voice activity
This release adds the report_vad(bool)
parameter to the enableAudioVolumeIndication
method to enable local voice activity detection. Once it is enabled, you can check the AgoraRtcAudioVolumeInfo
struct of the reportAudioVolumeIndicationOfSpeakers
callback for the voice activity status of the local user.
2. Choosing front and rear cameras
Users can select the front or rear camera before joining a channel. This release adds the AgoraCameraDirection
member variable to the AgoraCameraCapturerConfiguration
class to accomplish this. Choose the front or rear camera by selecting AgoraCameraDirectionRear(1)
or AgoraCameraDirectionFront(0)
respectively.
3. Supporting RGBA raw video data
This release supports RGBA raw video data. Use the C++ method getVideoFormatPreference
to set the format of the raw video data format.
You can also rotate or mirror the RGBA raw data using the C++ methods getRotationApplied
or getMirrorApplied
respectively.
Improvements
1. Improving the watermark function in interactive live streaming
This release adds a new addVideoWatermark
method with the following settings:
- The
visibleInPreview
member sets whether the watermark is visible in the local preview. - The
positionInLandscapeMode
/positionInPortraitMode
member sets the watermark position when the encoding video is in landscape/portrait mode.
This release optimizes the watermark function, reducing the CPU usage by 5% to 20%.
The original addVideoWatermark
method is deprecated.
2. Supporting more audio sample rates for recording
To enable more audio sample rate options for recording, this release adds a new startAudioRecording
method with a sampleRate
parameter. In the new method, you can set the sample rate as 16, 32, 44.1 or 48 kHz. The original method supports only a fixed sample rate of 32 kHz and is deprecated.
Issues fixed
Audio
- Audio freezes.
- Abnormal audio when a user rejoins the channel after a third-party app interrupts the call.
- Echoes occur when a user is in a channel.
Miscellaneous
- The remote users do not receive the
didUpdatedUserInfo
callback when the local user switches the network connection before joining the channel and calls thejoinChannelByUserAccount
method. - Mixing streams occur in Media Push.
API changes
To improve the user experience, we made the following changes in v2.9.1:
Added
startAudioRecording
addVideoWatermark
getVideoFormatPreference
getRotationApplied
getMirrorApplied
- The
report_vad
parameter in theenableAudioVolumeIndication
method - The
vad
member in theAgoraRtcAudioVolumeInfo
class - The
AgoraCameraDirection
member in theAgoraCameraCapturerConfiguration
class
Deprecated
startAudioRecording
addVideoWatermark
v2.9.0
v2.9.0 is released on Aug. 16, 2019.
Compatibility changes
1. Media Push
In this release, we deleted the following methods:
configPublisher
setVideoCompositingLayout
clearVideoCompositingLayout
If your app implements Media Push with the methods above, ensure that you upgrade the SDK to the latest version and use the following methods for the same function:
For how to implement the new methods, see Media Push.
2. Reporting the state of the remote video
This release extends the remoteVideoStateChangedOfUid
callback with more states of the remote video: Stopped(0), Starting(1), Decoding(2), Frozen(3), and Failed(4). It adds a reason parameter to the callback to indicate why the remote video state changes. The original remoteVideoStateChangedOfUid
callback is deleted. If you upgrade your Native SDK to the latest version, ensure that you re-implement the remoteVideoStateChangedOfUid
callback.
The new callback reports most of the remote video states, and therefore deprecates the firstRemoteVideoDecodedOfUid
callback. You can still use it, but we do not recommend doing so.
remoteVideoStateChangedOfUid
callback is triggered only when the remote video state has changed.3. Disabling/enabling the local audio
To improve the audio quality in the Communication
profile, this release sets the system volume to the media volume after you call the enableLocalAudio
(true) method. Calling enableLocalAudio
(false) switches the system volume back to the in-call volume.
New features
1. Faster switching to another channel
This release adds the switchChannelByToken
method to enable the audience in an interactive streaming channel to quickly switch to another channel. With this method, you can achieve a much faster switch than with the leaveChannel
and joinChannelByToken
methods. After the audience successfully switches to another channel by calling the switchChannelByToken
method, the SDK triggers the didLeaveChannelWithStats
and didJoinChannel
callbacks to indicate that the audience has left the original channel and joined a new one.
2. Channel media stream relay
This release adds the following methods to relay the media streams of a host from a source channel to a destination channel. This feature applies to scenarios such as online singing contests, where hosts of different interactive streaming channels interact with each other.
During the media stream relay, the SDK reports the states and events of the relay with the channelMediaRelayStateDidChange
and didReceiveChannelMediaRelayEvent
callbacks.
For more information on the implementation, API call sequence, sample code, and considerations, see Co-host Across Channels.
3. Reporting the local and remote audio state
This release adds the localAudioStateChange
and remoteAudioStateChangedOfUid
callbacks to report the local and remote audio states. With these callbacks, the SDK reports the following states for the local and remote audio:
- The local audio: Stopped(0), Recording(1), Encoding(2), or Failed(3). When the state is Failed(3), see the
error
parameter for troubleshooting. - The remote audio: Stopped(0), Starting(1), Decoding(2), Frozen(3), or Failed(4). See the
reason
parameter for why the remote audio state changes.
4. Reporting the local audio statistics
This release adds the localAudioStats
callback to report the statistics of the local audio during a call, including the number of channels, the sending sample rate, and the average sending bitrate of the local audio.
5. Pulling the remote audio data
To improve the experience in audio playback, this release adds the following methods to pull the remote audio data. After getting the audio data, you can process it and play it with the audio effects that you want.
enableExternalAudioSink
disableExternalAudioSink
pullPlaybackAudioFrameRawData
pullPlaybackAudioFrameSampleBufferByLengthInByte
The difference between the onPlaybackAudioFrame
callback and the pullPlaybackAudioFrameRawData
/ 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 an audio delay.pullPlaybackAudioFrameRawData
/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 external audio playback.
Improvements
1. Reporting more statistics of the in-call quality
This release adds the following statistics in the AgoraChannelStats
, AgoraRtcLocalVideoStats
, and AgoraRtcRemoteVideoStats
classes:
AgoraChannelStats
: The total number of the sent audio bytes, sent video bytes, received audio bytes, and received video bytes during a session.AgoraRtcLocalVideoStats
: The encoding bitrate, the width and height of the encoding frame, the number of frames, and the codec type of the local video.AgoraRtcRemoteVideoStats
: The packet loss rate of the remote video.
2. Improving the video quality of interactive live streaming
This release minimizes the video freeze rate under poor network conditions, improves the video sharpness, and optimizes the video smoothness when the packet loss rate is high.
3. Other Improvements
- Improves the audio quality when the audio scenario is set to
GameStreaming
. - Improves the audio quality after the user disables the microphone in the
Communication
profile.
Issues fixed
Audio
- When interoperating with a Web app, voice distortion occurs after the native app enables the remote sound position indication.
- Audio freezes when the audience in the
LiveBroadcasting
profile sets the audio session category to playback. - No audio after a Web app joins the channel when the remote sound position indication is enabled.
Video
- Occasional crashes occur when setting the video encoder configuration after joining the channel.
- Crashes occur when repeatedly changing the video resolution after joining the channel.
Miscellaneous
- Occasionally mixed streams in Media Push.
- Crashes occur after calling the
leaveChannel
method.
API Changes
To improve the user experience, we made the following changes in v2.9.0:
Added
enableExternalAudioSink
disableExternalAudioSink
pullPlaybackAudioFrameRawData
pullPlaybackAudioFrameSampleBufferByLengthInByte
localAudioStateChange
remoteAudioStateChangedOfUid
remoteVideoStateChangedOfUid
localAudioStats
switchChannelByToken
startChannelMediaRelay
updateChannelMediaRelay
stopChannelMediaRelay
channelMediaRelayStateDidChange
didReceiveChannelMediaRelayEvent
AgoraChannelStats
:txAudioBytes
,txVideoBytes
,rxAudioBytes
andrxVideoBytes
AgoraRtcLocalVideoStats
:encodedBitrate
,encodedFrameWidth
,encodedFrameHeight
,encodedFrameCount
andcodedType
AgoraRtcRemoteVideoStats
:packetLossRate
Deprecated
didMicrophoneEnabled
. Use AgoraAudioLocalStateStopped(0) or AgoraAudioLocalStateRecording(1) in thelocalAudioStateChange
callback instead.audioTransportStatsOfUid
. Use theremoteAudioStats
callback instead.videoTransportStatsOfUid
. Use theremoteVideoStats
callback instead.
Deleted
configPublisher
setVideoCompositingLayout
clearVideoCompositingLayout
remoteVideoStateChangedOfUid
v2.8.0
v2.8.0 is released on Jul. 8, 2019.
New features
1. Supporting string user IDs
Many apps use string user IDs. This release adds the following methods to enable apps to join an Agora channel directly with string user IDs as user accounts:
For other methods, Agora uses the integer uid parameter. The Agora Engine maintains a mapping table that contains the user ID and string user account, and you can get the corresponding user account or ID by calling the getUserInfoByUid or getUserInfoByUserAccount method.
To ensure smooth communication, use the same parameter type to identify all users within a channel, that is, all users should use either the integer user ID or the string user account to join a channel.
Note:
- Do not mix parameter types within the same channel. The following Agora SDKs support string user accounts:
- The Native SDK: v2.8.0 and later.
- The Web SDK: v2.5.0 and later.
If you use SDKs that do not support string user accounts, only integer user IDs can be used in the channel.
- If you change your user IDs into string user accounts, ensure that all app clients are upgraded to the latest version.
- If you use string user accounts, ensure that the token generation script on your server is updated to the latest version. If you join the channel with a user account, ensure that you use the same user account or its corresponding integer user ID to generate a token. Call the
getUserInfoByUserAccount
method to get the user ID that corresponds to the user account.
2. Adding remote audio and video statistics
To monitor the audio and video transmission quality during a call or interactive live streaming, this release adds the totalFrozenTime
and frozenRate
members in the AgoraRtcRemoteAudioStats and AgoraRtcRemoteVideoStats classes, to report the audio and video freeze time and freeze rate of the remote user.
This release also adds the numChannels
, receivedSampleRate
, and receivedBitrate
members in the AgoraRtcRemoteAudioStats class.
Improvements
This release adds a AgoraConnectionChangedKeepAliveTimeout(14)
member to the AgoraConnectionChangedReason
parameter of the connectionChangedToState callback. This member indicates a connection state change caused by the timeout of the connection keep-alive between the SDK and Agora's edge server.
Issues Fixed
- Unexpected behaviors when calling the
setRemoteSubscribeFallbackOption
method. - Occasional deadlocks when calling the
MediaIO
methods.
API Changes
To improve your experience, we made the following changes to the APIs:
Added
- registerLocalUserAccount
- joinChannelByUserAccount
- getUserInfoByUid
- getUserInfoByUserAccount
- didRegisteredLocalUser
- didUpdatedUserInfo
- The
numChannels
,receivedSampleRate
,receivedBitrate
,totalFrozenTime
, andfrozenRate
members in the AgoraRtcRemoteAudioStats class - The
totalFrozenTime
andfrozenRate
members in the AgoraRtcRemoteVideoStats class
Deprecated
- The
lowLatency
member in the AgoraLiveTranscoding class
v2.4.1
V2.4.1 is released on Jun 12th, 2019.
Compatibility changes
Ensure that you read the following SDK behavior changes if you migrate from an earlier SDK version.
1. Publishing streams to the RTMP
To improve the usability of the Media Push service, v2.4.1 defines the following parameter limits:
Class / Interface | Parameter Limit |
---|---|
AgoraLiveTranscoding | |
AgoraImage | url: The maximum length of this parameter is 1024 bytes. |
addPublishStreamUrl | url: The maximum length of this parameter is 1024 bytes. |
removePublishStreamUrl | url: The maximum length of this parameter is 1024 bytes. |
This release also adds the audioCodecProfile parameter in the LiveTranscoding
class to set the audio codec profile type. The default type is LC-AAC, which means the low-complexity audio codec profile.
v2.4.1 also adds five error codes to the error parameter in the streamPublishedWithUrl method for quick troubleshooting.
2. Renaming the receivedFrameRate parameter i n the RemoteVideoStats class
v2.4.1 renames the receivedFrameRate
parameter to rendererOutputFrameRate in the AgoraRtcRemoteVideoStats class to more accurately describe the statistics of the remote video stream.
New features
1. Adding media metadata
In interactive live streaming scenarios, the host can send shopping links, digital coupons, and online quizzes to the audience for more diversified interactive live streaming interactions. v2.4.1 adds the setMediaMetadataSource and the setMediaMetadataDelegate interface and the AgoraMediaMetadataDataSource and the AgoraMediaMetadataDelegate protocol, allowing the host to add metadata to the output video and to send media attached information.
2. State of the local video
v2.4.1 adds the localVideoStateChange callback to indicate the local video state. In this callback, the SDK returns the Stopped
, Capturing
, Encoding
, or Failed
state. When the state is Failed
, you can use the error code for troubleshooting. This callback indicates whether or not the interruption is caused by capturing or encoding. This release deprecates the rtcEngineCameraDidReady
and rtcEngineVideoDidStop
callbacks.
3. State of the Media Push
v2.4.1 adds the rtmpStreamingChangedToState callback to indicate the state of the Media Push and help you troubleshoot issues when exceptions occur. In this callback, the SDK returns the Idle
, Connecting
, Runing
, Recovering
, or Failure
state. When the state is Failure
, you can use the error code for troubleshooting. You can still use the streamPublishedWithUrl
and streamUnpublishedWithUrl
callbacks, but we do not recommend using them.
4. More reasons for a network connection state change
In the onConnectionStateChanged callback, v2.4.1 adds error codes to the reason parameter to help you troubleshoot issues when exceptions occur. The SDK returns the connectionChangedToState callback whenever the connection state changes. This release also deprecates AgoraWarningCodeLookupChannelRejected(105)
, AgoraErrorCodeTokenExpired(109)
, and AgoraErrorCodeInvalidToken(110)
.
**5. State of the local network type **
v2.4.1 adds the networkTypeChangedToType callback to indicate the local network type. In this callback, the SDK returns the Unknown
, Disconnected
, Lan
, Wifi
, 2G
, 3G
, or 4G
type. When the network connection is interrupted, this callback indicates whether or not the interruption is caused by a network type change or poor network conditions.
6. Getting the audio mixing volume
v2.4.1 adds the getAudioMixingPlayoutVolume and getAudioMixingPublishVolume methods, which respectively gets the audio mixing volume for local playback and remote playback, to help you troubleshoot audio volume related issues.
7. Reporting when the first remote audio frame is received and decoded
To get the more accurate time of the first audio frame from a specified remote user, v2.4.1 adds the firstRemoteAudioFrameDecodedOfUid callback to report to the app that the SDK decodes first remote audio. This callback is triggered in either of the following scenarios:
- The remote user joins the channel and sends the audio stream.
- The remote user stops sending the audio stream and re-sends it after 15 seconds.
The difference between the onFirstRemoteAudioDecoded and onFirstRemoteAudioFrame
callbacks is that the onFirstRemoteAudioFram
e callback occurs when the SDK receives the first audio packet. It occurs before the onFirstRemoteAudioDecoded
callback.
Improvements
1. Playing multiple online audio effect files simultaneously
v2.4.1 adds the support for playing multiple online audio effect files simultaneously by allowing you to call the playEffect method multiple times with the URLs of the online audio effect files.
2. Reporting more statistics
-
v2.4.1 adds the txPacketLossRate and rxPacketLossRate parameters in the AgoraChannelStats class. These parameters return the packet loss rate from the local client to the server and vice versa.
-
To provide more accurate statistics of the local and remote video, v2.4.1 makes the following changes to the following classes:
- AgoraRtcLocalVideoStats: Adds the encoderOutputFrameRate and rendererOutputFrameRate parameters
- AgoraRtcRemoteVideoStats: Adds the decoderOutputFrameRate parameter, and renames the receivedFrameRate parameter to the rendererOutputFrameRate parameter
3. Image enhancement
v2.4.1 assigns default values to various parameters in the AgoraBeautyOptions class to improve the image enhancement experience. This release also optimizes the image enhancement algorithm. Test results from Agora Lab suggest that the updated algorithm leads to lower GPU and CPU consumption. The power consumption is optimized by 40% - 50%.
4. Miscellaneous
- Improved the sound quality of the GameStreaming audio scenario.
- Reduced the audio and video latency.
- Reduced the SDK package size by 0.5 M.
- Improved the accuracy of the network quality after users change the video bitrate.
- Enabled the audio quality notification callback by default, that is, enabled the remoteAudioStats callback without calling the
enableAudioVolumeIndication
method. - Improved the stability of video services.
- Improved the stability of Media Push.
Issues fixed
Audio
- The audio stream is interrupted by Siri and does not resume.
Video
- Camera exposure issues.
- The user cannot see the remote video on the smartwatch.
Miscellaneous
- Users still receive the
onNetworkQuality
callback after leaving the channel. - Occasional crashes.
API changes
To improve your experience, we made the following changes to the APIs:
Unified the C++ interface for all platforms
v2.4.1 unifies the behavior of the C++ interfaces across different platforms so that you can apply the same code logic on different platforms. v2.4.1 implements the methods of the RtcEngineParameters
class in the IRtcEngine
class. Refer to Agora C++ API Reference for All Platforms home page for the applicable platforms and considerations of each interface.
Added
- getAudioMixingPlayoutVolume
- getAudioMixingPublishVolume
- firstRemoteAudioFrameDecodedOfUid
- localVideoStateChange
- networkTypeChangedToType
- rtmpStreamingChangedToState
- setMediaMetadataSource
- setMediaMetadataDelegate
- AgoraMediaMetadataSource
- AgoraMediaMetadataDelegate
- The audioCodecProfile parameter in the
LiveTranscoding
class - The txPacketLossRate and rxPacketLossRate parameters in the
AgoraChannelStats
class - The encoderOutputFrameRate and rendererOutputFrameRate parameters in the
AgoraRtcLocalVideoStats
class - The decoderOutputFrameRate and rendererOutputFrameRate (to replace
receivedRemoteRate
) parameters in theAgoraRtcRemoteVideoStats
class
Deprecated
enableAudioQualityIndication
rtcEngineCameraDidReady
. Use AgoraLocalVideoStreamStateCapturing(1) in the localVideoStateChange callback instead.rtcEngineVideoDidStop
. Use AgoraLocalVideoStreamStateStopped(0) in the localVideoStateChange callback instead.- The
AgoraWarningCodeLookupChannelRejected(105)
warning code. Use AgoraConnectionChangedRejectedByServer(10) in the connectionChangedToState callback instead. - The
AgoraErrorCodeTokenExpired(109)
error code. Use AgoraConnectionChangedTokenExpired(9) in the connectionChangedToState callback instead. - The
AgoraErrorCodeInvalidToken(110)
error code. Use AgoraConnectionChangedInvalidToken(8) in the connectionChangedToState callback instead. - The
AgoraErrorCodeStartCamera(1003)
error code. Use AgoraLocalVideoStreamErrorCaptureFailure(4) in the localVideoStateChange callback instead.
v2.4.0 and Earlier
v2.4.0
v2.4.0 is released on April 1, 2019.
Compatibility changes
- Agora Video SDK for iOS adds a library dependency on
CoreML.framework
in v2.4.0. Ensure that you add this library when integrating the SDK. For details, see Integrate the SDK. - If you integrate the SDK by using CocoaPods,ensure that you run
pod update
in your Terminal beforepod install
. If you prefer to specify the SDK version to obtain the latest release, ensure that you specify it as'AgoraRtcEngine_iOS', '2.4.0.1'
in the Podfile.
New Features
1. Image enhancement
In scenarios such as the video chat, interactive streaming, and online education, basic beautification is a popular feature. v2.4.0 adds the setBeautyEffectOptions
method, allowing you to adjust the contrast, brightness, smoothness and red saturation of an image. For more information, see Image Enhancement.
2. Voice changer and voice reverberation
Adding voice changer and reverberation effects in an audio chat room brings much more fun. v2.4.0 adds the setLocalVoiceChanger
and setLocalVoiceReverbPreset
methods, allowing you to change your voice or reverberation by choosing from the preset options. See Adjust the pitch and tone.
3. Tracking the sound position of a remote user
v2.4.0 adds the enableSoundPositionIndication
and setRemoteVoicePosition
methods. Call the enableSoundPositionIndication
method before joining a channel to enable stereo panning for the remote users, and then you can call the setRemoteVoicePosition
method to track the position of a remote user.
4. Pre-call last-mile network probe test
Conducting a last-mile probe test before joining the channel helps the local user to evaluate or predict the uplink network conditions. v2.4.0 adds the startLastmileProbeTest
, stopLastmileProbeTest
, and lastmileProbeResult
APIs, allowing you to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).
5.Setting the priority of a remote user's stream
v2.4.0 adds the setRemoteUserPriority
method for setting the priority of a remote user's media stream. You can 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.
6. State of an audio mixing file
v2.4.0 adds the localAudioMixingStateDidChanged
callback to report any change of the audio-mixing file playback state (playback succeeds or fails) and the corresponding reason. This release also adds the warning code 701, which is triggered 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 when playing the audio-mixing file.
7. Setting the log file size
The SDK has two log files, each with a default size of 512 KB. In case some customers require more than the default size, v2.4.0 adds the setLogFileSize
method for setting the log file size (KB).
8. Cloud proxy
Supports the cloud proxy service. See Use Cloud Proxy for details.
Improvements
1. Accuracy of call quality statistics
- v2.4.0 replaces the
startEchoTest
method with thestartEchoTestWithInterval
method. TheintervalInSeconds
parameter ofstartEchoTestWithIntervals
allows you to set the interval between when you speak and when the recording plays back. - v2.4.0 adds three parameters to the
AgoraRtcLocalVideoStats
class:sentTargetBitrate
for setting the target bitrate of the current encoder,sentTargetFrameRate
for setting the target frame rate, andqualityAdaptIndication
for reporting the quality of the local video since last count.
2. Video encoder preferences
v2.4.0 provides the following options for setting video encoder preferences:
- Setting preferences under limited bandwidth. v2.4.0 adds two parameters to the
AgoraVideoEncoderConfiguration
class:minFrameRate
anddegradationPreference
. You can use these parameters together to set the minimum video encoder frame rate and the video encoding degradation preference under limited bandwidth. For more information, see Set the Video Profile. - Setting the camera capture preference. v2.4.0 adds the
setCameraCapturerConfiguration
method, allowing you to set the camera capture preference. You can choose system performance over video quality or vice versa as needed. For more information, see the API Reference.
3. Core quality improvements
- Reduces the audio delay.
- Improves the video quality and stability.
- Shortens the time to render the first remote video frame.
Issues Fixed
Audio
- Calling the
enableLocalAudio
method disconnects all connected Bluetooth devices. - The SDK does not support audio mixing URLs with Chinese characters.
- The SDK does not return YES after the
pushExternalAudioFrameSampleBuffer
method call succeeds. - Volume levels of the high-pitch sound are lowered.
- Sounds are occasionally played fast.
Video
- If you skip the
renderMode
setting, the video stretches due to a mismatch with the display. - Video freezes on some lower-end devices.
- It takes too long to render the first received video frame.
Miscellaneous
- The user drop-offline time between Android and iOS is not unified.
- The SEI information does not synchronize with the media stream when publishing transcoded streams to the CDN.
API Changes
To improve your experience, we made the following changes to the APIs:
Added
setBeautyEffectOptions
setLocalVoiceChanger
setLocalVoiceReverbPreset
enableSoundPositionIndication
setRemoteVoicePosition
startLastmileProbeTest
stopLastmileProbeTest
setRemoteUserPriority
startEchoTestWithInterval
setCameraCapturerConfiguration
setLogFileSize
localAudioMixingStateDidChanged
lastmileProbeResult
Deprecated
startEchoTest
setVideoQualityParameters
Miscellaneous
v2.4.0 changes the type of the frameRate
parameter in the AgoraVideoEncoderConfiguration
class from enum
to int
.
v2.3.3 v2.3.3 is released on January 24, 2019.
Issues Fixed
Occasional inaccurate statistics returned in the networkQuality
callback.
v2.3.2
v2.3.2 is released on January 16, 2019.
Compatibility changes
Besides the new features and improvements mentioned below, it is worth noting that v2.3.2:
- Improves the SDK's ability to counter packet loss under unreliable network conditions.
- Improves the communication smoothness.
- Reduces video freezes in the
LiveBroadcasting
profile.
Before upgrading your SDK, ensure that the version is:
- Native SDK v1.11 or later.
- Web SDK v2.1 or later.
New Features
1. Automatic exposure at a point of interest
v2.3.2 adds the following methods and callback to support camera exposure and improve the captured video quality:
isCameraExposurePositionSupported
: Checks whether the device supports camera exposure.setCameraExposurePosition
: Sets the camera exposure position.cameraExposureDidChangedToRect
: Occurs when the camera exposure area changes. You can send the touch point coordinates in the view to the SDK for automatic exposure.
2. Video quality in the interactive live streaming
v2.3.2 adds the minBitrate
parameter (minimum encoding bitrate) in the setVideoEncoderConfiguration
method. The SDK automatically adjusts the encoding bitrate to adapt to the network conditions. Using a value greater than the default value forces the video encoder to output high-quality images but may cause more packet loss and hence sacrifice the smoothness of the video transmission. Agora does not recommend changing this value unless you have special requirements for image quality.
3. Independent audio mixing volume adjustments for local playback and remote publishing
v2.3.2 adds the adjustAudioMixingPlayoutVolume
and adjustAudioMixingPublishVolume
methods to complement the adjustAudioMixingVolume
method, allowing you to independently adjust the audio mixing volume for local playback and remote publishing.
This release also changes the behavior of the adjustPlaybackSignalVolume method to control only the voice volume. Therefore, to mute the local audio playback, call both the adjustPlaybackSignalVolume(0)
and adjustAudioMixingVolume(0)
methods.
See Adjust the Volume for the scenarios and corresponding APIs.
Improvements
1. Improves the accuracy of the call quality statistics
v2.3.2 deprecates the audioQualityOfUid
callback and replaces it with the remoteAudioStats
callback to improve the accuracy of the call quality statistics. The remoteAudioStats
callback returns parameters such as the audio frame loss rate, end-to-end audio delay, and jitter buffer delay at the receiver, which are more closely linked to the real user experience. In addition, v2.3.2 optimizes the algorithm of the networkQuality
callback for the uplink and downlink network qualities.
remoteAudioStats
: Reports the statistics of the remote audio stream from each user/host. This callback replaces the onAudioQuality callback.networkQuality
: Reports the last mile network quality of each user in the channel.
Agora plans to improve the following callback in subsequent versions:
lastmileQuality
: Reports the last mile network quality of the local user before the user joins a channel.
For the list of API methods related to the call quality statistics and on how and when to use them, see Report In-call Statistics.
2. New network connection policy
v2.3.2 adds the following API method and callback to get the current network connection state and reason for a connection state change:
getConnectionState
: Gets the connection state of the SDK.connectionChangedToState
: Occurs when the connection state of the SDK to the server changes.
v2.3.2 deprecates the rtcEngineConnectionDidInterrupted
and rtcEngineConnectionDidBanned
callbacks.
In the new API method, the network connection states are "disconnected", "connecting", "connected", "reconnecting", and "failed". The SDK triggers the connectionChangedToState
callback when the network connection state changes. The SDK also triggers the rtcEngineConnectionDidInterrupted
and rtcEngineConnectionDidBanned
callbacks under certain circumstances, but Agora does not recommend using them.
3. Improves the call rating system
v2.3.2 changes the rating parameter in the rate
method to "1 to 5" to encourage more feedback from end-users on the quality of a call or interactive live streaming. Application developers can use this feedback for future product improvement. Agora strongly recommends integrating this method in your application.
4. Improves the audio quality in music scenarios
v2.3.2 adds high-quality audio in scenarios such as music education. In the setAudioProfile
method, you can set AgoraAudioProfile
as MusicHighQuality(4) and AgoraAudioScenario
as GameStreaming(3) to minimize echo and noise while maintaining the quality of the music.
5. Other improvements
- Minimizes packet loss under unreliable network conditions in the
LiveBroadcasting
profile. - Accelerates the video quality recovery under network congestion.
- Improves the stability in pushing streams.
- Optimizes the API calling threads.
- Improves the performance of the SDK on mid-end and low-end iOS devices.
- Checks the headset and Bluetooth device connection.
- Reduces the audio delay.
Issues Fixed
The following issues are fixed in v2.3.2.
Audio
- A user joins the interactive live streaming with a Bluetooth headset. The audio is not played through the Bluetooth headset when the user leaves the channel and opens another application.
- Crashes when calling the
startAudioMixing
method to play music files. - A previously disabled microphone becomes enabled when the device connects to a headset.
- Cannot adjust the volume of the speaker when users change roles, join and leave channels, or a system phone or Siri interrupts.
- Users do not hear any voice for a while when an application switches back from the background.
Video
- Occasional issues when using an external video source.
- The cursor on the remote side is not in the same position as the local side when sharing the desktop.
API Changes
To improve your experience, we made the following changes to the APIs:
Added
isCameraExposurePositionSupported
setCameraExposurePosition
getConnectionState
adjustAudioMixingPlayoutVolume
adjustAudioMixingPublishVolume
connectionChangedToState
CameraExposureDidChangedToRect
remoteAudioStats
Deprecated
v2.3.1
v2.3.1 is released on September 28, 2018.
New Features
Disables/Re-enables the Local Audio Function
When a user joins a channel, the audio function is enabled by default.
To receive audio streams without sending any audio streams after joining a channel, this version adds the enableLocalAudio
method to disable or re-enable the local audio function.
Once the local audio function is disabled or re-enabled, the SDK returns the didMicrophoneEnabled
callback, and the local audio capturing stops.
This method does not affect receiving or playing the remote audio streams.
The difference between this method and muteLocalAudioStream
is that enableLocalAudio
does not capture or send any audio stream, while muteLocalAudioStream
captures but does not send audio streams.
Improvements
- Reduces the CPU consumption in the audio communication profile on some low-end iOS devices.
Issues Fixed
- Occasional crashes on some iOS devices when using customized video source functions.
- Occasional crashes on some iOS devices when using customized remote renderer functions.
- Occasional crashes when switching between the front and rear camera.
Communication
profile: If one user disables the video and re-enables it during a one-to-one call, it takes a long time for the other user to see the image.LiveBroadcasting
profile: Occasionally, the app freezes and the user cannot leave the channel after switching between the front and rear cameras on some iOS devices.LiveBroadcasting
: Occasionally, two taps are needed for a successful focus on some iOS devices.LiveBroadcasting
: Delay at the client due to incorrect statistics.- The timestamp in the captured raw video frames does not refresh with the frame.
v2.3.0
v2.3.0 is released on August 31, 2018.
Compatibility changes
- To support video rotation and enable better quality for the custom video source, this version deprecates the
setVideoProfile
method and uses thesetVideoEncoderConfiguration
method instead to set the video encoding configurations. You can still use thesetVideoProfile
method but we recommend using thesetVideoEncoderConfiguration
method to set the video profile because:- During the interactive live streaming, users can set the video orientation mode as adaptive, under which the SDK can transfer rotated video frames without cropping them, thus avoiding the “big headshot” or blurry images at the player.
- In scenarios involving external video sources, the SDK adjusts the width and height of the output video frames based on the inputting video frames, avoiding unnecessary cropping and thereby rendering more image frames at the player.
- An
Accelerate.framework
library is added to the SDK in v2.3.0, which is capable of large-scale mathematical computations and image calculations, optimized for high performance. - The security keys are improved and updated in v2.1.0.
New Features
1. Fallback options for the interactive live streaming under unreliable network conditions.
The audio and video quality of the interactive live streaming deteriorate under unreliable network conditions. To improve the efficiency of the interactive live streaming, the setLocalPublishFallbackOption
and setRemoteSubscribFallbackOption
methods are added. These methods allow the SDK to automatically disable the video stream when the network conditions cannot support both audio and video, and enable the video when the network conditions improve. The SDK triggers the didLocalPublishFallbackToAudioOnly
or didRemoteSubscribeFallbackToAudioOnly
callback when the stream falls back to audio-only or when the stream switches back to the video.
2. Notifies the user that the token expires in 30 seconds.
The SDK returns the tokenPrivilegeWillExpire
callback 30 seconds before a token expires to notify the app to renew it. When this callback is received, you need to generate a new token on your server and call the renewToken
method to pass the newly-generated token to the SDK.
3. Returns user-specific upstream and downstream statistics, including the bitrate, frame rate, packet loss rate, and time delay
The audioTransportStatsOfUid
and videoTransportStatsOfUid
callbacks are added to provide user-specific upstream and downstream statistics, including the bitrate, frame rate, and packet loss rate. During a call or interactive live streaming, the SDK triggers these callbacks once every two seconds after the local user receives audio/video packets from a remote user. The callbacks include the user ID, audio bitrate at the receiver, packet loss rate, and time delay (ms).
4. Sets the SDK’s control over an audio session
The SDK and app both have control over the audio session. However, the app may restrict the SDK’s control over an audio session and allow another app or a third-party component to control it by using the setAudioSessionOperationRestriction
method. You can implement different levels of control by choosing the corresponding restriction. You can call this method before or after joining the channel.
5. Sets the video encoder configurations
To support scenarios with video rotation and enable better quality for the custom video source, this release deprecates the setVideoProfile
method and uses the setVideoEncoderConfiguration
method instead to set the video encoding configurations. You can still use the setVideoProfile
method but Agora recommends using the setVideoEncoderConfiguration
method to set the video profile because:
- During the interactive live streaming, users can set the video orientation mode as adaptive, under which the SDK can transfer rotated video frames without cropping them, thus avoiding the “big headshot” or blurry images at the player.
- In scenarios involving external video sources, the SDK adjusts the width and height of the output video frames based on the inputting video frames, avoiding unnecessary cropping and thereby rendering more image frames at the player.
The AgoraVideoEncoderConfiguration
class provides a set of configurable video parameters, including the dimension, frame rate, bitrate, and orientation. For more information on the API, see Set the Video Encoder Configuration
.
6. Adds support for background image settings in setLiveTranscoding
The backgroundImage
parameter is added to the setLiveTranscoding
method allowing you to set the background image in the combined video of the interactive live streaming.
Improvements
- Improves the quality for one-on-one voice/video scenarios with optimized latency and smoothness, especially for areas like Southeast Asia, South America, Africa, and the Middle East.
- Improves the audio encoder efficiency in the interactive live streaming to reduce user traffic while ensuring the call quality.
- Improves the audio quality during a call or the interactive live streaming using the deep-learning algorithm.
Issues Fixed
- The users on the Web client cannot see the video sent from the Native client due to codec bugs.
- Excessive increase in the memory usage when multiple delegated hosts start streaming in the channel.
- Occasional video renderer crashes when the app switches to the background on some iOS devices.
- Occasional app crashes on some iOS devices.
- The remote view does not display on some devices.
- Occasional black screens on some iOS devices.
- Occasional ghost images.
- Occasional green lines at the bottom of the video when a user switches from a low stream to a high stream video in the
Communication
profile. - Crashes after publishing streams from some iOS devices.
- Occasional crashes on some iOS devices.
- Crashes when a user frequently mutes and resumes all sound effects on some iOS devices.
- Excessive increase in the memory usage for the host when the host frequently joins and leaves a channel that has multiple delegated hosts.
- Occasionally, the remote user cannot hear the host when the host switches between
Audience
andBroadcaster
. - Occasionally, the settings applied to the background image in live transcoding do not take effect.
- Occasionally on some devices, the video height and width are swapped in the
Communication
profile. - Occasionally, the
destroy
method does not respond after a user enables the video and joins a channel. - Occasionally on some iOS devices, a user fails to hear any sound after returning to the channel from a system phone call.
- Occasionally, the audience cannot adjust the channel volume.
- Occasional crashes when a user frequently joins and leaves the channel.
- Occasional crashes when you frequently set the video encoder profile on some iOS devices.
- Occasionally on iOS devices, a remote user cannot send video in a communication channel.
- Occasional failures to capture video of the delegated host when the hosts and the audience frequently change roles.
- Occasionally on some iOS devices, a web user can subscribe to the low-stream video even when the iOS device does not have the dual-stream mode enabled.
- Occasional crashes when calling the
setCameraFocusPositionInPreview
method on some devices. - Occasional crashes when one of the two hosts mutes or disables the local audio while playing the background music.
- Occasional crashes on the iOS device when the device interoperates with the Web and when a web user frequently joins and leaves a channel.
- A user cannot join a communication channel after frequently changing the video encoder profiles.
- Occasional crashes on some devices when preloading the sound effects.
- Video resolution inconsistencies between the encoder and decoder in the
LiveBroadcasting
profile. - Occasional video freezes in the
Communication
orLiveBroadcasting
profile. - Occasional crashes when calling the
muteRemoteVideoStream
method after joining the channel. - Occasionally, some iOS devices still receive the video fallback-specific callbacks even when the video fallback option is not enabled.
- Incorrect video orientation on some iOS devices when setting the video profile of an external video source during the interactive live streaming.
- On iOS, the bitrates cannot reach the target values when manually setting the video profile.
- Occasional inter-operational failures between an iOS and a macOS device.
- Occasional crashes on some iOS devices when a user leaves the interactive streaming channel while playing music using a third-party application.
- Occasional crashes on some iOS devices when leaving the channel.
- On iOS, when a host injects a stream to an interactive streaming channel, other hosts can still inject a second stream to the channel.
- Occasional crashes on some iOS devices when the user frequently turns on and off the camera.
- Occasional video freezes when switching from multiple hosts to a single host.
- Occasional inter-operational failures between SIP devices and the SDK.
- Occasional echo issues when using a specific audio card.
- Occasional video delays on some iOS devices.
- The video window size jumps from small to big on some iOS devices.
- Image blurs on some iOS devices when the camera vibrates.
- Failure to adjust the volume on some iOS devices.
API Changes
To improve your experience, we made the following changes to the APIs:
To avoid adding too many users with the same uid into the RTMP publishing channel, the following API methods are added in v2.3.0:
addUser
removeUser
The following API methods are deleted and no longer supported in v2.3.0. Agora provides the Recording SDK for better recording services.
-
startRecordingService
-
stopRecordingService
-
refreshRecordingServiceStatus
The following deprecated API methods are deleted and no longer supported from v2.3.0:
-
switchView
-
setSpeakerphoneVolume
v2.2.3
v2.2.3 is released on July 5, 2018.
Compatibility changes
The security keys are improved and updated in v2.1.0.
Issues Fixed
- Occasional online statistics crashes.
- Occasional crashes during the interactive live streaming.
- Excessive increase in the memory usage when multiple delegated hosts start streaming in the channel.
- Failure to report the uid and volume of the speaker in a channel.
- Unsteady voice volume of the host in the interactive live streaming.
- Occasional video freeze after a view size change.
v2.2.2
v2.2.2 is released on June 21, 2018.
Issues Fixed
- Fixed occasional online statistics crashes.
- Fixed the issue that the media and the signaling services cannot be accessed at the same time on some iOS devices.
- Fixed the issue of failing to report the uid and volume of the speaker in a channel.
- Fixed the issue of occasional video freeze after a view size change.
v2.2.1
v2.2.1 is released on May 30, 2018.
Issues Fixed
- Occasional crashes on some iOS devices.
- Occasional memory leak on some iOS devices.
- Occasional app crashes when the app starts audio mixing on some iOS devices.
v2.2.0
v2.2.0 is released on May 4, 2018.
New Features
1. Play the audio effect in the channel
Adds a publish
parameter in the playEffect
method for the remote user in the channel to hear the audio effect played locally.
If your SDK is upgraded to v2.2 from a previous version, pay attention to the functional changes of this API.
2. Deploy the proxy at the server
We provide a proxy package for enterprise users with corporate firewalls to deploy before accessing our services.
3. Get the remote video state
Adds the remoteVideoStateChangedOfUid
method to get the state of the remote video stream.
4. Add watermarks on the interactive video streaming
Adds the watermark function for users to add a PNG file to the local or Media Push as a watermark. Adds the addVideoWatermark
and clearVideoWatermarks
methods to add and delete watermarks in the interactive live streaming. Adds the watermark
parameter in the LiveTranscording
interface to add watermarks in Media Push.
Improvements
1. Audio volume indication
Improves the enableAudioVolumeIndication
method. This method once enabled, sends the audio volume indication of the speaker in its callback at set intervals, regardless of whether anyone is speaking in the channel.
2. Network quality detection during a session
To meet the customers’ need for real-time network quality detection in the channel, the onNetworkQuality
method improves its data accuracy.
3. Last mile network quality detection before joining a channel
To test if the customers’ network condition can support audio or video calls before joining the channel, the onLastmileQuality
callback changes its detection base from a fixed bitrate to the bitrate set by the customer in videoProfile
to improve data accuracy. When the network condition is unknown, the SDK triggers this callback once every 2 seconds.
4. Audio quality enhancement
Improves the audio quality in scenarios that involve music playback. To achieve high-fidelity music playback, you can set Scenario:AgoraAudioScenarioGameStreaming = 3
in the setAudioProfile
method.
5. Bitcode support
Adds support for Bitcode, which enables App optimization and thinning by the App Store. The package size of the Bitcode SDK is 2.5 times that of the normal one.
Issues Fixed
- Occasional screen display abnormalities when the iOS device sets its video in the landscape mode.
- Occasional screen display abnormalities when a large number of audience members join as the host in the interactive streaming channel.
- Fixed occasional echo issues caused by some iOS device.
v2.1.3
v2.1.3 is released on April 19, 2018.
In v2.1.3, Agora updates the bitrate values of the setVideoProfile
method in the LiveBroadcasting
profile. The bitrate values in v2.1.3 stay consistent with those in v2.0.
Issues Fixed
- Block callbacks are occasionally not received if the delegate is not set.
- NSAssertionHandler appears in external links to the SDK.
- Occasional recording failures on some phones when a user leaves a channel and turns on the built-in recording device.
LiveBroadcasting
profile: The iOS client cannot see the video from the web client in Windows 10 even after iOS calls theenableWebSdkInteroperability
method.- Occasional resolution changes after
UIImagePickerController
is used to enable the system camera and switch back to theLiveBroadcasting
profile. - Occasional crashes during a
Communication
orLiveBroadcasting
session.
Improvements
Improves the performance of screen sharing by shortening the time interval between which users switch from screen sharing to the normal Communication
or LiveBroadcasting
profile.
v2.1.2
v2.1.2 is released on April 2, 2018.
If you upgrade the SDK to v2.1.2 from a previous version, the interactive video streaming quality is better than the communication video quality in the same resolutions, resulting in the interactive live video streaming using more bandwidth.
New Features
Extends the setVideoProfile
method to enable users to manually set the resolution, frame rate, and bitrate of the video.
Issues Fixed
- Occasional crashes on iOS 11.
- Video freeze in DTX + AAC mode.
v2.1.1
v2.1.1 is released on March 16, 2018.
Agora has identified a critical issue in SDK v2.1. Upgrade to v2.1.1 if you are using Agora SDK v2.1.
v2.1.0
v2.1.0 is released on March 7, 2018.
New Features
1. Voice Optimization
Adds a scenario for the game chat room to reduce the bandwidth and cancel the noise with the setAudioProfile
method.
2. Enhance the audio effect input from the built-in microphone
In an interactive streaming, the host can enhance the local audio effects from the built-in microphone with the setLocalVoiceEqualization
and setLocalVoiceReverb
methods by implementing the voice equalization and reverberation effects.
3. Online statistics query
Adds RESTful APIs to check the status of the users in the channel, the channel list of a specific company, and whether the user is an audience or a host. For detailed information, see RESTful API.
4. 17-way video
Adds the support of 17-way video in interactive streaming.
5. Video source customization
Supports the default video-capturing features provided by the camera and the customized video source.
6. Renderer customization
Supports the default functions provided by the renderers to display the local and remote videos to meet your requirements. We provide a set of interfaces for customized renderers.
7. Injecting an external video stream
Adds the function of injecting an external video stream to an ongoing interactive live streaming.
8. Camera focus change
Adds a cameraFocusDidChanged
callback to report to the app when the camera focus area changes.
Improvement
Improvement | Description |
---|---|
Video Freeze Rate | Reduces the video freeze rate in the audience mode and for specific devices. |
Authentication | Supports a new authentication mechanism. Each legacy Dynamic Key (Channel Key) corresponds to a single privilege (for example, joining a channel), but each token in the new authentication mechanism includes all privileges (for example, joining a channel, hosting in, and stream-pushing). |
Billing Optimization | Small video resolutions are charged according to the voice-only mode. For example, 16 × 16. |
API Naming Optimization | Modifies a set of names for the API attributes and enumeration values. |
Issues Fixed
- Occasional crashes.
- Occasional blank screens.
- Occasionally, no voice after turning off the microphone.
v2.0.2
v2.0.2 was released on December 15, 2017, and fixes the FFmpeg symbol conflict.
v2.0
v2.0 is released on December 6, 2017.
New Features
- Adds the
setRemoteVideoStreamType
andenableDualStreamMode
methods in theCommunication
profile to support dual streams. - Updates the following callbacks for audio mixing and sound effects:
Name | Description |
---|---|
rtcEngineMediaEngineDidAudioMixingFinish | Removed. Replaced by rtcEngineLocalAudioMixingDidFinish . |
rtcEngineDidAudioEffectFinish | Added. Notifies the app when the local audio effect playback stops. |
rtcEngineRemoteAudioMixingDidStart | Added. Notifies the app when the remote user starts audio mixing. |
rtcEngineRemoteAudioMixingDidFinish | Added. Notifies the app when the remote user stops audio mixing. |
- Adds the camera management function in the
Communication
andLiveBroadcasting
profiles by adding the following API methods:
Name | Description |
---|---|
isCameraZoomSupported | Checks whether the device supports camera zoom. |
isCameraTorchSupported | Checks whether the device supports camera flash. |
isCameraFocusPositionInReviewSupported | Checks whether the device supports camera manual focus. |
isCameraAutoFocusFaceModeSupported | Checks whether the device supports auto-face focus. |
setCameraZoomFactor | Sets the camera zoom ratio. |
setCameraFocusPositionInPreview | Sets the position for manual focus and activates focusing. |
setCameraTorchOn | Sets the device to turn on the camera flash. |
setCameraAutoFocusFaceModeEnabled | Sets the device to start auto-face focusing. |
- Supports the external audio source in the
Communication
andLiveBroadcasting
profiles by adding the following API methods:
Name | Description |
---|---|
enableExternalAudioSourceWithSampleRate | Enables the external audio source. |
disableExternalAudioSource | Disables the external audio source. |
pushExternalAudioFrameRawData | Pushes the external audio frame. |
- Provides a set of RESTful APIs to ban a peer user from the server in the
Communication
andLiveBroadcasting
profiles. Contact support@agora.io to enable this function, if required.
Issues Fixed
Audio routing and Bluetooth issues.
v1.14
v1.14 is released on October 20, 2017.
New Features
- Adds the
setAudioProfile
method to set the audio parameters and scenarios. - Adds the
setLocalVoicePitch
method to set the local voice pitch. LiveBroadcasting
: Adds thesetInEarMonitoringVolume
method to adjust the volume of the in-ear monitor.
Improvements
- Optimizes the audio at high bitrates.
LiveBroadcasting
: The audience can view the host within one second in a single-stream mode (938 ms on average, and 734 ms under good network conditions).- Adds the ability to reduce the bandwidth.
- Before v1.14: If you muted the audio of a specific user, the network still sent the stream.
- Starting from v1.14: If you mute the audio of a specific user, the network will not send the stream of the user to reduce the bandwidth.
- Accurate control over the bitrate:
- Before v1.14: Inaccurate control over the bitrate often caused huge fluctuations, leading to network congestion and higher rates of packet and frame loss. This affected the accuracy of the bandwidth estimation module, especially when the network was under poor conditions.
- Starting from v1.14: Accurate control over the bitrate prevents huge fluctuations avoiding network congestion and shortening the transmission latency.
Issues Fixed:
Occasional crashes on iOS devices.
v1.13.1
v1.13.1 is released on September 28, 2017.
- Fixes the issue of unable to adjust the volume in the speaker mode on iOS 11 with iPhone 7 or later.
- Optimizes the echo issue under certain circumstances.
v1.13
v1.13 is released on September 4, 2017.
New Features
- Adds the function to dynamically enable and disable acquiring the sound card in the interactive live streaming.
- Adds the function to disable the audio playback.
- Adds the module map for the SDK, which means that bridging header files are not necessary for Swift projects.
- Supports the profile configuration for stream-pushing on the client side.
- Adds the
didClientRoleChanged
method to report on a user role switch between the host and the audience in the interactive live streaming. - Supports the push-stream failure callback on the server side.
Improvements:
The video profile is controllable by the software codec.
Issues Fixed:
Occasional crashes.
v1.12
v1.12 is released on July 25, 2017.
New Features:
- Adds the
injectStream
method to inject an RTMP stream into the current channel in interactive live streaming. - Adds the
aes-128-ecb
encryption mode in thesetEncryptionMode
method. - Adds the
quality
parameter in thestartAudioRecording
method to set the recording audio quality. - Adds a set of APIs to manage the audio effect.
Improvements:
In the Communication
profile, we improve the 320 × 180 resolution profile:
- Keeps the video smooth under poor network and equipment conditions.
- Enhances the image quality to be better than 180p under good network and equipment conditions.
Issues Fixed:
Occasional crashes.