实时音视频 Android&iOS&HarmonyOS

本文将介绍如何调整移动端实时音视频（TRTC）视频画面方向。
功能介绍
在实时音视频（TRTC）场景中，视频画面旋转方向的处理直接影响用户体验。与手机直播千篇一律的竖屏体验不同，TRTC 需要兼顾横屏和竖屏两种场景，同时还要应对摄像头角度、设备旋转、StatusBar 位置等多种复杂因素。
本文详细介绍 TRTC SDK 提供的视频旋转方向控制功能，包括：
如何实现竖屏模式，例如：微信的视频通话就是一个典型的竖屏体验模式。
如何实现横屏模式，例如：多人音视频房间 App（类似小鱼易连）往往都是采用横屏模式。
如何自定义控制本地画面和远程画面的旋转方向和填充模式。
平台支持
iOS
Android
Mac
Windows
Electron
HarmonyOS
微信小程序
Web 端
✓
✓
✓
✓
✓
✓
×
×
前提条件
在进行视频画面方向配置之前，请确保您已在项目中成功集成并实现了基础的实时音视频功能。具体接入方法请参考：快速接入指南。
视频旋转模式
实时音视频（TRTC）提供了多种视频旋转模式，以适应不同的业务场景需求。这些模式主要处理采集端和播放端的视频方向适配问题。
竖屏模式
如果要实现类似微信视频通话的体验模式，需要做两项工作：
步骤1：配置 App 界面为竖屏模式
iOS 平台
Android 平台
HarmonyOS
可以直接在 Xcode 的 General > Deployment Info > Device Orientation 中进行设置：
﻿
﻿
您也可以通过实现 AppDelegate 中的 supportedInterfaceOrientationsForWindow 方法来达到相同目标：
- (UIInterfaceOrientationMask)application:(UIApplication *)application 
    supportedInterfaceOrientationsForWindow:(UIWindow *)window 
{
﻿
    return  UIInterfaceOrientationMaskPortrait ;
﻿
}
说明
CSDN 上有一篇文章 iOS 横竖屏旋转及其基本适配方法，详细介绍了 iOS 平台中关于屏幕方向的一些开发经验。
通过指定 activity 的 screenOrientation 属性为 portrait，即可指定该界面为竖屏模式：
<activity android:name=".trtc.TRTCMainActivity"  android:launchMode="singleTask" android:windowSoftInputMode="adjustPan"
          android:screenOrientation="portrait" />
通过指定 module.json5 的 abilities 配置的 orientation 属性为 portrait ，即可指定该界面为竖屏模式：
{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "orientation": "portrait",  // 竖屏模式
        // ... 其他配置
      }
    ]
  }
}
步骤2：配置 SDK 使用竖屏分辨率
﻿在使用
 TRTCCloud 的 setVideoEncoderParam 接口设置视频编码参数时，将 resMode 指定为 TRTCVideoResolutionModePortrait 即可。
示例代码如下：
字段名
类型
说明
﻿videoResolution﻿
﻿TRTCVideoResolution﻿
字段含义：视频分辨率。
特别说明：如需使用竖屏分辨率，请指定 resMode 为 Portrait，例如：  640 × 360 + Portrait = 360 × 640 。
推荐取值：
 手机视频通话：建议选择 360 × 640 及以下分辨率，resMode 选择 Portrait，即竖屏分辨率。
 手机在线直播：建议选择 540 × 960，resMode 选择 Portrait，即竖屏分辨率。
 桌面平台（Win + Mac）：建议选择 640 × 360 及以上分辨率，resMode 选择 Landscape，即横屏分辨率。
﻿videoBitrate﻿
int
字段含义：目标视频码率，SDK 会按照目标码率进行编码，只有在弱网络环境下才会主动降低视频码率。
推荐取值：请参见本 TRTCVideoResolution 在各档位注释的最佳码率，也可以在此基础上适当调高。例如：TRTCVideoResolution_1280_720 对应 1200kbps 的目标码率，您也可以设置为 1500kbps 用来获得更好的观感清晰度。
特别说明：您可以通过同时设置 videoBitrate 和 minVideoBitrate 两个参数，用于约束 SDK 对视频码率的调整范围：
1.1  如果您追求“弱网络下允许卡顿但要保持清晰”的效果，可以设置 minVideoBitrate 为 videoBitrate 的 60%。
1.2 如果您追求“弱网络下允许模糊但要保持流畅”的效果，可以设置 minVideoBitrate 为一个较低的数值（例如 100kbps）。
1.3 如果您将 videoBitrate 和 minVideoBitrate 设置为同一个值，等价于关闭 SDK 对视频码率的自适应调节能力。
﻿videoFps﻿
int
字段含义：视频采集帧率。
推荐取值：15 fps 或 20 fps。5 fps 以下，卡顿感明显。10 fps 以下，会有轻微卡顿感。20 fps 以上，会浪费带宽（电影的帧率为24fps）。
特别说明：部分 Android 手机的前置摄像头并不支持 15 fps 以上的采集帧率，部分主打美颜功能的 Android 手机的前置摄像头的采集帧率可能低于10fps。
﻿resMode/videoResolutionMode﻿
﻿TRTCVideoResolutionMode﻿
字段含义：分辨率模式（横屏分辨率 or 竖屏分辨率）。
推荐取值：手机平台（iOS、Android、HarmonyOS）建议选择 Portrait，桌面平台（Windows、Mac）建议选择 Landscape。
特别说明：如需使用竖屏分辨率，请指定 resMode 为 Portrait，例如：  640 × 360 + Portrait = 360 × 640 。
iOS
Android
HarmonyOS
TRTCVideoEncParam* encParam = [TRTCVideoEncParam new];
encParam.videoResolution = TRTCVideoResolution_960_540;
encParam.videoBitrate = 850;
encParam.videoFps = 15;
//设置分辨率模式为竖屏模式
encParam.resMode = TRTCVideoResolutionModePortrait; 
﻿
[trtc setVideoEncoderParam: encParam];
TRTCCloudDef.TRTCVideoEncParam encParam = new TRTCCloudDef.TRTCVideoEncParam();
encParam.videoResolution = TRTCCloudDef.TRTC_VIDEO_RESOLUTION_960_540;
encParam.videoBitrate = 850;
encParam.videoFps = 15;
//设置分辨率模式为竖屏模式
encParam.videoResolutionMode = TRTCCloudDef.TRTC_VIDEO_RESOLUTION_MODE_PORTRAIT; 
﻿
trtc.setVideoEncoderParam(encParam);
const encParam = new TRTCVideoEncParam(
  TRTCVideoResolution.TRTCVideoResolution_960_540,
  TRTCVideoResolutionMode.TRTCVideoResolutionModePortrait, //设置分辨率模式为竖屏模式
  15,                                                         
  850,
  0,
  false
);
trtc.setVideoEncoderParam(encParam); 
横屏模式
如果希望 App 是横屏体验，那么您需要做的工作跟竖屏模式类似，只是将第一步和第二步中的参数都进行相应的调整即可。
尤其是 步骤2 中，TRTCVideoEncParam 中的 resMode 值：
在 iOS 平台中应该指定为 TRTCVideoResolutionModeLandscape。
在 Android 平台中应该指定为 TRTC_VIDEO_RESOLUTION_MODE_LANDSCAPE。
在 HarmonyOS 平台应该指定为 TRTCVideoResolutionModeLandscape。
自定义控制
实时音视频（TRTC）本身提供了大量的接口函数可以操控本地和远程画面的旋转方向和填充模式：
接口函数
参数
字段名
描述
﻿setLocalRenderParams﻿
﻿TRTCCloudDef.TRTCRenderParams﻿
fillMode
字段含义：画面填充模式。
推荐取值：填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：TRTC_VIDEO_RENDER_MODE_FILL﻿。
﻿
﻿
mirrorType
字段含义：画面镜像模式。
推荐取值：默认值：TRTC_VIDEO_MIRROR_TYPE_AUTO﻿。
﻿
﻿
rotation
字段含义：图像的顺时针旋转角度。
推荐取值：支持 90、180 以及 270 旋转角度。默认值：TRTC_VIDEO_ROTATION_0﻿。
﻿setRemoteRenderParams﻿
﻿TRTCCloudDef.TRTCRenderParams﻿
fillMode
字段含义：画面填充模式。
推荐取值：填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：TRTC_VIDEO_RENDER_MODE_FILL﻿。
﻿
﻿
mirrorType
字段含义：画面镜像模式。
推荐取值：默认值：TRTC_VIDEO_MIRROR_TYPE_AUTO﻿。
﻿
﻿
rotation
字段含义：图像的顺时针旋转角度。
推荐取值：支持 90、180 以及 270 旋转角度。默认值：TRTC_VIDEO_ROTATION_0﻿。
﻿
userId
-
指定远端用户的 ID。
﻿
streamType
-
可以设置为主路画面（TRTC_VIDEO_STREAM_TYPE_BIG﻿）或辅路画面（﻿TRTC_VIDEO_STREAM_TYPE_SUB﻿）。
﻿
﻿
﻿
重力感应自适应模式（GSensorMode）
实时音视频（TRTC）提供了设置重力感应的适配模式（11.7 及以上版本）功能，通过 TRTCCloud#setGravitySensorAdaptiveMode 接口开启。
开启重力感应后，如果采集端的设备发生旋转，采集端和观众端的画面都会进行相应地渲染以确保视野中的画面始终朝上。
只在 SDK 内部摄像头采集场景生效，并且只在移动端生效。
1. 该接口仅对采集端起作用，如果只是观看房间中的画面，开启此接口是无效的。
2. 当采集端设备发生 90 度或 270 度旋转时，采集端或者观众看到的画面可能会被裁剪以保持比例的协调。
枚举
取值
描述
是否锁定竖屏
效果图（推流端/拉流竖屏/拉流横屏）
﻿TRTC_GRAVITY_SENSOR_ADAPTIVE_MODE_DISABLE﻿
0
关闭重力感应，根据当前采集分辨率与设置的编码分辨率决策，如果两者不一致，则通过旋转90度，保证最大画幅。默认取值。
UI 固定为竖屏
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
UI 不锁定
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿TRTC_GRAVITY_SENSOR_ADAPTIVE_MODE_FILL_BY_CENTER_CROP﻿
1
开启重力感应，始终保证远端画面图像为正，中间过程需要处理分辨率不一致时，采用居中裁剪模式。
UI 固定为竖屏
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
UI 不锁定
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿TRTC_GRAVITY_SENSOR_ADAPTIVE_MODE_FIT_WITH_BLACK_BORDER﻿
2
开启重力感应，始终保证远端画面图像为正，中间过程需要处理分辨率不一致时，采用叠加黑边模式。
UI 固定为竖屏
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿
UI 不锁定
﻿
﻿
﻿
﻿
﻿
﻿
﻿

iOS	Android	Mac	Windows	Electron	HarmonyOS	微信小程序	Web 端
✓	✓	✓	✓	✓	✓	×	×

字段名	类型	说明
videoResolution	TRTCVideoResolution	字段含义：视频分辨率。特别说明：如需使用竖屏分辨率，请指定 `resMode` 为 Portrait，例如： 640 × 360 + Portrait = 360 × 640 。推荐取值：手机视频通话：建议选择 360 × 640 及以下分辨率，`resMode` 选择 Portrait，即竖屏分辨率。手机在线直播：建议选择 540 × 960，resMode 选择 Portrait，即竖屏分辨率。桌面平台（Win + Mac）：建议选择 640 × 360 及以上分辨率，`resMode` 选择 Landscape，即横屏分辨率。
videoBitrate	int	字段含义：目标视频码率，SDK 会按照目标码率进行编码，只有在弱网络环境下才会主动降低视频码率。推荐取值：请参见本 `TRTCVideoResolution` 在各档位注释的最佳码率，也可以在此基础上适当调高。例如：`TRTCVideoResolution_1280_720` 对应 1200kbps 的目标码率，您也可以设置为 1500kbps 用来获得更好的观感清晰度。特别说明：您可以通过同时设置 `videoBitrate` 和 `minVideoBitrate` 两个参数，用于约束 SDK 对视频码率的调整范围： 1.1 如果您追求“弱网络下允许卡顿但要保持清晰”的效果，可以设置 `minVideoBitrate` 为 `videoBitrate` 的 60%。 1.2 如果您追求“弱网络下允许模糊但要保持流畅”的效果，可以设置 `minVideoBitrate` 为一个较低的数值（例如 100kbps）。 1.3 如果您将 `videoBitrate` 和 `minVideoBitrate` 设置为同一个值，等价于关闭 SDK 对视频码率的自适应调节能力。
videoFps	int	字段含义：视频采集帧率。推荐取值：15 fps 或 20 fps。5 fps 以下，卡顿感明显。10 fps 以下，会有轻微卡顿感。20 fps 以上，会浪费带宽（电影的帧率为24fps）。特别说明：部分 Android 手机的前置摄像头并不支持 15 fps 以上的采集帧率，部分主打美颜功能的 Android 手机的前置摄像头的采集帧率可能低于10fps。
resMode/videoResolutionMode	TRTCVideoResolutionMode	字段含义：分辨率模式（横屏分辨率 or 竖屏分辨率）。推荐取值：手机平台（iOS、Android、HarmonyOS）建议选择 Portrait，桌面平台（Windows、Mac）建议选择 Landscape。特别说明：如需使用竖屏分辨率，请指定 `resMode` 为 Portrait，例如： 640 × 360 + Portrait = 360 × 640 。

接口函数	参数	字段名	描述
setLocalRenderParams	TRTCCloudDef.TRTCRenderParams	fillMode	字段含义：画面填充模式。推荐取值：填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：TRTC_VIDEO_RENDER_MODE_FILL。
				mirrorType	字段含义：画面镜像模式。推荐取值：默认值：TRTC_VIDEO_MIRROR_TYPE_AUTO。
				rotation	字段含义：图像的顺时针旋转角度。推荐取值：支持 90、180 以及 270 旋转角度。默认值：TRTC_VIDEO_ROTATION_0。
setRemoteRenderParams	TRTCCloudDef.TRTCRenderParams	fillMode	字段含义：画面填充模式。推荐取值：填充（画面可能会被拉伸裁剪）或适应（画面可能会有黑边），默认值：TRTC_VIDEO_RENDER_MODE_FILL。
				mirrorType	字段含义：画面镜像模式。推荐取值：默认值：TRTC_VIDEO_MIRROR_TYPE_AUTO。
				rotation	字段含义：图像的顺时针旋转角度。推荐取值：支持 90、180 以及 270 旋转角度。默认值：TRTC_VIDEO_ROTATION_0。
		userId	-	指定远端用户的 ID。
		streamType	-	可以设置为主路画面（TRTC_VIDEO_STREAM_TYPE_BIG）或辅路画面（TRTC_VIDEO_STREAM_TYPE_SUB）。

枚举	取值	描述	是否锁定竖屏	效果图（推流端/拉流竖屏/拉流横屏）
TRTC_GRAVITY_SENSOR_ADAPTIVE_MODE_DISABLE	0	关闭重力感应，根据当前采集分辨率与设置的编码分辨率决策，如果两者不一致，则通过旋转90度，保证最大画幅。默认取值。	UI 固定为竖屏

					UI 不锁定

TRTC_GRAVITY_SENSOR_ADAPTIVE_MODE_FILL_BY_CENTER_CROP	1	开启重力感应，始终保证远端画面图像为正，中间过程需要处理分辨率不一致时，采用居中裁剪模式。	UI 固定为竖屏

					UI 不锁定

TRTC_GRAVITY_SENSOR_ADAPTIVE_MODE_FIT_WITH_BLACK_BORDER	2	开启重力感应，始终保证远端画面图像为正，中间过程需要处理分辨率不一致时，采用叠加黑边模式。	UI 固定为竖屏

					UI 不锁定

Android&iOS&HarmonyOS

本页目录：

功能介绍

平台支持

前提条件

视频旋转模式

竖屏模式

步骤1：配置 App 界面为竖屏模式

步骤2：配置 SDK 使用竖屏分辨率

横屏模式

自定义控制

重力感应自适应模式（GSensorMode）