Skip to main content

Agora Conversational AI Engine v2.4 Release

×

March 2026 Agora Monthly Digest Meet our new AI agents

×

Preventing Android UI Freezing and Unresponsiveness Caused by Main Thread API Execution

Updated

Issue Description

When interacting with the application—such as switching user roles, toggling audio mute states, or leaving a channel—users may experience noticeable interface lag, delayed touch responses, or temporary Application Not Responding (ANR) warnings.

While the application does not crash, the user interface briefly freezes during high-frequency RTC operations.

 

Platform and SDK Context

  • Operating System: Android

  • SDK Component: Agora RTC SDK

     

Root Cause Analysis

This performance issue is caused by executing synchronous or resource-intensive SDK initialization and control methods directly on the Android Main UI Thread.

The Android Main Thread is responsible for rendering interface components and handling user input events at 60/120 fps. When methods like RTC engine initialization, setClientRole, muteLocalAudioStream, or leaveChannel perform internal state synchronization or hardware resource allocation on the UI thread, they block the message queue. This results in dropped frames and temporary UI unresponsiveness.

 

Solution and Resolution Steps

  1. Offload Heavy API Calls to Background Worker Threads

    Execute non-rendering SDK calls—especially role switching, track muting, and channel cleanup—on a dedicated worker thread or asynchronous task queue rather than the main thread.

     

  2. Optimize Engine Initialization Timing

    Avoid initializing the RTC engine instance immediately before a user enters a channel or triggers a UI event. Instead, pre-initialize the engine instance asynchronously during application startup or background activity initialization.

 

Prevention and Best Practice

To ensure smooth 60fps UI performance in complex Android applications, implement the following threading guidelines:

  • Strict UI/Worker Thread Separation: Keep all media control API operations (audio/video switching, spatial audio adjustments, network testing) strictly off the Main UI Thread.

  • Asynchronous Lifecycle Hooks: Ensure engine cleanup and channel leave logic (e.g., leaveChannel or destroy) inside onDestroy() or Activity lifecycle callbacks are dispatched asynchronously to prevent blocking the OS task stack during page transitions.

  • Monitor UI Blockings: Utilize tools like Android Profiler or StrictMode during development to identify and eliminate disk/network/SDK calls executing on the main thread.