Resolving Cloud Recording Layout Resets: Payload Configuration Structuring for Mixed Mode Recording

Issue Description

Cloud Recording sessions executed in Composite/Mix mode may generate output files with a fixed resolution of 360 by 640 portrait. This anomaly persists despite explicit specifications for landscape resolutions such as 1280 by 720 or 1920 by 1080 within the custom layout settings. The issue occurs when the recording gateway overlooks the structural arguments and defaults to baseline profiles without throwing an explicit API error code.

Platform/SDK

• Service: Agora Cloud Recording RESTful API
• SDK version: Agora RTC Web SDK (AgoraRTC_N, loaded via script tag)
• Recording Mode: Composite/Mix recording mode

Error Message

There may be no explicit API error.

Typical symptom:

• Mix mode output: 360 × 640 portrait
• Expected output: 1280 × 720 or other configured landscape resolution

In some malformed payload cases, the service may also use default values instead of the intended transcoding settings.

Root Cause

The resolution anomaly stems from an invalid object hierarchy within the start request JSON payload. The transcodingConfig object is placed outside the proper structural block. Specifically, the object is defined as a sibling to the recordingConfig rather than a nested parameter.

Because the JSON parser relies on strict structural paths, an incorrect nesting level causes the media server to ignore the custom width, height, and bitrate parameters. Consequently, the cloud recording engine falls back to default environmental parameters, leading to an unintended portrait aspect ratio.

Step-by-Step Solution

1. Verify Object Nesting Levels

   For mix mode, transcodingConfig must be nested inside clientRequest.recordingConfig.

   Incorrect Payload Example:

   {
     "cname": "test",
     "uid": "12345",
     "clientRequest": {
       "recordingConfig": {
         "channelType": 0,
         ...
       },
       "transcodingConfig": {
         "width": 1280,
         ...
       },
       "recordingFileConfig": {
         "avFileType": ["hls", "mp4"]
       }
     }
   }

   The schema above places the transcodingConfig configuration at the same level as the recordingConfig, which invalidates the custom properties.

2. Apply Correct Schema Hierarchy

   Reconstruct the request body to establish the proper nesting pattern. The technical path must map directly to the internal request configuration structure.

   Correct Payload Example:

   {
     "cname": "test",
     "uid": "12345",
     "clientRequest": {
       "recordingConfig": {
         "channelType": 0,
         ...,
         "transcodingConfig": {
           "width": 1280,
           ...
         }
       },
       "recordingFileConfig": {
         "avFileType": ["hls", "mp4"]
       }
     }
   }

3. Utilize Standard Token Acquisition

   Ensure the preliminary resource allocation request utilizes standard parameters. The session environment does not require unique scene identifiers to process mixed stream transcoding successfully.

   A normal acquire request such as the following is sufficient:

   {
     "resourceExpiredHour": 24,
     "scene": 0
   }

   There is no special scene value required just to make mix transcoding work correctly.

4. Deprecate Individual Subscription Parameters

   Omit channel selective subscription arrays when executing composite recording. Parameters targeting explicit video or audio user identification lists are unnecessary because the mixed mode engine automatically aggregates all available active media streams by default.

   In mix mode, these parameters are generally unnecessary:

   • subscribeVideoUids
   • subscribeAudioUids
   • subscribeUidGroup

   Cloud Recording in composite mode automatically subscribes to channel streams by default.

5. Validate Media Geometry Post Recording

   After fixing the JSON nesting, start a new recording session and verify the output using a tool such as ffprobe:

   ffprobe your-recorded-file.mp4

   The metadata output must confirm the intended resolution matching the modified request schema.

6. Account for Publisher Aspect Ratios

   Note that if the streaming client transmits a native portrait camera feed, the video track may display with black pillarboxes or maintain its portrait orientation inside the transcoded canvas depending on the chosen rendering mode. This expected behavioral pattern is separate from a complete configuration omission.

Best Practice

Payload structural validation must precede all session initializations. When output profiles unexpectedly revert to baseline settings, the application layer should audit the exact JSON nesting of the request parameters rather than troubleshooting codec profiles, regional network routing, or third party cloud storage targets.

• Always validate your JSON payload before sending it.
• Double-check bracket placement and object nesting, especially for clientRequest, recordingConfig, and transcodingConfig.
• Compare your request against the official mix mode start request example before testing.
• If output falls back to 360 × 640, first verify payload structure before troubleshooting codecs, storage, region, or publisher encoder settings.

Corresponding Document/Link

- Cloud Recording RESTful API

- Cloud Recording video profile reference

- Postman reference collection mentioned by support