NERTC SDK 提供自定义视频采集功能，帮助您向 SDK 提供自定义的视频输入源数据，并由 SDK 进行编码推流。本文档为您介绍如何通过 setExternalVideoSource 和 pushExternalVideoFrame 方法实现自定义视频采集功能。

功能描述

一般情况下，App 采用默认设备采集视频数据，通常是本设备的摄像头模块。但在部分场景下可能需要使用自定义的视频源，例如：

• 由第三方美颜 SDK 负责视频数据采集和视频数据的前处理，NERTC 负责视频数据编码和云端推流。
• 某些视频采集设备被系统独占。为避免与其它业务产生冲突，需要灵活的设备管理策略。例如，直播过程中需要录制短视频。
• 需要使用外部视频源，即非摄像头采集的数据，例如播放本地视频文件、屏幕共享、游戏直播等。

基于以上场景，NERTC SDK 支持使用自定义的视频源，以实现您在实际业务场景中的相关需求。

V5.3.0 及之后版本，子房间支持调用 IRtcChannel#setExternalVideoSource 和 IRtcChannel#pushExternalVideoFrame 设置外部视频输入。

技术原理

NERTC SDK 目前提供 Push 数据源的方式实现自定义的视频源。外部视频输入的场景中，NERTC SDK 会根据 setVideoConfig 中设置的max_profile或 height/ width 值，调整画面比例，并对数据源进行裁剪或缩放。视频的帧率由数据源自身控制。

在 Push 模式下进行视频源自定义时，视频数据的传输过程如下图所示。

注意事项

• 自定义视频采集场景中，您需要自行实现视频数据的采集和处理。

• 若您需要开启外部视频采集，建议在创建外部视频输入源之前调用 enableLocalVideo 方法关闭本地视频设备采集（若未打开则无需关心），再在创建外部视频输入源之后再次调用 enableLocalVideo 方法开启媒体传输通道。

• 请先开启外部视频输入（setExternalVideoSource），再开启本地视频预览（NERtc#startVideoPreview ）或开启媒体传输通道（enableLocalVideo ）。

• 当外部视频源输入作为主流或辅流时，内部引擎为启用状态，在切换房间（switchChannel）、主动离开房间（leaveChannel）、断网重连失败（onDisconnect）或重新加入房间（onReJoinChannel）后仍然有效。如果需要关闭该功能，请在下次通话前调用接口关闭该功能。

• 视频主流和辅流通道分别只能传输一个视频输入源，例如：

  • 若您已经开启了屏幕共享（使用辅流通道），则外部输入的视频源只能使用主流通道。
  • 若您在 enableLocalVideo 中已通过主流传输本设备的摄像头数据，则外部输入的视频源只能使用辅流通道。

• 对于 V5.3.0 及之后版本，如果当前正在使用本地视频辅流通道进行本地摄像头采集或者外部自定义视频输入，调用 startScreenCaptureByScreenRect 或 startScreenCaptureByWindowId 开启屏幕共享时，需要先调用enableLocalVideo停止辅流。如果当前正在屏幕共享，调用 enableLocalVideo 开启辅流时，需要调用 stopScreenCapture 先停止屏幕共享。

API 调用时序

sequenceDiagram
    participant 应用层
    participant NERtcSDK

    应用层->>NERtcSDK: init 初始化 SDK

    rect rgb(191, 223, 255)
    应用层 ->> NERtcSDK: setDevice 指定外部视频采集的设备
    end
    应用层->>NERtcSDK: setVideoConfig 设置基本的视频参数
    rect rgb(191, 223, 255)
    应用层 ->> NERtcSDK: setExternalVideoSource 开启外部视频源数据输入
    end
    Note right of 应用层: 请自行实现视频数据采集和处理
    应用层->>NERtcSDK: enableLocalVideo（true）开启媒体传输通道
    应用层->>NERtcSDK: joinChannel 加入房间
    NERtcSDK-->>应用层: onJoinChannel

    rect rgb(191, 223, 255)
    应用层 ->> NERtcSDK: pushExternalVideoFrame 将视频数据发送给 NERtc SDK
    end

实现方法

参考如下步骤，在您的项目中通过 Push 方式实现自定义视频源功能：

1. 指定外部视频采集的设备。

   调用 setDevice 方法，设置 device_id 参数为待采集视频的设备 ID，并设置 type 为 kNERTCVideoStreamMain（主流） 或 kNERtcVideoStreamSub（辅流）。

   视频采集设备 ID 可以通过 enumerateCaptureDevices 获取。

2. 设置基本的视频参数。

   调用 setVideoConfig 方法，设置基本的视频参数，特别是 width、height、frameRate 三个重要参数，要与真实的外部输入一致，否则会影响视频质量。

3. 开启外部视频源数据输入。

   调用 setExternalVideoSource 方法，设置 enable 参数为 true，并设置 type 为 kNERTCVideoStreamMain（主流） 或 kNERtcVideoStreamSub（辅流）。

4. 开启媒体传输通道。

   调用 enableLocalVideo 方法，设置 enable 参数为 true，并设置 type 为 kNERTCVideoStreamMain（主流） 或 kNERtcVideoStreamSub（辅流）。

   如果已经开启了本地视频采集，会自动切换到外部设备采集，不需要再次调用 enableLocalVideo 方法。

   对于 V5.3.0 及之后版本：

   • 如果当前正在屏幕共享，调用 enableLocalVideo 开启辅流时，需要调用 stopScreenCapture 先停止屏幕共享。
   • 如果当前正在使用本地视频辅流通道进行本地摄像头采集或者外部自定义视频输入，调用 startScreenCaptureByScreenRect 或 startScreenCaptureByWindowId 开启屏幕共享时，需要先调用enableLocalVideo停止辅流。

5. 指定外部采集设备后，您需要自行管理视频数据采集和处理，具体实现方法请参考 ExternalVideo 示例项目源码。

6. （可选）设置视频旋转方向。

   当设备方向变化后，您可以通过如下方式实现横竖屏切换：

   在将视频数据发送给 NERTC SDK 前，通过 NERtcVideoFrame 设置视频的方向。例如，设置 rotation 为 90，使视频帧顺时针旋转 90 度。

7. 将外部视频帧的数据发送给 NERTC SDK。

   完成视频数据处理后，调用 pushExternalVideoFrame 方法将视频数据发送给 SDK 进行后续操作；调用此方法时，您需要通过 frame 参数传入外部视频帧的数据信息，并设置 type 为 kNERTCVideoStreamMain（主流） 或 kNERTCVideoStreamSub（辅流）。

   • setDevice、setExternalVideoSource 、enableLocalVideo 和 pushExternalVideoFrame 4 个接口中设置的视频通道 Type 必须一致，同为主流或辅流，否则 NERTC SDK 会报错。

   • 当 NERtcVideoFrame 格式为 NERtcVideoFrame.Format.TEXTURE_OES 时，请先调用 pushExternalVideoFrame 的线程完成 eglMakeCurrent 调用。 可以使用 GLHelper.initGLContext 完成初始化。

   • NERtcVideoFrame中的 width、height、format 三个参数的值，要与外部输入的视频的实际值保持一致，否则会影响视频质量。

   • 如果设置的分辨率太高，可能会影响计费，请根据场景，合理设置 NERtcVideoFrame 中的 height 和 width 值。典型场景的推荐参数请参见音视频参数配置推荐。

示例项目源码

网易云信提供 ExternalVideo 示例项目源码，您可以参考该源码实现自定义视频采集。

示例代码

C++//以开启主流外部视频输入为例
//设置主流画布
nertc::NERtcVideoCanvas canvas;
canvas.cb = nullptr;
canvas.user_data = nullptr;
canvas.window = window; //渲染窗口句柄
canvas.scaling_mode = nertc::kNERtcVideoScaleFullFill; //设置视频缩放模式
rtc_engine->setupLocalVideoCanvas(&canvas);

vdm->setDevice(nertc::kNERtcExternalSubVideoDeviceID, nertc::kNERTCVideoStreamMain);//设置为外部设备采集
rtc_engine->setExternalVideoSource(nertc::kNERTCVideoStreamMain, true);//开启外部视频源数据输入
rtc_engine->enableLocalVideo(nertc::kNERTCVideoStreamMain, true);//开始视频（如果原先已经开启了视频，则不需要调用）
rtc_engine->pushExternalVideoEncodedFrame(nertc::kNERTCVideoStreamMain, encoded_frame);//推送自定义数据,需要定时循环调用

//切换回摄像头采集
rtc_engine_->setExternalVideoSource(nertc::kNERTCVideoStreamMain, false); //关闭外部视频源数据输入
video_device_manager->setDevice(cameraDeviceID); //设置选择的设备，可通过enumerateCaptureDevices获取视频设备信息

API 参考

方法	功能描述
setDevice	指定特定外部视频采集设备。
enableLocalVideo	开启或关闭本地视频采集。
setExternalVideoSource	开启外部视频源数据输入。
pushExternalVideoFrame	推送外部视频数据帧。

常见问题

• 自定义视频源支持哪些数据格式？

  自定义视频源的数据格式支持 I420、NV21、RGBA、TEXTURE_OES 和 TEXTURE_RGB。

• 自定义视频采集的分辨率和setLocalVideoConfig中设置的视频分辨率不一致时，以哪个分辨率为准

  当pushExternalVideoFrame 输入的视频分辨率和 setVideoConfig 中设置的分辨率、画布比例不一致时，例如pushExternalVideoFrame的分辨率为640 x 480（4：3）、setLocalVideoConfig的分辨率为1280 x 720（16：9），NERTC SDK 的推流视频处理逻辑如下：

  1. 画布比例采用 setVideoConfig 中设置的画布比例，本示例中为 16：9。
  2. 将自定义视频采集的分辨率（本示例中为 640 x 480）按照setVideoConfig 中设置的画布比例（本示例中为 16：9）进行裁剪，得到一个新的分辨率（640 x 360）。
  3. 根据上一步得到的新分辨率和setVideoConfig 中的分辨率，取两者中较小的分辨率作为推流分辨率。因此，本示例中最终的视频分辨率为 640 x 360。