This page provides the release notes for the Agora Video SDK for macOS.

Overview

The Video SDK supports the following scenarios:

  • Voice/Video Communication
  • Live Voice/Video Broadcast

For the key features included in each scenario, see Voice Overview, Video Overview, Audio Broadcast Overview and Video Broadcast Overview.

Known Issues and Limitations

A USB device driver issue occurs when you do not hear any audio or the audio is corrupted with a USB headset. USB is not user-friendly on macOS, and we recommend using higher quality headsets.

v3.0.1.1

v3.0.1.1 was released on Jun 18, 2020. This release fixed the crashes after calling registerVideoRenderFactory (deprecated).

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. This process should take no more than five minutes. See Migration Guide.

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 prefixes AgoraAudioVoiceBeauty and AgoraAudioGeneralBeautyVoice. The AgoraAudioVoiceBeauty elements enhance the local voice, and the AgoraAudioGeneralBeautyVoice enumerations add gender-based enhancement effects.
  • AgoraAudioReverbPreset adds the enumeration AgoraAudioReverbPresetVirtualStereo and several enumerations that have the prefix AgoraAudioReverbPresetFx. The AgoraAudioReverbPresetVirtualStereo enumeration implements reverberation in the virtual stereo, and the AgoraAudioReverbPresetFx 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:

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.

Fixed issues

  • This release fixed audio mixing issues.
  • This release fixed issues relating to authentication with an App ID and a token.

API changes

This release adds the following APIs:

v3.0.0.2

v3.0.0.2 was released on Apr 22, 2020.

New features

Specify 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 issues relating to no audio, disconnecting from a Bluetooth device after joining a channel, and the occasional failure to join a channel.

API changes

Added

sharedEngineWithConfig

v3.0.0

v3.0.0 was released on Mar 4, 2020.

In this release, Agora improves the user experience under poor network conditions for both the Communication and Live-broadcast profiles through the following measures:

  • Adopting a new architecture for the Communication profile.
  • Upgrading the last-mile network strategy for both the Communication and Live-broadcast 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_macOS_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.

The following table shows the difference in the file size when generating ipa files with a dynamic and static library:
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 a live broadcast to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.

Improvements

1. Audio profiles

To meet the need for higher audio quality, this release adjusts the corresponding audio profile of AgoraAudioProfileDefault(0) in the Live-Broadcast 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 the AgoraVideoEncoderConfiguration 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 the AgoraRtcVideoCanvas struct. You can use setupLocalVideo, to set a mirror effect for the local view, or use setupRemoteVideo to set a mirror effect for the remote view on the local device.
    • This release also adds the setLocalRenderMode and setRemoteRenderMode methods, both of which take an extra mirrorMode parameter. During a call, you can use setLocalRenderMode to update the mirror effect of the local view or setRemoteRenderMode to update the mirror effect of the remote view on the local device.

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.
  • When connected to a headset or Bluetooth, the macOS device changes its audio route to be uniform as the audio route shown in the device manager.

Added

Deprecated

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 the Live-broadcast profile only, also works in the Communication profile.
  • In some one-to-one communication, the downlink media stream falls back to audio-only under poor network conditions.
  • Occasionally, the UI of the system window is abnormal on macOS 10.15.

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. 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 Live Broadcasts

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

Video

The return value of the getDeviceInfo method does not match the actual available device.

API changes

To improve the user experience, we made the following changes in v2.9.1:

Added

Deprecated

  • startAudioRecording
  • addVideoWatermark

v2.9.0

v2.9.0 is released on Aug. 16, 2019.

Compatibility changes

1. RTMP streaming

In this release, we deleted the following methods:

  • configPublisher
  • setVideoCompositingLayout
  • clearVideoCompositingLayout

If your app implements RTMP streaming 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 Push Streams to the CDN.

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 following callbacks. You can still use them, but we do not recommend doing so.

The triggering timing of the new callback is different from the old one. The new 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 a Live Broadcast 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 Live Broadcast 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.

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 live broadcast video quality

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. Improving the screen sharing quality

This release improves the sharpness of text during screen sharing in the Communication profile, particularly when the network condition is poor. Note that this improvement takes effect only when you set contentHint as Details(2).

4. 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.
  • Crashes occur when testing the microphone.

Video

  • Video freezes.

Miscellaneous

  • Occasionally mixed streams in RTMP streaming.

API changes

To improve the user experience, we made the following changes in v2.9.0:

Added

Deprecated

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 live broadcast, 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

Video

  • Occasional deadlocks when calling the MediaIO methods.

Miscellaneous

  • Occasional crashes.

API changes

To improve your experience, we made the following changes to the APIs:

Added

Deprecated

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 RTMP streaming service, v2.4.1 defines the following parameter limits:

Class / Interface Parameter Limit
AgoraLiveTranscoding
  • videoFrameRate: Frame rate (fps) of the CDN live output video stream. The value range is [0, 30], and the default value is 15. Agora adjusts all values over 30 to 30.
  • videoBitrate: Bitrate (Kbps) of the RTMP live output video stream. The default value is 400. Set this parameter according to the Video Bitrate Table. If you set a bitrate beyond the proper range, the SDK automatically adapts it to a value within the range.
  • videoCodecProfile: The video codec profile. Set it as BASELINE, MAIN, or HIGH (default). If you set this parameter to other values, Agora adjusts it to the default value of HIGH.
  • size: Pixel of the video. The minimum value of size is 16 x 16.
    		•
    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 in 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 live broadcast scenarios, the host can send shopping links, digital coupons, and online quizzes to the audience for more diversified live broadcast 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. Optimized screen sharing

    To avoid image cropping and distortion in screen sharing, v2.4.1 optimizes the encoding algorithms. In this release Agora applies the following encoding algorithms:

    Suppose the value of dimensions is 1920 x 1080 pixels, that is, 2073600 pixels:

    • If the value of the screen dimensions is lower than that of the encoding dimensions, for example, 1000 x 1000 pixels, the SDK uses 1000 x 1000 pixels for encoding.
    • If the value of the screen dimensions is higher than that of the encoding dimensions, for example, 2000 x 2000 pixels, the SDK uses the maximum value under 1920 x 1080 pixels with the aspect ratio of the screen dimension (1:1) for encoding, that is, 1440 x 1440 pixels.

    Agora uses the dimensions value in the AgoraScreenCaptureParameters class to calculate the charges. If you do not set the value of dimensions, the SDK uses the default value of 1920 x 1080 to calculate the charges.

    You can also choose whether or not to capture the mouse cursor when sharing the screen. v2.4.1 adds the captureMouseCursor parameter in the AgoraScreenCaptureParameters class and captures the mouse by default.

    3. 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.

    4. State of the RTMP streaming

    v2.4.1 adds the rtmpStreamingChangedToState callback to indicate the state of the RTMP streaming 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.

    5. 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).

    6. 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.

    7. 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.

    8. 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 onFirstRemoteAudioFrame callback occurs when the SDK receives the first audio packet. It occurs before the onFirstRemoteAudioDecoded callback.

    Improvements

    1. Reporting more statistics

    2. 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 RTMP streaming.

    Issues fixed

    Video

    • The user cannot switch between the screen sharing stream and the camera stream.

    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

    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

    If you integrate the SDK by using CocoaPods，ensure that you run pod update in your Terminal before pod install. If you prefer to specify the SDK version to obtain the latest release, ensure that you specify it as 'AgoraRtcEngine_macOS', '2.4.0.1' in the Podfile.

    New features

    1. Advanced screen sharing

    v2.4.0 upgrades screen sharing and provides the following advanced functions:

    v2.4.0 deprecates the startScreenCapture method. We recommend using the new methods for screen sharing. With the new methods, developers need to design the code logic to obtain the displayId and windowId. For more information, see Share the Screen.

    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. Audio device loopback test

    v2.4.0 adds the startAudioDeviceLoopbackTest and stopAudioDeviceLoopbackTest methods for testing whether the local audio devices are working properly. The test involves only the local audio devices and does not report the network condition.

    6. 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.

    7. 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.

    8. 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).

    9. Cloud proxy

    Supports the cloud proxy service. See Use Cloud Proxy for details.

    Improvements

    1. Accuracy of call quality statistics
    2. Video encoder preferences

    v2.4.0 provides the following options for setting video encoder preferences:

    3. Core quality improvements
    • Reduces the audio delay.
    • Improves the video quality and stability.
    • Shortens the time to render the first remote video frame.
    • Improves the video smoothness and reduces the time delay when sharing a screen under poor network conditions.
    • Optimizes the usage of CPU and RAM resources.

    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.
    • The app cannot get the virtual sound card information with the getAudioPlaybackDevices method.
    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.
    • The Electron SDK crashes if the virtual camera does not support 640 x 480.
    • The cursor on the local screen is not accurately projected onto the remote screen.
    Miscellaneous:
    • The SEI information does not synchronize with the media stream when publishing transcoded streams to the RTMP.

    API changes

    To improve your experience, we made the following changes to the APIs:

    Added
    Deprecated
    • startEchoTest
    • startScreenCapture
    • 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.

    Improvements

    v2.3.3 optimizes the screen-sharing algorithm for different scenarios. The video smoothness and quality are enhanced when a user presents slides or browses websites. v2.3.3 also improves the initial image quality in the Communication profile.

    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 Live Broadcast 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. Video quality in a live broadcast

    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.

    2. 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.

    3. Fallback options for a live broadcast under unreliable network conditions

    Unreliable network conditions affect the overall quality of a live broadcast. v2.3.2 adds the setLocalPublishFallbackOption and setRemoteSubscribeFallbackOption methods to allow the SDK to:

    • Automatically disable the video stream when the network conditions cannot support both audio and video, or
    • 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 switches back to the video.

    4. Upstream and downstream statistics of each remote user/host

    v2.3.2 adds the audioTransportStatsOfUid and videoTransportStatsOfUid callbacks to provide the upstream and downstream statistics of each remote user/host. During a call or live broadcast, the SDK triggers these callbacks once every two seconds after the local user receives audio/video packets from a remote user. The callbacks return the user ID, received audio/video bitrate, packet loss rate, and network time delay (ms).

    5. New video encoder configuration

    To support video rotation scenarios and improve the quality of the custom video source, v2.3.2 deprecates the setVideoProfile method and replaces it with the setVideoEncoderConfiguration method to set the video encoder configurations. The AgoraVideoEncoderConfiguration class provides a set of configurable video parameters, including the dimension, frame rate, bitrate, and orientation. You can still use the setVideoProfile method, but we recommend using the setVideoEncoderConfiguration method to set the video profile.

    6. Virtual sound card

    v2.3.2 adds the deviceName parameter in the enableLoopbackRecording method, allowing you to use a virtual sound card for audio recording:

    • To use the current sound card, set deviceName as NULL.
    • To use a virtual card, set deviceName as the name of the virtual card.

    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 the reason for a connection state change:

    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 we do 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 live broadcast. You can use this feedback for future product improvement. We strongly recommend integrating this method in your application.

    4. Other improvements
    • Minimizes packet loss under unreliable network conditions in the Live Broadcast profile.
    • Accelerates the video quality recovery under network congestion.
    • Optimizes the API calling threads.
    • Checks the headset and Bluetooth device connection.
    • Reduces the audio delay.
    • Optimizes video capture methods on macOS and reduces performance loss.

    Issues fixed

    The following issues are fixed in v2.3.2:

    SDK
    • Crashes on macOS.
    Audio
    • A user joins a live broadcast 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
    • The users on the Web client cannot see the video sent from the Native client due to codec bugs.
    • 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
    Deprecated

    v2.2.3

    v2.2.3 is released on July 5, 2018.

    The security keys are improved and updated in v2.1.0. If you are using an Agora SDK version earlier than v2.1.0 and wish to migrate to the latest version, see Token Migration Guide.

    Issues Fixed

    • Occasional online statistics crashes.
    • Occasional crashes during a live broadcast.
    • Excessive increase in the memory usage when multiple delegated hosts broadcast in the channel.
    • Occasional video freeze after a view size change.
    • Failing to report the uid and volume of the speaker in a channel.

    v2.2.2

    v2.2.2 is released on June 21, 2018.

    Issues fixed

    • Fixed occasional online statistics crashes.
    • 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 30th, 2018 and improves the internal code implementation.

    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 to enable 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 broadcasting video

    Adds the watermark function for users to add a PNG file to the local or RTMP broadcast as a watermark. Adds the addVideoWatermark and clearVideoWatermarks methods to add and delete watermarks in a local live-broadcast. Adds the watermark parameter in the LiveTranscording interface to add watermarks in RTMP broadcasts.

    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 voice or video calls before joining the channel, the onLastmileQuality callback changes its detection 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 still triggers this callback once every 2 seconds.

    4. Audio Quality Enhancement

    Improves the audio quality in scenarios that involve music playback.

    Issues fixed

    • Occasional crashes on the macOS device.
    • Occasional screen display abnormalities when a large number of audience members join as the host in a live-broadcast channel.

    v2.1.3

    v2.1.3 is released on April 19, 2018.

    In v2.1.3, we updated the bitrate values of the setVideoProfile method in the Live-broadcast 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.

    Improvements

    Improves the performance of screen sharing by shortening the time interval between which users switch from screen sharing to the normal communication or live-broadcast mode.

    v2.1.2

    v2.1.2 is released on April 2, 2018.

    If you upgraded the SDK to v2.1.2 from a previous version, the live-broadcast video quality will be better than the communication video quality in the same resolutions, resulting in the live broadcasts 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

    The video resolution of the shared screen is worse in the Communication profile than in Live-broadcast profile.

    v2.1.1

    v2.1.1 is released on March 16, 2018.

    We identified a critical bug in SDK v2.1. Upgrade to v2.1.1 if you are using the 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. Enhances the audio effect input from the built-in microphone

    In an interactive broadcast, 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:

    4. 17-way Video

    Adds the support of 17-way video in interactive broadcasts, see:

    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. Screen sharing for interactive broadcast
    • Before v2.1.0: The Agora SDK only supported the screen-sharing function in video calls
    • From v2.1.0: The Agora SDK added the screen-sharing function in interactive broadcasts.

    Improvements

    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 voice-only mode. For example, 16 x 16.
    API Naming Optimization Modifies a set of names for the API attributes and enumeration values.

    v2.0.2

    v2.0.2 is 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 and enableDualStreamMode methods in the Communication 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 and Live-broadcast 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 camera 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 and Live-broadcast 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 to the Agora SDK.
    • Provides a set of RESTful APIs to ban a peer user from the server in the Communication and Live-broadcast 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.
    • Live Broadcast: Adds the setInEarMonitoringVolume method to adjust the volume of the in-ear monitor.

    Improvements

    • Optimizes the audio at high bitrates.
    • Live Broadcast: The audience can view the host within one second in a single-stream mode (858 ms on average, and 625 ms in 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 in poor conditions.
      • Starting from v1.14: Accurate control over the bitrate prevents huge fluctuations avoiding network congestion and shortening the transmission latency.

    v1.13.1

    v1.13.1 is released on September 28, 2017 and 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 a live broadcast.
    • Adds the function to disable the audio playback.
    • Adds the module map for the SDK, which means bridging header files are not necessary for Swift projects.
    • Supports the profile configuration for stream-pushing on the client side.
    • Adds the didClientRoleChanged callback to indicate a user role change between the host and audience in a live broadcast.
    • Supports the push-stream failure callback on the server side.

    Improvements:

    • Screen Sharing: Enhances the video definition and fluency.
    • Screen Sharing: Supports updating the captured region dynamically.
    • The video profile is controllable by the software codec.

    Issues fixed:

    Occasional crashes on some devices.

    v1.12

    v1.12 is released on July 25, 2017.

    New functions:

    • Adds the injectStream method to inject an RTMP stream into the current channel in the Live-broadcast profile.
    • Adds the aes-128-ecb encryption mode in the setEncryptionMode method.
    • Adds the quality parameter in the startAudioRecording method to set the recording audio quality.
    • Adds a set of API methods to manage the audio effect.
    • Adds the ActiveSpeaker method to report on the active speaker in the current channel.
    • Removes the setScreenCaptureWindow method, and updates the startScreenCapture method to share the whole screen and specify the window or region in the Communication profile.
    • Adds displaying the mouse function when the screen-sharing function is enabled in the Communication profile.

    Improvements:

    In the Communication profile, the 320 × 180 resolution profile is improved.

    • 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.