Resolving Cloud Recording Layout Failures: Transitioning from String to Integer UIDs

Issue Description

Cloud Recording sessions utilizing custom or mixed layouts may result in files displaying only a blank, black, or colored background. In these scenarios, although the recording completes successfully and the media files are playable, the participant video streams fail to appear within the designated regions. This issue frequently occurs during the implementation of active-speaker layouts or fixed-grid arrangements.

Platform/SDK

• Service: Agora Cloud Recording (RESTful API)

• Client SDK: Agora Web SDK utilizing RTC integration

Error Characterization

The system typically does not return an explicit API error. The failure is observed post-session through the following symptoms:

• The generated MP4 or HLS files contain no captured video tracks for specific participants.

• The output rendering displays only the background color defined in the canvas configuration.

• The Cloud Recording status remains "processing" or "uploaded" despite the missing visual content.

Root Cause

The primary cause of this rendering failure is a UID type mismatch between the channel participants and the recording configuration. In this case, users were effectively joining with String UID behavior, while Cloud Recording custom layout requires the correct integer UIDs.

When an application joins users via String UIDs (User Accounts), Agora internally maps these to assigned integer UIDs for transmission. However, the Cloud Recording layoutConfig requires the exact integer UID that identifies the media stream. If the recording service receives a string-based identifier or a mismatching integer, it cannot associate the incoming media packets with the defined layout regions, resulting in an empty canvas. Additionally, misplacement of the transcodingConfig within the API request body can lead to the service ignoring all layout parameters.

Step by Step Solution

1. Validate API Request Structure

   Ensure that the transcodingConfig object is correctly nested within the recordingConfig parent key during the start request. Specifically, the path must be clientRequest.recordingConfig.transcodingConfig. If this object is placed at the wrong hierarchy level, the service will default to a standard layout and ignore custom configurations.

2. Select the Appropriate Layout Mode

   Configure the mixedVideoLayout parameter based on your specific requirements:

   • mixedVideoLayout: 0 = floating layout where the SDK manages positions automatically.
   • mixedVideoLayout: 3 = custom layout where you provide a specific layoutConfig for fixed positioning.

3. Enforce Integer UID Consistency Across the Workflow

   Transition the entire application lifecycle to utilize integer UIDs exclusively. This eliminates mapping discrepancies and ensures the recording service can identify streams:

   • Join Logic: Ensure the client joins the RTC channel using a numeric integer.

   • Token Generation: Utilize the buildTokenWithUid method rather than account-based builders.

   • Layout Definition: Pass the identical integer UID into the layoutConfig object.

   Cloud Recording does not support String UID in this scenario.

   If your app joins users with a String UID, Agora internally maps it to an integer UID, and your layoutConfig.uid values may no longer match the actual stream identity used by Cloud Recording.

4. Implement Explicit Type Conversion in Web Applications

   For Web SDK integrations where UIDs might be received as strings from a database or API, perform an explicit conversion before the join event. Use functions such as parseInt with a radix of 10 to guarantee the value is treated as a 32-bit unsigned integer by the Agora engine.

   • parseInt(uid, 10)
   • or another safe integer conversion

   This ensures the SDK joins with an integer UID instead of a string value.

   • If needed, on Web SDK, you can inspect client.uid after join to confirm the exact UID value being used.

5. Audit Active Speaker Dynamic Updates

   Since active-speaker transitions are not automated within the Cloud Recording service, you must manage these via API updates:

   • Detect the active speaker on the client side using volume indication callbacks.

   • Transmit the speaker's UID to your application server.

   • Invoke the updateLayout API to reassign the prominent video region to that specific integer UID.

   Note

   • For landscape recordings, publish a landscape video stream from the client by setting width and height properly in createCameraVideoTrack.

6. Manage API Call Frequency

   Avoid triggering layout updates for every volume change, as high-frequency calls may exceed the service QPS limits. Implement a throttling or debounce mechanism to ensure updates are sent only when a significant speaker transition is confirmed.

Best Practice

• Always use integer UIDs for Cloud Recording workflows.
• Generate tokens with buildTokenWithUid, not buildTokenWithAccount, when using recording layouts tied to UIDs.
• Use the same UID format consistently for:
  • RTC join
  • token generation
  • layoutConfig
  • update layout requests
• Test your payload first in Postman to validate request structure before implementing it in code.
• Throttle active-speaker layout updates to avoid excessive API calls.

Corresponding Document/Link

- Agora Documentation: Cloud Recording Layout Management

- Technical Note: String UID Limitations and Mappings

- API Reference: Web SDK iAgoraRtcClient UID