# 设置视频编码属性 (/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 与屏幕的相对方向保持一致,与手机重力感应无关(例如微信)。因此,视频和屏幕的相对位置在视频采集端和播放端始终一致。 - 采集端横屏时: ![../_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) #### 降级偏好 [#降级偏好] 为保证弱网下用户的视频体验,声网 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 与屏幕的相对方向保持一致,与手机重力感应无关(例如微信)。因此,视频和屏幕的相对位置在视频采集端和播放端始终一致。 - 采集端横屏时: ![../_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) **FixedLandscape** 在 `FixedLandscape` 模式下,输出的视频相对 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) **FixedPortrait** 在 `FixedPortrait` 模式下,输出的视频相对 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) #### 降级偏好 [#降级偏好-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 总是处于横屏模式。如果采集到的视频是竖屏模式,则视频编码器会对其进行裁剪。该方式适用于接收端无法处理旋转信息的情况。 当使用后置摄像头作为视频采集器时,视频采集器和播放器的视频方向如下图所示。 - 横向模式下采集的视频(不需要视频裁剪): ![../_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) **FixedPortrait** 在 `FixedPortrait` 模式下,输出的视频相对 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) #### 降级偏好 [#降级偏好-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 与屏幕的相对方向保持一致,与手机重力感应无关(例如微信)。因此,视频和屏幕的相对位置在视频采集端和播放端始终一致。 - 采集端横屏时: ![../_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` 参数设置视频编码的镜像模式,从而决定远端用户看到的视频画面。 <_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** 回调,当视频大小和旋转信息发生改变时触发该回调。如下图所示: ![绑定 OnVideoSizeChanged 回调的节点示意图](https://web-cdn.agora.io/docs-portal/img/rtc/bp-bind-onvideosizechanged.png) ### 实现回调函数 [#实现回调函数] #### 实现 **OnVideoConfigConfirmClicked** 回调函数 [#实现-onvideoconfigconfirmclicked-回调函数] 按照以下步骤,实现 **OnVideoConfigConfirmClicked** 回调函数,并调用 `SetVideoEncoderConfiguration` 方法设置视频编码属性。 1. 在关卡蓝图的 **My Blueprint** 面板中,创建 **OnVideoConfigConfirmClicked** UI 事件节点。 2. 将已创建好的 UI 元素连接至 **Make VideoEncoderConfiguration**,将用户输入的编码参数传入 `VideoEncoderConfiguration`。 如下图所示: ![配置 VideoEncoderConfiguration 参数的蓝图片段示意图](https://web-cdn.agora.io/docs-portal/img/rtc/bp-videoconfig-value.png) 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**,分别调整本地视图和远端视图,如下图所示。 ![处理 OnVideoSizeChanged 回调并调整视图的蓝图片段示意图](https://web-cdn.agora.io/docs-portal/img/rtc/bp-onvideosizechanged.png) ## 开发注意事项 [#开发注意事项-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" />