Rotate the Video
Introduction
The following figure shows how the Agora SDK captures, processes, and outputs videos.
Video rotation involves the video capturer and the video player, where:
- The video capturer captures the video and outputs the video information, that is, the relative position of the video and the status bar.
- The video player renders the received video and rotates the video according to the rotation information.
To avoid issues such as video scaling and scropping caused by video rotation, the Agora SDK provides a orientationMode parameter in the setVideoEncoderConfiguration method. You can use this parameter to set the video orientation mode according to your scenario to get the video you want.
Implementation
Before setting the video orientation mode, ensure that you have implemented basic real-time communication functions in your project. For details, see Start a Video Call or Start Interactive Video Streaming.
The orientationMode parameter provides three modes, ADAPTIVE, FIXED_LANDSCAPE, and FIXED_PORTRAIT for different user needs.
ADAPTIVE
In the ADAPTIVE mode, the output video always follows the orientation of the captured video, because the receiver takes the rotational information passed on from the video encoder. This mode is mainly used between Agora’s SDKs.
The following figures show the video orientations at the video capturer and player when a rear camera is used as the video capturer. Note that the video orientation differs according to the UI lock of your app.
UI lock (or UI unlock with the app disabling the screen auto-rotation)
The relative position of the status bar remains the same as the screen and not according to the phone tilt (for example in WeChat). Therefore, the relative position of the video and the screen remains the same for the video capturer and the player.
For a landscape capturer:
For a portrait capturer:
UI unlock with the app enabling the screen auto-rotation
The status bar of the app remains horizontal, regardless of the orientation of the screen (for example in Facetime). Therefore, the relative position of the video and the phone tilt remains the same for the video capturer and the player.
For a landscape capturer:
For a portrait capturer:
FIXED_LANDSCAPE
In the Fixed_LANDSCAPE mode, the video capturer sends the video in the landscape orientation relative to the status bar. If the captured video is in portrait mode, the video encoder crops it to fit the output.
This mode applies to situations where the receiving end cannot process the rotational information. For example, Media Push.
The following figures show the video orientations at the video capturer and the player when a rear camera is used as the video capturer.
The captured video in the landscape mode (video cropping is not needed):
The captured video in the portrait mode (video cropping is needed):
FIXED_PORTRAIT
In the Fixed_PORTRAIT mode, the video capturer sends out the video in the portrait orientation relative to the status bar. If the captured video is in landscape mode, the video encoder crops it to fit the output.
This mode applies to situations where the receiving end cannot process the rotational information. For example, Media Push.
The following figures show the video orientations at the video capturer and the player when a rear camera is used as the video capturer.
The captured video in the portrait mode (video cropping is not needed):
The captured video in the landscape mode (video cropping is needed):
API reference
Considerations
Set the orientationMode parameter in the setVideoEncoderConfiguration method. For the API call sequence and sample code of this method, see Video Profiles.
