# 设置视频编码属性 (/zh-CN/realtime-media/rtc/build/video/video-profile/harmonyos) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍如何调用声网提供的 API 设置视频编码属性。 ## 功能介绍 [#功能介绍-4] 视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。 声网 SDK 提供了 `setVideoEncoderConfiguration` 方法,用于设置视频编码属性。你可以在 `enableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。 ## 前提条件 [#前提条件-5] 在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。 ## 实现方法 [#实现方法-5] 你可以参考如下示例代码,在你的项目中设置各种视频编码参数: ```arkts let encoderConfig = new VideoEncoderConfiguration() encoderConfig.dimensions = new VideoDimensions(960, 540) encoderConfig.frameRate = 15 encoderConfig.orientationMode = OrientationMode.ORIENTATION_MODE_ADAPTIVE this.rtcEngine.setVideoEncoderConfiguration(encoderConfig) this.rtcEngine.enableVideo() ``` ## 开发注意事项 [#开发注意事项-5] - `setVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。 - `setVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。 ## 参考信息 [#参考信息-5] ### 示例项目 [#示例项目-4] 声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。 JoinVideoChannel.ets} href="https://gitee.com/agoraio-community/API-Examples/tree/main/HarmonyOS/APIExample/entry/src/main/ets/pages/basic/JoinVideoChannel.ets" /> JoinVideoChannel.ets} href="https://github.com/Shengwang-Community/API-Examples/tree/main/HarmonyOS/APIExample/entry/src/main/ets/pages/basic/JoinVideoChannel.ets" /> ### API 参考 [#api-参考-5] - [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#api_irtcengine_setvideoencoderconfiguration) - [`onVideoSizeChanged`](/zh-CN/api-reference/rtc/harmonyos/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged) ### 视频参数推荐值 [#视频参数推荐值-4] 通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点; 如果是一对四场景, 老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。 一般可按下列场景中的推荐值进行设置。 - 双人视频通话场景: - 分辨率 320 × 240,帧率 15 fps,码率 200 Kbps - 分辨率 640 × 360,帧率 15 fps,码率 400 Kbps - 一对多视频通话场景: - 分辨率 160 × 120,帧率 15 fps,码率 65 Kbps - 分辨率 320 × 180,帧率 15 fps,码率 140 Kbps - 分辨率 320 × 240,帧率 15 fps,码率 200 Kbps ### 分辨率、帧率和码率 [#分辨率帧率和码率-4] 视频编码属性的参数如下所示: - `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-4)了解如何设置视频输出的方向模式。 - `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。 - `minBitrate`:如果你对视频质量有特殊的需求,可以通过 `minBitrate` 参数进行设置。`minBitrate` 为视频最低编码码率 (Kbps)。声网 SDK 会根据网络条件进行码率自适应。将此参数设置为大于默认值时,会强制视频编码器输出高质量的视频图像,但可能会导致丢包率增高并影响视频播放的流畅度。 :::info[信息] - `minBitrate` 的默认值可以满足大多数实时场景的要求。一般情况下声网建议你不要更改默认值。 - 为获得高质量的视频,需要将分辨率、码率和帧率维持在相对平衡的状态。较高的分辨率需要较高的码率。在码率一定的情况下,过高的帧率会降低分辨率。 - 当视频因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时,取值会尽量接近最大值。 ::: 声网 SDK 提供了多种分辨率、帧率以供选择,你也可以根据下表自行定义。 :::warning[注意] 当你设置了分辨率和帧率后,SDK 会自动匹配相应的基准码率,声网不建议你自行修改码率。 ::: | 分辨率 (宽 × 高) | 帧率 (fps) | |------------------------|------------------| | 160 × 120 | 15 | | 120 × 120 | 15 | | 320 × 180 | 15 | | 180 × 180 | 15 | | 240 × 180 | 15 | | 320 × 240 | 15 | | 240 × 240 | 15 | | 424 × 240 | 15 | | 640 × 360 | 15 | | 360 × 360 | 15 | | 640 × 360 | 30 | | 360 × 360 | 30 | | 480 × 360 | 15 | | 480 × 360 | 30 | | 640 × 480 | 15 | | 480 × 480 | 15 | | 640 × 480 | 30 | | 480 × 480 | 30 | | 848 × 480 | 15 | | 848 × 480 | 30 | | 640 × 480 | 10 | | 960 × 540 | 15 | | 960 × 540 | 30 | | 1280 × 720 | 15 | | 1280 × 720 | 30 | | 960 × 720 | 15 | | 960 × 720 | 30 | | 1920 × 1080 | 15 | | 1920 × 1080 | 30 | | 1920 × 1080 | 60 | | 2560 × 1440 | 30 | | 2560 × 1440 | 60 | | 3840 × 2160 | 30 | | 3840 × 2160 | 60 | ### 视频模式 [#视频模式-4] 视频模式包括多种设置,你可以根据业务需求调整视频的方向、画质和镜像效果。 #### 旋转方向模式 [#旋转方向模式-4] 在视频旋转场景中,我们主要关注采集端和播放端的行为。其中: - 采集端采集视频并输出视频。即视频和 Status Bar 的相对位置。 - 播放端渲染接收到的视频图像,并根据接收到的旋转信息,结合自身 Status Bar 的相对位置旋转视频。 为防止视频因旋转出现大头、缩放或剪切的问题,声网 SDK 在 `setVideoEncoderConfiguration` 中提供了 `orientationMode` 参数。你可以通过这个参数,结合视频场景需要,获取想要的视频渲染效果。 `orientationMode` 参数提供了三种模式以适应不同的用户需求:`ORIENTATION_MODE_ADAPTIVE`、`ORIENTATION_MODE_FIXED_LANDSCAPE` 和 `ORIENTATION_MODE_FIXED_PORTRAIT`。 无论采取哪种模式,声网 SDK 都保证视频和 Status Bar 的相对位置在采集端和播放端始终一致。 **ORIENTATION_MODE_ADAPTIVE** 在 `ORIENTATION_MODE_ADAPTIVE` 模式下, SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景: 当使用后置摄像头采集视频时,视频采集器和播放器的视频方向如下图所示。请注意,视频方向因 UI 是否锁定而异。 **UI 锁定(或禁用 App 屏幕自动旋转)** Status Bar 与屏幕的相对方向保持一致,与手机重力感应无关(例如微信)。因此,视频和屏幕的相对位置在视频采集端和播放端始终一致。 - 采集端横屏时: ![../_images/rotation_adaptive_uilock_landscape.jpg](https://web-cdn.agora.io/docs-files/rotation_adaptive_uilock_landscape.jpg) - 采集端竖屏时: ![../_images/rotation_adaptive_uilock_portrait.jpg](https://web-cdn.agora.io/docs-files/rotation_adaptive_uilock_portrait.jpg) **UI 不锁定(启用 App 屏幕自动旋转)** 无论屏幕的方向如何(例如,在 Facetime 中),App 中的 Status Bar 始终在水平方向。因此,视频和重力的相对方向在采集端和播放端始终一致。 - 采集端横屏时: ![../_images/rotation_adaptive_uiunlock_landscape.jpg](https://web-cdn.agora.io/docs-files/rotation_adaptive_uiunlock_landscape.jpg) - 采集端竖屏时: ![UI 不锁定且采集端竖屏](https://web-cdn.agora.io/docs-portal/img/rtc/videoprofile/rotation_adaptive_uiunlock_portrait.png) **ORIENTATION_MODE_FIXED_LANDSCAPE** 在 `ORIENTATION_MODE_FIXED_LANDSCAPE` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。 当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。 - 横向模式下采集的视频(不需要视频裁剪): ![../_images/rotation_fixed_landscape.jpg](https://web-cdn.agora.io/docs-files/rotation_fixed_landscape.jpg) - 竖屏模式下采集的视频(需要视频裁剪): ![../_images/rotation_fixed_landscape_cut.jpg](https://web-cdn.agora.io/docs-files/rotation_fixed_landscape_cut.jpg) **ORIENTATION_MODE_FIXED_PORTRAIT** 在 `ORIENTATION_MODE_FIXED_PORTRAIT` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。 当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。 - 采集到的视频是竖屏模式(不需要视频裁剪): ![../_images/rotation_fixed_portrait.jpg](https://web-cdn.agora.io/docs-files/rotation_fixed_portrait.jpg) - 采集到的视频是横屏模式(需要视频裁剪): ![../_images/rotation_fixed_portrait_cut.jpg](https://web-cdn.agora.io/docs-files/rotation_fixed_portrait_cut.jpg) #### 降级偏好 [#降级偏好-4] 为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。 #### 镜像模式 [#镜像模式-4] 默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。