# 自定义视频采集和渲染 (/zh-CN/api-reference/rtc/harmonyos/video/video-custom-capturenrendering)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_video_custom_capturenrendering"></a>

<a id="api_irtcengine_createcustomvideotrack"></a>

<a id="ariaid-title2"></a>

## createCustomVideoTrack [#createcustomvideotrack]

创建一个自定义的视频轨道。

<a id="api_irtcengine_createcustomvideotrack__prototype"></a>

```ts
public abstract createCustomVideoTrack(): number;
```

<a id="api_irtcengine_createcustomvideotrack__detailed_desc"></a>

### 详情 [#详情]

当你需要在频道中发布自定义采集视频时，可参考以下步骤：

1. 调用该方法创建视频轨道并获得视频轨道 ID。
2. 调用 [joinChannelWithOptions](/zh-CN/api-reference/rtc/harmonyos/channel#api_irtcengine_joinchannel2) 加入频道时，将 [ChannelMediaOptions](/zh-CN/api-reference/rtc/harmonyos/class-channelmediaoptions) 中的 customVideoTrackId 设置为你想要发布的视频轨道 ID，并将 publishCustomVideoTrack 设置为 `true`。
3. 调用 [pushExternalVideoFrameById](/zh-CN/api-reference/rtc/harmonyos/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe3) 将 videoTrackId 指定为步骤 2 中指定的视频轨道 ID，即可实现在频道内发布对应的自定义视频源。

<a id="api_irtcengine_createcustomvideotrack__return_values"></a>

### 返回值 [#返回值]

- 方法调用成功，返回视频轨道 ID 作为该视频轨道的唯一标识。
- 方法调用失败，返回 0xffffffff。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类]

- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_destroycustomvideotrack"></a>

<a id="ariaid-title3"></a>

## destroyCustomVideoTrack [#destroycustomvideotrack]

销毁指定的视频轨道。

<a id="api_irtcengine_destroycustomvideotrack__prototype"></a>

```ts
public abstract destroyCustomVideoTrack(videoTrackId: number): number;
```

<a id="api_irtcengine_destroycustomvideotrack__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="videotrackid"></a>
<Parameter name="videoTrackId">

调用 [createCustomVideoTrack](/zh-CN/api-reference/rtc/harmonyos/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法返回的视频轨道 ID。

</Parameter>
</ParameterList>

<a id="api_irtcengine_destroycustomvideotrack__return_values"></a>

### 返回值 [#返回值-1]

- 0: 方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-1]

- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_pushvideoframe3"></a>

<a id="ariaid-title4"></a>

## pushExternalVideoFrameById [#pushexternalvideoframebyid]

将外部原始视频帧通过自定义视频轨道发布到频道中。

<a id="api_irtcengine_pushvideoframe3__prototype"></a>

```ts
public abstract pushExternalVideoFrameById(frame: VideoFrame, videoTrackId: number): number;
```

<a id="api_irtcengine_pushvideoframe3__detailed_desc"></a>

### 详情 [#详情-1]

当你需要在频道中发布自定义采集视频时，可参考以下步骤：

1. 调用 [createCustomVideoTrack](/zh-CN/api-reference/rtc/harmonyos/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack) 方法创建视频轨道并获得视频轨道 ID。
2. 调用 [joinChannelWithOptions](/zh-CN/api-reference/rtc/harmonyos/channel#api_irtcengine_joinchannel2) 加入频道时，将 [ChannelMediaOptions](/zh-CN/api-reference/rtc/harmonyos/class-channelmediaoptions) 中的 customVideoTrackId 设置为你想要发布的视频轨道 ID，并将 publishCustomVideoTrack 设置为 `true`。
3. 调用该方法将 videoTrackId 指定为步骤 2 中指定的视频轨道 ID，即可实现在频道内发布对应的自定义视频源。

:::error
危险： 调用该方法后，即使你停止推送外部视频帧到 SDK，自定义采集的视频流仍然会被计入视频时长用量并产生费用，声网建议你根据实际情况采取相应措施避免此类视频计费：

- 如果你不再需要采集外部视频数据，可以调用 [destroyCustomVideoTrack](/zh-CN/api-reference/rtc/harmonyos/video/video-custom-capturenrendering#api_irtcengine_destroycustomvideotrack) 销毁自定义采集的视频轨道。
- 如果你只想将采集到的外部视频数据用于本地预览、而不在频道内发布，可以调用 [muteLocalVideoStream](/zh-CN/api-reference/rtc/harmonyos/publishnsubscribe#api_irtcengine_mutelocalvideostream) 取消发送视频流，或调用 [updateChannelMediaOptions](/zh-CN/api-reference/rtc/harmonyos/channel#api_irtcengine_updatechannelmediaoptions) 将 publishCustomVideoTrack 设置为 `false`。
:::

<a id="api_irtcengine_pushvideoframe3__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="frame"></a>
<Parameter name="frame">

待推送的外部原始视频帧。详见 [VideoFrame](/zh-CN/api-reference/rtc/harmonyos/class-videoframe)。

</Parameter>
<a id="videotrackid-1"></a>
<Parameter name="videoTrackId">

调用 createCustomVideoTrack 方法返回的视频轨道 ID。默认值为 0。

</Parameter>
</ParameterList>

<a id="api_irtcengine_pushvideoframe3__return_values"></a>

### 返回值 [#返回值-2]

- 0: 推送成功。
- &lt; 0: 推送失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-2]

- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_pushvideoframe4"></a>

<a id="ariaid-title5"></a>

## pushExternalVideoFrame [#pushexternalvideoframe]

推送外部原始视频帧到 SDK。

<a id="api_irtcengine_pushvideoframe4__prototype"></a>

```ts
public abstract pushExternalVideoFrame(frame: VideoFrame): boolean;
```

<a id="api_irtcengine_pushvideoframe4__detailed_desc"></a>

### 详情 [#详情-2]

调用 [setExternalVideoSource](/zh-CN/api-reference/rtc/harmonyos/video/video-custom-capturenrendering#api_imediaengine_setexternalvideosource) 方法，设置 enabled 参数为 `true`、encodedFrame 参数为 `false` 后，你可以调用本方法将未编码的外部视频帧推送到 SDK。

<a id="api_irtcengine_pushvideoframe4__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="frame-1"></a>
<Parameter name="frame">

待推送的外部原始视频帧。详见 [VideoFrame](/zh-CN/api-reference/rtc/harmonyos/class-videoframe)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_pushvideoframe4__return_values"></a>

### 返回值 [#返回值-3]

- `true`：方法调用成功。
- `false`：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-3]

- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)

<a id="api_imediaengine_setexternalvideosource"></a>

<a id="ariaid-title6"></a>

## setExternalVideoSource [#setexternalvideosource]

设置外部视频源。

<a id="api_imediaengine_setexternalvideosource__prototype"></a>

```ts
public abstract setExternalVideoSource(enable: boolean, useTexture: boolean, sourceType: Constants.ExternalVideoSourceType): number;
```

<a id="api_imediaengine_setexternalvideosource__detailed_desc"></a>

调用该方法启用外部视频源后，你可以调用 [pushExternalVideoFrameById](/zh-CN/api-reference/rtc/harmonyos/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe3) 向 SDK 推送外部视频数据。

<a id="api_imediaengine_setexternalvideosource__timing"></a>

### 调用时机 [#调用时机]

该方法需要在加入频道前调用。

<a id="api_imediaengine_setexternalvideosource__restriction"></a>

### 调用限制 [#调用限制]

不支持在频道内动态切换视频源。如果已调用该方法启用外部视频源并加入频道，若想切换为内部视频源，必须先退出频道，然后调用该方法关闭外部视频源，再重新加入频道。

<a id="api_imediaengine_setexternalvideosource__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="enable"></a>
<Parameter name="enable">

是否启用外部视频源：

- `true`: 启用外部视频源。SDK 准备接收外部视频帧。
- `false`:（默认）不启用外部视频源。

</Parameter>
<a id="usetexture"></a>
<Parameter name="useTexture">

是否使用 Texture 格式的外部视频帧：

- `true`: 使用 Texture 格式的外部视频帧。
- `false`: 不使用 Texture 格式的外部视频帧。

</Parameter>
<a id="sourcetype"></a>
<Parameter name="sourceType">

外部视频帧是否编码，详见 [ExternalVideoSourceType](/zh-CN/api-reference/rtc/harmonyos/enum-externalvideosourcetype)。

</Parameter>
</ParameterList>

<a id="api_imediaengine_setexternalvideosource__return_values"></a>

### 返回值 [#返回值-4]

- 0：方法调用成功。
- &lt; 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-4]

- [RtcEngine](/zh-CN/api-reference/rtc/harmonyos/rtc-interface-class#class_irtcengine)