The Voice SDK supports the following scenarios:
- Voice call
- Live interactive audio streaming
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 was released on August 27, 2020.
This release changes the
AgoraAreaCode for regional connection. The latest area codes are as follows:
AgoraAreaCodeCN: Mainland China.
AgoraAreaCodeNA: North America.
AgoraAreaCodeAS: Asia, excluding Mainland China.
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 was released on August 11, 2020.
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 email@example.com and discuss the format of customized messages with us.
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.
This release adds the
enableEncryption method for enabling built-in encryption, and deprecates the following methods:
3. More in-call statistics
This release adds the following attributes to provide more in-call statistics:
AgoraRtcLocalAudioStats, which represents the audio packet loss rate (%) from the local client to the Agora edge server before applying anti-packet loss strategies.
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|
||18 Kbps||18 Kbps|
||64 Kbps||48 Kbps|
||80 Kbps||56 Kbps|
||96 Kbps||128 Kbps|
||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_4.log. The SDK writes the latest logs in
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.
This release fixed the issue that the app failed to record any audio because the audio device module failed to start.
- Warning code:
- Error code:
- Warning code:
v3.0.1 was released on May 27, 2020.
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.
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
AgoraAudioVoiceChangeradds several elements that have the prefixes
AgoraAudioVoiceBeautyelements enhance the local voice, and the
AgoraAudioGeneralBeautyVoiceenumerations add gender-based enhancement effects.
AgoraAudioReverbPresetadds the enumeration
AgoraAudioReverbPresetVirtualStereoand several enumerations that have the prefix
AgoraAudioReverbPresetVirtualStereoenumeration implements reverberation in the virtual stereo, and the
AgoraAudioReverbPresetFxenumerations 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
onPlaybackAudioFrameBeforeMixingEx in the
After successfully registering the audio observer, if you set the return value of
true, you can get the corresponding audio data from
onPlaybackAudioFrameBeforeMixingEx. In a multi-channel scenario, Agora recommends setting the return value as
- This release fixed audio mixing issues.
- This release fixed issues relating to authentication with an App ID and a token.
This release adds the following APIs:
- Several elements that have the prefixes
AgoraAudioReverbPresetVirtualStereoand several elements that have the prefixes
v188.8.131.52 was released on Apr 22, 2020.
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.
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.
v3.0.0 was released on Mar 4, 2020.
In this release, Agora improves the user experience under poor network conditions for both the
LiveBroadcasting profiles through the following measures:
- Adopting a new architecture for the
- Upgrading the last-mile network strategy for both the
LiveBroadcastingprofiles, 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.
Renaming the static library and adding support for dynamic library
To unify the library names across platforms, this release renames the library from
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.
|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)|
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 12.7 M and increases the framework folder size by 13.9 M.
1. Multiple channel management
To enable a user to join an unlimited number of channels at a time, this release adds the
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
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 live interactive streaming to adjust the playback volume of different remote users, or to repeatedly adjust the playback volume of the same remote user.
1. Audio profiles
To meet the need for higher audio quality, this release adjusts the corresponding audio profile of
AgoraAudioProfileDefault(0) in the
|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:
This release enables interoperability between the Native SDK and the Web SDK by default, and deprecates the
- 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.
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.
channelIdparameter in the
memoryAppUsageInKbytesmembers in the
firstRemoteAudioFrameOfUid. Use the
streamUnpublishedWithUrl. Use the
v2.9.1 is released on Sep 19, 2019.
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.
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.
To improve the user experience, we made the following changes in v2.9.1:
report_vadparameter in the
vadmember in the
v2.9.0 is released on Aug. 16, 2019.
1. RTMP streaming
In this release, we deleted the following methods:
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. 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.
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
joinChannelByToken methods. After the audience successfully switches to another channel by calling the
switchChannelByToken method, the SDK triggers the
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.
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
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
errorparameter for troubleshooting.
- The remote audio: Stopped(0), Starting(1), Decoding(2), Frozen(3), or Failed(4). See the
reasonparameter 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
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.
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.
1. Reporting more statistics of the in-call quality
This release adds the following statistics in the
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
- Improves the audio quality after the user disables the microphone in the
- 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.
- Occasionally mixed streams in RTMP streaming.
To improve the user experience, we made the following changes in v2.9.0:
didMicrophoneEnabled. Use AgoraAudioLocalStateStopped(0) or AgoraAudioLocalStateRecording(1) in the
audioTransportStatsOfUid. Use the
v2.8.0 is released on Jul. 8, 2019.
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.
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
getUserInfoByUserAccountmethod 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 live interactive streaming, this release adds the
frozenRate members in the AgoraRtcRemoteAudioStats class, to report the audio freeze time and freeze rate of the remote user.
This release also adds the
receivedBitrate members in the AgoraRtcRemoteAudioStats class.
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.
- Occasional crashes.
To improve your experience, we made the following changes to the APIs:
frozenRatemembers in the AgoraRtcRemoteAudioStats class
lowLatencymember in the AgoraLiveTranscoding class
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
- Push Streams to the CDN
- 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.