# 设置视频编码属性 (/zh-CN/realtime-media/rtc/build/video/video-profile)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" />
## 功能介绍 [#功能介绍]
本文介绍如何调用声网提供的 API 设置视频编码属性。视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `setVideoEncoderConfiguration` 方法,用于设置视频编码属性。你可以在 `enableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。
## 前提条件 [#前提条件]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法]
你可以参考如下示例代码,在你的项目中设置各种视频编码参数:
```java
// 根据用户在界面的选择设置视频编码的分辨率、帧率、码率与横竖屏方向模式
VideoEncoderConfiguration.VideoDimensions value = VD_640x360;
try {
Field tmp = VideoEncoderConfiguration.class.getDeclaredField(dimension.getSelectedItem(toString());
tmp.setAccessible(true);
value = (VideoEncoderConfiguration.VideoDimensions) tmp.get(null);
} catch (NoSuchFieldException e) {
Log.e("Field", "Can not find field " + dimension.getSelectedItem().toString());
} catch (IllegalAccessException e) {
Log.e("Field", "Could not access field " + dimension.getSelectedItem().toString());
}
engine.setVideoEncoderConfiguration(new VideoEncoderConfiguration(
value,
VideoEncoderConfiguration.FRAME_RATE.valueOf(framerate.getSelectedItem().toString()),
Integer.valueOf(et_bitrate.getText().toString()),
VideoEncoderConfiguration.ORIENTATION_MODE.valueOf(orientation.getSelectedItem().toStri())
));
```
## 开发注意事项 [#开发注意事项]
- `setVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `setVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
## 参考信息 [#参考信息]
### 示例项目 [#示例项目]
声网提供了开源的实时音视频互动示例项目供你参考,你可以前往下载或查看其中的源代码。
JoinChannelVideo} href="https://gitee.com/agoraio-community/API-Examples/blob/main/Android/APIExample/app/src/main/java/io/agora/api/example/examples/basic/JoinChannelVideo.java" />
JoinChannelVideo} href="https://github.com/Shengwang-Community/API-Examples/blob/main/Android/APIExample/app/src/main/java/io/agora/api/example/examples/basic/JoinChannelVideo.java" />
### API 参考 [#api-参考]
- [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/android/video/video-basic#api_irtcengine_setvideoencoderconfiguration)
- [`onVideoSizeChanged`](/zh-CN/api-reference/rtc/android/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged)
### 视频参数推荐值 [#视频参数推荐值]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点; 如果是一对四场景, 老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式)了解如何设置视频输出的方向模式。
- `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。
- `bitrate`:视频编码码率 (Kbps)。默认值为 `STANDARD_BITRATE`,即标准码率模式。在标准码率模式下,SDK 会根据已设置的频道场景、分辨率和帧率为你设置一个合适的码率。
- `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 |
### 视频模式 [#视频模式]
视频模式包括多种设置,你可以根据业务需求调整视频的方向、画质和镜像效果。
#### 旋转方向模式 [#旋转方向模式]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频。即视频和 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 与屏幕的相对方向保持一致,与手机重力感应无关(例如微信)。因此,视频和屏幕的相对位置在视频采集端和播放端始终一致。
- 采集端横屏时:

- 采集端竖屏时:

**UI 不锁定(启用 App 屏幕自动旋转)**
无论屏幕的方向如何(例如,在 Facetime 中),App 中的 Status Bar 始终在水平方向。因此,视频和重力的相对方向在采集端和播放端始终一致。
- 采集端横屏时:

- 采集端竖屏时:

**ORIENTATION_MODE_FIXED_LANDSCAPE**
在 `ORIENTATION_MODE_FIXED_LANDSCAPE` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。
- 横向模式下采集的视频(不需要视频裁剪):

- 竖屏模式下采集的视频(需要视频裁剪):

**ORIENTATION_MODE_FIXED_PORTRAIT**
在 `ORIENTATION_MODE_FIXED_PORTRAIT` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。
- 采集到的视频是竖屏模式(不需要视频裁剪):

- 采集到的视频是横屏模式(需要视频裁剪):

#### 降级偏好 [#降级偏好]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" />
本文介绍如何调用声网提供的 API 设置视频编码属性。
## 功能介绍 [#功能介绍-1]
视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `setVideoEncoderConfiguration` 方法,用于设置视频编码属性。你可以在 `enableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。
## 前提条件 [#前提条件-1]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-1]
你可以参考如下示例代码,在你的项目中设置各种视频编码参数:
```swift
// 根据用户在界面的选择设置视频编码的分辨率、帧率、码率与横竖屏方向模式
let resolution = configs["resolution"] as? CGSize,
let fps = configs["fps"] as? Int,
let orientation = config["orientation"] as? AgoraVideoOutputOrientationMode else {return}
agoraKit.setVideoEncoderConfiguration(AgoraVideoEncoderConfiguration(size: resolution,
frameRate: AgoraVideoFrameRate(rawValue: fps) ?? .fps15,
bitrate: AgoraVideoBitrateStandard,
orientationMode: orientation))
```
## 开发注意事项 [#开发注意事项-1]
- `setVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `setVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
## 参考信息 [#参考信息-1]
### 示例项目 [#示例项目-1]
声网提供了开源的实时音视频互动示例项目供你参考,你可以前往下载或查看其中的源代码。
JoinChannelVideo} href="https://gitee.com/agoraio-community/API-Examples/blob/main/iOS/APIExample/APIExample/Examples/Basic/JoinChannelVideo/JoinChannelVideo.swift" />
JoinChannelVideo} href="https://github.com/Shengwang-Community/API-Examples/tree/main/iOS/APIExample/APIExample/Examples/Basic/JoinChannelVideo" />
### API 参考 [#api-参考-1]
- [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/ios/video/video-basic#api_irtcengine_setvideoencoderconfiguration)
- [`videoSizeChangedOfSourceType`](/zh-CN/api-reference/rtc/ios/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged)
### 视频参数推荐值 [#视频参数推荐值-1]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点; 如果是一对四场景, 老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率-1]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-1)了解如何设置视频输出的方向模式。
- `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。
- `bitrate`:视频编码码率 (Kbps)。默认值为 `AgoraVideoBitrateStandard`,即标准码率模式。在标准码率模式下,SDK 会根据已设置的频道场景、分辨率和帧率为你设置一个合适的码率。
- `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 |
### 视频模式 [#视频模式-1]
视频模式包括多种设置,你可以根据业务需求调整视频的方向、画质和镜像效果。
#### 旋转方向模式 [#旋转方向模式-1]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频。即视频和 Status Bar 的相对位置。
- 播放端渲染接收到的视频图像,并根据接收到的旋转信息,结合自身 Status Bar 的相对位置旋转视频。
为防止视频因旋转出现大头、缩放或剪切的问题,声网 SDK 在 `setVideoEncoderConfiguration` 中提供了 `orientationMode` 参数。你可以通过这个参数,结合视频场景需要,获取想要的视频渲染效果。
`orientationMode` 参数提供了三种模式以适应不同的用户需求:`Adaptive`, `FixedLandscape`, 和 `FixedPortrait`。
无论采取哪种模式,声网 SDK 都保证视频和 Status Bar 的相对位置在采集端和播放端始终一致。
**Adaptive**
在 `Adaptive` 模式下, SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景。
当使用后置摄像头采集视频时,视频采集器和播放器的视频方向如下图所示。请注意,视频方向因 UI 是否锁定而异。
**UI 已锁定(或禁用 App 屏幕自动旋转)**
Status Bar 与屏幕的相对方向保持一致,与手机重力感应无关(例如微信)。因此,视频和屏幕的相对位置在视频采集端和播放端始终一致。
- 采集端横屏时:

- 采集端竖屏时:

**UI 不锁定(启用 App 屏幕自动旋转)**
无论屏幕的方向如何(例如,在 Facetime 中),App 中的 Status Bar 始终在水平方向。因此,视频和重力的相对方向在采集端和播放端始终一致。
- 采集端横屏时:

- 采集端竖屏时:

**FixedLandscape**
在 `FixedLandscape` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。
- 横向模式下采集的视频(不需要视频裁剪):

- 竖屏模式下采集的视频(需要视频裁剪):

**FixedPortrait**
在 `FixedPortrait` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。
- 采集到的视频是竖屏模式(不需要视频裁剪):

- 采集到的视频是横屏模式(需要视频裁剪):

#### 降级偏好 [#降级偏好-1]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-1]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="macos" />
本文介绍如何调用声网提供的 API 设置视频编码属性。
## 功能介绍 [#功能介绍-2]
视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `setVideoEncoderConfiguration` 方法,用于设置视频编码属性。你可以在 `enableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。
## 前提条件 [#前提条件-2]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-2]
你可以参考如下示例代码,在你的项目中设置各种视频编码参数:
```swift
// 根据用户在界面的选择设置视频编码的分辨率、帧率、码率与横竖屏方向模式
let resolution = configs["resolution"] as? CGSize,
let fps = configs["fps"] as? Int,
let orientation = config["orientation"] as? AgoraVideoOutputOrientationMode else {return}
agoraKit.setVideoEncoderConfiguration(AgoraVideoEncoderConfiguration(size: resolution,
frameRate: AgoraVideoFrameRate(rawValue: fps) ?? .fps15,
bitrate: AgoraVideoBitrateStandard,
orientationMode: orientation))
```
## 开发注意事项 [#开发注意事项-2]
- `setVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `setVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
## 参考信息 [#参考信息-2]
### 示例项目 [#示例项目-2]
声网提供了开源的实时音视频互动示例项目供你参考,你可以前往下载或查看其中的源代码。
JoinChannelVideo} href="https://gitee.com/agoraio-community/API-Examples/blob/main/macOS/APIExample/Examples/Basic/JoinChannelVideo" />
JoinChannelVideo} href="https://github.com/Shengwang-Community/API-Examples/blob/main/macOS/APIExample/Examples/Basic/JoinChannelVideo" />
### API 参考 [#api-参考-2]
- [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_setvideoencoderconfiguration)
- [`videoSizeChangedOfSourceType`](/zh-CN/api-reference/rtc/macos/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged)
### 视频参数推荐值 [#视频参数推荐值-2]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点; 如果是一对四场景, 老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率-2]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-2)了解如何设置视频输出的方向模式。
- `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。
- `bitrate`:视频编码码率 (Kbps)。默认值为 `AgoraVideoBitrateStandard`,即标准码率模式。在标准码率模式下,SDK 会根据已设置的频道场景、分辨率和帧率为你设置一个合适的码率。
- `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 |
### 视频模式 [#视频模式-2]
视频模式包括多种设置,你可以根据业务需求调整视频的方向、画质和镜像效果。
#### 旋转方向模式 [#旋转方向模式-2]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频。即视频和 Status Bar 的相对位置。
- 播放端渲染接收到的视频图像,并根据接收到的旋转信息,结合自身 Status Bar 的相对位置旋转视频。
为防止视频因旋转出现大头、缩放或剪切的问题,声网 SDK 在 `setVideoEncoderConfiguration` 中提供了 `orientationMode` 参数。你可以通过这个参数,结合视频场景需要,获取想要的视频渲染效果。
`orientationMode` 参数提供了三种模式以适应不同的用户需求:`Adaptive`, `FixedLandscape`, 和 `FixedPortrait`。
无论采取哪种模式,声网 SDK 都保证视频和 Status Bar 的相对位置在采集端和播放端始终一致。
**Adaptive**
在 `Adaptive` 模式下, SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景。
**FixedLandscape**
在 `FixedLandscape` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。
- 横向模式下采集的视频(不需要视频裁剪):

- 竖屏模式下采集的视频(需要视频裁剪):

**FixedPortrait**
在 `FixedPortrait` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。
- 采集到的视频是竖屏模式(不需要视频裁剪):

- 采集到的视频是横屏模式(需要视频裁剪):

#### 降级偏好 [#降级偏好-2]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-2]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" />
你可以根据终端用户的设备、浏览器、网络状况和实际应用场景设置视频属性,调整视频的清晰度和流畅度,从而获得较高的用户体验。
点击[在线体验](https://webdemo.agora.io/example/advanced/adjustVideoProfile/index.html)试用设置视频属性功能。
## 前提条件 [#前提条件-3]
开始前,请确保你已参考[快速开始](/zh-CN/realtime-media/rtc/get-started/quick-start)在你的项目中实现基本的实时音视频功能。
## 实现方法 [#实现方法-3]
声网 Web SDK 提供两种方式设置视频属性:
- 在创建视频轨道时设置:
- 调用 `AgoraRTC.createCameraVideoTrack` 创建摄像头视频轨道时,通过修改 `encoderConfig` 参数设置使用 SDK 预设值或者自定义配置。
- 调用 `AgoraRTC.createScreenVideoTrack` 创建屏幕共享视频轨道时,通过修改 `encoderConfig` 参数设置使用 SDK 预设值或者自定义配置。
- 调用 `AgoraRTC.createCustomVideoTrack` 创建自定义视频轨道时,通过修改 `bitrateMax`、`bitrateMin` 参数设置码率。自 v4.17.1 起,还可以通过 `width`、`height`、`frameRate` 参数设置分辨率和帧率。
- 创建视频轨道后动态调整(发布前和发布后都支持):
- 摄像头视频轨道可以调用 `CameraVideoTrack.setEncoderConfiguration` 动态调整视频属性。
- 自 v4.17.1 起,屏幕共享视频轨道和自定义视频轨道也可以调用 `LocalVideoTrack.setEncoderConfiguration` 动态调整视频属性。
以摄像头视频轨道为例:
**创建时使用预设视频编码属性**
```javascript
AgoraRTC.createCameraVideoTrack({
encoderConfig: "720p_1",
}).then(localVideoTrack => { /** ... **/ });
```
SDK 支持的预设视频属性可参考下方的[分辨率和浏览器对照表](#preset-video-profiles)。SDK 默认的视频属性为 `"480p_1"`。
**创建时自定义视频编码属性**
```javascript
AgoraRTC.createCameraVideoTrack({
encoderConfig: {
width: 640,
// 支持指定一个范围和参考值,具体配置参考相关 API 文档
height: { ideal: 480, min: 400, max: 500 },
frameRate: 15,
bitrateMin: 600, bitrateMax: 1000,
},
}).then(localVideoTrack => {/** ... **/ });
```
**创建后通过预设值动态调整视频编码属性**
```javascript
CameraVideoTrack.setEncoderConfiguration("480p_1").then(() => { /** ... **/ })
```
**创建后动态调整自定义视频编码属性**
```javascript
CameraVideoTrack.setEncoderConfiguration({ width: 1280, height: 720 }).then(() => { /** ... **/ })
```
## 参考信息 [#参考信息-3]
### 开发注意事项 [#开发注意事项-3]
- 不同的浏览器对分辨率的支持可能不同,具体的支持情况详见[分辨率和浏览器对照表](#preset-video-profiles)。
- 由于部分浏览器的限制,用户通过 SDK 设置的分辨率有一定概率与实际采集的分辨率不符。当浏览器不支持用户设置的分辨率时,计量计费会以实际采集的分辨率为准,实际采集的分辨率有可能大于或者小于设置的分辨率。
- 视频能否达到 1080p 以上的分辨率取决于设备的性能,在性能配备较低的设备上有可能无法实现。如果采用 720p 分辨率而设备性能跟不上,则有可能出现帧率过低的情况。
- Safari 浏览器视频帧率为 30 fps,不支持自定义视频帧率。
- 动态修改视频属性仅支持 Chrome 63 及以上版本和 Safari 11 及以上版本。在部分 iOS 设备上动态修改视频属性可能会导致视频出现黑边。
### API 参考 [#api-参考-3]
- [`AgoraRTC.createCameraVideoTrack`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#createcameravideotrack)
- [`AgoraRTC.createScreenVideoTrack`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#createscreenvideotrack)
- [`AgoraRTC.createCustomVideoTrack`](/zh-CN/api-reference/rtc/web/interfaces/iagorartc#createcustomvideotrack)
- [`LocalVideoTrack.setEncoderConfiguration`](/zh-CN/api-reference/rtc/web/interfaces/ilocalvideotrack#setencoderconfiguration)
### 常用分辨率、帧率和码率 [#常用分辨率帧率和码率]
通常来讲,视频属性的选择要根据产品实际情况来确定,比如,如果是一对一场景,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点;如果是一对四场景,老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按以下场景推荐值进行设置。
- 2 人视频通话场景:
- 分辨率 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
### 分辨率和浏览器对照表 [#分辨率和浏览器对照表]
下表列出了 SDK 预设的视频属性配置,以及在各浏览器上的支持情况。你可以参考下表进行自定义设置。
| 视频属性 | 分辨率(宽×高) | 帧率 (fps) | Chrome | Firefox | Safari |
| -------- | --------------- | ----------- | ------------ | --------- | -------- |
| 120p | 160 × 120 | 15 | ✔ | - | - |
| 120p_1 | 160 × 120 | 15 | ✔ | - | ✔ |
| 120p_3 | 120 × 120 | 15 | ✔ | - | - |
| 180p | 320 × 180 | 15 | ✔ | - | - |
| 180p_1 | 320 × 180 | 15 | ✔ | - | - |
| 180p_3 | 180 × 180 | 15 | ✔ | - | - |
| 180p_4 | 240 × 180 | 15 | ✔ | - | ✔ |
| 240p | 320 × 240 | 15 | ✔ | - | - |
| 240p_1 | 320 × 240 | 15 | ✔ | - | ✔ |
| 240p_3 | 240 × 240 | 15 | ✔ | - | - |
| 240p_4 | 424 × 240 | 15 | ✔ | - | - |
| 360p | 640 × 360 | 15 | ✔ | - | - |
| 360p_1 | 640 × 360 | 15 | ✔ | - | - |
| 360p_3 | 360 × 360 | 15 | ✔ | - | - |
| 360p_4 | 640 × 360 | 30 | ✔ | - | - |
| 360p_6 | 360 × 360 | 30 | ✔ | - | - |
| 360p_7 | 480 × 360 | 15 | ✔ | - | ✔ |
| 360p_8 | 480 × 360 | 30 | ✔ | - | - |
| 360p_9 | 640 × 360 | 15 | ✔ | - | - |
| 360p_10 | 640 × 360 | 24 | ✔ | - | - |
| 360p_11 | 640 × 360 | 24 | ✔ | - | - |
| 480p | 640 × 480 | 15 | ✔ | ✔ | ✔ |
| 480p_1 | 640 × 480 | 15 | ✔ | ✔ | ✔ |
| 480p_2 | 640 × 480 | 30 | ✔ | ✔ | ✔ |
| 480p_3 | 480 × 480 | 15 | ✔ | ✔ | ✔ |
| 480p_4 | 640 × 480 | 30 | ✔ | ✔ | ✔ |
| 480p_6 | 480 × 480 | 30 | ✔ | ✔ | ✔ |
| 480p_8 | 848 × 480 | 15 | ✔ | ✔ | ✔ |
| 480p_9 | 848 × 480 | 30 | ✔ | ✔ | ✔ |
| 480p_10 | 640 × 480 | 10 | ✔ | ✔ | ✔ |
| 720p | 1280 × 720 | 15 | ✔ | ✔ | ✔ |
| 720p_1 | 1280 × 720 | 15 | ✔ | ✔ | ✔ |
| 720p_2 | 1280 × 720 | 30 | ✔ | ✔ | ✔ |
| 720p_3 | 1280 × 720 | 30 | ✔ | ✔ | ✔ |
| "720p_auto" ① | 1280 × 720 | 30 | ✔ | ✔ | ✔ |
| 720p_5 | 960 × 720 | 15 | ✔ | ✔ | ✔ |
| 720p_6 | 960 × 720 | 30 | ✔ | ✔ | ✔ |
| 1080p | 1920 × 1080 | 15 | ✔ | - | ✔ |
| 1080p_1 | 1920 × 1080 | 15 | ✔ | - | ✔ |
| 1080p_2 | 1920 × 1080 | 30 | ✔ | - | ✔ |
| 1080p_3 | 1920 × 1080 | 30 | ✔ | - | ✔ |
| 1080p_5 | 1920 × 1080 | 60 | ✔ | - | ✔ |
:::warning[注意]
① `"720p_auto"` 仅推荐在 Safari 上设置,用于确保能够动态调整编码分辨率,详见[发版说明](/zh-CN/realtime-media/rtc/reference/release-notes)。
:::
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="windows" />
本文介绍如何调用声网提供的 API 设置视频编码属性。
## 功能介绍 [#功能介绍-3]
视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `setVideoEncoderConfiguration` 方法设置视频编码属性。你可以在 `enableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。
## 前提条件 [#前提条件-4]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-4]
你可以参考如下示例代码,在你的项目中设置各种视频编码参数:
```cpp
// 创建视频编码配置对象
VideoEncoderConfiguration videoConfig;
// 设置视频宽度
videoConfig.dimensions.width = 1280;
// 设置视频高度
videoConfig.dimensions.height = 720;
// 设置帧率为15 fps
videoConfig.frameRate = FRAME_RATE_FPS_15;
// 设置码率为800 Kbps
videoConfig.bitrate = 800 * 1000;
// 设置旋转方向模式为 ADAPTIVE
videoConfig.orientationMode = ORIENTATION_MODE_ADAPTIVE;
// 设置降级偏好为 MAINTAIN_QUALITY
videoConfig.degradationPreference = MAINTAIN_QUALITY;
// 应用视频编码配置
rtcEngine->setVideoEncoderConfiguration(videoConfig);
```
## 开发注意事项 [#开发注意事项-4]
- `setVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `setVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
## 参考信息 [#参考信息-4]
### 示例项目 [#示例项目-3]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
JoinChannelVideo} href="https://gitee.com/agoraio-community/API-Examples/tree/main/windows/APIExample/APIExample/Basic/LiveBroadcasting" />
JoinChannelVideo} href="https://github.com/Shengwang-Community/API-Examples/tree/main/windows/APIExample/APIExample/Basic/LiveBroadcasting" />
### API 参考 [#api-参考-4]
- [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_setvideoencoderconfiguration)
- [`onVideoSizeChanged`](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged)
### 视频参数推荐值 [#视频参数推荐值-3]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点;如果是一对四场景,老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率-3]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-3)了解如何设置视频输出的方向模式。
- `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。
- `bitrate`:视频编码码率 (Kbps)。默认值为 `STANDARD_BITRATE`,即标准码率模式。在标准码率模式下,SDK 会根据已设置的频道场景、分辨率和帧率为你设置一个合适的码率。
- `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 |
### 视频模式 [#视频模式-3]
视频模式包括多种设置,你可以根据业务需求调整视频的方向、画质和镜像效果。
#### 旋转方向模式 [#旋转方向模式-3]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频。即视频和 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 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景:
- 如果采集的视频是横屏模式,则输出的视频也是横屏模式。
- 如果采集的视频是竖屏模式,则输出的视频也是竖屏模式。
**ORIENTATION_MODE_FIXED_LANDSCAPE**
在 `ORIENTATION_MODE_FIXED_LANDSCAPE` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
**ORIENTATION_MODE_FIXED_PORTRAIT**
在 `ORIENTATION_MODE_FIXED_PORTRAIT` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
#### 降级偏好 [#降级偏好-3]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-3]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="harmonyos" />
本文介绍如何调用声网提供的 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 与屏幕的相对方向保持一致,与手机重力感应无关(例如微信)。因此,视频和屏幕的相对位置在视频采集端和播放端始终一致。
- 采集端横屏时:

- 采集端竖屏时:

**UI 不锁定(启用 App 屏幕自动旋转)**
无论屏幕的方向如何(例如,在 Facetime 中),App 中的 Status Bar 始终在水平方向。因此,视频和重力的相对方向在采集端和播放端始终一致。
- 采集端横屏时:

- 采集端竖屏时:

**ORIENTATION_MODE_FIXED_LANDSCAPE**
在 `ORIENTATION_MODE_FIXED_LANDSCAPE` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。
- 横向模式下采集的视频(不需要视频裁剪):

- 竖屏模式下采集的视频(需要视频裁剪):

**ORIENTATION_MODE_FIXED_PORTRAIT**
在 `ORIENTATION_MODE_FIXED_PORTRAIT` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。
- 采集到的视频是竖屏模式(不需要视频裁剪):

- 采集到的视频是横屏模式(需要视频裁剪):

#### 降级偏好 [#降级偏好-4]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-4]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="electron" />
本文介绍如何调用声网提供的 API 设置视频编码属性。
## 功能介绍 [#功能介绍-5]
视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `setVideoEncoderConfiguration` 方法,用于设置视频编码属性。你可以在 `enableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。
## 前提条件 [#前提条件-6]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-6]
你可以参考如下示例代码,在你的项目中设置各种视频编码参数:
```typescript
// 视频编码参数配置
this.engine?.setVideoEncoderConfiguration({
// 设置视频编码类型为 H264
codecType: VideoCodecType.VideoCodecH264,
// 设置视频编码的分辨率为 640 x 360 (px)
dimensions: {
width: 640,
height: 360,
},
// 设置帧率为 15 fps
frameRate: 15,
// 设置码率模式为 StandardBitrate
bitrate: 0,
// 设置最低编码码率为 1 Kbps
minBitrate: -1,
// 设置旋转方向模式为 Adaptive
orientationMode: OrientationMode.OrientationModeAdaptive,
// 设置降级偏好为 MaintainQuality
degradationPreference: DegradationPreference.MaintainQuality,
// 禁用发送编码视频时的镜像模式
mirrorMode: VideoMirrorModeType.VideoMirrorModeDisabled,
});
```
## 开发注意事项 [#开发注意事项-6]
- `setVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `setVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
## 参考信息 [#参考信息-6]
### API 参考 [#api-参考-6]
- [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/electron/video/video-basic#api_irtcengine_setvideoencoderconfiguration)
### 视频参数推荐值 [#视频参数推荐值-5]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点; 如果是一对四场景, 老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率-5]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-5)了解如何设置视频输出的方向模式。
- `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。
- `bitrate`:视频编码码率 (Kbps)。默认值为 `STANDARD_BITRATE`,即标准码率模式。在标准码率模式下,SDK 会根据已设置的频道场景、分辨率和帧率为你设置一个合适的码率。
- `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 |
### 视频模式 [#视频模式-5]
#### 旋转方向模式 [#旋转方向模式-5]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频。即视频和 Status Bar 的相对位置。
- 播放端渲染接收到的视频图像,并根据接收到的旋转信息,结合自身 Status Bar 的相对位置旋转视频。
为防止视频因旋转出现大头、缩放或剪切的问题,声网 SDK 在 `setVideoEncoderConfiguration` 中提供了 `orientationMode` 参数。你可以通过这个参数,结合视频场景需要,获取想要的视频渲染效果。
`orientationMode` 参数提供了三种模式以适应不同的用户需求:`OrientationModeAdaptive`、`OrientationModeFixedLandscape` 和 `OrientationModeFixedPortrait`。
无论采取哪种模式,声网 SDK 都保证视频和 Status Bar 的相对位置在采集端和播放端始终一致。
**OrientationModeAdaptive**
在 `OrientationModeAdaptive` 模式下, SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景:
- 如果采集的视频是横屏模式,则输出的视频也是横屏模式。
- 如果采集的视频是竖屏模式,则输出的视频也是竖屏模式。
**OrientationModeFixedLandscape**
在 `OrientationModeFixedLandscape` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
**OrientationFixedPortrait**
在 `OrientationFixedPortrait` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
#### 降级偏好 [#降级偏好-5]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-5]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="unity" />
本文介绍如何调用声网提供的 API 设置视频编码属性。
## 功能介绍 [#功能介绍-6]
在视频通话或视频互动直播场景下,视频画面是否清晰流畅,很大程度上决定了用户体验。
视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `SetVideoEncoderConfiguration` 方法设置视频编码属性。此方法可以在初始化 `IRtcEngine` 后的任何阶段(加入频道之前或之后)调用。
如果在加入频道后不需要重新设置视频编码属性,声网建议在 `EnableVideo` 前调用 `SetVideoEncoderConfiguration`,以加快首帧出图的时间。
## 前提条件 [#前提条件-7]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-7]
你可以参考如下示例代码,在你的项目中设置各种视频编码参数:
```csharp
// 视频编码参数配置
VideoEncoderConfiguration config = new VideoEncoderConfiguration
{
// 设置视频编码的分辨率 (px)
dimensions = _dimensions[dim],
// 设置帧率为 15 fps
frameRate = 15,
// 设置码率模式为 STANDARD_BITRATE
bitrate = 0,
// 设置最低编码码率为 1 Kbps
minBitrate = 1,
// 设置旋转方向模式为 ADAPTIVE
orientationMode = ORIENTATION_MODE.ORIENTATION_MODE_ADAPTIVE,
// 设置降级偏好为 MAINTAIN_FRAMERATE
degradationPreference = DEGRADATION_PREFERENCE.MAINTAIN_FRAMERATE,
// 设置发送编码视频时的镜像模式为 AUTO
mirrorMode = VIDEO_MIRROR_MODE_TYPE.VIDEO_MIRROR_MODE_AUTO
};
// 设置视频编码属性
RtcEngine.SetVideoEncoderConfiguration(config);
```
## 参考信息 [#参考信息-7]
### 开发注意事项 [#开发注意事项-7]
- `SetVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `SetVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
### 示例项目 [#示例项目-5]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### 视频参数推荐值 [#视频参数推荐值-6]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点;如果是一对四场景,老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率-6]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-6)了解如何设置视频输出的方向模式。
- `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。
- `bitrate`:视频编码码率 (Kbps)。默认值为 `STANDARD_BITRATE`,即标准码率模式。在标准码率模式下,SDK 会根据已设置的频道场景、分辨率和帧率为你设置一个合适的码率。
- `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 |
### 视频模式 [#视频模式-6]
视频模式包括多种设置,你可以根据业务需求调整视频的方向、画质和镜像效果。
#### 旋转方向模式 [#旋转方向模式-6]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频。即视频和 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 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景:
- 如果采集的视频是横屏模式,则输出的视频也是横屏模式。
- 如果采集的视频是竖屏模式,则输出的视频也是竖屏模式。
**ORIENTATION_MODE_FIXED_LANDSCAPE**
在 `ORIENTATION_MODE_FIXED_LANDSCAPE` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
**ORIENTATION_MODE_FIXED_PORTRAIT**
在 `ORIENTATION_MODE_FIXED_PORTRAIT` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
#### 降级偏好 [#降级偏好-6]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-6]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="flutter" />
本文介绍如何调用声网提供的 API 设置视频编码属性。
## 功能介绍 [#功能介绍-7]
视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `setVideoEncoderConfiguration` 方法,用于设置视频编码属性。你可以在 `enableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。
## 前提条件 [#前提条件-8]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-8]
你可以参考如下示例代码,在你的项目中设置各种视频编码参数:
```dart
await _engine.setVideoEncoderConfiguration(
const VideoEncoderConfiguration(
dimensions: VideoDimensions(width: 1920, height: 1080), // 设置分辨率
frameRate: 15, // 设置帧率
bitrate: 800, // 设置码率
orientationMode: OrientationMode.orientationModeAdaptive, // 设置旋转方向模式
degradationPreference: DegradationPreference.maintainQuality, // 设置降级偏好
),
);
```
## 开发注意事项 [#开发注意事项-8]
- `setVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `setVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
## 参考信息 [#参考信息-8]
### API 参考 [#api-参考-7]
- [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/flutter/video/video-basic#api_irtcengine_setvideoencoderconfiguration)
### 视频参数推荐值 [#视频参数推荐值-7]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点; 如果是一对四场景, 老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率-7]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-7)了解如何设置视频输出的方向模式。
- `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。
- `bitrate`:视频编码码率 (Kbps)。默认值为 `standardBitrate`,即标准码率模式。在标准码率模式下,SDK 会根据已设置的频道场景、分辨率和帧率为你设置一个合适的码率。
- `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 |
### 视频模式 [#视频模式-7]
视频模式包括多种设置,你可以根据业务需求调整视频的方向、画质和镜像效果。
#### 旋转方向模式 [#旋转方向模式-7]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频。即视频和 Status Bar 的相对位置。
- 播放端渲染接收到的视频图像,并根据接收到的旋转信息,结合自身 Status Bar 的相对位置旋转视频。
为防止视频因旋转出现大头、缩放或剪切的问题,声网 SDK 在 `setVideoEncoderConfiguration` 中提供了 `orientationMode` 参数。你可以通过这个参数,结合视频场景需要,获取想要的视频渲染效果。
`orientationMode` 参数提供了三种模式以适应不同的用户需求:`orientationModeAdaptive`、`orientationModeFixedLandscape` 和 `orientationModeFixedPortrait`。
无论采取哪种模式,声网 SDK 都保证视频和 Status Bar 的相对位置在采集端和播放端始终一致。
**orientationModeAdaptive**
在 `orientationModeAdaptive` 模式下, SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景:
- 如果采集的视频是横屏模式,则输出的视频也是横屏模式。
- 如果采集的视频是竖屏模式,则输出的视频也是竖屏模式。
**orientationModeFixedLandscape**
在 `orientationModeFixedLandscape` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
**orientationModeFixedPortrait**
在 `orientationModeFixedPortrait` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
#### 降级偏好 [#降级偏好-7]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-7]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="react-native" />
本文介绍如何调用声网提供的 API 设置视频编码属性。
## 功能介绍 [#功能介绍-8]
视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `setVideoEncoderConfiguration` 方法,用于设置视频编码属性。你可以在 `enableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。
## 前提条件 [#前提条件-9]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-9]
你可以参考如下示例代码,在你的项目中设置各种视频编码参数:
```typescript
// 视频编码参数配置
this.engine?.setVideoEncoderConfiguration({
// 设置视频编码类型为 H264
codecType: VideoCodecType.VideoCodecH264,
// 设置视频编码的分辨率为 640 x 360 (px)
dimensions: {
width: 640,
height: 360,
},
// 设置帧率为 15 fps
frameRate: 15,
// 设置码率模式为 StandardBitrate
bitrate: 0,
// 设置最低编码码率为 1 Kbps
minBitrate: -1,
// 设置旋转方向模式为 Adaptive
orientationMode: OrientationMode.OrientationModeAdaptive,
// 设置降级偏好为 MaintainQuality
degradationPreference: DegradationPreference.MaintainQuality,
// 禁用发送编码视频时的镜像模式
mirrorMode: VideoMirrorModeType.VideoMirrorModeDisabled,
});
```
## 开发注意事项 [#开发注意事项-9]
- `setVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `setVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
## 参考信息 [#参考信息-9]
### API 参考 [#api-参考-8]
- [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/react-native/video/video-basic#api_irtcengine_setvideoencoderconfiguration)
### 视频参数推荐值 [#视频参数推荐值-8]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点; 如果是一对四场景, 老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率-8]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-8)了解如何设置视频输出的方向模式。
- `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。
- `bitrate`:视频编码码率 (Kbps)。默认值为 `STANDARD_BITRATE`,即标准码率模式。在标准码率模式下,SDK 会根据已设置的频道场景、分辨率和帧率为你设置一个合适的码率。
- `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 |
### 视频模式 [#视频模式-8]
#### 旋转方向模式 [#旋转方向模式-8]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频。即视频和 Status Bar 的相对位置。
- 播放端渲染接收到的视频图像,并根据接收到的旋转信息,结合自身 Status Bar 的相对位置旋转视频。
为防止视频因旋转出现大头、缩放或剪切的问题,声网 SDK 在 `setVideoEncoderConfiguration` 中提供了 `orientationMode` 参数。你可以通过这个参数,结合视频场景需要,获取想要的视频渲染效果。
`orientationMode` 参数提供了三种模式以适应不同的用户需求:`OrientationModeAdaptive`、`OrientationModeFixedLandscape` 和 `OrientationModeFixedPortrait`。
无论采取哪种模式,声网 SDK 都保证视频和 Status Bar 的相对位置在采集端和播放端始终一致。
**OrientationModeAdaptive**
在 `OrientationModeAdaptive` 模式下, SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景:
- 如果采集的视频是横屏模式,则输出的视频也是横屏模式。
- 如果采集的视频是竖屏模式,则输出的视频也是竖屏模式。
**OrientationModeFixedLandscape**
在 `OrientationModeFixedLandscape` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
**OrientationFixedPortrait**
在 `OrientationFixedPortrait` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
#### 降级偏好 [#降级偏好-8]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-8]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="unreal" />
本文介绍如何调用声网提供的 API 设置视频编码属性。
## 功能介绍 [#功能介绍-9]
视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `setVideoEncoderConfiguration` 方法设置视频编码属性。你可以在 `enableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。
## 前提条件 [#前提条件-10]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现方法 [#实现方法-10]
你可以参考如下示例代码,在你的项目中设置各种视频编码参数:
```cpp
// 创建视频编码配置对象
VideoEncoderConfiguration videoConfig;
// 设置视频宽度
videoConfig.dimensions.width = 1280;
// 设置视频高度
videoConfig.dimensions.height = 720;
// 设置帧率为15 fps
videoConfig.frameRate = FRAME_RATE_FPS_15;
// 设置码率为800 Kbps
videoConfig.bitrate = 800 * 1000;
// 设置旋转方向模式为 ADAPTIVE
videoConfig.orientationMode = ORIENTATION_MODE_ADAPTIVE;
// 设置降级偏好为 MAINTAIN_QUALITY
videoConfig.degradationPreference = MAINTAIN_QUALITY;
// 应用视频编码配置
rtcEngine->setVideoEncoderConfiguration(videoConfig);
```
## 开发注意事项 [#开发注意事项-10]
- `setVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `setVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
## 参考信息 [#参考信息-10]
### 示例项目 [#示例项目-6]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### API 参考 [#api-参考-9]
- [`setVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#api_irtcengine_setvideoencoderconfiguration)
- [`onVideoSizeChanged`](/zh-CN/api-reference/rtc/unreal-cpp/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged)
### 视频参数推荐值 [#视频参数推荐值-9]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点;如果是一对四场景,老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率-9]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-9)了解如何设置视频输出的方向模式。
- `frameRate`:视频编码的帧率 (fps),即每秒钟要编码多少帧画面。默认值为 15。通常情况下,帧率越大,画面越流畅。在对视频流畅度要求较高的场景下,可以将此参数设置为 20 或 25。建议不要将 `frameRate` 设置为大于 30。
- `bitrate`:视频编码码率 (Kbps)。默认值为 `STANDARD_BITRATE`,即标准码率模式。在标准码率模式下,SDK 会根据已设置的频道场景、分辨率和帧率为你设置一个合适的码率。
- `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 |
### 视频模式 [#视频模式-9]
视频模式包括多种设置,你可以根据业务需求调整视频的方向、画质和镜像效果。
#### 旋转方向模式 [#旋转方向模式-9]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频。即视频和 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 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景:
- 如果采集的视频是横屏模式,则输出的视频也是横屏模式。
- 如果采集的视频是竖屏模式,则输出的视频也是竖屏模式。
**ORIENTATION_MODE_FIXED_LANDSCAPE**
在 `ORIENTATION_MODE_FIXED_LANDSCAPE` 模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
**ORIENTATION_MODE_FIXED_PORTRAIT**
在 `ORIENTATION_MODE_FIXED_PORTRAIT` 模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
#### 降级偏好 [#降级偏好-9]
为保证弱网下用户的视频体验,声网 SDK 还提供了 `degradationPreference` 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-9]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过 `mirrorMode` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="blueprint" />
本文介绍如何调用声网提供的 API 设置视频编码属性。
## 功能介绍 [#功能介绍-10]
视频编码属性包含视频分辨率、帧率、码率等影响视频质量的参数设置。你可以通过设置视频编码属性,控制视频流在不同网络条件下的展示方式。
声网 SDK 提供了 `SetVideoEncoderConfiguration` 方法设置视频编码属性。
你可以在 `EnableVideo` 前调用该方法以加快首帧出图的时间;也可以在频道内调用该方法以灵活调整视频编码属性。
## 前提条件 [#前提条件-11]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能。详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现步骤 [#实现步骤]
### 创建 UI 元素 [#创建-ui-元素]
在 **BP_VideoWidget** 中,创建一个 **Video Encoder Configuration** 区域,包含以下控件:
- **ET_FPS**:设置视频编码的帧率。
- **ET_Width**:设置视频的宽度。
- **ET_Height**:设置视频的高度。
- **ET_BitRate**:设置视频的码率。
- **ET_MinBitRate**:设置视频的最低编码码率。
设置好的 UI 界面如下图所示:
### 绑定事件 [#绑定事件]
按照以下步骤,在节点中绑定对应的事件。
1. 在 **Bind UIEvent** 节点中,绑定 **OnVideoConfigConfirmClicked** UI 回调,当用户在 **Video Encoder Confguration** 中设置了视频编码参数时,会触发该回调。如下图所示:
2. 在 **Bind Event** 节点中,绑定 **OnVideoSizeChanged** 回调,当视频大小和旋转信息发生改变时触发该回调。如下图所示:

### 实现回调函数 [#实现回调函数]
#### 实现 **OnVideoConfigConfirmClicked** 回调函数 [#实现-onvideoconfigconfirmclicked-回调函数]
按照以下步骤,实现 **OnVideoConfigConfirmClicked** 回调函数,并调用 `SetVideoEncoderConfiguration` 方法设置视频编码属性。
1. 在关卡蓝图的 **My Blueprint** 面板中,创建 **OnVideoConfigConfirmClicked** UI 事件节点。
2. 将已创建好的 UI 元素连接至 **Make VideoEncoderConfiguration**,将用户输入的编码参数传入 `VideoEncoderConfiguration`。 如下图所示:

3. 调用 **Set Video Encoder Configuration** 方法,并根据实际需求在 **Make VideoEncoderConfiguration** 中设置以下参数:
- **Orientation Mode**:视频的旋转方向。
- **Degradation Preference**:当带宽受限时视频编码的降级偏好。
- **Mirror Mode**:远端用户看到的视频画面是否镜像。
- **Compression Preference**:视频编码的压缩偏好。
设置好的界面如下图所示:
#### 实现 **OnVideoSizeChanged** 回调函数 [#实现-onvideosizechanged-回调函数]
按照以下步骤,实现 **OnVideoSizeChanged** 回调函数,并通过回调中获取的视频变化信息调整本地视图。
1. 在关卡蓝图的 **My Blueprint** 面板中,创建 **OnVideoSizeChanged** 事件节点。
2. 从 **OnVideoSizeChanged** 中获取视频变化信息关键参数:`sourceType`、`uid`、`width`、`height`、`rotation`,然后将这些参数传入 **Make FVideoViewIdentity**,分别调整本地视图和远端视图,如下图所示。

## 开发注意事项 [#开发注意事项-11]
- `SetVideoEncoderConfiguration` 中的各参数值是在理想网络状态下的最大值。声网 SDK 会根据实时网络环境和设备,对设置的参数作自适应调整,通常会下调参数。
- `SetVideoEncoderConfiguration` 中的参数设置可能会影响计费。如果因自适应产生参数下调,计费按用户实际订阅的视频分辨率为准。详见[计费说明](/zh-CN/realtime-media/rtc/reference/billing-strategy)。
## 参考信息 [#参考信息-11]
### 示例项目 [#示例项目-7]
声网提供了开源的示例项目供你参考,你可以前往下载或查看其中的源代码。
### API 参考 [#api-参考-10]
- [`SetVideoEncoderConfiguration`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-basic#api_irtcengine_setvideoencoderconfiguration)
- [`FOnVideoSizeChanged`](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-basic#callback_irtcengineeventhandler_onvideosizechanged)
### 视频参数推荐值 [#视频参数推荐值-10]
通常来讲,视频编码参数的选择要根据产品实际情况和场景来确定。比如,在一对一教学场景下,老师和学生的窗口比较大,要求分辨率会高一点,随之帧率和码率也要高一点; 如果是一对四场景, 老师和学生的窗口都比较小,分辨率可以低一点,对应的码率帧率也会低一点,以减少编解码的资源消耗和缓解下行带宽压力。
一般可按下列场景中的推荐值进行设置。
- 双人视频通话场景:
- 分辨率 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
### 分辨率、帧率和码率 [#分辨率帧率和码率-10]
视频编码属性的参数如下所示:
- `dimensions`:视频编码的分辨率 (px)。默认值为 960 × 540。通常情况下,分辨率越高,视频的清晰度会越好。该参数的值不代表最终视频输出的方向。点击[旋转方向模式](#旋转方向模式-10)了解如何设置视频输出的方向模式。
- `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 |
### 视频模式 [#视频模式-10]
视频模式包括多种设置,你可以根据业务需求调整视频的方向、画质和镜像效果。
#### 旋转方向模式 [#旋转方向模式-10]
在视频旋转场景中,我们主要关注采集端和播放端的行为。其中:
- 采集端采集视频并输出视频,以及视频和 Status Bar(状态栏)的相对位置。
- 播放端渲染接收到的视频图像,并根据接收到的旋转信息,结合自身 Status Bar 的相对位置旋转视频。
为防止视频因旋转出现大头、缩放或剪切的问题,声网 SDK 在 `SetVideoEncoderConfiguration` 中提供了 **Orientation Mode** 参数。你可以通过这个参数,结合视频场景需要,获取想要的视频渲染效果。
**Orientation Mode** 参数提供了三种模式以适应不同的用户需求:**ORIENTATION_MODE_ADAPTIVE**、**ORIENTATION_MODE_FIXED_LANDSCAPE** 和 **ORIENTATION_MODE_FIXED_PORTRAIT**。
无论采取哪种模式,声网 SDK 都保证视频和 Status Bar 的相对位置在采集端和播放端始终一致。
**ORIENTATION_MODE_ADAPTIVE**
在该模式下,SDK 输出的视频方向与采集到的视频方向一致。接收端会根据收到的视频旋转信息对视频进行旋转。该模式适用于接收端可以调整视频方向的场景:
- 如果采集的视频是横屏模式,则输出的视频也是横屏模式。
- 如果采集的视频是竖屏模式,则输出的视频也是竖屏模式。
**ORIENTATION_MODE_FIXED_LANDSCAPE**
在该模式下,输出的视频相对 Status Bar 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
**ORIENTATION_MODE_FIXED_PORTRAIT**
在该模式下,输出的视频相对 Status Bar 总是处于竖屏模式。如果采集到的视频是横屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。
#### 降级偏好 [#降级偏好-10]
为保证弱网下用户的视频体验,声网 SDK 还提供了 **Degradation Preference** 参数,来设置带宽受限时视频编码的降级偏好。
#### 镜像模式 [#镜像模式-10]
默认情况下,SDK 在编码时不对视频作镜像操作。你可以通过设置 **Mirror Mode** 参数从而确定远端用户看到的视频画面是否镜像。
<_PlatformProcessedMarker close="true" />