# Release notes (/en/realtime-media/broadcast-streaming/reference/release-notes/ios)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
This page provides the release notes for the Video SDK release streams used by Video Calling.
* [Video SDK](#video-sdk)
* [MetaKit extension](#metakit-extension)
* [Camera Movement extension](#camera-movement-extension)
* [Notifications](#notifications)
## Video SDK [#video-sdk-2]
### Known issues [#known-issues-2]
### v4.6.2 [#v462-2]
Released on January 19, 2026.
#### New features [#new-features-38]
Included in this release:
* **Support for multitasking camera capture on iOS**
Starting with iOS 16, the system supports multitasking, allowing users to use multiple apps in parallel. Common multitasking modes include Split views, Slide over, Picture in picture, and Stage manager. Starting from this version, the SDK supports iOS camera multitasking capture capabilities, allowing continuous audio and video capture in multitasking scenarios. In real-time audio and video interaction scenarios, enabling this feature allows use cases such as referencing materials during video calls, displaying courseware side-by-side in interactive teaching, or managing product backends during live streaming. For details, refer to [How can I enable multitasking camera capture on iOS?](/en/api-reference/faq/integration/multitasking).
Based on Agora Lab testing, the following device models and OS versions support this feature:
| Device Model | Chip | OS | Split View | Slide Over | Picture in Picture | Stage Manager |
| ---------------------------------- | ---- | ------------- | :--------: | :--------: | :----------------: | :-----------: |
| iPad Air 2 | A8X | iPadOS 14.7.1 | — | ✔ | — | — |
| iPad Pro (10.5-inch) | A10X | iPadOS 15.0 | ✔ | ✔ | ✔ | ✔ |
| iPad mini (5th generation) | A12 | iPadOS 17.5.1 | ✔ | ✔ | ✔ | ✔ |
| iPad Pro (11-inch, 2nd generation) | A12Z | iPadOS 18.4.1 | ✔ | ✔ | ✔ | ✔ |
| iPad Pro (11-inch, 3rd generation) | M1 | iPadOS 17.6.1 | ✔ | ✔ | ✔ | ✔ |
| iPhone 11 | A13 | 16.1.1 | — | — | ✔ | — |
* **Support for getting audio buffer delay**
To address the issue where the main vocal and background accompaniment may be out of sync in karaoke scenarios, this release adds the `getAudioBufferDelay` method to the Media Player module to get the millisecond-level audio buffer delay when playing media files.
#### Improvements [#improvements-46]
This release includes the following enhancements:
* **Seamless switching for sound effect files**
Adds support for seamless switching of sound effect files. For the same sound effect file, if you call `preloadEffect` followed by `playEffect`, the SDK does not close the file after playback completes or when `stopEffect` is called. When you call `playEffect` again, the SDK reuses the loaded file to enable loop playback and seamless switching. This feature also works in multi-channel scenarios.
* **Improved accuracy of network quality evaluation**
Improves the accuracy of network quality evaluation in the `networkQuality` callback, making the reported data better reflect the user's perceived experience.
* **Support for 24kHz sampling rate for audio playback**
Adds support for audio data with a sample rate of 24000 Hz in `onPlaybackAudioFrame`. When calling `setPlaybackAudioFrameParameters` to set the playback audio format, you can set `sampleRate` to `24000`.
* **`onEncodedVideoFrameReceived` supports `channelId`**
Adds the `channelId` parameter to the `onEncodedVideoFrameReceived` callback, helping you identify which channel the encoded video data belongs to.
* **Additional improvements**
* Adds error codes `AgoraErrorCodePcmSendFormat (200)` and `AgoraErrorCodePcmSendBufferOverflow (201)` to report PCM data transmission errors.
#### Compatibility changes [#compatibility-changes-23]
This release introduces the following compatibility changes:
* **Support for custom encoding frame rate**
Changes the data type of the `frameRate` parameter in `AgoraVideoEncoderConfiguration` from an enumeration to an `Int`. During integration, refer to the original `AgoraVideoFrameRate` enum values for configuration.
* **Audio Spectrum removed from Lite and Voice packages**
To further reduce SDK package size, this version removes the Audio Spectrum feature from the Lite and Voice SDK packages. If you need the Audio Spectrum feature, please integrate the Full package.
* **Disabled automatic macro mode switching**
Automatic macro mode switching on the camera may cause video flickering. To prevent this issue, this version disables automatic macro mode switching. You can still manually switch macro mode using private parameters based on your business or scenario needs. If needed, please [contact support](mailto\:support@agora.io).
* **Decoder plugins built into the SDK**
The relevant decoder plugins are now built into the SDK to ensure overall decoding compatibility.
* **armv7 architecture no longer supported by default**
Starting from this version, the SDK no longer supports the armv7 architecture by default. If you need to support it, please [contact support](mailto\:support@agora.io).
#### Issues fixed [#issues-fixed-49]
This release fixed the following issues:
* Beauty effects did not work in some scenarios.
* When calling `leaveChannel` and `destroy` on a sub-thread while the UI orientation changed simultaneously, the app crashed.
* On some iOS 16 devices, when a user joined a channel as a broadcaster with the audio scenario set to `AgoraAudioScenarioChatRoom` and called `enableLocalAudio` to disable local audio capture, the call volume could not be adjusted.
* When switching video resolution under hardware exceptions, no encoded frames were output, causing the video to freeze.
### v4.6.0 [#v460-2]
Released on August 26, 2025.
The version of the `aosl.xcframework` library in the v4.6.0 SDK is 1.3.0. You can find the library version information in `Info.plist`.
#### Compatibility changes [#compatibility-changes-24]
This version includes SDK behavior changes, API deprecations, and deletions. To ensure your app functions correctly, update your code after upgrading to this version.
For details on deprecated and deleted APIs in each version, see the [API Sunset Notice](/en/api-reference/api-ref/video/api-sunset).
* **Deprecation of direct CDN streaming APIs**
Deprecates the APIs related to direct CDN streaming, which will be removed in a future release. Agora recommends using [Media Push](/en/realtime-media/media-push) instead.
* `setDirectCdnStreamingAudioConfiguration:`
* `setDirectCdnStreamingVideoConfiguration:`
* `startDirectCdnStreaming:publishUrl:mediaOptions:`
* `stopDirectCdnStreaming`
* `rtcEngine:didDirectCdnStreamingStateChanged:reason:message:`
* `AgoraDirectCdnStreamingMediaOptions`
* `AgoraDirectCdnStreamingStats`
* `AgoraDirectCdnStreamingState`
* `AgoraDirectCdnStreamingReason`
* **Deprecation of virtual metronome APIs**
Deprecates the APIs for the virtual metronome feature, which will be removed in a future release.
* `startRhythmPlayer:sound2:config:`
* `configRhythmPlayer:`
* `rtcEngine:didRhythmPlayerStateChanged:reason:`
* **Deprecation of watermark APIs**
Deprecates the old watermark APIs. Agora recommends using the new watermark APIs introduced in this version.
* `addVideoWatermark:options:`
* `addVideoWatermarkEx:options:connection:`
* **Deletion of redundant APIs**
Removed the following redundant APIs and parameters:
* `setLocalPublishFallbackOption:`
* `rtcEngine:didLocalPublishFallbackToAudioOnly:`
* `downlinkNetworkInfoUpdate`
* `wlAccStats`
* `AgoraWlAccReason`
* `AgoraWlAccAction`
* `rtcEngine:wlAccStats:averageStats:`
* `rtcEngine:wlAccMessage:action:wlAccMsg:`
* `enableWirelessAccelerate`
* `receivedFrameRate` (removed from `AgoraRtcRemoteVideoStats`)
* **Changes to int UID and string UID mapping**
* Before v4.6.0: If you used `registerLocalUserAccountWithAppID:userAccount:` to register a string UID (for example, `"aa"`) and obtain an int UID (for example, `123`), joining a channel with this int UID automatically mapped it to the original string UID (`"aa"`).
* From v4.6.0: The SDK no longer automatically maps an int UID to the original string UID. If you need to join the channel with the original string UID, call `joinChannelByUserAccount:token:channelId:joinSuccess:` directly with the string UID. After upgrading, review and update your app logic to ensure users join the channel with the expected identity.
* **Added domain whitelist**
If you have upgraded from a previous SDK version to v4.6.0 and are using the domain whitelist feature (set `domainLimit` in `AgoraRtcEngineConfig` to `YES`), add the following domains to the whitelist to ensure uninterrupted communication:
* `*.rtnsvc.com`
* `*.realtimemesh.com`
* **Default log path change**
This release changes the default log path from `AppSandbox/Library/documents/agorasdk.log` to `AppSandbox/Library/caches/agorasdk.log`. If you upgrade the SDK from v4.3.1 or later to v4.6.0, ensure that you use the new path to access the log file.
#### New features [#new-features-39]
* **Simulcasting multi-bitrate video streams (Beta)**
Added support for sending multiple video streams of different resolutions from a single video source, including in multi-channel scenarios. You can now configure up to four layers: one high-resolution stream and up to three lower-resolution streams. Use configuration options to define resolution, bitrate, and whether to automatically reduce the number of streams when network or device performance drops. Subscribers can choose which stream to receive based on their network conditions. This feature helps developers deliver smooth experiences in scenarios such as conferences, large classes, and interactive live streaming, even when network conditions are poor.
* **Multipath network transmission**
Introduced multipath transmission for devices with multiple network interfaces (such as 5G, Wi-Fi, and LAN). This feature improves stability in challenging network environments and is suitable for scenarios such as in-vehicle systems, IoT, trains, and highways. Enable it by setting `enableMultipath` in `AgoraRtcChannelMediaOptions` to `YES`.
* *Dynamic mode*: Dynamically selects the optimal path based on network conditions. Suitable for scenarios sensitive to data consumption but requiring high quality, such as meetings and educational settings. Optionally set `preferMultipathType` to prioritize a path type.
* *Duplicate mode*: Sends data simultaneously over all available paths for maximum stability. This mode eliminates the impact of poor network conditions and is suitable for scenarios with extreme quality requirements, such as outdoor broadcasting and parallel control.
Configure uplink and downlink modes separately with `uplinkMultipathMode` and `downlinkMultipathMode`. Monitor performance with the `rtcEngine:didMultipathStatsChanged:` callback, which reports data usage and other statistics for each path.
* **Video quality scoring**
Added the `mosValue` member to `AgoraRtcRemoteVideoStats` to report a score from 1 (poor) to 5 (excellent) for received video quality. This enables real-time monitoring and parameter adjustment. Contact [support@agora.io](mailto\:support@agora.io) to enable this feature.
* **Support for adding multiple watermarks**
Added `addVideoWatermarkWithImageUrl:options:` and `addVideoWatermarkWithImageUrlEx:options:connection:` methods that support multiple watermarks with IDs and layering order. Use `removeVideoWatermark:` to remove a specific watermark.
* **Asynchronous engine destruction**
Added the `destroy:` method with an option for asynchronous destruction, triggering the `engineReleasedBlock` callback.
* **Token renewal result callback**
Added the `rtcEngine:didRenewTokenResult:` callback and `RENEW_TOKEN_ERROR_CODE` for handling the result of `renewToken:`.
* **Advanced beauty (Beta)**
Introduced a brand-new advanced beauty feature, delivering a powerful yet easy-to-use beautification solution.
* **Precision beauty effects**
* *Face shaping*: Supports independent fine-tuning of 29 facial areas (for example, slimming face, enlarging eyes, narrowing nose) or one-click natural effects via presets.
* *Style makeup*: Offers rich effects including eyeshadow, colored contacts, eyeliner, eyebrow shaping, lipstick, blush, under-eye highlights, and facial contouring.
* *Skin enhancement*: Includes professional skin optimizations such as teeth whitening, nasolabial fold removal, dark circle reduction, and eye brightening.
* **Unified and simple API**
Manage all beauty, makeup, and filter functions through three core nodes — `BEAUTY`, `STYLE_MAKEUP`, and `FILTER` — using `IVideoEffectObject` for unified parameter setup and lifecycle control.
* **Ready-to-use presets**
Integrates multiple out-of-the-box style templates (for example, "Natural Beauty," "Senior Makeup," "Cool White Filter") for instant polished results.
* **Dynamic parameter control**
Enables real-time reading and modification of granular parameters (for example, smoothing strength, lipstick type) via key-value pairs, with support for saving custom configurations and resetting defaults.
* **Local resource guarantee**
All beauty resources (effects, filters, makeup) are packaged as local bundle files, ensuring stability and reliability.
* **Other new features**
* Added `setPlaybackAudioFrameBeforeMixingParameters:` to configure the format of raw audio frames returned in `onPlaybackAudioFrameBeforeMixing:channelId:uid:`.
* Added `preloadEffectEx:soundId:` for preloading audio effects in a specific channel, supporting both local and online files.
* Added `playEffectEx:soundId:filePath:loopCount:pitch:pan:gain:publish:startPos:` for playing audio effects in a specific channel with advanced controls.
* Added the `position` member in `AgoraContentInspectModule` to choose the capture point for screenshot uploads.
* Added the `screenColorType` member to `AgoraSegmentationProperty` for specifying or detecting background screen color.
#### Improvements [#improvements-47]
* Added support for G.711 and G.722 audio codecs when inter-operating with the Web SDK for better cross-platform audio compatibility.
* Improved video clarity in screen sharing scenarios involving documents.
#### Issues fixed [#issues-fixed-50]
This version fixes the following issues:
* Online audio effect playback restarted from the beginning when `seekToPosition:` was called.
* Occasional echoes in media volume mode when a broadcaster published a microphone audio stream while playing an audio effect with `playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:` and music with `startAudioMixing:loopback:cycle:startPos:`.
* Missing media metadata observer callback when `setMediaMetadataDelegate:withType:` was called after `setExternalVideoSource:useTexture:sourceType:` (Android, iOS).
* Occasional crashes (Android, iOS).
* Media relay occasionally reported `AgoraChannelMediaRelayStateFailure` and `AgoraChannelMediaRelayErrorServerErrorResponse` after the following sequence: join, relay, unpublish, leave, rejoin, and start relay again.
### v4.5.2 [#v452-1]
v4.5.2 was released on April 22, 2025.
Note
The `aosl.xcframework` library version in Video SDK v4.5.2 is 1.2.13. You can check the version in the `Info.plist` file.
#### Issues fixed [#issues-fixed-51]
This release fixes the following issues:
* While playing a multi-track media file, noise was heard when adjusting the audio pitch using `setAudioPitch`.
* When the host called `createCustomAudioTrack:config:` to create a custom audio track with `trackType` set to `AUDIO_TRACK_DIRECT`, then called `pushExternalAudioFrameRawData:samples:sampleRate:channels:trackId:timestamp:` to push custom audio frames to a channel, and finally called `playEffect:filePath:loopCount:pitch:pan:gain:publish:startPos:` to play an audio effect, audience members in the channel heard noise.
* Apps using the SDK occasionally experienced UI lag caused by main thread blocking during audio and video interactions.
* Calling `openWithMediaSource:` and setting `isLiveSource` to `YES` in the source parameter to play a video stream caused playback failure.
* When calling `enableVirtualBackground` to enable the virtual background, the background image appeared enlarged and blurry when the device was rotated.
* When the sender transmitted multi-channel encoded audio, noise was occasionally heard by the receiver.
* When the app integrated a media player and called `open` twice to load different media resources consecutively, the second call incorrectly triggered the `AgoraRtcMediaPlayer:infoUpdated:` callback with information from the first media resource.
* After enabling user volume indication with `enableAudioVolumeIndication:smooth:reportVad:`, the `rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:` callback reported a local user volume of 0 for both local and remote users.
* The app occasionally froze during audio and video communication.
* When you called `enableVideoImageSource:options:` to enable the video image source feature, the sending side appeared to stream successfully, but the `rtcEngine:didVideoPublishStateChange:sourceType:oldState:newState:elapseSinceLastState:` callback reported a publish failure.
* In multi-channel scenarios, if the app called `setupRemoteVideoEx:connection:` to initialize the remote user's view before successfully calling `joinChannelExByToken:connection:delegate:mediaOptions:joinSuccess:`, the first frame of the remote video occasionally experienced significant delay.
### v4.5.1 [#v451-1]
v4.5.1 was released on March 4, 2025.
Note
The `aosl.xcframework` library version in Video SDK v4.5.1 is 1.2.13. You can check the version in the `Info.plist` file.
#### New Features [#new-features-40]
1. **AI Conversation Scenario**
This version introduces the `AgoraAudioScenarioAiClient` audio scenario, specifically designed for interacting with the conversational AI agent created by [Conversational AI Engine](/en/introduction/conversational-ai). This scenario optimizes the audio transmission algorithm based on the characteristics of AI-generated voices, ensuring stable voice data transmission even in weak network conditions with up to 80% packet loss. The optimization enhances conversation continuity and reliability, adapting to various challenging network environments.
#### Improvements [#improvements-48]
* Reduced SDK initialization time on specific device models.
#### Issues Fixed [#issues-fixed-52]
This release resolves the following issues:
* When joining two or more channels simultaneously and calling `takeSnapshotEx:uid:filePath:` to capture local video stream screenshots consecutively, the first channel's screenshot failed.
* When using the `pause` method to pause playback, then calling `seekToPosition:` to move to a specific position, and finally calling `play`, the Media Player resumed from the paused position instead of the specified position.
* When using the Media Player, the file path of the media resource returned by `getPlaySrc` did not update after calling `switchSrc:syncPts:` to switch to a new media resource.
* Pushing video frames in `i420` format to the channel while using `CVPixelBuffer` to process these frames caused crashes.
* Calling `setupLocalVideo:` to set up two views and then enabling face detection with `enableFaceDetection:` prevented face information from being detected in the newly assigned views.
* In screen-sharing scenarios, the receiving user saw a green line on the shared image.
* In interactive live streaming scenarios, after joining a channel as an audience member using a `string` user ID, audio occasionally became unsynchronized with video.
* AI noise suppression and AI echo cancellation plugins sometimes failed when used together.
### v4.5.0 [#v450-2]
v4.5.0 was released on November 27, 2024.
#### Compatibility changes [#compatibility-changes-25]
This version includes optimizations to some features, including changes to SDK behavior and API renaming and deletion. To ensure normal operation of the project, update the code in the app after upgrading to this release.
Note
As of v4.5.0, both Video SDK and Signaling SDK (v2.2.0 and above) include the `aosl.xcframework` library. If you manually integrate Video SDK via CDN and also use Signaling SDK, delete the earlier version of the `aosl.xcframework` library to avoid conflicts. The `aosl.xcframework` library version in Video SDK v4.5.0 is 1.2.13. You can check the version in the `Info.plist` file.
1. **Changes in strong video noise suppression**
This version adjusts the implementation of strong video noise suppression. The `AgoraVideoDenoiserLevel` removes `AgoraVideoDenoiserLevelStrength`. Instead, after enabling video noise suppression by calling [`setVideoDenoiserOptions:options:`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setvideodenoiseroptions\(_\:options:\)), you can call the [`setBeautyEffectOptions:options:`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setbeautyeffectoptions\(_\:options:\)) method to enable the beauty skin smoothing feature. Using both together will help achieve better video noise suppression effects. For strong noise suppression, it is recommended to set the skin smoothing parameters as detailed in [`setVideoDenoiserOptions:options:`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setvideodenoiseroptions\(_\:options:\)).
Additionally, due to this adjustment, to achieve the best low-light enhancement effect with a focus on image quality, you need to enable video noise suppression first and use specific settings as detailed in [`setLowlightEnhanceOptions:options:`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setlowlightenhanceoptions\(_\:options:\)).
2. **Changes in video encoding preferences**
To enhance the user's video interaction experience, this version optimizes the default preferences for video encoding:
* In the [`AgoraCompressionPreference`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoracompressionpreference) enumeration class, a new `AgoraCompressionAuto` (-1) enumeration is added, replacing the original `AgoraCompressionQuality` (1) as the default value. In this mode, the SDK will automatically choose between `AgoraCompressionLowLatency` or `AgoraCompressionQuality` based on your video scene settings to achieve the best user experience.
* In the [`AgoraDegradationPreference`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoradegradationpreference) enumeration class, a new `AgoraDegradationMaintainAuto` (-1) enumeration is added, replacing the original `AgoraDegradationMaintainQuality` (1) as the default value. In this mode, the SDK will automatically choose between `AgoraDegradationMaintainFramerate`, `AgoraDegradationBalanced`, or `AgoraDegradationMaintainResolution` based on your video scene settings to achieve the optimal overall quality of experience (QoE).
#### New features [#new-features-41]
1. **Live show scenario**
This version adds the `AgoraApplicationLiveShowScenario`(3) (Live Show) enumeration to [`AgoraApplicationScenarioType`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraapplicationscenariotype). You can call `setVideoScenario:` to set the video business scenario to show room. In this scenario, fast video rendering and high image quality are crucial. The SDK implements several performance optimizations, such as enabling accelerated audio and video frame rendering to minimize first-frame latency for better image quality and bandwidth efficiency.
2. **Maximum frame rate for video rendering**
This version adds the `setLocalRenderTargetFps` and `setRemoteRenderTargetFps` methods, which support setting the maximum frame rate for video rendering locally and remotely. The actual frame rate for video rendering by the SDK will be as close to this value as possible.
In use-cases where the frame rate requirement for video rendering is not high (for example, screen sharing, online education) or when the remote end uses mid-to-low-end devices, you can use this set of methods to limit the video rendering frame rate, thereby reducing CPU consumption and improving system performance.
3. **Filter effects**
This version introduces the `setFilterEffectOptions:options:sourceType:` method. You can pass a cube map file (`.cube`) in the `config` parameter to apply custom filter effects such as whitening, vivid, cool, black and white, and others. Additionally, the SDK provides a built-in `built_in_whiten_filter.cube` file to quickly apply a whitening filter effect.
4. **Local audio mixing**
This version introduces the local audio mixing feature. You can call the `startLocalAudioMixer` method to mix the audio streams from the local microphone, media player, sound card, and remote audio streams into a single audio stream, which can then be published to the channel. When you no longer need audio mixing, you can call the `stopLocalAudioMixer` method to stop local audio mixing. During the mixing process, you can call the `updateLocalAudioMixerConfiguration` method to update the configuration of the audio streams being mixed.
Example use cases for this feature include:
* When using the local video mixing feature, the associated audio streams of the mixed video streams can be simultaneously captured and published.
* In live streaming use-cases, users can receive audio streams within the channel, mix multiple audio streams locally, and then forward the mixed audio stream to other channels.
* In educational use-cases, teachers can mix the audio from interactions with students locally and then forward the mixed audio stream to other channels.
5. **Color space settings**
This version adds the `colorSpace` parameter to [`AgoraOutputVideoFrame`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraoutputvideoframe) and [`AgoraVideoFrame`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoravideoframe). You can use this parameter to set the color space properties of the video frame. By default, the color space uses Full Range and BT.709 standard configuration. You can flexibly adjust according to your own capture or rendering needs, further enhancing the customization capabilities of video processing.
#### Improvements [#improvements-49]
1. **Virtual background algorithm optimization**
This version upgrades the virtual background algorithm, making the segmentation between the portrait and the background more accurate. There is no background exposure, the body contour of the portrait is complete, and the detail recognition of fingers is significantly improved. Additionally, the edges between the portrait and the background are more stable, reducing edge jumping and flickering in continuous video frames.
2. **Snapshot at specified video observation points**
This version introduces the `takeSnapshotWithConfig:config:` and `takeSnapshotExWithConfig:uid:config:` methods. You can use the `config` parameter when calling these methods to take snapshots at specified video observation points, such as before encoding, after encoding, or before rendering, to achieve more flexible snapshot effects.
3. **Custom audio capture improvements**
This version adds the `enableAudioProcessing` member parameter to [`AgoraAudioTrackConfig`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraaudiotrackconfig), which is used to control whether to enable 3A audio processing for custom audio capture tracks of the `AUDIO_TRACK_DIRECT` type. The default value of this parameter is `NO`, meaning that audio processing is not enabled. Users can enable it as needed, enhancing the flexibility of custom audio processing.
4. **Other improvements**
* In use-cases where Alpha transparency effects are achieved by stitching video frames and Alpha data, the rendering performance on the receiving end has been improved, effectively reducing stuttering and latency.
* This version optimizes the logic for calling `queryDeviceScore` to obtain device score levels, improving the accuracy of the score results.
* After calling `enableLocalAudio:` to disable local audio capture within the channel, the mute side button on the phone can be used to mute the background sound effects played by the app.
* When calling `switchSrc:syncPts:` to switch between live streams or on-demand streams of different resolutions, smooth and seamless switching can be achieved. An automatic retry mechanism has been added in case of switching failures. The SDK will automatically retry 3 times after a failure. If it still fails, the `AgoraRtcMediaPlayer:didOccurEvent:elapsedTime:message:` callback will report the `AgoraMediaPlayerEventSwitchError` event, indicating that an error has occurred during media resource switching.
* When calling `setPlaybackSpeed:` to set the playback speed of an audio file, the minimum supported speed is 0.3x.
#### Bug fixes [#bug-fixes-3]
This version fixes the following issues:
* When the video source of the sender is in the JPEG format, the frame rate on the receiving end occasionally falls below expectations.
* Occasional instances where the receiving end cannot hear the sender during audio and video interaction.
* During audio and video interaction, if the sender's device system version is iOS 17, the receiving end occasionally cannot hear the sender.
* In live streaming use-cases, the time taken to reconnect to the live room after the audience end disconnects due to network switching is longer than expected.
* No sound when playing online media resources using the media player after the app starts.
* Occasional instances of no sound in audio capture after resuming from being interrupted by other system apps.
* Calling `startAudioMixing:loopback:cycle:` and then immediately calling `pauseAudioMixing` to pause the music file playback does not take effect.
### v4.4.0 [#v440-2]
v4.4.0 was released on August 5, 2024.
#### Compatibility changes [#compatibility-changes-26]
This version includes optimizations to some features, including changes to SDK behavior and API renaming and deletion. To ensure normal operation of the project, update the code in the app after upgrading to this release.
Note
Starting from v4.4.0, the SDK provides an API sunset notice, which includes information about deprecated and removed APIs in each version. See [API sunset notice](/en/api-reference/api-ref/video/api-sunset).
1. To distinguish context information in different extension callbacks, this version removes the original extension callbacks and adds new corresponding callbacks that contain context information (see table below). You can identify the extension name, the user ID, and the service provider name through `AgoraExtensionContext` in each callback.
| Original callback | New callback |
| -------------------- | ------------------------------- |
| `onEvent` | `onExtensionEventWithContext` |
| `onExtensionStarted` | `onExtensionStartedWithContext` |
| `onExtensionStopped` | `onExtensionStoppedWithContext` |
| `onExtensionError` | `onExtensionErrorWithContext` |
2. Prior to v4.4.0, when a user was set to the audience role and `setAudioScenario` was called with `AgoraAudioScenarioChatRoom`, the system displayed the microphone-in-use indicator.
Starting with v4.4.0, the SDK uses native iOS APIs to manage the microphone. As a result, audience users in a chatroom scenario no longer see the indicator.
3. This version renames the `receiveMetadata` callback to `didMetadataReceived` and removes the `data` and `timeStamp` parameters. You can get metadata-related information, including `timeStamp` (timestamp of the sent data), `uid` (user ID), and `channelId` (channel name) through the newly-added `metadata` parameter.
#### New features [#new-features-42]
1. **Lite SDK**
Starting from this version, Agora introduces Lite SDK, which includes only the basic audio and video capabilities and partially cuts advanced features, effectively reducing the app size after integrating the SDK.
* Lite SDK supports manual integration or third-party repository integration.
* For information on dynamic libraries included in the Lite SDK, see [App size optimization](/en/realtime-media/video/build/optimize-and-operate/app-size-optimization).
* For the list of APIs supported by Lite SDK, see [API reference](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit).
* For the limitations and precautions when using the Lite SDK to play media files, refer to [Which audio file formats does the Agora Video SDK support?](/en/api-reference/faq/product/audio_format)
2. **Alpha transparency effects**
This version introduces the Alpha transparency effects feature, supporting the transmission and rendering of Alpha channel data in video frames for SDK capture and custom capture use-cases, enabling transparent gift effects, custom backgrounds on the receiver end, and so on:
* `AgoraOutputVideoFrame` and `AgoraVideoFrame` add the `alphaBuffer` member, which sets the Alpha channel data.
* `AgoraVideoFrame` adds the `fillAlphaBuffer` member. For BGRA or RGBA formatted video data, it sets whether to automatically extract the Alpha channel data and fill it into `alphaBuffer`.
* `AgoraOutputVideoFrame` and `AgoraVideoFrame` add the `alphaStitchMode` member, which sets the relative position of `alphaBuffer` and video frame stitching.
Additionally, `AgoraAdvancedVideoOptions` adds a new member `encodeAlpha`, which is used to set whether to encode and send Alpha information to the remote end. By default, the SDK does not encode and send Alpha information; if you need to encode and send Alpha information to the remote end (for example, when virtual background is enabled), explicitly call `setVideoEncoderConfiguration` to set the video encoding properties and set `encodeAlpha` to `YES`.
3. **Voice AI tuner**
This version introduces the voice AI tuner feature, which can enhance the sound quality and tone, similar to a physical sound card. You can enable the voice AI tuner feature by calling the `enableVoiceAITuner` method and passing in the sound effect types supported in the `AgoraVoiceAITunerType` enum to achieve effects like deep voice, cute voice, husky singing voice, and so on.
#### Improvements [#improvements-50]
1. **Facial region beautification**
To avoid losing details in non-facial areas during heavy skin smoothing, this version improves the skin smoothing algorithm. The SDK now recognizes various parts of the face, applying smoothing to facial skin areas excluding the mouth, eyes, and eyebrows. In addition, the SDK supports smoothing up to two faces simultaneously.
2. **Other improvements**
This version also includes the following improvements:
* Optimizes the transmission strategy: Calling `enableInstantMediaRendering` no longer impacts the security of the transmission link.
* Deprecates redundant enumeration values `AgoraClientRoleChangeFailedRequestTimeout` and `AgoraClientRoleChangeFailedConnectionFailed` in `AgoraClientRoleChangeFailedReason`.
#### Issues fixed [#issues-fixed-53]
This release fixes the following issues:
* Occasional app crashes occurred when multiple remote users joined a channel simultaneously during real-time interaction.
* Remote video occasionally froze or displayed corrupted images when the app returned to the foreground after being in the background for a while.
* After the sender called `startDirectCdnStreaming` to start direct CDN streaming, frequent switching or toggling of the network occasionally resulted in a black screen on the receiver's end without a streaming failure callback on the sender's end.
* Audio playback failed when pushing external audio data using `pushExternalAudioFrameRawData` and the sample rate was not set as a recommended value, such as 22050 Hz and 11025 Hz.
### v4.3.2 [#v432-1]
v4.3.2 was released on June 4, 2024.
#### Improvements [#improvements-51]
1. This release enhances the usability of the [setRemoteSubscribeFallbackOption](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setremotesubscribefallbackoption\(_:\)) method by removing the timing requirements for invocation. It can now be called both before and after joining the channel to dynamically switch audio and video stream fallback options in weak network conditions.
2. The Agora media player supports playing mp4 files with an Alpha channel.
#### Issues fixed [#issues-fixed-54]
This version fixed the following issues:
* The remote video froze or became pixelated when the app returned to the foreground after being in the background for a long time.
* The local preview image rotated by 90° on some iPad devices, which did not meet expectations.
* Occasional video smoothness issues during audio and video interactions.
* The app occasionally crashed when the decoded video resolution on the receiving end was an odd number.
* The app occasionally crashed when remote users left the channel.
* When playing an audio file using \[startAudioMixing [1/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/startaudiomixing\(_\:loopback\:cycle:\)) and the playing finished, the SDK sometimes failed to trigger the [audioMixingStateChanged](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginedelegate/rtcengine\(_\:audiomixingstatechanged\:reasoncode:\)) (`AgoraAudioMixingStateTypeStopped`, `AgoraAudioMixingReasonAllLoopsCompleted`) callback which reports that the playing is completed.
* When calling the \[playEffect [3/3\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/playeffect\(_\:filepath\:loopcount\:pitch\:pan\:gain\:publish\:startpos:\)) method to play sound effect files shorter than 1 second with `loopCount` set to `0`, there was no sound.
* When using the Agora media player to play a video and stopping it during playing, sometimes there was no sound for a short time after the playback was resumed.
### v4.3.1 [#v431-1]
v4.3.1 was released on April 29, 2024.
#### New features [#new-features-43]
1. **Privacy manifest file**
To meet Apple's safety compliance requirements for app publication, the SDK now includes a privacy manifest file, `PrivacyInfo.xcprivacy`, detailing the SDK's API calls that access or use user data, along with a description of the types of data collected.
Note
If you need to publish an app with SDK versions prior to v4.3.1 to the Apple App Store, manually add the `PrivacyInfo.xcprivacy` file to your Xcode project. For more details, see [How can I add a privacy manifest to my iOS app?](/en/api-reference/faq/other/ios_privacy_manifest)
\:::
1. **Portrait center stage**
To enhance the presentation effect in online meetings, shows, and online education use-cases, this version introduces the [enableCameraCenterStage](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enablecameracenterstage\(_:\)) method to activate the Portrait center stage. This ensures that presenters, regardless of movement, always remain centered in the video frame, achieving better presentation effects.
Before enabling portrait center stage, it is recommended to verify whether your current device supports this feature by calling [isCameraCenterStageSupported](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/iscameracenterstagesupported\(\)). A list of supported devices can be found in the API documentation at [enableCameraCenterStage](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enablecameracenterstage\(_:\)).
2. **Camera stabilization**
To improve video stability in mobile filming, low-light environments, and hand-held shooting use-cases, this version introduces a camera stabilization feature. You can activate this feature and select an appropriate stabilization mode by calling [setCameraStabilizationMode](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setcamerastabilizationmode\(_:\)), achieving more stable and clearer video footage.
3. **Wide and ultra-wide cameras**
To allow users to capture a broader field of view and more complete scene content, this release introduces support for wide and ultra-wide cameras. You can first call [queryCameraFocalLengthCapability](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/querycamerafocallengthcapability\(\)) to check the device's focal length capabilities, and then call [setCameraCapturerConfiguration](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setcameracapturerconfiguration\(_:\)) and set `cameraFocalLengthType` to the supported focal length types, including wide and ultra-wide.
4. **Data stream encryption**
This version adds `datastreamEncryptionEnabled` to [AgoraEncryptionConfig](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraencryptionconfig) for enabling data stream encryption. You can set this when you activate encryption with [enableEncryption](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enableencryption\(_\:encryptionconfig:\)). If there are issues causing failures in data stream encryption or decryption, these can be identified by the newly added `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE` and `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE` enumerations.
5. **Local video rendering**
This version adds the following member to [AgoraRtcVideoCanvas](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcvideocanvas) to support more local rendering capabilities:
* `enableAlphaMask`: This member enables the receiving end to initiate Alpha mask rendering. Alpha mask rendering can create images with transparent effects or extract human figures from video content.
6. **Adaptive configuration for low-quality video streams**
This version introduces adaptive configuration for low-quality video streams. When you activate the dual-stream mode and set up low-quality video streams on the sending side using [setDualStreamMode \[2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setdualstreammode\(_\:streamconfig:\)), the SDK defaults to the following behaviors:
* The default encoding resolution for low-quality video streams is set to 50% of the original video encoding resolution.
* The bitrate for the small streams is automatically matched based on the video resolution and frame rate, eliminating the need for manual specification.
7. **Other features**
* A new method [enableEncryptionEx](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enableencryptionex\(_\:encryptionconfig\:connection:\)) is added for enabling media stream or data stream encryption in multi-channel use-cases.
* A new method [setAudioMixingPlaybackSpeed](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setaudiomixingplaybackspeed\(_:\)) is introduced for setting the playback speed of audio files.
* A new method [getCallIdEx](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/getcallidex\(_:\)) is introduced for retrieving call IDs in multi-channel use-cases.
8. **Beta features**
* Speech driven avatar is released in beta. See [beta documentation](/en/realtime-media/video/reference/release-notes) for details.
#### Improvements [#improvements-52]
1. **Virtual background algorithm optimization**
To enhance the accuracy and stability of human segmentation when activating virtual backgrounds against solid colors, this version optimizes the green screen segmentation algorithm:
* Supports recognition of any solid color background, no longer limited to green screens.
* Improves accuracy in recognizing background colors and reduces the background exposure during human segmentation.
* After segmentation, the edges of the human figure, especially around the fingers, are more stable, significantly reducing flickering at the edges.
2. **Custom audio capture optimization**
To enhance the flexibility of custom audio capture, this release deprecates [pushExternalAudioFrameSampleBuffer \[1/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/pushexternalaudioframesamplebuffer\(_:\)) and introduces [pushExternalAudioFrameSampleBuffer \[2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/pushexternalaudioframesamplebuffer\(_\:samplerate\:channels\:trackid:\)). Compared to the deprecated method, the new method adds parameters such as `sampleRate`, `channels`, and `trackId`. These support pushing external CMSampleBuffer audio data to the channel via custom audio tracks, and allow for the setting of sample rates and channel counts for external audio sources.
3. **CPU consumption reduction of in-ear monitoring**
This release adds an enumerator `AgoraEarMonitoringFilterReusePostProcessingFilter` in `AgoraEarMonitoringFilterType`. For complex audio processing use-cases, you can specify this option to reuse the audio filter after sender-side processing in in-ear monitoring, thereby reducing CPU consumption. Note that this option may increase the latency of in-ear monitoring, which is suitable for latency-tolerant use-cases requiring low CPU consumption.
4. **Other improvements**
This version also includes the following improvements:
* Optimization of video encoding and decoding strategies in non-screen-sharing use-cases to save system performance overhead.
* Improved stability in processing video by the raw video frame observer.
* Enhanced media player capabilities to handle WebM format videos, including support for rendering Alpha channels.
* In [AgoraAudioEffectPreset](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraaudioeffectpreset), a new enumeration `AgoraAudioEffectPresetRoomAcousticsChorus` (chorus effect) is added, enhancing the spatial presence of vocals in chorus use-cases.
* In [AgoraRtcRemoteAudioStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcremoteaudiostats), a new `e2eDelay` field is added to report the delay from when the audio is captured on the sending end to when the audio is played on the receiving end.
#### Issues fixed [#issues-fixed-55]
This version fixed the following issue:
* Fixed an issue where SEI data output did not synchronize with video rendering when playing media streams containing SEI data using the media player.
* When the network conditions of the sender deteriorated (for example, in poor network environments), the receiver occasionally experienced a decrease in video smoothness and an increase in lag.
#### API changes [#api-changes-30]
**Added**
* [enableCameraCenterStage](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enablecameracenterstage\(_:\))
* [isCameraCenterStageSupported](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/iscameracenterstagesupported\(\))
* [setCameraStabilizationMode](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setcamerastabilizationmode\(_:\))
* [AgoraCameraStabilizationMode](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoracamerastabilizationmode)
* The `enableAlphaMask` member in [AgoraRtcVideoCanvas](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcvideocanvas)
* [setFaceInfoDelegate](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setfaceinfodelegate\(_:\))
* [AgoraFaceInfoDelegate](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorafaceinfodelegate)
* [onFaceInfo](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorafaceinfodelegate/onfaceinfo\(_:\))
* The `publishLipSyncTrack` member in [AgoraRtcChannelMediaOptions](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcchannelmediaoptions)
* [AgoraMediaSourceType](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoramediasourcetype) adds `AgoraMediaSourceTypeSpeechDriven`
* [AgoraVideoSourceType](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoravideosourcetype) adds `AgoraVideoSourceTypeSpeechDriven`
* [AgoraEncryptionConfig](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraencryptionconfig) adds `datastreamEncryptionEnabled`
* [AgoraEncryptionErrorType](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraencryptionerrortype) adds the following enumerations:
* `ENCRYPTION_ERROR_DATASTREAM_DECRYPTION_FAILURE`
* `ENCRYPTION_ERROR_DATASTREAM_ENCRYPTION_FAILURE`
* [AgoraRtcRemoteAudioStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcremoteaudiostats) adds `e2eDelay`
* [AgoraErrorCode](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraerrorcode) adds `AgoraErrorCodeDatastreamDecryptionFailed`
* [AgoraAudioEffectPreset](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraaudioeffectpreset) adds `AgoraAudioEffectPresetRoomAcousticsChorus`, enhancing the spatial presence of vocals in chorus use-cases
* [getCallIdEx](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/getcallidex\(_:\))
* [enableEncryptionEx](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enableencryptionex\(_\:encryptionconfig\:connection:\))
* [setAudioMixingPlaybackSpeed](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setaudiomixingplaybackspeed\(_:\))
* [queryCameraFocalLengthCapability](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/querycamerafocallengthcapability\(\))
* [AgoraFocalLengthInfo](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorafocallengthinfo)
* [AgoraFocalLength](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorafocallength)
* [AgoraCameraCapturerConfiguration](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoracameracapturerconfiguration) adds a new member `cameraFocalLengthType`
* [AgoraEarMonitoringFilterType](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraearmonitoringfiltertype) adds a new enumeration `AgoraEarMonitoringFilterBuiltInAudioFilters`
* [pushExternalAudioFrameSampleBuffer \[2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/pushexternalaudioframesamplebuffer\(_\:samplerate\:channels\:trackid:\))
**Deprecated**
* [pushExternalAudioFrameSampleBuffer \[1/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/pushexternalaudioframesamplebuffer\(_:\))
### v4.3.0 [#v430-2]
v4.3.0 was released on February 22, 2024.
#### Compatibility changes [#compatibility-changes-27]
This release has optimized the implementation of some functions, involving renaming or deletion of some APIs. To ensure the normal operation of the project, you need to update the code in the app after upgrading to this release.
1. **Renaming parameters in callbacks**
In order to make the parameters in some callbacks and the naming of enumerations in enumeration classes easier to understand, the following modifications have been made in this release. Please modify the parameter settings in the callbacks after upgrading to this release.
| Callback | Original parameter name | New parameter name |
| ---------------------------------- | ----------------------- | ------------------ |
| `localAudioStateChanged` | `error` | `reason` |
| `localVideoStateChanged` | `error` | `reason` |
| `onDirectCdnStreamingStateChanged` | `error` | `reason` |
| `didChangedToState` | `error` | `reason` |
| `rtmpStreamingChangedToState` | `errCode` | `reason` |
| Original enumeration class | New enumeration class |
| ------------------------------ | ------------------------------- |
| `AgoraAudioLocalError` | `AgoraAudioLocalReason` |
| `AgoraLocalVideoStreamError` | `AgoraLocalVideoStreamReason` |
| `AgoraDirectCdnStreamingError` | `AgoraDirectCdnStreamingReason` |
| `AgoraMediaPlayerError` | `AgoraMediaPlayerReason` |
| `AgoraRtmpStreamingError` | `AgoraRtmpStreamingReason` |
**Note:** For specific renaming of enumerations, please refer to [API changes](#api-changes).
2. **Channel media relay**
To improve interface usability, this release removes some methods and callbacks for channel media relay. Use the alternative options listed in the table below:
| Deleted methods and callbacks | Alternative methods and callbacks |
| ---------------------------------------------------------- | ---------------------------------- |
| * `startChannelMediaRelay`
* `updateChannelMediaRelay` | `startOrUpdateChannelMediaRelay` |
| - `startChannelMediaRelayEx`
- `updateChannelMediaRelayEx` | `startOrUpdateChannelMediaRelayEx` |
| `didReceiveChannelMediaRelayEvent` | `channelMediaRelayStateDidChange` |
3. **Custom video source**
Since this release, `pushExternalVideoFrame`\[1/2] is migrated from `AgoraRtcEngineKit(Ex)` to `AgoraRtcEngineKit`.
4. **Audio route**
Starting with this release, `AgoraAudioOutputRoutingBluetooth` in [AgoraAudioOutputRouting](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraaudiooutputrouting) is renamed to `AgoraAudioOutputRoutingBluetoothDeviceHfp`, representing a Bluetooth device using the HFP protocol. `AgoraAudioOutputRoutingBluetoothDeviceA2dp`(10) is added to represent the audio route to a Bluetooth device using the A2DP protocol.
5. **Reasons for local video state changes**
This release makes the following modifications to the enumerations in the [AgoraLocalVideoStreamReason](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoralocalvideostreamreason) class:
* The `AgoraLocalVideoStreamErrorEncodeFailure` enumeration has been changed to `AgoraLocalVideoStreamReasonCodecNotSupport`.
6. **Log encryption behavior changes**
For security and performance reasons, as of this release, the SDK encrypts logs and no longer supports printing plaintext logs via the console.
Refer to the following solutions for different needs:
* If you need to know the API call status, please check the API logs and print the SDK callback logs yourself.
* For any other special requirements, please contact [technical support](mailto\:support@agora.io) and provide the corresponding encrypted logs.
#### New features [#new-features-44]
1. **Custom mixed video layout on the receiving end**
To facilitate customized layout of mixed video stream at the receiver end, this release introduces the [`didTranscodedStreamLayoutInfoUpdatedWithUserId`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginedelegate/rtcengine\(_\:didtranscodedstreamlayoutinfoupdatedwithuserid\:videolayoutinfo:\)) callback. When the receiver receives the channel's mixed video stream sent by the video mixing server, this callback is triggered, reporting the layout information of the mixed video stream and the layout information of each sub-video stream in the mixed stream. The receiver can set a separate `view` for rendering the sub-video stream (distinguished by `subviewUid`) in the mixed video stream when calling the [setupRemoteVideo](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setupremotevideo\(_:\)) method, achieving a custom video layout effect.
When the layout of the sub-video streams in the mixed video stream changes, this callback will also be triggered to report the latest layout information in real time.
Through this feature, the receiver end can flexibly adjust the local view layout. When applied in a multi-person video use-case, the receiving end only needs to receive and decode a mixed video stream, which can effectively reduce the CPU usage and network bandwidth when decoding multiple video streams on the receiving end.
2. **Local preview with multiple views**
This release supports local preview with simultaneous display of multiple frames, where the videos shown in the frames are positioned at different observation positions along the video link. Examples of usage are as follows:
1. Call [setupLocalVideo](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setuplocalvideo\(_:\)) to set the first view: Set the `position` parameter to `AgoraVideoModulePositionPostCaptureOrigin` (introduced in this release) in `AgoraRtcVideoCanvas`. This corresponds to the position after local video capture and before preprocessing. The video observed here does not have preprocessing effects.
2. Call [setupLocalVideo](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setuplocalvideo\(_:\)) to set the second view: Set the `position` parameter to `AgoraVideoModulePositionPostCapture` in `AgoraRtcVideoCanvas`, the video observed here has the effect of video preprocessing.
3. Observe the local preview effect: The first view is the original video of a real person; the second view is the virtual portrait after video preprocessing (including image enhancement, virtual background, and local preview of watermarks) effects.
3. **Query Device Score**
This release adds the [queryDeviceScore](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/querydevicescore\(\)) method to query the device's score level to ensure that the user-set parameters do not exceed the device's capabilities. For example, in HD or UHD video use-cases, you can first call this method to query the device's score. If the returned score is low (for example, below 60), you need to lower the video resolution to avoid affecting the video experience. The minimum device score required for different business use-cases is varied. For specific score recommendations, please contact [technical support](mailto\:support@agora.io).
4. **Select different audio tracks for local playback and streaming**
This release introduces the [selectMultiAudioTrack](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcmediaplayerprotocol/selectmultiaudiotrack\(_\:publishtrackindex:\)) method that allows you to select different audio tracks for local playback and streaming to remote users. For example, in use-cases like online karaoke, the host can choose to play the original sound locally and publish the accompaniment in the channel. Before using this function, you need to open the media file through the `openWithMediaSource` method and enable this function by setting the `enableMultiAudioTrack` parameter in [AgoraMediaSource](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoramediasource).
5. **Device test for audio capturing and playback**
This release introduces the following methods to test whether the audio capturing or playback devices work properly before joining a channel:
* [startRecordingDeviceTest](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/startrecordingdevicetest\(_:\)): Tests whether the local audio capturing device, such as the speaker, is working properly. After calling this method, the SDK triggers a callback at the time interval set in this method, which reports uid = 0 and the volume information of the capturing device. After the test is completed, you need to call the newly added [stopRecordingDeviceTest](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/stoprecordingdevicetest\(\)) method to stop the test.
* [startPlaybackDeviceTest](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/startplaybackdevicetest\(_:\)): Tests whether the local audio playback device is working properly. You can specify the audio file to be played through the `testAudioFilePath` parameter and see if your audio device works properly. After the test is completed, you need to call the newly added [stopPlaybackDeviceTest](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/stopplaybackdevicetest\(\)) method to stop the test.
6. **Others**
This release has passed the test verification of the following APIs and can be applied to the entire series of the SDK v4.x.
* [setRemoteSubscribeFallbackOption](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setremotesubscribefallbackoption\(_:\)): Sets fallback option for the subscribed video stream in weak network conditions.
* [didRemoteSubscribeFallbackToAudioOnly](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginedelegate/rtcengine\(_\:didremotesubscribefallbacktoaudioonly\:byuid:\)): Occurs when the subscribed video stream falls back to audio-only stream due to weak network conditions or switches back to the video stream after the network conditions improve.
* \[setPlayerOption [1/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcmediaplayerprotocol/setplayeroption\(_\:value:\)) and \[setPlayerOption [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcmediaplayerprotocol/setplayeroptionstring\(_\:value:\)): Sets media player options for providing technical previews or special customization features.
* [enableCustomAudioLocalPlayback](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enablecustomaudiolocalplayback\(_\:enabled:\)): Sets whether to enable the local playback of external audio source.
#### Improvements [#improvements-53]
1. **SDK task processing scheduling optimization**
This release optimizes the scheduling mechanism for internal tasks within the SDK, with improvements in the following aspects:
* The speed of video rendering and audio playback for both remote and local first frames improves by 10% to 20%.
* The API call duration and response time are reduced by 5% to 50%.
* The SDK's parallel processing capability significantly improves, delivering higher video quality (720P, 24 fps) even on lower-end devices. Additionally, image processing remains more stable in use-cases involving high resolutions and frame rates.
* The stability of the SDK is further enhanced, leading to a noticeable decrease in the crash rate across various specific use-cases.
2. **In-ear monitoring volume boost**
This release provides users with more flexible in-ear monitoring audio adjustment options, supporting the ability to set the in-ear monitoring volume to four times the original volume by calling [setInEarMonitoringVolume](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setinearmonitoringvolume\(_:\)).
3. **Spatial audio effects usability improvement**
* This release optimizes the design of the [setZones](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraspatialaudiokitbase/setzones\(_:\)) method, supporting the ability to set the `zones` parameter to `NULL`, indicating the clearing of all echo cancellation zones.
* As of this release, it is no longer necessary to unsubscribe from the audio streams of all remote users within the channel before calling methods in [AgoraLocalSpatialAudioKit](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoralocalspatialaudiokit).
* This release introduces the [updateSelfTransform](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraspatialaudiokitbase/updateselftransform\(_:\)) method, designed to pass position vectors for direct rendering in iOS native frameworks such as SceneKit or RealityKit.
4. **Local audio state changed callback optimization**
This release introduces the following enumeration in [AgoraAudioLocalReason](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraaudiolocalreason), enabling users to obtain more details about local audio errors through the `localAudioStateChanged` callback:
* `AgoraAudioLocalReasonInterrupted`: The local audio capture is interrupted by system calls, Siri, or alarm clocks. Remind your users to end the phone call, Siri, or alarm clock if the local audio capture is required.
5. **Optimization of video pre-processing methods**
This release adds overloaded methods with the `sourceType` parameter for the following 5 video preprocessing methods, which support specifying the media source type for applying video preprocessing effects by passing in `sourceType` (for example, applying on a custom video capture media source):
* \[setBeautyEffectOptions [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setbeautyeffectoptions\(_\:options\:sourcetype:\))
* \[setLowlightEnhanceOptions [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setlowlightenhanceoptions\(_\:options\:sourcetype:\))
* \[setVideoDenoiserOptions [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setvideodenoiseroptions\(_\:options\:sourcetype:\))
* \[setColorEnhanceOptions [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setcolorenhanceoptions\(_\:options\:sourcetype:\))
* \[enableVirtualBackground [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enablevirtualbackground\(_\:backdata\:segdata\:sourcetype:\))
6. **Other Improvements**
This release also includes the following improvements:
* This release optimizes the SDK's domain name resolution strategy, improving the stability of calling to resolve domain names in complex network environments.
* When passing in an image with transparent background as the virtual background image, the transparent background can be filled with customized color.
* This release adds the `earMonitorDelay` and `aecEstimatedDelay` members in [AgoraRtcLocalAudioStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartclocalaudiostats) to report ear monitor delay and acoustic echo cancellation (AEC) delay, respectively.
* The [cacheStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcmediaplayerdelegate/agorartcmediaplayer\(_\:cachestats:\)) callback is added to report the statistics of the media file being cached. This callback is triggered once per second after file caching is started.
* The [playbackStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcmediaplayerdelegate/agorartcmediaplayer\(_\:playbackstats:\)) callback is added to report the statistics of the media file being played. This callback is triggered once per second after the media file starts playing. You can obtain information like the audio and video bitrate of the media file through `AgoraMediaPlayerPlaybackStats`.
#### Issues fixed [#issues-fixed-56]
This release fixed the following issues:
* When sharing two screen sharing video streams simultaneously, the reported `captureFrameRate` in the [localVideoStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginedelegate/rtcengine\(_\:localvideostats\:sourcetype:\)) callback is 0, which is not as expected.
#### API changes [#api-changes-31]
**Added**
* [`didTranscodedStreamLayoutInfoUpdatedWithUserId`](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginedelegate/rtcengine\(_\:didtranscodedstreamlayoutinfoupdatedwithuserid\:videolayoutinfo:\))
* [AgoraVideoLayoutInfo](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoravideolayoutinfo)
* The `subviewUid` member in [AgoraRtcVideoCanvas](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcvideocanvas)
* [updateSelfTransform](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraspatialaudiokitbase/updateselftransform\(_:\))
* The `AgoraAudioLocalReasonInterrupted` enumeration in [AgoraAudioLocalReason](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraaudiolocalreason)
* [enableCustomAudioLocalPlayback](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enablecustomaudiolocalplayback\(_\:enabled:\))
* [queryDeviceScore](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/querydevicescore\(\))
* The `AgoraMediaSourceTypeCustomVideo` enumeration in [AgoraMediaSourceType](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoramediasourcetype)
* \[setBeautyEffectOptions [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setbeautyeffectoptions\(_\:options\:sourcetype:\))
* \[setLowlightEnhanceOptions [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setlowlightenhanceoptions\(_\:options\:sourcetype:\))
* \[setVideoDenoiserOptions [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setvideodenoiseroptions\(_\:options\:sourcetype:\))
* \[setColorEnhanceOptions [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/setcolorenhanceoptions\(_\:options\:sourcetype:\))
* \[enableVirtualBackground [2/2\]](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/enablevirtualbackground\(_\:backdata\:segdata\:sourcetype:\))
* The `AgoraAudioOutputRoutingBluetoothDeviceA2dp` enumeration in [AgoraAudioOutputRouting](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoraaudiooutputrouting)
* Adds the `earMonitorDelay` and `aecEstimatedDelay` in [AgoraRtcLocalAudioStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartclocalaudiostats)
* [selectMultiAudioTrack](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcmediaplayerprotocol/selectmultiaudiotrack\(_\:publishtrackindex:\))
* [cacheStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcmediaplayerdelegate/agorartcmediaplayer\(_\:cachestats:\))
* [playbackStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcmediaplayerdelegate/agorartcmediaplayer\(_\:playbackstats:\))
* [AgoraMediaPlayerPlaybackStats](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agoramediaplayerplaybackstats)
* [startPlaybackDeviceTest](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/startplaybackdevicetest\(_:\))
* [stopPlaybackDeviceTest](https://api-ref.agora.io/en/video-sdk/ios/4.x/documentation/agorartckit/agorartckit/agorartcenginekit/stopplaybackdevicetest\(\))
**Modified**
* `pushExternalVideoFrame`\[1/2] is migrated from `AgoraRtcEngineKit(Ex)` to `AgoraRtcEngineKit`
* `AgoraAudioOutputRoutingBluetooth` is renamed as `AgoraAudioOutputRoutingBluetoothDeviceHfp`
* All `Error` fields in the following enumerations are changed to `Reason`:
* `AgoraAudioLocalErrorOK`
* `AgoraAudioLocalErrorFailure`
* `AgoraAudioLocalErrorDeviceNoPermission`
* `AgoraAudioLocalErrorDeviceBusy`
* `AgoraAudioLocalErrorRecordFailure`
* `AgoraAudioLocalErrorEncodeFailure`
* `AgoraLocalVideoStreamErrorOK`
* `AgoraLocalVideoStreamErrorFailure`
* `AgoraLocalVideoStreamErrorDeviceNoPermission`
* `AgoraLocalVideoStreamErrorDeviceBusy`
* `AgoraLocalVideoStreamErrorCaptureFailure`
* `AgoraLocalVideoStreamErrorCodecNotSupport`
* `AgoraLocalVideoStreamErrorCaptureInBackGround`
* `AgoraLocalVideoStreamErrorCaptureMultipleForegroundApps`
* `AgoraLocalVideoStreamErrorCaptureNoDeviceFound`
* `AgoraLocalVideoStreamErrorCaptureDeviceDisconnected`
* `AgoraLocalVideoStreamErrorCaptureDeviceInvalidId`
* `AgoraDirectCdnStreamingErrorOK`
* `AgoraDirectCdnStreamingErrorFailed`
* `AgoraDirectCdnStreamingErrorAudioPublication`
* `AgoraDirectCdnStreamingErrorVideoPublication`
* `AgoraDirectCdnStreamingErrorNetConnect`
* `AgoraDirectCdnStreamingErrorBadName`
* `AgoraMediaPlayerErrorNone`
* `AgoraMediaPlayerErrorInvalidArguments`
* `AgoraMediaPlayerErrorInternal`
* `AgoraMediaPlayerErrorNoSource`
* `AgoraMediaPlayerErrorInvalidMediaSource`
* `AgoraMediaPlayerErrorUnknowStreamType`
* `AgoraMediaPlayerErrorObjNotInitialized`
* `AgoraMediaPlayerErrorCodecNotSupported`
* `AgoraMediaPlayerErrorVideoRenderFailed`
* `AgoraMediaPlayerErrorInvalidState`
* `AgoraMediaPlayerErrorUrlNotFound`
* `AgoraMediaPlayerErrorInvalidConnectState`
* `AgoraMediaPlayerErrorSrcBufferUnderflow`
* `AgoraMediaPlayerErrorInterrupted`
* `AgoraMediaPlayerErrorNotSupported`
* `AgoraMediaPlayerErrorTokenExpired`
* `AgoraMediaPlayerErrorUnknown`
* `AgoraRtmpStreamingErrorOK`
* `AgoraRtmpStreamingErrorInvalidParameters`
* `AgoraRtmpStreamingErrorEncryptedStreamNotAllowed`
* `AgoraRtmpStreamingErrorConnectionTimeout`
* `AgoraRtmpStreamingErrorInternalServerError`
* `AgoraRtmpStreamingErrorRtmpServerError`
* `AgoraRtmpStreamingErrorTooOften`
* `AgoraRtmpStreamingErrorReachLimit`
* `AgoraRtmpStreamingErrorNotAuthorized`
* `AgoraRtmpStreamingErrorStreamNotFound`
* `AgoraRtmpStreamingErrorFormatNotSupported`
* `AgoraRtmpStreamingErrorNotBroadcaster`
* `AgoraRtmpStreamingErrorTranscodingNoMixStream`
* `AgoraRtmpStreamingErrorNetDown`
* `AgoraRtmpStreamingErrorInvalidPrivilege`
* `AgoraRtmpStreamingErrorUnpublishOK`
**Deleted**
* `startChannelMediaRelay`
* `updateChannelMediaRelay`
* `startChannelMediaRelayEx`
* `updateChannelMediaRelayEx`
* `didReceiveChannelMediaRelayEvent`
* `AgoraChannelMediaRelayEvent`
### v4.2.6 [#v426-1]
v4.2.6 was released on November 17, 2023.
#### Issues fixed [#issues-fixed-57]
This release fixed the following issues:
* When using an iOS 16 or later device with Bluetooth headphones connected before joining the channel, the audio routing after joining the channel was not as expected: Audio was played from the speaker, not the Bluetooth headphones.
* In specific use-cases, such as when the network packet loss rate was high or when the broadcaster left the channel without destroying the engine and then re-joined the channel, the video on the receiving end stuttered or froze.
### v4.2.3 [#v423-1]
v4.2.3 was released on October 11, 2023.
#### New features [#new-features-45]
1. **Update video screenshot and upload**
To facilitate the integration of third-party video moderation services from Agora Extensions Marketplace, this version has the following changes:
* The `AgoraContentInspectTypeImageModeration` enumeration is added in `AgoraContentInspectType` which means using video moderation extensions from Agora Extensions Marketplace to take video screenshots and upload them.
* An optional parameter `serverConfig` is added in `AgoraContentInspectConfig`, which is for server-side configuration related to video screenshot and upload via extensions from Agora Extensions Marketplace. By configuring this parameter, you can integrate multiple third-party moderation extensions and achieve flexible control over extension switches and other features. For more details, please contact [technical support](mailto\:support@agora.io).
In addition, this version also introduces the `enableContentInspectEx` method, which supports taking screenshots for multiple video streams and uploading them.
2. **Check device support for advanced features**
This version adds the `isFeatureAvailableOnDevice` method to check whether the capability of the current device meets the requirements of the specified advanced feature, such as virtual background and image enhancement.
Before using advanced features, you can check whether the current device supports these features based on the call result. This helps to avoid performance degradation or unavailable features when enabling advanced features on low-end devices. Based on the return value of this method, you can decide whether to display or enable the corresponding feature button, or notify the user when the device's capabilities are insufficient.
In addition, since this version, calling `enableVirtualBackground` and `setBeautyEffectOptions` automatically triggers a test on the capability of the current device. When the device is considered underperformed, the error code -4 is returned, indicating the device does not support the feature.
#### Improvements [#improvements-54]
1. **Optimize virtual background memory usage**
This version has upgraded the virtual background algorithm, reducing the memory usage of the virtual background feature. Compared to the previous version, the memory consumption of the app during the use of the virtual background feature on low-end devices has been reduced by approximately 4% to 10% (specific values may vary depending on the device model and platform).
**Other improvements**
This release includes the following additional improvements:
* Optimizes the logic of handling invalid parameters. When you call the `setPlaybackSpeed` method to set the playback speed of audio files, if you pass an invalid parameter, the SDK returns the error code -2, which means that you need to reset the parameter.
* Optimizes the logic of Token parsing, in order to prevent an app from crash when an invalid token is passed in.
#### Issues fixed [#issues-fixed-58]
This release fixed the following issues:
* Occasional failure of joining a channel when the local system time was not set correctly.
* When calling the `playEffect [3/3]` method to play two audio files using the same `soundId`, the first audio file was sometimes played repeatedly.
* Calling `takeSnapshotEx` once receives the `snapshotTaken` callback for multiple times.
#### API changes [#api-changes-32]
**Added**
* `enableContentInspectEx`
* `AgoraContentInspectTypeImageModeration` in `AgoraContentInspectType`.
* `serverConfig` in `AgoraContentInspectConfig`
* `isFeatureAvailableOnDevice`
* `AgoraFeatureType`
### v4.2.2 [#v422-1]
v4.2.2 was released on July 27, 2023.
#### New features [#new-features-46]
1. **Wildcard token**
This release introduces wildcard tokens. Agora supports setting the channel name used for generating a token as a wildcard character. The token generated can be used to join any channel if you use the same user id. In use-cases involving multiple channels, such as switching between different channels, using a wildcard token can avoid repeated application of tokens every time users joining a new channel, which reduces the pressure on your token server. See [Secure authentication with tokens](/en/realtime-media/video/build/authenticate-users/deploy-token-server#generate-wildcard-tokens).
All 4.x SDKs support using wildcard tokens.
2. **Preloading channels**
This release adds `preloadChannelByToken [1/2]` and `preloadChannelByToken [2/2]` methods, which allows a user whose role is set as audience to preload channels before joining one. Calling the method can help shortening the time of joining a channel, thus reducing the time it takes for audience members to hear and see the host.
When preloading more than one channels, Agora recommends that you use a wildcard token for preloading to avoid repeated application of tokens every time you joining a new channel, thus saving the time for switching between channels. See [Secure authentication with tokens](/en/realtime-media/video/build/authenticate-users/deploy-token-server#generate-wildcard-tokens).
3. **Customized background color of video canvas**
In this release, the `backgroundColor` member has been added to `AgoraRtcVideoCanvas`, which allows you to customize the background color of the video canvas when setting the properties of local or remote video display.
4. **Video source types for local preview**
To allow users in selecting different types of video sources for local video preview, this release introduces `startPreview [2/2]` and `stopPreview [2/2]`. You can call `startPreview [2/2]` and specify the type of video source to be previewed by setting the `sourceType` parameter, and call `stopPreview [2/2]` to stop the video preview.
The video source type specified in this method must match the video source type set in the `AgoraRtcVideoCanvas` of the `setupLocalVideo` method.
#### Improvements [#improvements-55]
1. **Improved camera capture effect**
This release has improved camera capture effect in the following aspects:
1. Support for camera exposure adjustment
This release adds `isCameraExposureSupported` to query whether the device supports exposure adjustment and `setCameraExposureFactor` to set the exposure ratio of the camera.
2. Optimization of default camera selection
Since this release, the default camera selection behavior of the SDK is aligned with that of the iOS system camera. If the device has multiple rear cameras, better shooting perspectives, zooming capabilities, low-light performance, and depth sensing can be achieved during video capture, thereby improving the quality of video capture.
2. **Virtual Background Algorithm Upgrade**
This version has upgraded the portrait segmentation algorithm of the virtual background, which comprehensively improves the accuracy of portrait segmentation, the smoothness of the portrait edge with the virtual background, and the fit of the edge when the person moves. In addition, it optimizes the precision of the person's edge in use-cases such as meetings, offices, homes, and under backlight or weak light conditions.
3. **Channel media relay**
The number of target channels for media relay has been increased to 6. When calling `startOrUpdateChannelMediaRelay` and `startOrUpdateChannelMediaRelayEx`, you can specify up to 6 target channels.
4. **Enhancement in video codec query capability**
To improve the video codec query capability, this release adds the `codecLevels` member in `CodecCapAgoraVideoCodecCapInfoInfo`. After successfully calling `queryCodecCapability`, you can obtain the hardware and software decoding capability levels of the device for H.264 and H.265 video formats through `codecLevels`.
This release includes the following additional improvements:
1. The SDK automatically adjusts the frame rate of the sending end based on the screen sharing use-case. Especially in document sharing use-cases, this feature avoids exceeding the expected video bitrate on the sending end to improve transmission efficiency and reduce network burden.
2. To help users understand the reasons for more types of remote video state changes, the `AgoraVideoRemoteReasonCodecNotSupport` enumeration has been added to the `remoteVideoStateChangedOfUid` callback, indicating that the local video decoder does not support decoding the received remote video stream.
#### Issues fixed [#issues-fixed-59]
This release fixed the following issues:
* Slow channel reconnection after the connection was interrupted due to network reasons.
* In screen sharing use-cases, the delay of seeing the shared screen was occasionally higher than expected on some devices.
* In custom video capturing use-cases, `setBeautyEffectOptions`, `setLowlightEnhanceOptions`, `setVideoDenoiserOptions`, and `setColorEnhanceOptions` could not load extensions automatically.
#### API changes [#api-changes-33]
**Added**
* `startPreview [2/2]`
* `stopPreview [2/2]`
* `setCameraExposureFactor`
* `isCameraExposureSupported`
* `preloadChannelByToken [1/2]`
* `preloadChannelByToken [2/2]`
* `updatePreloadChannelToken`
* The following members in `AgoraRtcChannelMediaOptions`:
* `publishThirdCameraTrack`
* `publishFourthCameraTrack`
* `publishThirdScreenTrack`
* `publishFourthScreenTrack`
* `AgoraVideoCodecCapLevels`
* `AgoraVideoCodecCapabilityLevel`
* `backgroundColor` in `AgoraRtcVideoCanvas`
* `codecLevels` in `CodecCapAgoraVideoCodecCapInfoInfo`
* `AgoraVideoRemoteReasonCodecNotSupport` in `AgoraVideoRemoteReason`
### v4.2.1 [#v421-2]
This version was released on June 21, 2023.
#### Improvements [#improvements-56]
This version improves the network transmission strategy, enhancing the smoothness of audio and video interactions.
#### Issues fixed [#issues-fixed-60]
This version fixed the following issues:
* Inability to join channels caused by SDK's incompatibility with some older versions of AccessToken.
* After the sending end called `setAINSMode` to activate AI noise reduction, occasional echo was observed by the receiving end.
* Brief noise occurred while playing media files using the media player.
* Occasional crash after calling the `destroyMediaPlayer` method.
### v4.2.0 [#v420-2]
v4.2.0 was released on May 23, 2023.
#### Compatibility changes [#compatibility-changes-28]
If you use the features mentioned in this section, ensure that you modify the implementation of the relevant features after upgrading the SDK.
**1. Video capture**
This release optimizes the APIs for camera and screen capture function. As of v4.2.0, ensure you use the alternative methods listed in the table below and specify the video source by setting the `sourceType` parameter.
| Deleted Methods | Alternative Methods |
| :---------------------------- | :------------------- |
| `startSecondaryCameraCapture` | `startCameraCapture` |
| `stopSecondaryCameraCapture` | `stopCameraCapture` |
**2. Video data acquisition**
* The `onCaptureVideoFrame` and `onPreEncodeVideoFrame` callbacks are added with a new parameter called `sourceType`, which is used to indicate the specific video source type.
* The following callbacks are deleted. Get the video source type through the `sourceType` parameter in the `onPreEncodeVideoFrame` and `onCaptureVideoFrame` callbacks.
* `onScreenCaptureVideoFrame`
* `onPreEncodeScreenVideoFrame`
**3. Channel media options**
* `publishCustomAudioTrackEnableAec` in `AgoraRtcChannelMediaOptions` is deleted. Use `publishCustomAudioTrack` instead.
* `publishTrancodedVideoTrack` in `AgoraRtcChannelMediaOptions` is renamed to `publishTranscodedVideoTrack`.
* `publishCustomAudioSourceId` in `AgoraRtcChannelMediaOptions` is renamed to `publishCustomAudioTrackId`.
**4. Miscellaneous**
* `didApiCallExecute` is deleted. Agora recommends getting the results of the API implementation through relevant channels and media callbacks.
* `enableDualStreamMode`\[1/2] and `enableDualStreamMode`\[2/2] are depredated. Use `setDualStreamMode`\[1/2] and `setDualStreamMode`\[2/2] instead.
* `startChannelMediaRelay`, `updateChannelMediaRelay`, `startChannelMediaRelayEx` and `updateChannelMediaRelayEx` are deprecated. Use `startOrUpdateChannelMediaRelay` and `startOrUpdateChannelMediaRelayEx` instead.
#### New features [#new-features-47]
**1. AI noise suppression**
This release introduces the AI noise suppression function. Once enabled, the SDK automatically detects and reduces background noises. Whether in bustling public venues or real-time competitive arenas that demand lightning-fast responsiveness, this function guarantees optimal audio clarity, providing users with an elevated audio experience. You can enable this function through the newly-introduced `setAINSMode` method and set the noise suppression mode as balance, aggressive or low latency according to your use-case.
**2. Enhanced virtual background**
To increase the fun of real-time video calls and protect user privacy, this version has enhanced the virtual background feature. You can now set custom backgrounds of various types by calling the `enableVirtualBackground` method, including:
* Process the background as Alpha information without replacement, only separating the portrait and the background. This can be combined with the local video mixing feature to achieve a portrait-in-picture effect.
* Replace the background with various formats of local videos.
**3. Video scenario settings**
This release introduces `setVideoScenario` for setting the video application scene. The SDK will automatically enable the best practice strategy based on different scenes, adjusting key performance indicators to optimize video quality and improve user experience. Whether it is a formal business meeting or a casual online gathering, this feature ensures that the video quality meets the requirements.
Currently, this feature provides targeted optimizations for real-time video conferencing scenarios, including:
* Automatically activate multiple anti-weak network technologies to enhance the capability and performance of low-quality video streams in meeting scenarios where high bitrates are required, ensuring smoothness when multiple streams are subscribed by the receiving end.
* Monitor the number of subscribers for the high-quality and low-quality video streams in real time, dynamically adjusting the configuration of the high-quality stream and dynamically enabling or disabling the low-quality stream, to save uplink bandwidth and consumption.
**4. Local video mixing**
This release adds the local video mixing feature. You can use the `startLocalVideoTranscoder` method to mix and render multiple video streams locally, such as camera-captured video, screen sharing streams, video files, images, etc. This allows you to achieve custom layouts and effects, making it easy to create personalized video display effects to meet various use-case requirements, such as remote meetings, live streaming, online education, while also supporting features like portrait-in-picture effect.
Additionally, the SDK provides the `updateLocalTranscoderConfiguration` method and the `didLocalVideoTranscoderErrorWithStream` callback. After enabling local video mixing, you can use the `updateLocalTranscoderConfiguration` method to update the video mixing configuration. Where an error occurs in starting the local video mixing or updating the configuration, you can get the reason for the failure through the `didLocalVideoTranscoderErrorWithStream` callback.
Local video mixing requires more CPU resources. Therefore, Agora recommends enabling this function on devices with higher performance.
**5. Cross-device synchronization**
In real-time collaborative singing use-cases, network issues can cause inconsistencies in the downlinks of different client devices. To address this, this release introduces `getNtpWallTimeInMs` for obtaining the current Network Time Protocol (NTP) time. By using this method to synchronize lyrics and music across multiple client devices, users can achieve synchronized singing and lyrics progression, resulting in a better collaborative experience.
#### Improvements [#improvements-57]
**1. Voice changer**
This release introduces the `setLocalVoiceFormant` method that allows you to adjust the formant ratio to change the timbre of the voice. This method can be used together with the `setLocalVoicePitch` method to adjust the pitch and timbre of voice at the same time, enabling a wider range of voice transformation effects.
**2. Enhanced screen share**
This release adds the `queryScreenCaptureCapability` method, which is used to query the screen capture capabilities of the current device. To ensure optimal screen sharing performance, particularly in enabling high frame rates like 60 fps, Agora recommends you to query the device's maximum supported frame rate using this method beforehand.
This release also adds the `setScreenCaptureScenario` method, which is used to set the scenario type for screen sharing. The SDK automatically adjusts the smoothness and clarity of the shared screen based on the scenario type you set.
**3. Audio and video synchronization**
For custom video and audio capture use-cases, this release introduces `getCurrentMonotonicTimeInMs` for obtaining the current Monotonic Time. By passing this value into the timestamps of audio and video frames, developers can accurately control the timing of their audio and video streams, ensuring proper synchronization.
**4. Multi-camera capture**
This release introduces `startCameraCapture`. By calling this method multiple times and specifying the `sourceType` parameter, developers can start capturing video streams from multiple cameras for local video mixing or multi-channel publishing. This particularly useful for use-cases such as remote medical care and online education, where multiple cameras need to be connected.
**5. Channel media relay**
This release introduces `startOrUpdateChannelMediaRelay` and `startOrUpdateChannelMediaRelayEx`, allowing for a simpler and smoother way to start and update media relay across channels. With these methods, developers can easily start the media relay across channels and update the target channels for media relay with a single method. Additionally, the internal interaction frequency has been optimized, effectively reducing latency in function calls.
**6. Custom audio tracks**
To better meet the needs of custom audio capture use-cases, this release adds `createCustomAudioTrack` and `destroyCustomAudioTrack` for creating and destroying custom audio tracks. Two types of audio tracks are also provided for users to choose from, further improving the flexibility of capturing external audio source:
* Mixable audio track: Supports mixing multiple external audio sources and publishing them to the same channel, suitable for multi-channel audio capture use-cases.
* Direct audio track: Only supports publishing one external audio source to a single channel, suitable for low-latency audio capture use-cases.
#### Issues fixed [#issues-fixed-61]
This release fixed the following issues:
* When the host frequently switching the user role between broadcaster and audience in a short period of time, the audience members cannot hear the audio of the host.
* Occasional loss of the `firstRemoteVideoFrameOfUid` callback during channel media relay.
* The receiver actively subscribed to the high-quality stream but unexpectedly received a low-quality stream.
* Abnormal client status cased by an exception in the `onRemoteAudioStateChanged` callback.
#### API changes [#api-changes-34]
**Added**
* `startCameraCapture`
* `stopCameraCapture`
* `startOrUpdateChannelMediaRelay`
* `startOrUpdateChannelMediaRelayEx`
* `getNtpWallTimeInMs`
* `setVideoScenario`
* `getCurrentMonotonicTimeInMs`
* `didLocalVideoTranscoderErrorWithStream`
* `startLocalVideoTranscoder`
* `updateLocalTranscoderConfiguration`
* `queryScreenCaptureCapability`
* `setScreenCaptureScenario`
* `setAINSMode`
* `createCustomAudioTrack`
* `destroyCustomAudioTrack`
* `AudioTrackConfig`
* `AgoraAudioTrackType`
* `AgoraApplicationScenarioType`
* `AgoraScreenCaptureFrameRateCapability`
* The `domainLimit` and `autoRegisterAgoraExtensions` members in `AgoraRtcEngineConfig`
* The `channelId` and `uid` parameters in `stateDidChanged` and `informationDidUpdated` callbacks
* The `sourceType` parameter in `onCaptureVideoFrame` and `onPreEncodeVideoFrame` callbacks
* The `AgoraVirtualBackgroundNone` and `AgoraVirtualBackgroundVideo` enumerators in `AgoraVirtualBackgroundSourceType`
**Deprecated**
* `enableDualStreamMode`\[1/2]
* `enableDualStreamMode`\[2/2]
* `startChannelMediaRelay`
* `startChannelMediaRelayEx`
* `updateChannelMediaRelay`
* `updateChannelMediaRelayEx`
* `didReceiveChannelMediaRelayEvent`
* `AgoraChannelMediaRelayEvent`
**Deleted**
* `startSecondaryCameraCapture`
* `stopSecondaryCameraCapture`
* `didApiCallExecute`
* `publishCustomAudioTrackEnableAec` in `AgoraRtcChannelMediaOptions`
* `onScreenCaptureVideoFrame`
* `onPreEncodeScreenVideoFrame`
### v4.1.1 [#v411-2]
v4.1.1 was released on January xx, 2023.
#### Compatibility changes [#compatibility-changes-29]
**1. Default video encoding resolution**
As of this release, the SDK optimizes the video encoder algorithm and upgrades the default video encoding resolution from 640 × 360 to 960 × 540 to accommodate improvements in device performance and network bandwidth, providing users with a full-link HD experience in various audio and video interaction use-cases.
You can call the `setVideoEncoderConfiguration` method to set the expected video encoding resolution in the video encoding parameters configuration.
The increase in the default resolution affects the aggregate resolution and thus the billing rate. See [Pricing](/en/realtime-media/video/reference/pricing).
**2. Options for subscribing to remote video streams**
This release changes the name of `setRemoteVideo` to `setRemoteVideoSubscriptionOptions`, and the name of `setRemoteVideoEx` to `setRemoteVideoSubscriptionOptionsEx`. If you upgrade the SDK to this version or later, to avoid affecting your service, ensure that you modify the names of these two methods.
#### New features [#new-features-48]
**1. Instant frame rendering**
This release adds the `enableInstantMediaRendering` method to enable instant rendering mode for audio and video frames, which can speed up the first video or audio frame rendering after the user joins the channel.
**2. Video rendering tracing**
This release adds the `startMediaRenderingTracing` and `startMediaRenderingTracingEx` methods. The SDK starts tracing the rendering status of the video frames in the channel from the moment this method is called and reports information about the event through the `videoRenderingTracingResultOfUid` callback.
Agora recommends that you use this method in conjunction with the UI settings (such as buttons and sliders) in your app. For example, call this method at the moment when the user clicks the "Join Channel" button, and then get the indicators in the video frame rendering process through the `videoRenderingTracingResultOfUid` callback. This enables developers to facilitate developers to optimize the indicators to improve the user experience.
#### Improvements [#improvements-58]
**1. Video frame observer**
As of this release, the SDK optimizes the `onRenderVideoFrame` callback, and the meaning of the return value is different depending on the video processing mode:
* When the video processing mode is `AgoraVideoFrameProcessModeReadOnly`, the return value is reserved for future use.
* When the video processing mode is `AgoraVideoFrameProcessModeReadWrite`, the SDK receives the video frame when the return value is `YES`; the video frame is discarded when the return value is `NO`.
**2. Super resolution**
This release improves the performance of super resolution. To optimize the usability of super resolution, this release removes `enableRemoteSuperResolution`. Super resolution is now included in the online strategies of video quality enhancement which does not require extra configuration.
#### Issues fixed [#issues-fixed-62]
This release fixed the following issues:
* Playing audio files with a sample rate of 48 kHz failed.
* When there were multiple video streams in a channel, calling some video enhancement APIs occasionally failed.
* At the moment when a user left a channel, a request for leaving was not sent to the server and the leaving behavior was incorrectly determined by the server as timed out.
#### API changes [#api-changes-35]
**Added**
* `enableInstantMediaRendering`
* `startMediaRenderingTracing`
* `startMediaRenderingTracingEx`
* `videoRenderingTracingResultOfUid`
* `AgoraMediaRenderTraceEvent`
* `VideoRenderingTracingInfo`
**Modified**
* `setRemoteVideo` to `setRemoteVideoSubscriptionOptions`
* `setRemoteVideoEx` to `setRemoteVideoSubscriptionOptionsEx`
**Deleted**
* `enableRemoteSuperResolution`
* Deleted `superResolutionType` in `AgoraRtcRemoteVideoStats`
### v4.1.0 [#v410-2]
v4.1.0 was released on November xx, 2022.
#### New features [#new-features-49]
#### **1. Multiple cameras for video capture** [#1-multiple-cameras-for-video-capture]
This release supports multi-camera video capture. You can call `enableMultiCamera` to enable multi-camera capture mode, call `startSecondaryCameraCapture` to start capturing video from the second camera, and then publish the captured video to the second channel.
To stop using multi-camera capture, you need to call `stopSecondaryCameraCapture` to stop the second camera capture, then call `enableMultiCamera` and set `enabled` to `NO`.
**2. Headphone equalization effect**
This release adds the `setHeadphoneEQParameters` method, which is used to adjust the low- and high-frequency parameters of the headphone EQ. This mainly useful in spatial audio use-cases. If you cannot achieve the expected headphone EQ effect after calling `setHeadphoneEQPreset`, you can call setHeadphoneEQParameters to adjust the EQ.
**3. Encoded video frame observer**
This release adds the `setRemoteVideo` method in the `AgoraRtcEngineKit` and `AgoraRtcEngineKitEx` classes. When you call the `setEncodedVideoFrameDelegate` method to register a video frame observer for the encoded video frames, the SDK subscribes to the encoded video frames by default. If you want to change the subscription options, you can call these new methods to set them.
For more information about registering video observers and subscription options, see the API reference.
**4. MPUDP (MultiPath UDP) (Beta)**
As of this release, the SDK supports MPUDP protocol, which enables you to connect and use multiple paths to maximize the use of channel resources based on the UDP protocol. You can use different physical NICs on both mobile and desktop and aggregate them to effectively combat network jitter and improve transmission quality.
> To enable this feature, contact [support@agora.io](mailto\:support@agora.io).
**5. Camera capture options**
This release adds the `followEncodeDimensionRatio` member in `AgoraCameraCapturerConfiguration`, which enables you to set whether to follow the video aspect ratio already set in `setVideoEncoderConfiguration` when capturing video with the camera.
**6. Multi-channel management**
This release adds a series of multi-channel related methods that you can call to manage audio and video streams in multi-channel use-cases.
* The `muteLocalAudioStreamEx` and `muteLocalVideoStreamEx` methods are used to cancel or resume publishing a local audio or video stream, respectively.
* The `muteAllRemoteAudioStreamsEx` and `muteAllRemoteVideoStreamsEx` are used to cancel or resume the subscription of all remote users to audio or video streams, respectively.
* The `startRtmpStreamWithoutTranscodingEx`, `startRtmpStreamWithTranscodingEx`, `updateRtmpTranscodingEx`, and `stopRtmpStreamEx` methods are used to implement Media Push in multi-channel use-cases.
* The `startChannelMediaRelayEx`, `updateChannelMediaRelayEx`, `pauseAllChannelMediaRelayEx`, `resumeAllChannelMediaRelayEx`, and `stopChannelMediaRelayEx` methods are used to relay media streams across channels in multi-channel use-cases.
* Adds the `leaveChannelEx` \[2/2] method. Compared with the `leaveChannelEx` \[1/2] method, a new `options` parameter is added, which is used to choose whether to stop recording with the microphone when leaving a channel in a multi-channel use-case.
**7. Video encoding preferences**
In general use-cases, the default video encoding configuration meets most requirements. For certain specific use-cases, this release adds the `advancedVideoOptions` member in `VideoEncoderConfiguration` for advanced settings of video encoding properties:
* `compressionPreference`: The compression preferences for video encoding, which is used to select low-latency or high-quality video preferences.
* `encodingPreference`: The video encoder preference, which is used to select adaptive preference, software encoder preference, or hardware encoder video preferences.
**8. Client role switching**
In order to enable users to know whether the switched user role is low-latency or ultra-low-latency, this release adds the `newRoleOptions` parameter to the `didClientRoleChanged` callback. The value of this parameter is as follows:
* `AgoraAudienceLatencyLevelLowLatency` (1): Low latency.
* `AgoraAudienceLatencyLevelUltraLowLatency` (2): Ultra-low latency.
#### Improvements [#improvements-59]
**1. Relaying media streams across channels**
This release optimizes the `updateChannelMediaRelay` method as follows:
* Before v4.1.0: If the target channel update fails due to internal reasons in the server, the SDK returns the error code `AgoraChannelMediaRelayEventUpdateDestinationChannelRefused`(8), and you need to call the `updateChannelMediaRelay` method again.
* v4.1.0 and later: If the target channel update fails due to internal server reasons, the SDK retries the update until the target channel update is successful.
**2. Reconstructed AIAEC algorithm**
This release reconstructs the AEC algorithm based on the AI method. Compared with the traditional AEC algorithm, the new algorithm can preserve the complete, clear, and smooth near-end vocals under poor echo-to-signal conditions, significantly improving the system's echo cancellation and dual-talk performance. This gives users a more comfortable call and live-broadcast experience. AIAEC is suitable for conference calls, chats, karaoke, and other use-cases.
**3. Virtual background**
This release optimizes the virtual background algorithm. Improvements include the following:
* The boundaries of virtual backgrounds are handled in a more nuanced way and image matting is now extremely thin.
* The stability of the virtual background is improved whether the portrait is still or moving, effectively eliminating the problem of background flickering and exceeding the range of the picture.
* More application use-cases are now supported, and a user obtains a good virtual background effect day or night, indoors or out.
* A larger variety of postures are now recognized, when half the body is motionless, the body is shaking, the hands are swinging, or there is fine finger movement. This helps to achieve a good virtual background effect in conjunction with many different gestures.
#### **Other improvements** [#other-improvements-1]
This release includes the following additional improvements:
* Reduces the latency when pushing external audio sources.
* Improves the performance of echo cancellation when using the `AgoraAudioScenarioMeeting` scenario.
* Improves the smoothness of SDK video rendering.
* Enhances the ability to identify different network protocol stacks and improves the SDK's access capabilities in multiple-operator network scenarios.
#### **Issues fixed** [#issues-fixed-63]
This release fixed the following issues:
* Calling `startAudioMixing` to play music files in the `ipod-library://item` path failed.
* Audience members heard buzzing noises when the host switched between speakers and earphones during live streaming.
* Different timestamps for audio and video data were obtained simultaneously and separately via `onRecordAudioFrame` and `onCaptureVideoFrame` callbacks.
* The call `getExtensionProperty` failed and returned an empty string.
* When entering a live streaming room that has been played for a long time as an audience, the time for the first frame to be rendered was shortened.
#### **API changes** [#api-changes-36]
**Added**
* `enableMultiCamera`
* `startSecondaryCameraCapture`
* `stopSecondaryCameraCapture`
* `setHeadphoneEQParameters`
* `setRemoteVideo`
* `AgoraVideoSubscriptionOptions`
* `muteLocalAudioStreamEx`
* `muteLocalVideoStreamEx`
* `muteAllRemoteAudioStreamsEx`
* `muteAllRemoteVideoStreamsEx`
* `startRtmpStreamWithoutTranscodingEx`
* `startRtmpStreamWithTranscodingEx`
* `updateRtmpTranscodingEx`
* `stopRtmpStreamEx`
* `startChannelMediaRelayEx`
* `updateChannelMediaRelayEx`
* `pauseAllChannelMediaRelayEx`
* `resumeAllChannelMediaRelayEx`
* `stopChannelMediaRelayEx`
* `followEncodeDimensionRatio` in `AgoraCameraCapturerConfiguration`
* `hwEncoderAccelerating` in `AgoraRtcLocalVideoStats`
* `leaveChannelEx` \[2/2]
* `advancedVideoOptions` in `AgoraVideoEncoderConfiguration`
* `newRoleOptions` in `didClientRoleChanged`
* `adjustUserPlaybackSignalVolumeEx`
* `enableAudioVolumeIndicationEx`
**Deprecated**
* `didApiCallExecute`. Use the callbacks triggered by specific methods instead.
**Deleted**
* Removes deprecated member parameters `backgroundImage` and `watermark` in `AgoraLiveTranscoding` class.
* Removes `AgoraChannelMediaRelayEventUpdateDestinationChannelRefused`(8) in `didReceiveChannelMediaRelayEvent`.
### v4.0.0 [#v400-2]
v4.0.0 was released on September 15, 2022.
#### New features [#new-features-50]
**2. Full HD and Ultra HD resolution**
In order to improve the interactive video experience, the SDK optimizes the whole process of video capturing, encoding, decoding and rendering. Starting from this version, it supports Full HD (FHD) and Ultra HD (UHD) video resolutions. You can set the `dimensions` parameter to 1920 × 1080 or higher resolution when calling the `setVideoEncoderConfiguration` method. If your device does not support high resolutions, the SDK will automatically fall back to an appropriate resolution.
The UHD resolution (4K, 60 fps) is currently in beta and requires certain device performance and network bandwidth. If you want to experience this feature, contact [technical support](mailto\:support@agora.io).
High resolution typically means higher performance consumption. To avoid a decrease in experience due to insufficient device performance, Agora recommends that you enable FHD and UHD video resolutions on devices with better performance.
The increase in the default resolution affects the aggregate resolution and thus the billing rate. See [Pricing](/en/realtime-media/video/reference/pricing).
### v4.2.2 [#v422-2]
v4.2.2 was released on july 27, 2023.
#### New features [#new-features-51]
1. **Wildcard token**
This release introduces wildcard tokens. Agora supports setting the channel name used for generating a token as a wildcard character. The token generated can be used to join any channel if you use the same user id. In use-cases involving multiple channels, such as switching between different channels, using a wildcard token can avoid repeated application of tokens every time users joining a new channel, which reduces the pressure on your token server. See [Secure authentication with tokens](/en/realtime-media/video/build/authenticate-users/authentication-workflow).
All 4.x SDKs support using wildcard tokens.
2. **Preloading channels**
This release adds `preloadChannelByToken[1/2]` and `preloadChannelByToken[2/2]` methods, which allows a user whose role is set as audience to preload channels before joining one. Calling the method can help shortening the time of joining a channel, thus reducing the time it takes for audience members to hear and see the host.
When preloading more than one channels, Agora recommends that you use a wildcard token for preloading to avoid repeated application of tokens every time you joining a new channel, thus saving the time for switching between channels. See [Secure authentication with tokens](/en/realtime-media/video/build/authenticate-users/authentication-workflow).
3. **Customized background color of video canvas**
In this release, the `backgroundColor` member has been added to `AgoraRtcVideoCanvas`, which allows you to customize the background color of the video canvas when setting the properties of local or remote video display.
4. **Video source types for local preview**
To allow users in selecting different types of video sources for local video preview, this release introduces `startPreview[2/2]` and `stopPreview[2/2]`. You can call `startPreview[2/2]` and specify the type of video source to be previewed by setting the `sourceType` parameter, and call `stopPreview[2/2]` to stop the video preview.
The video source type specified in this method must match the video source type set in the `AgoraRtcVideoCanvas` of the `setupLocalVideo` method.
#### Improvements [#improvements-60]
1. **Improved camera capture effect**
This release has improved camera capture effect in the following aspects:
1. Support for camera exposure adjustment
This release adds `isCameraExposureSupported` to query whether the device supports exposure adjustment and `setCameraExposureFactor` to set the exposure ratio of the camera.
2. Optimization of default camera selection
Since this release, the default camera selection behavior of the SDK is aligned with that of the iOS system camera. If the device has multiple rear cameras, better shooting perspectives, zooming capabilities, low-light performance, and depth sensing can be achieved during video capture, thereby improving the quality of video capture.
2. **Virtual Background Algorithm Upgrade**
This version has upgraded the portrait segmentation algorithm of the virtual background, which comprehensively improves the accuracy of portrait segmentation, the smoothness of the portrait edge with the virtual background, and the fit of the edge when the person moves. In addition, it optimizes the precision of the person's edge in use-cases such as meetings, offices, homes, and under backlight or weak light conditions.
3. **Channel media relay**
The number of target channels for media relay has been increased to 6. When calling `startOrUpdateChannelMediaRelay` and `startOrUpdateChannelMediaRelayEx`, you can specify up to 6 target channels.
4. **Enhancement in video codec query capability**
To improve the video codec query capability, this release adds the `codecLevels` member in `CodecCapAgoraVideoCodecCapInfoInfo`. After successfully calling `queryCodecCapability`, you can obtain the hardware and software decoding capability levels of the device for H.264 and H.265 video formats through `codecLevels`.
This release includes the following additional improvements:
1. The SDK automacially adjusts the frame rate of the sending end based on the screen sharing use-case. Especially in document sharing use-cases, this feature avoids exceeding the expected video bitrate on the sending end to improve transmission efficiency and reduce network burden.
2. To help users understand the reasons for more types of remote video state changes, the `AgoraVideoRemoteReasonCodecNotSupport` enumeration has been added to the `remoteVideoStateChangedOfUid` callback, indicating that the local video decoder does not support decoding the received remote video stream.
#### Issues fixed [#issues-fixed-64]
This release fixed the following issues:
* Slow channel reconnection after the connection was interrupted due to network reasons.
* In screen sharing use-cases, the delay of seeing the shared screen was occasionally higher than expected on some devices.
* In custom video capturing use-cases, `setBeautyEffectOptions`, `setLowlightEnhanceOptions`, `setVideoDenoiserOptions`, and `setColorEnhanceOptions` could not load extensions automatically.
#### API changes [#api-changes-37]
**Added**
* `startPreview [2/2]`
* `stopPreview [2/2]`
* `setCameraExposureFactor`
* `isCameraExposureSupported`
* `preloadChannelByToken [1/2]`
* `preloadChannelByToken [2/2]`
* `updatePreloadChannelToken`
* The following members in `AgoraRtcChannelMediaOptions`:
* `publishThirdCameraTrack`
* `publishFourthCameraTrack`
* `publishThirdScreenTrack`
* `publishFourthScreenTrack`
* `AgoraVideoCodecCapLevels`
* `AgoraVideoCodecCapabilityLevel`
* `backgroundColor` in `AgoraRtcVideoCanvas`
* `codecLevels` in `CodecCapAgoraVideoCodecCapInfoInfo`
* `AgoraVideoRemoteReasonCodecNotSupport` in `AgoraVideoRemoteReason`
### v4.2.1 [#v421-3]
This version was released on June 21, 2023.
#### Improvements [#improvements-61]
This version improves the network transmission strategy, enhancing the smoothness of audio and video interactions.
#### Issues fixed [#issues-fixed-65]
This version fixed the following issues:
* Inability to join channels caused by SDK's incompatibility with some older versions of AccessToken.
* After the sending end called `setAINSMode` to activate AI noise reduction, occasional echo was observed by the receiving end.
* Brief noise occurred while playing media files using the media player.
* Occasional crash after calling the `destroyMediaPlayer` method.
### v4.2.0 [#v420-3]
v4.2.0 was released on May 24, 2023.
#### Compatibility changes [#compatibility-changes-30]
If you use the features mentioned in this section, ensure that you modify the implementation of the relevant features after upgrading the SDK.
**1. Video capture**
This release optimizes the APIs for camera and screen capture function. As of v4.2.0, ensure you use the alternative methods listed in the table below and specify the video source by setting the `sourceType` parameter.
| Deleted Methods | Alternative Methods |
| :---------------------------- | :------------------- |
| `startSecondaryCameraCapture` | `startCameraCapture` |
| `stopSecondaryCameraCapture` | `stopCameraCapture` |
**2. Video data acquisition**
The `onCaptureVideoFrame` and `onPreEncodeVideoFrame` callbacks are added with a new parameter called `sourceType`, which is used to indicate the specific video source type.
**3. Channel media options**
* `publishCustomAudioTrackEnableAec` in `AgoraRtcChannelMediaOptions` is deleted. Use `publishCustomAudioTrack` instead.
* `publishTrancodedVideoTrack` in `AgoraRtcChannelMediaOptions` is renamed to `publishTranscodedVideoTrack`.
* `publishCustomAudioSourceId` in `AgoraRtcChannelMediaOptions` is renamed to `publishCustomAudioTrackId`.
**4. Miscellaneous**
* `didApiCallExecute` is deleted. Agora recommends getting the results of the API implementation through relevant channels and media callbacks.
* `enableDualStreamMode`\[1/2] and `enableDualStreamMode`\[2/2] are deprecated. Use `setDualStreamMode`\[1/2] and `setDualStreamMode`\[2/2] instead.
* `startChannelMediaRelay`, `updateChannelMediaRelay`, `startChannelMediaRelayEx`, and `updateChannelMediaRelayEx` are deprecated. Use `startOrUpdateChannelMediaRelay` and `startOrUpdateChannelMediaRelayEx` instead.
#### New features [#new-features-52]
**1. AI Noise Suppression**
This release introduces public APIs for the AI Noise Suppression function. Once enabled, the SDK automatically detects and reduces background noises. Whether in bustling public venues or real-time competitive arenas that demand lightning-fast responsiveness, this function guarantees optimal audio clarity, providing users with an elevated audio experience. You can enable this function through the newly-introduced `setAINSMode` method and set the noise suppression mode as balance, aggressive, or low latency according to your use-case.
Agora charges separately for this function. See [AI Noise Suppression unit pricing](/en/realtime-media/video/reference/pricing#ai-noise-suppression-pricing).
**2. Enhanced Virtual Background**
To increase the fun of real-time video calls and protect user privacy, this version has enhanced the Virtual Background function. You can now set custom backgrounds of various types by calling the `enableVirtualBackground` method, including:
* Process the background as Alpha information without replacement, only separating the portrait and the background. This can be combined with the local video mixing feature to achieve a portrait-in-picture effect.
* Replace the background with various formats of local videos.
See [Virtual Background documentation](/en/realtime-media/video/build/apply-video-effects/virtual-background).
**3. Video scenario settings**
This release introduces `setVideoScenario` for setting the video application scene. The SDK will automatically enable the best practice strategy based on different scenes, adjusting key performance indicators to optimize video quality and improve user experience. Whether it is a formal business meeting or a casual online gathering, this feature ensures that the video quality meets the requirements.
Currently, this feature provides targeted optimizations for real-time video conferencing scenarios, including:
* Automatically activate multiple anti-weak-network technologies to enhance the capability and performance of low-quality video streams in meeting scenarios where high bitrates are required, ensuring smoothness when multiple streams are subscribed by the receiving end.
* Monitor the number of subscribers for the high-quality and low-quality video streams in real time, dynamically adjusting the configuration of the high-quality stream and dynamically enabling or disabling the low-quality stream, to save uplink bandwidth and consumption.
**4. Local video mixing**
This release adds the local video mixing feature. You can use the `startLocalVideoTranscoder` method to mix and render multiple video streams locally, such as camera-captured video, screen sharing streams, video files, images, etc. This allows you to achieve custom layouts and effects, making it easy to create personalized video display effects to meet various use-case requirements, such as remote meetings, live streaming, online education, while also supporting features like portrait-in-picture effect.
Additionally, the SDK provides the `updateLocalTranscoderConfiguration` method and the `didLocalVideoTranscoderErrorWithStream` callback. After enabling local video mixing, you can use the `updateLocalTranscoderConfiguration` method to update the video mixing configuration. Where an error occurs in starting the local video mixing or updating the configuration, you can get the reason for the failure through the `didLocalVideoTranscoderErrorWithStream` callback.
Local video mixing requires more CPU resources. Therefore, Agora recommends enabling this function on devices with higher performance.
**5. Cross-device synchronization**
In real-time collaborative singing use-cases, network issues can cause inconsistencies in the downlinks of different client devices. To address this, this release introduces `getNtpWallTimeInMs` for obtaining the current Network Time Protocol (NTP) time. By using this method to synchronize lyrics and music across multiple client devices, users can achieve synchronized singing and lyrics progression, resulting in a better collaborative experience.
#### Improvements [#improvements-62]
**1. Voice changer**
This release introduces the `setLocalVoiceFormant` method that allows you to adjust the formant ratio to change the timbre of the voice. This method can be used together with the `setLocalVoicePitch` method to adjust the pitch and timbre of voice at the same time, enabling a wider range of voice transformation effects.
**2. Enhanced screen share**
This release adds the `queryScreenCaptureCapability` method, which is used to query the screen capture capabilities of the current device. To ensure optimal screen sharing performance, particularly in enabling high frame rates like 60 fps, Agora recommends you to query the device's maximum supported frame rate using this method beforehand.
This release also adds the `setScreenCaptureScenario` method, which is used to set the scenario type for screen sharing. The SDK automatically adjusts the smoothness and clarity of the shared screen based on the scenario type you set.
**3. Audio and video synchronization**
For custom video and audio capture use-cases, this release introduces `getCurrentMonotonicTimeInMs` for obtaining the current Monotonic Time. By passing this value into the timestamps of audio and video frames, developers can accurately control the timing of their audio and video streams, ensuring proper synchronization.
**4. Multi-camera capture**
This release introduces `startCameraCapture`. By calling this method multiple times and specifying the `sourceType` parameter, developers can start capturing video streams from multiple cameras for local video mixing or multi-channel publishing. This particularly useful for use-cases such as remote medical care and online education, where multiple cameras need to be connected.
**5. Channel media relay**
This release introduces `startOrUpdateChannelMediaRelay` and `startOrUpdateChannelMediaRelayEx`, allowing for a simpler and smoother way to start and update media relay across channels. With these methods, developers can easily start the media relay across channels and update the target channels for media relay with a single method. Additionally, the internal interaction frequency has been optimized, effectively reducing latency in function calls.
**6. Custom audio tracks**
To better meet the needs of custom audio capture use-cases, this release adds `createCustomAudioTrack` and `destroyCustomAudioTrack` for creating and destroying custom audio tracks. Two types of audio tracks are also provided for users to choose from, further improving the flexibility of capturing external audio source:
* Mixable audio track: Supports mixing multiple external audio sources and publishing them to the same channel, suitable for multi-channel audio capture use-cases.
* Direct audio track: Only supports publishing one external audio source to a single channel, suitable for low-latency audio capture use-cases.
#### Issues fixed [#issues-fixed-66]
This release fixed the following issues:
* When the host frequently switched the user role between broadcaster and audience in a short period of time, the audience members could not hear the audio of the host.
* Occasional loss of the `firstRemoteVideoFrameOfUid` callback during channel media relay.
* The receiver actively subscribed to the high-quality stream but unexpectedly received a low-quality stream.
* Abnormal client status caused by an exception in the `onRemoteAudioStateChanged` callback.
#### API changes [#api-changes-38]
**Added**
* `startCameraCapture`
* `stopCameraCapture`
* `startOrUpdateChannelMediaRelay`
* `startOrUpdateChannelMediaRelayEx`
* `getNtpWallTimeInMs`
* `setVideoScenario`
* `getCurrentMonotonicTimeInMs`
* `didLocalVideoTranscoderErrorWithStream`
* `startLocalVideoTranscoder`
* `updateLocalTranscoderConfiguration`
* `queryScreenCaptureCapability`
* `setScreenCaptureScenario`
* `setAINSMode`
* `createAudioCustomTrack`
* `destroyAudioCustomTrack`
* `AudioTrackConfig`
* `AgoraAudioTrackType`
* `AgoraApplicationScenarioType`
* `AgoraScreenCaptureFrameRateCapability`
* The `domainLimit` and `autoRegisterAgoraExtensions` members in `AgoraRtcEngineConfig`
* The `channelId` and `uid` parameters in `stateDidChanged` and `informationDidUpdated` callbacks
* The `sourceType` parameter in `onCaptureVideoFrame` and `onPreEncodeVideoFrame` callbacks
* The `AgoraVirtualBackgroundNone` and `AgoraVirtualBackgroundVideo` enumerators in `AgoraVirtualBackgroundSourceType`
**Deprecated**
* `enableDualStreamMode`\[1/2]
* `enableDualStreamMode`\[2/2]
* `startChannelMediaRelay`
* `startChannelMediaRelayEx`
* `updateChannelMediaRelay`
* `updateChannelMediaRelayEx`
* `didReceiveChannelMediaRelayEvent`
* `AgoraChannelMediaRelayEvent`
**Deleted**
* `startSecondaryCameraCapture`
* `stopSecondaryCameraCapture`
* `didApiCallExecute`
* `publishCustomAudioTrackEnableAec` in `AgoraRtcChannelMediaOptions`
### v4.1.1 [#v411-3]
v4.1.1 was released on February 8, 2023.
#### Compatibility changes [#compatibility-changes-31]
**1. Default video encoding resolution**
As of this release, the SDK optimizes the video encoder algorithm and upgrades the default video encoding resolution from 640 × 360 to 960 × 540 to accommodate improvements in device performance and network bandwidth, providing users with a full-link HD experience in various audio and video interaction use-cases.
Call the `setVideoEncoderConfiguration` method to set the expected video encoding resolution in the video encoding parameters configuration.
The increase in the default resolution affects the aggregate resolution and thus the billing rate. See [Pricing](/en/realtime-media/video/reference/pricing).
**2. Options for subscribing to remote video streams**
This release changes the name of `setRemoteVideo` to `setRemoteVideoSubscriptionOptions`, and the name of `setRemoteVideoEx` to `setRemoteVideoSubscriptionOptionsEx`. If you upgrade the SDK to this version or later, to avoid affecting your service, ensure that you modify the names of these two methods.
#### New features [#new-features-53]
**1. Instant frame rendering**
This release adds the `enableInstantMediaRendering` method to enable instant rendering mode for audio and video frames, which can speed up the first video or audio frame rendering after the user joins the channel.
**2. Video rendering tracing**
This release adds the `startMediaRenderingTracing` and `startMediaRenderingTracingEx` methods. The SDK starts tracing the rendering status of the video frames in the channel from the moment this method is called and reports information about the event through the `videoRenderingTracingResultOfUid` callback.
Agora recommends that you use this method in conjunction with the UI settings, such as buttons and sliders, in your app. For example, call this method when the user clicks **Join Channel** and then get the indicators in the video frame rendering process through the `videoRenderingTracingResultOfUid` callback.
This enables developers to optimize the indicators and improve the user experience.
#### Improvements [#improvements-63]
**1. Video frame observer**
As of this release, the SDK optimizes the `onRenderVideoFrame` callback, and the meaning of the return value is different depending on the video processing mode:
* When the video processing mode is `AgoraVideoFrameProcessModeReadOnly`, the return value is reserved for future use.
* When the video processing mode is `AgoraVideoFrameProcessModeReadWrite`, the SDK receives the video frame when the return value is `YES`. The video frame is discarded when the return value is `NO`.
**2. Super resolution**
This release improves the performance of super resolution. To optimize the usability of super resolution, this release removes `enableRemoteSuperResolution`. Super resolution is now included in the online strategies of video quality enhancement which does not require extra configuration.
#### Issues fixed [#issues-fixed-67]
This release fixed the following issues:
* Playing audio files with a sample rate of 48 kHz failed.
* When there were multiple video streams in a channel, calling some video enhancement APIs occasionally failed.
#### API changes [#api-changes-39]
**Added**
* `enableInstantMediaRendering`
* `startMediaRenderingTracing`
* `startMediaRenderingTracingEx`
* `videoRenderingTracingResultOfUid`
* `AgoraMediaRenderTraceEvent`
* `VideoRenderingTracingInfo`
**Modified**
* `setRemoteVideo` to `setRemoteVideoSubscriptionOptions`
* `setRemoteVideoEx` to `setRemoteVideoSubscriptionOptionsEx`
**Deleted**
* `enableRemoteSuperResolution`
* `superResolutionType` in `AgoraRtcRemoteVideoStats`
### v4.1.0 [#v410-3]
v4.1.0 was released on December 15, 2022.
#### New features [#new-features-54]
#### **1. Multiple cameras for video capture** [#1-multiple-cameras-for-video-capture-1]
This release supports multi-camera video capture. You can call `enableMultiCamera` to enable multi-camera capture mode, call `startSecondaryCameraCapture` to start capturing video from the second camera, and then publish the captured video to the second channel.
To stop using multi-camera capture, you need to call `stopSecondaryCameraCapture` to stop the second camera capture, then call `enableMultiCamera` and set `enabled` to `NO`.
**2. Headphone equalization effect**
This release adds the `setHeadphoneEQParameters` method, which is used to adjust the low- and high-frequency parameters of the headphone EQ. This mainly useful in spatial audio use-cases. If you cannot achieve the expected headphone EQ effect after calling `setHeadphoneEQPreset`, you can call `setHeadphoneEQParameters` to adjust the EQ.
**3. Encoded video frame observer**
This release adds the `setRemoteVideo` method in the `AgoraRtcEngineKit` and `AgoraRtcEngineKitEx` classes. When you call the `setEncodedVideoFrameDelegate` method to register a video frame observer for the encoded video frames, the SDK subscribes to the encoded video frames by default. If you want to change the subscription options, you can call these new methods to set them.
For more information about registering video observers and subscription options, see the API reference.
**4. MPUDP (MultiPath UDP) (Beta)**
As of this release, the SDK supports MPUDP protocol, which enables you to connect and use multiple paths to maximize the use of channel resources based on the UDP protocol. You can use different physical NICs on both mobile and desktop and aggregate them to effectively combat network jitter and improve transmission quality. To enable this feature, contact [support@agora.io](mailto\:support@agora.io).
**5. Camera capture options**
This release adds the `followEncodeDimensionRatio` member in `AgoraCameraCapturerConfiguration`, which enables you to set whether to follow the video aspect ratio already set in `setVideoEncoderConfiguration` when capturing video with the camera.
**6. Multi-channel management**
This release adds a series of multi-channel related methods that you can call to manage audio and video streams in multi-channel use-cases.
* The `muteLocalAudioStreamEx` and `muteLocalVideoStreamEx` methods are used to cancel or resume publishing a local audio or video stream, respectively.
* The `muteAllRemoteAudioStreamsEx` and `muteAllRemoteVideoStreamsEx` are used to cancel or resume the subscription of all remote users to audio or video streams, respectively.
* The `startRtmpStreamWithoutTranscodingEx`, `startRtmpStreamWithTranscodingEx`, `updateRtmpTranscodingEx`, and `stopRtmpStreamEx` methods are used to implement Media Push in multi-channel use-cases.
* The `startChannelMediaRelayEx`, `updateChannelMediaRelayEx`, `pauseAllChannelMediaRelayEx`, `resumeAllChannelMediaRelayEx`, and `stopChannelMediaRelayEx` methods are used to relay media streams across channels in multi-channel use-cases.
* Adds the `leaveChannelEx` \[2/2] method. Compared with the `leaveChannelEx` \[1/2] method, a new `options` parameter is added, which is used to choose whether to stop recording with the microphone when leaving a channel in a multi-channel use-case.
**7. Video encoding preferences**
In general use-cases, the default video encoding configuration meets most requirements. For certain specific use-cases, this release adds the `advancedVideoOptions` member in `VideoEncoderConfiguration` for advanced settings of video encoding properties:
* `compressionPreference`: The compression preferences for video encoding, which is used to select low-latency or high-quality video preferences.
* `encodingPreference`: The video encoder preference, which is used to select adaptive preference, software encoder preference, or hardware encoder video preferences.
**8. Client role switching**
In order to enable users to know whether the switched user role is low-latency or ultra-low-latency, this release adds the `newRoleOptions` parameter to the `didClientRoleChanged` callback. The value of this parameter is as follows:
* `AgoraAudienceLatencyLevelLowLatency` (1): Low latency.
* `AgoraAudienceLatencyLevelUltraLowLatency` (2): Ultra-low latency.
**9. Brand-new AI Noise Suppression**
The SDK supports a new version of AI noise reduction (in comparison to the basic AI noise reduction in v3.7.x). The new AI noise reduction has better vocal fidelity, cleaner noise suppression, and adds a dereverberation option. To experience this feature, contact [support@agora.io](mailto\:support@agora.io).
**10. Spatial audio effect**
This release adds the following features applicable to spatial audio effect use-cases, which can effectively enhance the user's sense of presence experience in virtual interactive use-cases.
* Sound insulation area: You can set a sound insulation area and sound attenuation parameter by calling `setZones`. When the sound source (which can be a user or the media player) and the listener belong to the inside and outside of the sound insulation area, the listener experiences an attenuation effect similar to that of the sound in the real environment when it encounters a building partition. You can also set the sound attenuation parameter for the media player and the user, respectively, by calling `setPlayerAttenuation` and `setRemoteAudioAttenuation`, and specify whether to use that setting to force an override of the sound attenuation parameter in `setZones`.
* Doppler sound: You can enable Doppler sound by setting the `enable_doppler` parameter in `SpatialAudioParams`, and the receiver experiences noticeable tonal changes in the event of a high-speed relative displacement between the source and receiver (such as in a racing game use-case).
* Headphone equalizer: You can use a preset headphone equalization effect by calling the `setHeadphoneEQPreset` method to improve the hearing of the headphones.
#### Improvements [#improvements-64]
**1. Relaying media streams across channels**
This release optimizes the `updateChannelMediaRelay` method as follows:
* Before v4.1.0: If the target channel update fails due to internal reasons in the server, the SDK returns the error code `AgoraChannelMediaRelayEventUpdateDestinationChannelRefused`(8), and you need to call the `updateChannelMediaRelay` method again.
* v4.1.0 and later: If the target channel update fails due to internal server reasons, the SDK retries the update until the target channel update is successful.
**2. Reconstructed AIAEC algorithm**
This release reconstructs the AEC algorithm based on the AI method. Compared with the traditional AEC algorithm, the new algorithm can preserve the complete, clear, and smooth near-end vocals under poor echo-to-signal conditions, significantly improving the system's echo cancellation and dual-talk performance. This gives users a more comfortable call and live-broadcast experience. AIAEC is suitable for conference calls, chats, karaoke, and other use-cases.
**3. Virtual background**
This release optimizes the virtual background algorithm. Improvements include the following:
* The boundaries of virtual backgrounds are handled in a more nuanced way and image matting is now extremely thin.
* The stability of the virtual background is improved whether the portrait is still or moving, effectively eliminating the problem of background flickering and exceeding the range of the picture.
* More application use-cases are now supported, and a user obtains a good virtual background effect day or night, indoors or out.
* A larger variety of postures are now recognized, when half the body is motionless, the body is shaking, the hands are swinging, or there is fine finger movement. This helps to achieve a good virtual background effect in conjunction with many different gestures.
**Other improvements**
This release includes the following additional improvements:
* Reduces the latency when pushing external audio sources.
* Improves the performance of echo cancellation when using the `AgoraAudioScenarioMeeting` scenario.
* Improves the smoothness of SDK video rendering.
* Enhances the ability to identify different network protocol stacks and improves the SDK's access capabilities in multiple-operator network scenarios.
#### **Issues fixed** [#issues-fixed-68]
This release fixed the following issues:
* Calling `startAudioMixing` to play music files in the `ipod-library://item` path failed.
* Audience members heard buzzing noises when the host switched between speakers and earphones during live streaming.
* Different timestamps for audio and video data were obtained simultaneously and separately via `onRecordAudioFrame` and `onCaptureVideoFrame` callbacks.
* The call `getExtensionProperty` failed and returned an empty string.
* When entering a live streaming room that has been played for a long time as an audience, the time for the first frame to be rendered was shortened.
#### **API changes** [#api-changes-40]
**Added**
* `enableMultiCamera`
* `startSecondaryCameraCapture`
* `stopSecondaryCameraCapture`
* `setHeadphoneEQParameters`
* `setRemoteVideo`
* `AgoraVideoSubscriptionOptions`
* `muteLocalAudioStreamEx`
* `muteLocalVideoStreamEx`
* `muteAllRemoteAudioStreamsEx`
* `muteAllRemoteVideoStreamsEx`
* `startRtmpStreamWithoutTranscodingEx`
* `startRtmpStreamWithTranscodingEx`
* `updateRtmpTranscodingEx`
* `stopRtmpStreamEx`
* `startChannelMediaRelayEx`
* `updateChannelMediaRelayEx`
* `pauseAllChannelMediaRelayEx`
* `resumeAllChannelMediaRelayEx`
* `stopChannelMediaRelayEx`
* `followEncodeDimensionRatio` in `AgoraCameraCapturerConfiguration`
* `hwEncoderAccelerating` in `AgoraRtcLocalVideoStats`
* `leaveChannelEx` \[2/2]
* `advancedVideoOptions` in `AgoraVideoEncoderConfiguration`
* `newRoleOptions` in `didClientRoleChanged`
* `adjustUserPlaybackSignalVolumeEx`
* `enableAudioVolumeIndicationEx`
**Deprecated**
* `didApiCallExecute`. Use the callbacks triggered by specific methods instead.
**Deleted**
* Removes deprecated member parameters `backgroundImage` and `watermark` in `AgoraLiveTranscoding` class.
* Removes `AgoraChannelMediaRelayEventUpdateDestinationChannelRefused`(8) in `didReceiveChannelMediaRelayEvent`.
### v4.0.1 [#v401-2]
v4.0.1 was released on September 29, 2022.
#### Compatibility changes [#compatibility-changes-32]
1. To improve code usability, this release changes the parameters in optional type in the following classes to basic data types such as ` bool` and `int`:
* `isAgoraSource` and `isLiveSource` in `AgoraMediaSource` is changed from optional to bool.
* All parameter types in `AgoraRtcChannelMediaOptions` are changed from `optional` to `bool` or `int`.
#### New features [#new-features-55]
**1. In-ear monitoring**
This release adds `getEarMonitoringAudioParams` callback to set the audio data format of the in-ear monitoring. You can use your own audio effect processing module to pre-process the audio frame data of the in-ear monitoring to implement custom audio effects. After calling `setAudioFrameDelegate` to register the audio observer, set the audio data format in the return value of the `getEarMonitoringAudioParams` callback. The SDK calculates the sampling interval based on the return value of the callback, and triggers the `onEarMonitoringAudioFrame` callback based on the sampling interval.
**2. Local network connection types**
To make it easier for users to know the connection type of the local network at any stage, this release adds the `getNetworkType` method. You can use this method to get the type of network connection in use, including UNKNOWN, DISCONNECTED, LAN, WIFI, 2G, 3G, 4G, 5G. When the local network connection type changes, the SDK triggers the `networkTypeChangedToType` callback to report the current network connection type.
**3. Audio stream filter**
This release introduces filtering audio streams based on volume. Once this function is enabled, the Agora server ranks all audio streams by volume and transports 3 audio streams with the highest volumes to the receivers by default. The number of audio streams to be transported can be adjusted; you can contact [support@agora.io](mailto\:support@agora.io) to adjust this number according to your use-case.
Meanwhile, Agora supports publishers to choose whether or not the audio streams being published are to be filtered based on volume. Streams that are not filtered will bypass this filter mechanism and transported directly to the receivers. In use-cases where there are a number of publishers, enabling this function helps reducing the bandwidth and device system pressure for the receivers.
To enable this function, contact [support@agora.io](mailto\:support@agora.io).
#### API changes [#api-changes-41]
**Added**
* `getEarMonitoringAudioParams`
* `getNetworkType`
* `isAudioFilterable` in the `ChannelMediaOptions`
* `setZones`
* `setPlayerAttenuation`
* `setRemoteAudioAttenuation`
* `muteRemoteAudioStream`
* `SpatialAudioParams`
* `setHeadphoneEQPreset`
* `AgoraHeadphoneEQPreset`
**Deprecated**
* `startEchoTest` \[2/3]
### v4.0.0 [#v400-3]
v4.0.0 was released on September 15, 2022.
#### Compatibility changes [#compatibility-changes-33]
**1. Integration change**
This release has optimized the implementation of some features, resulting in incompatibility with v3.7.x. The following are the main features with compatibility changes:
* Multiple channel
* Media stream publishing control
* Custom video capture and rendering (Media IO)
* Warning codes
After upgrading the SDK, you need to update the code in your app according to your business use-cases. For details, see [Migrate from v3.7.x to v4.0.0](/en/realtime-media/video/reference/migration-guide).
#### New features [#new-features-56]
**1. Multiple media tracks**
This release supports one `AgoraRtcEngineKit` instance to collect multiple audio and video sources at the same time and publish them to the remote users by setting `AgoraRtcEngineKit(Ex)` and `AgoraRtcChannelMediaOptions`.
* After calling `joinChannelByToken` to join the first channel, call `joinChannelExByToken` multiple times to join multiple channels, and publish the specified stream to different channels through different user ID (`localUid`) and `AgoraRtcChannelMediaOptions` settings.
You can also experience the following features with the multi-channel capability:
* Publish multiple sets of audio streams to the remote users through different user IDs (`uid`).
* Mix multiple audio streams and publish to the remote users through a user ID (`uid`).
**2. Full HD and Ultra HD resolution (Beta)**
In order to improve the interactive video experience, the SDK optimizes the whole process of video capturing, encoding, decoding and rendering. Starting from this version, it supports Full HD (FHD) and Ultra HD (UHD) video resolutions. You can set the `dimensions` parameter to 1920 × 1080 or higher resolution when calling the `setVideoEncoderConfiguration` method. If your device does not support high resolutions, the SDK will automatically fall back to an appropriate resolution.
The UHD resolution (4K, 60 fps) is currently in beta and requires certain device performance and network bandwidth. If you want to enable this feature, contact [technical support](mailto\:support@agora.io).
High resolution typically means higher performance consumption. To avoid a decrease in experience due to insufficient device performance, Agora recommends that you enable FHD and UHD video resolutions on devices with better performance.
The increase in the default resolution affects the aggregate resolution and thus the billing rate. See [Pricing](/en/realtime-media/video/reference/pricing).
**3. Agora media player**
To make it easier for users to integrate the Agora SDK and reduce the SDK's package size, this release introduces the Agora media player. After calling the `createMediaPlayerWithDelegate` method to create a media player object, you can then call the methods in the `AgoraRtcMediaPlayerProtocol` class to experience a series of functions, such as playing local and online media files, preloading a media file, changing the CDN route for playing according to your network conditions, or sharing the audio and video streams being played with remote users.
**4. Ultra-high audio quality**
To make the audio clearer and restore more details, this release adds the `AgoraVoiceBeautifierUltraHighQuality` enumeration. In use-cases that mainly feature the human voice, such as chat or singing, you can call `setVoiceBeautifierPreset` and use this enumeration to experience ultra-high audio quality.
**5. Spatial audio**
This feature is in experimental status. To enable this feature, contact [support@agora.io](mailto\:support@agora.io). Contact [Technical Support](mailto\:support@agora.io) if needed.
You can set the spatial audio for the remote user as following:
* Local Cartesian Coordinate System Calculation: This solution uses the `AgoraLocalSpatialAudioKit` class to implement spatial audio by calculating the spatial coordinates of the remote user. You need to call `updateSelfPosition` and `updateRemotePosition` to update the spatial coordinates of the local and remote users, respectively, so that the local user can hear the spatial audio effect of the remote user.
You can also set the spatial audio for the media player as following:
* Local Cartesian Coordinate System Calculation: This solution uses the `AgoraLocalSpatialAudioKit` class to implement spatial audio. You need to call `updateSelfPosition` and `updatePlayerPositionInfo` to update the spatial coordinates of the local user and media player, respectively, so that the local user can hear the spatial audio effect of media player.
**6. Real-time chorus**
This release gives real-time chorus the following abilities:
* Two or more choruses are supported.
* Each singer is independent of each other. If one singer fails or quits the chorus, the other singers can continue to sing.
* Very low latency experience. Each singer can hear each other in real time, and the audience can also hear each singer in real time.
This release adds the `AgoraAudioScenarioChorus` enumeration in `AgoraAudioScenario`. With this enumeration, users can experience ultra-low latency in real-time chorus when the network conditions are good.
**7. Extensions from the Agora extensions marketplace**
In order to enhance the real-time audio and video interactive activities based on the Agora SDK, this release supports the one-stop solution for the extensions from the [Agora extensions marketplace](https://api-ref.agora.io/en/agora-extensions-marketplace/):
* Easy to integrate: The integration of modular functions can be achieved simply by calling an API, and the integration efficiency is improved by nearly 95%.
* Extensibility design: The modular and extensible SDK design style endows the Agora SDK with good extensibility, which enables developers to quickly build real-time interactive apps based on the Agora extensions marketplace ecosystem.
* Build an ecosystem: A community of real-time audio and video apps has developed that can accommodate a wide range of developers, offering a variety of extension combinations. After integrating the extensions, developers can build richer real-time interactive functions. For details, see [Use an Extension](/en/realtime-media/video/build/customize-audio-processing/use-an-extension).
* Become a vendor: Vendors can integrate their products with Agora SDK in the form of extensions, display and publish them in the Agora extensions marketplace, and build a real-time interactive ecosystem for developers together with Agora. For details on how to develop and publish extensions, see [Become a Vendor](/en/api-reference/api-ref/extensions-marketplace/provisioning).
**8. Enhanced channel management**
To meet the channel management requirements of various business use-cases, this release adds the following functions to the `AgoraRtcChannelMediaOptions` structure:
* Sets or switches the publishing of multiple audio sources.
* Sets or switches channel profile and user role.
* Controls audio publishing delay.
Set `AgoraRtcChannelMediaOptions` when calling `joinChannelByToken` or `joinChannelExByToken` to specify the publishing and subscription behavior of a media stream, for example, whether to subscribe to the audio and video streams of remote users. After joining the channel, call `updateChannelWithMediaOptions` to update the settings in `AgoraRtcChannelMediaOptions` at any time, for example, to switch the published audio sources.
**9. Screen sharing**
This release optimizes the screen sharing function. You can enable this function in the following ways.
* Call the `StartScreenCapture` method before joining a channel, and then call `JoinChannelByToken` \[2/4] to join a channel and set `publishScreenCaptureVideo` as `YES`.
* Call the `StartScreenCapture` method after joining a channel, and then call `updateChannelWithMediaOptions` to set `publishScreenCaptureVideo` as `YES`.
**10. Subscription allowlists and blocklists**
This release introduces subscription allowlists and blocklists for remote audio streams. You can add a user ID that you want to subscribe to in your allowlist, or add a user ID for the streams you do not wish to see to your blocklists. You can experience this feature through the following APIs, and in use-cases that involve multiple channels, you can call the following methods in the `AgoraRtcEngineKit(Ex)` interface:
* `setSubscribeAudioBlacklist`：Set the audio subscription blocklist.
* `setSubscribeAudioWhitelist`：Set the audio subscription allowlist.
If a user is added in a blocklist and a allowlist at the same time, only the blocklist takes effect.
**11. Set audio scenarios**
To make it easier to change audio scenarios, this release adds the `setAudioScenario` method. For example, if you want to change the audio scenario from `AgoraAudioScenarioDefault` to `AgoraAudioScenarioGameStreaming` when you are in a channel, you can call this method.
#### Improvements [#improvements-65]
**1. Fast channel switching**
This release can achieve the same switching speed as `switchChannelByToken` in v3.7.x through the `leaveChannel` and `joinChannelByToken` methods so that you don't need to take the time to call the `switchChannelByToken` method.
**2. Voice pitch of the local user**
This release adds `voicePitch` in `AgoraRtcAudioVolumeInfo` of `reportAudioVolumeIndicationOfSpeakers`. You can use `voicePitch` to get the local user's voice pitch and perform business functions such as rating for singing.
## Extensions [#extensions]
## MetaKit extension [#metakit-extension-1]
### v2.2.0 [#v220-2]
v2.2.0 was released on September 13, 2024.
#### New features [#new-features-144]
**Stickers**
This version adds the sticker feature that uses the face capture driver and follows the character's head movements. The SDK provides subpackages for glasses (`material_sticker_glass`), masks (`material_sticker_facemask`), veils (`material_sticker_veil`), and dragon head hats (`material_sticker_dragonhat`). You can load the corresponding scene resources to quickly experience the effects of different stickers.
**Portrait edge light**
This release adds a new portrait edge light effect. To experience it, specify the subpackage resource as `material_effect_ray` when loading scene resources.
**Advertising light text-to-image**
This version adds a text-to-image feature for the advertising lights. When setting the advertising light effects, you can specify the text content through the `text` parameter and add animation effects through the `animation` parameter. This includes jumping, waving, or swaying, to make the text appear dynamically on the screen.
#### Improvements [#improvements-160]
This update adds support for `loadMaterial` and `unloadMaterial` in `setExtensionPropertyWithVendor`.
* When using `loadMaterial` to load scene resources, you can specify the resource path of the required subpackage. The engine will automatically request the scene texture and render the scene.
* If you need to switch to another scene, just use `loadMaterial` again to pass in another subpackage resource path. The engine will automatically switch to the new scene.
* When you no longer need to experience the scene, use `unloadMaterial` to uninstall scene resources.
This improvement significantly enhances the usability of the extension. You can quickly experience different functional use-cases by simply specifying different subpackage resource paths when loading.
#### API changes [#api-changes-86]
**Added**
* `loadMaterial`
* `unloadMaterial`
### v2.1.0 [#v210-3]
v2.1.0 was released on March 6, 2024.
This update focuses on optimizing the performance of the MetaKit extension, ensuring more efficient operation and a better user experience.
### v2.0.0 [#v200-4]
v2.0.0 was released on February 23, 2024.
This is the first release of the MetaKit extension. This extension integrates multiple AI technologies to provide users with diverse video enhancement functions in audio and video interaction use-cases.
## Camera Movement extension [#camera-movement-extension-1]
### v1.2.0 [#v120-2]
v1.2.0 was released on April 29, 2024.
#### Improvements [#improvements-161]
* Added support for Video SDK v4.3.x.
* Improved the performance of the Camera Movement extension, reducing potential stuttering issues on low-end devices.
### v1.0.0 [#v100-4]
v1.0.0 was released on February 23, 2024.
This is the initial release of the Agora Camera Movement extension.
The extension uses AI technology and intelligent camera movement algorithms to provide various features for audio and video interaction use-cases.
## Notifications [#notifications]
### 2022.10 [#202210]
* After you enable Agora Notifications, your server receives the events that you subscribe to in the form of HTTPS requests.
* To improve communication security between the Agora Notifications and your server, Agora backend uses signatures
for identity verification.
* As of this release, you can use Agora Notifications in conjunction with this product.