Video Capture Rotation
Feature Overview
ZEGOCLOUD provides 4 capture rotation modes for mobile devices (Fixed Resolution Ratio mode, Adaption mode, Alignment mode, and Custom mode) to simplify the complex adaptation issues developers face when implementing multi-device rotation behaviors, such as camera angle, resolution, auto-rotation, and statusbar position adaptation. You can configure different modes through the setAppOrientationMode interface based on rotation behavior and business scenario requirements.
- To ensure expected results, both publishing and playing ends must maintain the same mode within a single call or the same room.
- Both publishing and playing versions need to be v2.23.0 or higher to use Adaption and Alignment modes, so we recommend using them in new applications.
- PC, Web, and mixing services have adapted to rotation modes. Since they don't have mobile rotation characteristics, the statusbar defaults to the top of the screen.
- Fixed Resolution Ratio mode supports all protocol scenarios. Adaption and Alignment modes only support ZEGO RTC private protocol and ZEGO mixing service.
Fixed Resolution Ratio Mode
In Fixed Resolution Ratio mode, the video output direction always maintains a fixed ratio relative to the statusbar, and the video aspect ratio depends on the encoding resolution ratio.
Advantages: Fixed Resolution Ratio mode applies to all scenarios and is also commonly used in live streaming scenarios. This mode handles video rotation at the capture end, so the playing end doesn't need additional processing, avoiding compatibility issues with live streaming distribution channels.
When the encoding ratio is portrait, the behavior at publishing and playing ends is as follows:
-
UI fixed to portrait
-
UI not locked (App screen auto-rotation enabled)
Adaption Mode
In Adaption mode, regardless of how the device is held or the UI orientation, the image always remains vertically upright.
Advantages: In Adaption mode, users can choose their preferred way of holding the device for video calls. It is suitable for 1v1 or multi-person video RTC scenarios. You can also implement live streaming business through mixing and forwarding.
- Adaption mode does not support direct CDN push. If you need live streaming, you can use ZEGO mixing service to handle multi-person video rotation behavior before forwarding to CDN. If needed, please contact ZEGO technical support to enable this configuration.
- Adaption mode records camera angle, holding method, statusbar position, and other information in the ZEGO private transmission protocol, so it only supports ZEGO RTC protocol and ZEGO mixing service.
Behavior is as follows:
Alignment Mode
In Alignment mode, using the statusbar as a reference, the video direction at the playing end is consistent with the video direction at the publishing end preview. The playing end uses the statusbar as a reference to rotate the image, and the rotation angle at the playing end is consistent with the rotation angle at the publishing end preview.
Advantages: Alignment mode is similar to Adaption mode, but users can actively adjust fullscreen or aspect-ratio scaled display by combining the auto-rotation switch and holding method. It is suitable for 1v1 or multi-person video RTC scenarios.
- Alignment mode does not support direct CDN push. If you need live streaming, you can use ZEGO mixing service to handle multi-person video rotation behavior before forwarding to CDN. If needed, please contact ZEGO technical support to enable this configuration.
- Alignment mode records camera angle, holding method, statusbar position, and other information in the ZEGO private transmission protocol, so it only supports ZEGO RTC protocol and ZEGO mixing service.
-
When UI is fixed to portrait:
-
When UI is fixed to landscape:
-
UI not locked (App screen auto-rotation enabled)
Custom Mode (Default)
In Custom mode, you can customize the video capture rotation behavior according to your needs. The implementation method is more flexible. For specific implementation steps, please refer to How to customize video capture rotation mode?
Implementation Flow
The following implementation flow only applies to Fixed Resolution Ratio mode, Adaption mode, and Alignment mode. If you need to customize video capture rotation, please refer to Video Rotation.
Publishing End
The publishing end needs to call the setAppOrientationMode interface to set any capture rotation mode.
Please call the setAppOrientationMode interface immediately after calling createEngineWithProfile, then call the startPublishingStream or startPreview interface.
ZegoExpressEngine.instance.setAppOrientationMode(ZegoOrientationMode.FixedResolutionRatio);Playing End
Only in Adaption mode, the playing end needs to call the setAppOrientationMode interface to set Adaption mode before playing streams.
- Please call the setAppOrientationMode interface immediately after calling createEngineWithProfile to set the video orientation mode, then call startPlayingStream to start playing streams.
- In Adaption mode, only RTC stream playing is supported.
ZegoExpressEngine.instance.setAppOrientationMode(ZegoOrientationMode.Adaption);