Video Rotation
Feature Overview
This document applies to the following platforms: Android, iOS.
When users use mobile devices for live streaming or video calls, they typically have the following rotation options:
- Fixed portrait
- Fixed landscape
- Auto-switch between portrait and landscape
The examples below use the default "ZegoViewMode.AspectFit" (aspect-ratio scaled, may have black borders) mode for rendering at the playing end. For details, please refer to ZegoViewMode.
Fixed Portrait
Indicates that the publishing end captures video in a fixed portrait orientation. When the remote device orientation is portrait, the viewed image fills the device screen with a portrait effect. When the remote device orientation is landscape, the viewed image appears rotated relative to the publishing end's image (the following diagram shows a 90-degree counterclockwise rotation as an example).
-
If the device rotation is locked:
-
If the device rotation is not locked:
Fixed Landscape
Indicates that the publishing end captures video in a fixed landscape orientation. When the remote device orientation is landscape, the viewed image fills the device screen with a landscape effect. When the remote device orientation is portrait, the viewed image appears rotated relative to the publishing end's image (the following diagram shows a 90-degree counterclockwise rotation as an example).
-
If the device rotation is locked:
-
If the device rotation is not locked:
Auto-switch Between Portrait and Landscape
Provides video rotation functionality, allowing users to rotate the video 90, 180, or 270 degrees counterclockwise relative to the phone's upright direction as needed. This allows users to achieve their desired video rendering effect based on the video scenario requirements. After video rotation, automatic adjustments will be made to adapt to the encoded image resolution.
The interfaces used for the above three methods differ. For details, please refer to Usage Steps in this document.
Example Source Code Download
Please refer to Download Example Source Code to obtain the source code.
For related source code, please check the files in the "lib/topics/CommonFunctions/video_rotation" directory.
Prerequisites
Before implementing video capture rotation, please ensure:
- You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information.
- You have integrated ZEGO Express SDK in your project and implemented basic audio/video publishing and playing functionality. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
Usage Steps
Fixed Portrait
When using portrait live streaming or video calls, the width resolution should be smaller than the height resolution. Assuming it is "360 × 640", you need to follow these steps to implement the functionality.
- Call the createEngineWithProfile interface to create an SDK engine instance. For details, please refer to "Create Engine" in Quick Start - Implementation.
// Create engine for general scenario access
// appID is obtained through official website registration, format: 1234567890
// ZegoScenario.GENERAL for general scenario access
// appSign is obtained through official website registration, format: "1234567890"
// enablePlatformView indicates whether to use platformView, needs to be set to true when using createPlatformView
var profile = new ZegoEngineProfile(appID, ZegoScenario.GENERAL, appSign: appSign, enablePlatformView: enablePlatformView);
ZegoExpressEngine.createEngineWithProfile(profile);- Call the setVideoConfig interface to set the encoding resolution. The default value is "360 × 640", which can be adjusted as needed. You can use preset values through
ZegoVideoConfig.preset, such asZegoVideoConfigPreset.Preset360P.
// ZegoVideoConfigPreset.Preset360P preset capture resolution 360 × 640, encoding resolution 360 × 640, bitrate 600, frame rate 15
var config = ZegoVideoConfig.preset(ZegoVideoConfigPreset.Preset360P);The resolution settings for portrait live streaming are as follows:
ZegoExpressEngine.instance.setVideoConfig(config);- Call the loginRoom interface to log in to the room. For details, please refer to "Log In to Room" in Quick Start - Implementation.
ZegoExpressEngine.instance.loginRoom("test_roomid", ZegoUser.id("test_userid"));- Call the startPreview interface to start local preview for displaying local images. The viewID is obtained by calling ZegoExpressEngine.instance.createCanvasView.
// viewID is obtained by calling ZegoExpressEngine.instance.createCanvasView of ZEGO Express SDK
ZegoExpressEngine.instance.startPreview(canvas: ZegoCanvas(viewID));- Call the startPublishingStream interface to start publishing, pushing local audio/video streams to the real-time audio/video cloud. For details, please refer to "Publish Stream" in Quick Start - Implementation.
ZegoExpressEngine.instance.startPublishingStream("test_streamid");- Use fixed portrait mode for live streaming or video calls.
Fixed Landscape
When using landscape live streaming or video calls, the width resolution should be larger than the height resolution. Assuming it is "640 × 360", you need to follow these steps to implement the functionality.
- Call the createEngineWithProfile interface to create an SDK engine instance. For details, please refer to "Create Engine" in Quick Start - Implementation.
// Create engine for general scenario access
// appID is obtained through official website registration, format: 1234567890
// ZegoScenario.GENERAL for general scenario access
// appSign is obtained through official website registration, format: "1234567890"
// enablePlatformView indicates whether to use platformView, needs to be set to true when using createPlatformView
var profile = new ZegoEngineProfile(appID, ZegoScenario.GENERAL, appSign: appSign, enablePlatformView: enablePlatformView);
ZegoExpressEngine.createEngineWithProfile(profile);- Call the setVideoConfig interface to set the encoding resolution to "640 × 360".
var config = ZegoVideoConfig.preset(ZegoVideoConfigPreset.Preset360P);
config.captureWidth = 640;
config.captureHeight = 360;The resolution settings for landscape live streaming are as follows:
config.encodeWidth = 640;
config.encodeHeight = 360;
ZegoExpressEngine.instance.setVideoConfig(config);- Call the setAppOrientation interface to set the video orientation. If rotating 90 degrees counterclockwise, the parameter for the following interface is DeviceOrientation.landscapeRight. If rotating 90 degrees clockwise, the parameter is DeviceOrientation.landscapeLeft.
ZegoExpressEngine.instance.setAppOrientation(DeviceOrientation.landscapeRight);- Call the loginRoom interface to log in to the room. For details, please refer to "Log In to Room" in Quick Start - Implementation.
ZegoExpressEngine.instance.loginRoom("test_roomid", ZegoUser.id("test_userid"));- Call the startPreview interface to start local preview for displaying local images. The viewID is obtained by calling ZegoExpressEngine.instance.createCanvasView.
// viewID is obtained by calling ZegoExpressEngine.instance.createCanvasView of ZEGO Express SDK
ZegoExpressEngine.instance.startPreview(canvas: ZegoCanvas(viewID));- Call the startPublishingStream interface to start publishing, pushing local audio/video streams to the real-time audio/video cloud. For details, please refer to "Publish Stream" in Quick Start - Implementation.
ZegoExpressEngine.instance.startPublishingStream("test_streamid");- Use fixed landscape mode for live streaming or video calls.
Auto-switch Between Portrait and Landscape
If during live streaming or video calls, the App is set to rotate the video display based on gravity sensing, you need to listen for screen rotation events on the corresponding platform and rotate the video direction accordingly.
When developers use SDK capture, switching between portrait and landscape is mainly achieved by setting the encoding resolution through the setVideoConfig interface and setting the video orientation through the setAppOrientation interface.
You can listen for screen rotation events by adding an addPostFrameCallback callback through WidgetsBinding, and in the event handling callback, modify the corresponding encoding resolution and inform the SDK of the App's orientation.
// Initialize WidgetsBinding
WidgetsFlutterBinding.ensureInitialized();
// Add this window as an observer to WidgetsBinding
WidgetsBinding.instance.addObserver(this);
WidgetsBinding.instance.addPostFrameCallback((_) {
if(MediaQuery.of(context).orientation == Orientation.portrait){
_videoConfig.encodeWidth = 360;
_videoConfig.encodeHeight = 640;
ZegoExpressEngine.instance.setAppOrientation(DeviceOrientation.portraitUp);
} else if (MediaQuery.of(context).orientation == Orientation.landscape){
_videoConfig.encodeWidth = 640;
_videoConfig.encodeHeight = 360;
ZegoExpressEngine.instance.setAppOrientation(DeviceOrientation.landscapeLeft);
}
ZegoExpressEngine.instance.setVideoConfig(_videoConfig);
});
// Remove observer when destroying window or not in use
WidgetsBinding.instance.removeObserver(this);FAQ
-
Why does the recorded live stream seem unwatchable?
When switching between portrait and landscape, the stream's encoding resolution is modified. Some third-party players have poor compatibility with videos that have resolution changes, which may cause playback failures. Therefore, it is generally not recommended to modify the resolution during live streaming or video calls when switching between portrait and landscape.