Skip to main content

Agora Conversational AI Engine v2.4 Release

×

March 2026 Agora Monthly Digest Meet our new AI agents

×

Handling iOS Hardware Decoder Crashes During Remote Media Stream Disconnection

Updated

Issue Description

The application crashes during video decoding when a remote participant disables their local video stream. This occurs because the iOS hardware decoder is being released while it is still processing video frames asynchronously.

 

Platform/SDK

  • Operating System: iOS

  • Architecture: arm64

  • Affected SDK Version: Agora Native SDK v4.2.2.141 and earlier versions within the v4.x branch

 

Error Characteristics

This crash does not typically return a standard SDK error code. Engineers must inspect the crash log stack trace for the following internal identifiers:

  • AgoraRtcKit: Failure point within the media engine.

  • webrtc::VCMDecodedFrameCallback::Decoded: Indicates a failure during the callback of a decoded frame.

  • VideoToolbox: Failure associated with the iOS native hardware acceleration framework.

 

Root Cause

In SDK version 4.2.2, the iOS VideoToolbox decoder closes asynchronously. When a remote user calls enableLocalVideo(false), the SDK begins to release the video decoder (~VideoNodeRxProcessor and decoder_.reset()) while the hardware decoder is still finishing an asynchronous decoding task. This race condition can cause a crash.

 

Solution

  1. Verify Stack Trace Integrity 

    Examine the customer’s crash report to confirm the presence of the webrtc::VCMDecodedFrameCallback reference. This confirms that the crash is related to the known asynchronous decoder release issue.

     

  2. Identify the Mandatory Upgrade Path 

    Instruct the customer to upgrade their integration to a stable version. Use the following version-specific improvements as a reference for the customer:

    • v4.2.3: The asynchronous call in releaseDecoder was removed, reducing crash likelihood.
    • v4.2.6.2: Decoding and decoder destruction were moved to the same processing queue, ensuring synchronization and preventing this crash.

    • v4.3.0 and later: The decoder callback was restructured to execute safely on the internal thread, eliminating race conditions.

      Can recommend upgrading to Agora SDK v4.2.6.2 or any version in the v4.3.x branch to resolve this specific race condition.These improvements in newer versions ensure stable decoder release and prevent crashes during remote video enable/disable events.

       

  3. Implement Interim Mitigation 

    If an immediate upgrade is not feasible for the customer, advise them to reduce the frequency of camera toggling. Minimizing the repeated invocation of enableLocalVideo decreases the likelihood of triggering the asynchronous release conflict.

     

Summary

Upgrading to the recommended versions ensures that decoder operations are fully synchronized and thread-safe. Following the implementation of these updates, engineers should verify stability using internal monitoring tools to confirm the elimination of the VideoToolbox access violation.

Related articles