Release Notes

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

Known issues and limitations

Compatibility with macOS Monterey 12

As of v3.4.4, the SDK supports macOS Monterey 12. For the SDK versions between v3.2.0 and v3.4.3 inclusive, crashes occur on macOS Monterey 12. To fix this issue, upgrade the SDK to v3.4.4 or later.

USB device driver issue

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.

Rosetta translation issue

If your app is integrated with the SDK earlier than v3.3.0, the app can only run under Rosetta translation on Mac devices with the M1 chip, which causes a memory leak when a user frequently joins and leaves a channel.

To avoid this issue, upgrade the SDK to v3.3.0 or later and adapt the app to x86-64 and arm64 architectures.

v3.7.1

v3.7.1 was released on August 4, 2022.

Improvements

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

• 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.
• gatewayRtt reported by the reportRtcStats callback was inaccurate when the network latency was too high or the router did not respond to ICMP packets.
• Occasionally, it took users longer than normal to join a channel for the first time.

v3.7.0.2

v3.7.0.2 was released on June 6, 2022 and improved the stability of the SDK.

v3.7.0

v3.7.0 was released on April 11, 2022.

Compatibility changes

1. 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
- (BOOL)onRecordAudioFrame:(AgoraAudioFrame* _Nonnull)frame; in the AgoraAudioDataFrameProtocolprotocol	func onRecordAudioFrame(_ frame: AgoraAudioFrame) -> Bool {}	func onRecord(_ frame: AgoraAudioFrame) -> Bool {}

2. Log path

As of v3.7.0, on macOS, the default SDK log path when disabling the sandbox has changed from ～/Library/Logs/agorasdk.log to /Users/<username>/Library/Caches/<App Bundle Identifier>/Logs/agorasdk.log. If you upgrade the SDK, the old logs are stored at the old path, but the new logs are stored at the new path.

New features

1. Virtual sound cards

When calling enableLoopbackRecording for the loopback audio capture, developers typically use common virtual sound cards on macOS, including Soundflower and BlackHole. But these virtual sound cards sometimes experience compatibility issues with the M1 chip or the latest systems, and deferred maintenance.

To improve the loopback audio capture experience, Agora has developed its own virtual sound card: AgoraALD (Agora Audio Loopback Device). You can replace your current virtual sound card with AgoraALD using the following steps:

• Install AgoraALD. See AgoraALD Virtual Sound Card.
• Change the value of deviceName in the enableLoopbackRecording method to "AgoraALD".

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

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

5. 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 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. A new version of noise suppression

Agora has added the option of using a new version of noise suppression to further improve audio quality. To experience this feature, contact support@agora.io

3. playEffect improvements

This release improves the internal implementation logic of playEffect to avoid blocking and reduce freezing when playing an audio effect file.

4. Audio experience optimization

This release reduces audio stuttering under network conditions with burst jitter and high packet loss.

5. Transmission upgrade

This release upgrades transmission protocols and algorithms to enhance the SDK‘s ability to counter poor network conditions.

API changes

Added

• enableLocalVoicePitchCallback
• reportLocalVoicePitchFrequency
• didClientRoleChangeFailed
• AgoraConnectionChangedSameUidLogin(19) and AgoraConnectionChangedTooManyBroadcasters(20) in AgoraConnectionChangedReason

Deprecated

• Warning code AgoraWarningCodeSetClientRoleNotAuthorized(119), use AgoraClientRoleChangeFailedReason instead.

v3.6.2.1

v3.6.2.1 was released on March 4, 2022.

This release fixed a crash of the SDK on systems earlier than macOS 10.11. This crash was due to strong references by some dynamic libraries to the Metal library.

v3.6.2

v3.6.2 was released on February 22, 2022.

Compatibility changes

Dynamic library format change

This release changes .framework files in the SDK to .xcframework files. Compared with the Framework format, the XCFramework format is more flexible and supports the Swift Package Manager for integration.

If you are integrating by using the SDK download link, when you upgrade to v3.6.2, you must modify the project as follows:

1. In the TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content menu and project folder, remove all .framework files.
2. In this menu and project folder, add the corresponding .xcframework files.

For integration details, see the Quickstart Guide.

New features

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

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 device test

To support testing audio devices after joining a channel, this release improves the following methods and callbacks:

• Adds reportAudioDeviceTestVolume, which reports the volume information of the audio device being tested.
• Changes call sequence of startRecordingDeviceTest, startPlaybackDeviceTest, and startAudioDeviceLoopbackTest. Before v3.6.2, you can call these methods only before joining a channel; as of v3.6.2, you can call these methods either before or after joining a channel. After a successful method call, the SDK triggers the following callbacks:
  • reportAudioVolumeIndicationOfSpeakers and reportAudioDeviceTestVolume when you call the methods before joining a channel. Both callbacks report the same volume information. If you upgrade the SDK to v3.6.2 or later, Agora recommendeds using reportAudioDeviceTestVolume.
  • reportAudioDeviceTestVolume when you call the methods after joining a channel.

3. Audio recording

This release extends startAudioRecordingWithConfig with support for setting recording with dual channels and higher audio quality.

• By adding recordingChannel to AgoraAudioRecordingConfiguration, 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 using startAudioRecordingWithConfig.
• By adding AgoraAudioRecordingQualityUltraHigh(3) to AgoraAudioRecordingConfiguration.recordingQuality, it enables you to set the recorded audio quality to ultra-high. Ultra-high quality is the highest quality available in recordingQuality. 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.

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

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

Fixed issues

This release fixed audio stuttering under high jitter networks.

API changes

Added

• enableWirelessAccelerate
• wlAccStats
• wlAccMessage
• reportAudioDeviceTestVolume
• recordingChannel in AgoraAudioRecordingConfiguration
• AgoraAudioRecordingQualityUltraHigh(3) in AgoraAudioRecordingConfiguration.recordingQuality
• didProxyConnected
• AgoraTcpProxy(2) in AgoraCloudProxyType

Modified

• Timing restrictions for the startRecordingDeviceTest, startPlaybackDeviceTest, and startAudioDeviceLoopbackTest method calls.
• The behavior of AgoraNoneProxy(0) in AgoraCloudProxyType.

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.

This release fixed this issue: The CDN live streaming failed because of the abnormal resolution of the RTMP streaming URL with a port number.

v3.6.0.1

v3.6.0.1 was released on December 13, 2021.

This release fixed the following issues:

• v3.6.0 incorrectly renamed the dynamic library Agorafdkaac.framework to AgoraFDKAAC.framework.

• Crashes occurred when the SDK v3.6.0 was integrated using CocoaPods.

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 method addPublishStreamUrl(NO).
• startRtmpStreamWithTranscoding: Starts pushing media streams to a CDN and sets the transcoding configuration. This method works the same as calling the old methods setLiveTranscoding and addPublishStreamUrl(YES) in sequence.
• updateRtmpTranscoding: Updates the transcoding configuration. This method works the same as the non-first call to the old method setLiveTranscoding.
• stopRtmpStream: Stops pushing media streams to a CDN. This method works the same as the old method removePublishStreamUrl.

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, adding AgoraRtmpStreamingStateDisconnecting(5): The SDK is disconnecting from the Agora streaming server and CDN. When you call remove or stop to stop the streaming normally, the SDK reports the streaming state as Disconnecting, Idle in sequence.

  • 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): The update or setLiveTranscoding 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.

• Using the HE-AAC v2 audio codec during streaming with transcoding: This is achieved by adding AgoraAudioCodecProfileHEAACv2 to AgoraAudioCodecProfileType.

New features

Following the system default audio device

To help developers more flexibly manage audio device switching, this release adds the following methods：

• getDefaultAudioDevice: Gets the default audio device of the system.
• followSystemPlaybackDevice: Sets the audio playback device used by the SDK to follow the system default audio playback device.
• followSystemRecordingDevice: Sets the audio recording device used by the SDK to follow the system default audio recording device.

On macOS, after initialized, the SDK uses the system default audio device to play and capture audio by default, and always follows the system default audio device. If you do not need the SDK to follow the system default audio device, call followSystemPlaybackDevice(NO) and followSystemRecordingDevice(NO).

Fixed issues

This release fixed the issue that occasionally Web clients could not hear Native clients.

API changes

Added

• startRtmpStreamWithoutTranscoding

• startRtmpStreamWithTranscoding

• updateRtmpTranscoding

• stopRtmpStream

• AgoraRtmpStreamingStateDisconnecting(5) in AgoraRtmpStreamingState

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

• AgoraAudioCodecProfileHEAACv2 in the AgoraAudioCodecProfileType class

• getDefaultAudioDevice

• followSystemPlaybackDevice

• followSystemRecordingDevice

v3.5.2

v3.5.2 was released on November 25, 2021.

Compatibility changes

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 the AgoraRtcEngineKit class with a valid channel name.
• When a user who has already joined an AgoraRtcChannel channel calls the joining channel method of this AgoraRtcChannel 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.

New features

Testing audio call loop

To check whether the local audio device and network conditions can guarantee the proper sending and receiving of audio 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 device and network conditions are working properly.

Compared to startEchoTestWithInterval, startEchoTestWithConfig can secure the test, but cannot support setting the time interval for reporting test results.

Fixed issues

This release fixed the following issues:

• Remote users heard slightly unsynchronized voice and music when a user called startAudioMixing on some Android devices.
• Echoes could occur when a user joined a channel for the first time.

API changes

This release adds the startEchoTestWithConfig method.

v3.5.1

v3.5.1 was released on October 14, 2021.

New features

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

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

3. Advanced settings of the music file

To set the playback speed 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.
• setAudioMixingDualMonoMode: Sets the channel mode of the current music file to original mode, left channel mode, right channel mode, or mixed channel mode.

4. 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 getAudioFileInfoand 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) to AgoraNetworkType. When the local network changes to 5G, the SDK triggers the networkTypeChangedToType callback to report this network connection type.
• Supports calling enableLastmileTest or startLastmileProbeTest 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 noise suppression, 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.
• When the local user called muteAllRemoteAudioStreams and received onRemoteAudioStateChanged (AgoraAudioRemoteReasonLocalMuted), onRemoteAudioStateChanged (AgoraAudioRemoteReasonRemoteMuted) was incorrectly received after 15 seconds.
• As of v3.4.5, the return value was inaccurate when you called joinChannelByToken multiple times in a row.
• The method call of enableExternalAudioSourceWithSampleRate before joining the channel did not take effect.
• On some device models, when the audio was played through a speaker, echoes occasionally occurred if the speaker volume was set to the maximum value.
• The SDK additionally triggered the localAudioStateChange callback to report AgoraAudioLocalStateRecording(1) when you called enableLocalAudio(NO) after joining a channel.

API changes

Added

• pauseAllChannelMediaRelay
• resumeAllChannelMediaRelay
• The following enumerators in AgoraChannelMediaRelayEvent:
  • AgoraChannelMediaRelayEventPauseSendPacketToDestChannelSuccess
  • AgoraChannelMediaRelayEventPauseSendPacketToDestChannelFailed
  • AgoraChannelMediaRelayEventResumeSendPacketToDestChannelSuccess
  • AgoraChannelMediaRelayEventResumeSendPacketToDestChannelFailed
• pushExternalAudioFrameRawData [2/2]
• pushExternalAudioFrameSampleBuffer [2/2]
• setExternalAudioSourceVolume
• setAudioMixingPlaybackSpeed
• setAudioMixingDualMonoMode
• getAudioFileInfo
• didRequestAudioFileInfo
• AgoraNetworkTypeMobile5G in AgoraNetworkType

Deprecated

• pushExternalAudioFrameRawData [1/2]
• pushExternalAudioFrameSampleBuffer [1/2]
• getAudioMixingDuration

v3.5.0.4

v3.5.0.4 was released on September 26, 2021.

This release fixed the issue that repeated declaration of the didAudioMuted, didVideoEnabled, didLocalVideoEnabled, and firstRemoteVideoDecodedOfUid functions occurred in the header file.

v3.5.0.3

v3.5.0.3 was released on September 6, 2021.

This release fixed the naming conflict existed in the AgoraReachability class between the Agora RTC SDK and Agora RTM SDK.

v3.5.0.1

v3.5.0.1 was released on August 4, 2021. This release fixed the following issue: Due to the strong reference to AgoraRtcEngineDelegate by AgoraRtcEngineKit, the AgoraRtcEngineDelegate object was released only when AgoraRtcEngineKit was destroyed, which caused a memory leak.

v3.5.0

v3.5.0 was released on July 20, 2021.

Improvements

In scenarios where the AGC is enabled, the convergence time for noise reduction is shortened, which reduces noise fluctuations.

Fixed issues

This release fixed the following issues:

• In some audio scenarios, if a user disabled the speakerphone and then joined a channel, the speakerphone was automatically enabled.
• After calling setAudioDataFrame to register the original audio data callback, and calling enableLoopbackRecording to start the sound card capturing, noises occurred when a user played a local audio file.
• 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 the reportRtcStats callback was not accurate.

v3.4.6

v3.4.6 was released on July 15, 2021. This release fixed the following issues:

• Failed to run app on Xcode 12 via My Mac (Designed for iPad) on M1 Mac.
• After connecting the UltraStudio Recorder 3G recording device to the app, a user could not record audio through the UltraStudio Recorder 3G.
• The missing nonnull and _Nullable modifiers in Objective-C header files caused warnings when the project was run.

v3.4.5

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) and AgoraEncryptionModeAES256GCM2 (8) encryption modes in AgoraEncryptionMode. The new GCM encryption modes use a more secure KDF (Key Derivation Function) and support setting the key and salt.
• The encryptionKdfSalt in AgoraEncryptionConfig to add the salt for the AgoraEncryptionModeAES128GCM2 (7) and AgoraEncryptionModeAES256GCM2 (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).

See Media Stream Encryption.

2. Audio stream publishing behavior changes

To flexibly control the publishing state in multiple channels, this release optimizes the AgoraRtcChannel class as follows:

• Deprecates the publish and unpublish methods, and adds muteLocalAudioStream instead.
• Adds the publishLocalAudio member in AgoraRtcChannelMediaOptions. The default value is YES. 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 set publishLocalAudio to NO when the user joins other channels; otherwise, the user fails to join the channel.
• After calling setClientRole(AgoraClientRoleBroadcaster), the local user publishes audio streams by default. You no longer need to call publish.

The above improvements bring the following changes in the AgoraRtcEngineKit class:

• muteLocalAudioStream of AgoraRtcEngineKit do not take effect for channels created by the AgoraRtcChannel class, so you need to use the muteLocalAudioStream of the AgoraRtcChannel class instead.
• When a user joins a channel by using joinChannelByToken with the options parameter, you can set the publishing state.
• If a user joins a channel by calling joinChannelByToken with the options parameter, muteLocalAudioStream only takes effect when it is called after joinChannelByToken.

If you upgrade the SDK to v3.4.5 or later, to avoid affecting your service, Agora recommends modifying the implementation of muteLocalAudioStream 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 to setAudioDataFrame, and the name of AgoraAudioFrameDelegate to AgoraAudioDataFrameProtocol.
• 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 the onRecordFrame callback.
  • getPlaybackAudioParams: Sets the audio playback format for the onPlaybackFrame callback.
  • getMixedAudioParams: Sets the audio mixing format for the onMixedFrame 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.

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 code AgoraRtmpStreamingErrorCodeUnpublishOK (100), which reports that the streaming has been stopped normally. After you call removePublishStreamUrl to stop streaming, the SDK returns this error code and state code AgoraRtmpStreamingStateIdle (0).
• To rtmpStreamingEventWithUrl: Event code AgoraRtmpStreamingEventUrlAlreadyInUse (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. Media device state

To unify the definition of media device states across platforms, this release modifies the value of the state parameter in the stateChanged callback:

• Changes the definition of 0 from "Added" to "The device is ready for use".
• Changes the value reporting the device is not connected from 1 to 8.

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.
• When the user in a channel connected or disconnected a media device, the SDK did not trigger the callback to report the media device's state changes.

API changes

Added

• AgoraRtmpStreamingErrorCodeUnpublishOK (100) in AgoraRtmpStreamingErrorCode
• AgoraRtmpStreamingEventUrlAlreadyInUse (2) in AgoraRtmpStreamingEvent
• AgoraEncryptionModeAES128GCM2 (7) and AgoraEncryptionModeAES256GCM2 (8) in AgoraEncryptionMode
• encryptionKdfSalt in AgoraEncryptionConfig
• muteLocalAudioStream in AgoraRtcChannel
• publishLocalAudio in AgoraRtcChannelMediaOptions
• The following callbacks in AgoraAudioDataFrameProtocol:
  • getObservedAudioFramePosition
  • getRecordAudioParams
  • getMixedAudioParams
  • getPlaybackAudioParams

Modified

• The values of the state parameter in the stateChanged callback
• startAudioMixing
• setAudioFrameDelegate to setAudioDataFrame
• AgoraAudioFrameDelegate to AgoraAudioDataFrameProtocol

Deprecated

• publish and unpublish in AgoraRtcChannel

v3.4.4

v3.4.4 was released on June 18, 2021. This release supports macOS Monterey 12.

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.
• On some low-end devices of the MacBook Air series, when the start time of audio recording on the client exceeded 5 seconds, the audio device module (ADM) restarted indefinitely.
• 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 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.

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

1. Music file playback state

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 the reason parameter.
• Deprecates AgoraAudioMixingErrorCode and replaces it with AgoraAudioMixingReasonCode instead. Using AgoraAudioMixingReasonCode, 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 the AgoraAudioMixingStatePlaying 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.

2. Volume control of microphone

As of this release, the adjustRecordingSignalVolume method only adjusts the volume of the signal captured by the microphone. If you need to adjust the volume of the signal captured by the sound card, use the adjustLoopbackRecordingSignalVolume method instead.

New features

1. Volume control of sound cards

This release adds the adjustLoopbackRecordingSignalVolume method. You can call this method after calling enableLoopbackRecording to adjust the volume of the signal captured by the sound card.

2. Playback progress of audio effect files

To control the playback progress of audio effect files, this release adds the following methods:

• playEffect3: Sets the playback position when starting playback of an audio effect file by using the startPos 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 playEffect2 method. You can use playEffect3 instead.

Improvements

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

2. Audio recording

To set the recording configuration during audio recording, this release adds the startAudioRecordingWithConfig method and deprecates startAudioRecording2. 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.

Fixed issues

This release fixed that the reportAudioVolumeIndicationOfSpeakers callback returned incorrect volume information after you called enableSoundPositionIndication(YES).

API changes

Added

• adjustLoopbackRecordingSignalVolume
• playEffect3
• getEffectDuration
• setEffectPosition
• getEffectCurrentPosition
• startAudioMixing2
• startAudioRecordingWithConfig3
• Error Code: AgoraErrorCodeAlreadyInRecording(160)

Modified

• localAudioMixingStateDidChanged

Deprecated

• startAudioRecording2
• playEffect2
• startAudioMixing1
• AgoraAudioMixingErrorCode

v3.3.2

v3.3.2 was released on March 29, 2021. This release fixed the issue where the local user heard noises from the remote user when a remote user was silent for a long time under certain circumstances.

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.

API changes

This release adds the following APIs:

• setVoiceConversionPreset
• AgoraEncryptionModeAES128GCM and AgoraEncryptionModeAES256GCM in AgoraEncryptionMode
• mosValue in AgoraRtcRemoteAudioStats

v3.3.0

v3.3.0 was released on January 22, 2021.

Compatibility changes

1. Integration change

This release adds AgoraCore.framework, 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 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 each mute-related method independently controls the user's subscribing state. When you call methods with the prefixes muteAll and muteRemote together, the method that is called later takes effect.
• Methods with the prefix muteAll set whether to subscribe to the audio streams of all remote users, including all subsequent users, which means methods with the prefix muteAll contain the function of methods with the prefix setDefaultMute. Agora recommends not calling methods with the prefixes muteAll and setDefaultMute 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. Native support for the M1 chip

This release adds native support for the M1 chip, which means the Agora SDK supports both x86-64 and arm64 architectures. As of v3.3.0, apps that integrate the Agora SDK can natively run on Mac devices with the M1 chip, and you no longer need to set the Rosetta translation.

2. Channel media options

To help developers control media subscription more flexibly, this release adds the joinChannelByToken2 and switchChannelByToken2 methods to set whether users subscribe to all remote audio streams in a channel when joining and switching channels.

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

4. Noise suppression

To eliminate non-stationary noise based on traditional noise reduction, this release adds enableDeepLearningDenoise to enable noise suppression.

Before enabling noise suppression, integrate the AgoraAIDenoiseExtension.framework dynamic library into your project files.

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

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

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 macOS 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 the AgoraVoiceBeautifierPreset constant
• enableDeepLearningDenoise
• joinChannelByToken2
• switchChannelByToken2
• createDataStream
• The logConfig property in the AgoraRtcEngineConfig class
• setAudioFrameDelegate
• onRecordAudioFrame
• onPlaybackAudioFrame
• onMixedAudioFrame
• onPlaybackAudioFrameBeforeMixing
• The qoeQuality and qualityChangedReason properties in the AgoraRtcRemoteAudioStats class
• setCloudProxy
• Error code: AgoraErrorCodeModuleNotFound(157)

Deprecated

• 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.
• When Native clients integrated with the Agora Voice SDK interoperated with Web clients, the Web clients continuously reported the Client.on(disable-local-video) or Client.on(mute-video) 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.

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:

1. Copy the above files to the folder where the AgoraRtcKit.framework file is located.
2. Open Xcode, go to TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content menu, click +, then click Add Other… to add Agorafdkaac.framework and AgoraSoundTouch.framework. Ensure the status of these dynamic libraries is Embed & Sign.

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

To improve the audio experience for multi-person meetings, this release adds AgoraAudioScenarioMeeting(8) in setAudioProfile.

2. 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 with setLocalVoiceChanger, this method deletes audio effects such as a little boy’s voice and a more spatially resonant voice.
• setAudioEffectPreset: Compared with setLocalVoiceReverbPreset, 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.

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

• Users could not hear the audio when calling with AirPods.
• When calling enumerateDevices, the SDK unnecessarily requested permission to use the microphone.

API changes

Added

• setClientRole
• setBeautyEffectOptions
• setAudioEffectPreset
• setVoiceBeautifierPreset
• setAudioEffectParameters
• AgoraAudioScenarioMeeting(8) in AgoraAudioScenario

Deprecated

• setLocalVoiceChanger
• setLocalVoiceReverbPreset

v3.1.2

v3.1.2 was released on September 15, 2020.

This release fixed the issue that hosts fail to push streams to CDN.

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.
• didAudioSubscribeStateChange: Reports the change of the audio subscribing state.

2. First local frame published callback

This release adds the firstLocalAudioFramePublished callback to report that the first audio 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. Encryption

This release adds the enableEncryption method for enabling built-in encryption, and deprecates the following methods:

• setEncryptionSecret
• setEncryptionMode

3. More in-call statistics

This release adds the following attributes to provide more in-call statistics:

• Adds txPacketLossRate in AgoraRtcLocalAudioStats, which represents the audio packet loss rate (%) from the local client to the Agora edge server before applying anti-packet loss strategies.
• Adds publishDuration in AgoraRtcRemoteAudioStats, which represents the total publish duration (ms) of the remote media stream.

4. 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	For the interactive streaming profile: 64 Kbps For the communication profile: 18 Kbps	For the interactive streaming profile: 52 Kbps For the communication profile: 18 Kbps
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

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

6. Audio route

To play audio on more devices, this release adds four enumerators in AgoraAudioOutputRouting, and supports USB, HDMI, DisplayPort peripherals, and Apple AirPlay.

Issues fixed

This release fixed the issue that the app failed to record any audio because the audio device module failed to start.

API changes

Added

• didAudioPublishStateChange
• didAudioSubscribeStateChange
• firstLocalAudioFramePublished
• enableEncryption
• txPacketLossRate in AgoraRtcLocalAudioStats class
• publishDuration in AgoraRtcRemoteAudioStats class
• rtmpStreamingEventWithUrl
• Warning code: AgoraWarningCodeAdmCategoryNotPlayAndRecord(1029) and AgoraWarningCodeApmResidualEcho(1053)
• Error code: AgoraErrorCodeNoServerResources(103)

Deprecated

• setEncryptionSecret
• setEncryptionMode
• firstLocalAudioFrame

Deleted

• Warning code: AgoraWarningCodeAdmImproperSettings(1053)

v3.0.1

v3.0.1 was released on May 27, 2020.

Compatibility changes

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.

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. Data post-processing in multiple channels (C++)

This release adds support for post-processing remote audio data in a multi-channel scenario by adding isMultipleChannelFrameWanted and onPlaybackAudioFrameBeforeMixingEx in the IAudioFrameObserver class.

After successfully registering the audio observer, if you set the return value of isMultipleChannelFrameWanted as true, you can get the corresponding audio data from onPlaybackAudioFrameBeforeMixingEx. In a multi-channel scenario, Agora recommends setting the return value as true.

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:

• setAudioMixingPitch
• Several elements that have the prefixes AgoraAudioVoiceBeauty and AgoraAudioGeneralBeautyVoice in the AgoraAudioVoiceChanger enumeration
• AgoraAudioReverbPresetVirtualStereo and several elements that have the prefixes AgoraAudioReverbPresetFx in the AgoraAudioReverbPreset enumeration
• totalActiveTime in the AgoraRtcRemoteAudioStats 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 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 LiveBroadcasting profiles through the following measures:

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

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

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

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

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

• The channelId parameter in the AgoraRtcAudioVolumeInfo struct
• createRtcChannel
• AgoraRtcChannel class
• AgoraRtcChannelDelegate class
• The gatewayRtt, memoryAppUsageRatio, memoryTotalUsageRatio and memoryAppUsageInKbytes members in the AgoraChannelStats class

Deprecated

• enableWebSdkInteroperability
• firstRemoteAudioFrameDecodedOfUid and firstRemoteAudioFrameOfUid. Use the remoteAudioStateChangedOfUid callback instead.
• streamPublishedWithUrl and streamUnpublishedWithUrl. Use the rtmpStreamingChangedToState callback instead.

v2.9.1

v2.9.1 is released on Sep 19, 2019.

New features

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.

Improvements

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.

API changes

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

Added

• startAudioRecording
• The report_vad parameter in the enableAudioVolumeIndication method
• The vad member in the AgoraRtcAudioVolumeInfo class

Deprecated

• startAudioRecording

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

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:

• setLiveTranscoding
• addPublishStreamUrl
• removePublishStreamUrl
• rtmpStreamingChangedToState

For how to implement the new methods, see Media Push.

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

• startChannelMediaRelay
• updateChannelMediaRelay
• stopChannelMediaRelay

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

• AgoraChannelStats: The total number of the sent audio bytes and received audio bytes during a session.

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

Miscellaneous

• Occasionally mixed streams in Media Push.

API changes

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

Added

• enableExternalAudioSink
• disableExternalAudioSink
• pullPlaybackAudioFrameRawData
• pullPlaybackAudioFrameSampleBufferByLengthInByte
• localAudioStateChange
• remoteAudioStateChangedOfUid
• localAudioStats
• switchChannelByToken
• startChannelMediaRelay
• updateChannelMediaRelay
• stopChannelMediaRelay
• channelMediaRelayStateDidChange
• didReceiveChannelMediaRelayEvent
• AgoraChannelStats: txAudioBytes and rxAudioBytes

Deprecated

• didMicrophoneEnabled. Use AgoraAudioLocalStateStopped(0) or AgoraAudioLocalStateRecording(1) in the localAudioStateChange callback instead.
• audioTransportStatsOfUid. Use the remoteAudioStats callback instead.

Deleted

• configPublisher

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:

• registerLocalUserAccount
• joinChannelByUserAccount

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 statistics

To monitor the audio transmission quality during a call or interactive live streaming, this release adds the totalFrozenTime and frozenRate members in the AgoraRtcRemoteAudioStats class, to report the audio 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

• Occasional crashes.

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, and frozenRate members in the AgoraRtcRemoteAudioStats class

Deprecated

• The lowLatency member in the AgoraLiveTranscoding class

v2.4.1

V2.4.1 is released on Jun 12th, 2019.

This is the first release of the Agora Voice SDK for macOS. Refer to the following guides to quickly integrate the SDK and enable real-time voice communication in your project.

• Quick start
• Use security keys
• Report in-call statistics
• Adjust the volume
• Play audio effects/audio mixing
• Set the voice changer and reverberation effects
• Media Push
• Test or select a media device
• Use Cloud Proxy

If you migrate to this SDK from the macOS Video SDK, refer to the Release notes for the macOS video SDK for audio improvements.