# 自定义视频采集 (/zh-CN/realtime-media/rtc/build/video/custom-video-source/macos)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
自定义视频采集是指通过自定义的视频采集源实现对视频流的采集。
与 SDK 默认的视频采集方式不同,自定义视频采集支持用户自行控制采集源,实现更加精细的视频属性调整。例如,支持通过高清摄像头、无人机摄像头或其他类型的摄像头实现视频采集,同时支持动态调整视频质量、分辨率和帧率等参数,以适应不同的应用场景和需求。
声网推荐优先使用更为稳定、可靠、集成维护难度低的 SDK 视频采集,如果你有特定的视频采集需求或无法使用 SDK 采集,那么自定义视频采集为你提供灵活、可定制的方案。
## 技术原理 [#技术原理-2]
声网 SDK 提供自定义视频轨道方式实现视频自采集。你可以创建一个或多个自定义视频轨道,加入频道并在每个频道中发布已创建的视频轨道。你需要使用自采集模块驱动采集设备对视频进行采集,并将采集的视频帧通过视频轨道发送给 SDK。
下图展示在单频道和多频道中实现自定义视频采集时,视频数据的传输过程:
仅在一个频道内发布自采集视频流:

在多个频道内发布不同的自采集视频流:

## 前提条件 [#前提条件-2]
在进行操作之前,请确保你已经在项目中实现了基本的实时音视频功能,详见[实现音视频互动](/zh-CN/realtime-media/rtc/get-started/quick-start)。
## 实现自定义视频采集 [#实现自定义视频采集-2]
参考下图调用时序,在你的 App 中实现自定义视频采集:
参考如下步骤,在你的 App 中实现自定义视频采集功能:
### 1. 创建自定义视频轨道 [#1-创建自定义视频轨道-2]
初始化 `AgoraRtcEngineKit` 后,调用 `createCustomVideoTrack` 创建自定义视频轨道并获得视频轨道 ID。根据场景需要,你可以创建多个自定义视频轨道。
```swift
// 如需创建多个自定义视频轨道,可以多次调用 createCustomVideoTrack
customCamera?.trackId = agoraKit.createCustomVideoTrack()
```
### 2. 加入频道并发布自定义视频轨道 [#2-加入频道并发布自定义视频轨道-2]
调用 `joinChannelByToken`[2/4] 加入单频道,或调用 `joinChannelExByToken`[1/2] 加入多频道。在 `AgoraRtcChannelMediaOptions` 中,将 `customVideoTrackId` 设置为步骤 1 中获得的视频轨道 ID,并将 `publishCustomVideoTrack` 设置为 `true`,即可发布指定的自定义视频轨道。
```swift tab="加入单频道"
let option = AgoraRtcChannelMediaOptions()
option.clientRoleType = .broadcaster
option.autoSubscribeAudio = true
option.autoSubscribeVideo = true
// highlight-start
// 发布自采集视频流
option.publishCustomVideoTrack = true
// 设置自定义视频轨道 ID
option.customVideoTrackId = Int(customCamera?.trackId ?? 0)
// highlight-end
NetworkManager.shared.generateToken(channelName: channel, success: { token in
// 加入单频道
let result = self.agoraKit.joinChannel(byToken: token, channelId: channel, uid: 0, mediaOptions: option)
if result != 0 {
self.isProcessing = false
self.showAlert(title: "Error", message: "joinChannel call failed: \(result), please check your params")
}
})
```
```swift tab="加入多频道"
// 如需在多个频道发布自定义视频轨道,则需要多次设置 AgoraRtcChannelMediaOptions 并多次调用 joinChannelEx
let option = AgoraRtcChannelMediaOptions()
option.clientRoleType = .broadcaster
option.autoSubscribeAudio = true
option.autoSubscribeVideo = true
// highlight-start
// 发布自采集视频流
option.publishCustomVideoTrack = true
// 设置自定义视频轨道 ID
option.customVideoTrackId = Int(trackId)
// highlight-end
let connection = AgoraRtcConnection()
connection.localUid = uid
connection.channelId = channelName
NetworkManager.shared.generateToken(channelName: channelName, uid: uid) { token in
// 加入多频道
let result = self.agoraKit.joinChannelEx(byToken: token,
connection: connection,
delegate: self,
mediaOptions: option,
joinSuccess: nil)
if result != 0 {
self.showAlert(title: "Error", message: "joinChannel call failed: \(result), please check your params")
}
}
```
### 3. 实现自采集模块 [#3-实现自采集模块-2]
声网提供 [CustomVideoSourcePushMulti.swift](https://github.com/Shengwang-Community/API-Examples/blob/main/macOS/APIExample/Examples/Advanced/CustomVideoSourcePushMulti/CustomVideoSourcePushMulti.swift) 演示从本地文件读取 YUV 格式的视频数据。在实际的生产环境中,你需要结合业务需求为你的设备创建自定义视频采集模块。
### 4. 通过视频轨道推送视频数据到 SDK [#4-通过视频轨道推送视频数据到-sdk-2]
调用 `pushExternalVideoFrame`[1/2] 将采集到的视频帧通过视频轨道推送至 SDK。其中,`videoTrackId` 要与步骤 2 加入频道时指定视频轨道 ID 一致,`AgoraVideoFrame` 中可以设置视频帧的像素格式、数据类型和时间戳等参数。
:::info[信息]
- 以下代码演示推送 CVPixelBufferRef 格式的视频数据。其他支持的视频帧格式详见 [`AgoraVideoFrame`](/zh-CN/api-reference/rtc/macos/class-externalvideoframe) 的 `format`。
- 为确保音视频同步,声网建议你将 `AgoraVideoFrame` 的 `time`(时间戳)设置为系统 Monotonic Time。你可以调用 `getCurrentMonotonicTimeInMs` 获取当前的 Monotonic Time。
:::
```swift
let videoFrame = AgoraVideoFrame()
videoFrame.format = 12
videoFrame.textureBuf = buffer
videoFrame.rotation = Int32(rotation)
agoraKit.pushExternalVideoFrame(videoFrame, videoTrackId: trackId)
```
### 5. 销毁自定义视频轨道 [#5-销毁自定义视频轨道-2]
如果你需要停止发布自定义采集的视频,调用 `destroyCustomVideoTrack` 销毁视频轨道。如需销毁多个视频轨道,可多次调用 `destroyCustomVideoTrack`。
```swift
// 销毁自定义视频轨道
agoraKit.destroyCustomVideoTrack(UInt(userModel?.trackId ?? 0))
// 离开频道
agoraKit.leaveChannelEx(connection) { state in
LogUtils.log(message: "warning: \(state.description)", level: .info)
}
```
## 参考信息 [#参考信息-2]
### 适用场景 [#适用场景-2]
你可以在多种行业的多种场景下使用到自定义视频采集:
#### 视频特殊处理和增强 [#视频特殊处理和增强-2]
在某些游戏或虚拟现实应用中,需要对视频流进行实时的特效处理、滤镜处理或其他增强效果。在这种情况下,使用自定义视频采集可以直接获取原始视频流,并进行实时处理,从而实现更加逼真的游戏或虚拟现实效果。
#### 高精度视频采集 [#高精度视频采集-2]
在视频监控领域,需要对场景中的细节进行精细的观察和分析,此时使用自定义视频采集可以获得更高的图像质量和更精细的采集控制。
#### 特定视频源采集 [#特定视频源采集-2]
在 IoT、直播等行业需要使用特定的摄像头、监控设备或其他非摄像头设备视频源,例如视频捕捉卡、录屏数据等。在这种情况下,使用 SDK 内部采集可能无法满足需求,必须使用自定义视频采集来实现对特定视频源的采集。
#### 与特定设备或第三方应用无缝对接 [#与特定设备或第三方应用无缝对接-2]
在智能家居或物联网领域,需要将设备中的视频传输到用户的手机或电脑上进行监控和控制,此时可能需要使用特定的设备或应用程序进行视频采集。在这种情况下,使用自定义视频采集可以方便地将特定设备或应用程序与 RTC SDK 进行对接。
#### 特定的视频编码格式 [#特定的视频编码格式-2]
在特定直播场景中,可能需要使用特定的视频编码格式来满足业务需求,此时使用 SDK 内部采集可能无法满足需求,必须使用自定义视频采集来实现对特定编码格式视频的采集和自定义编码。
### 优势介绍 [#优势介绍-2]
使用自定义视频采集,你可以体验到:
#### 更多类型的视频流 [#更多类型的视频流-2]
自定义视频采集功能可以使用更高质量、更多类型的采集设备和摄像头,从而获得更清晰、更流畅的视频流。这有助于提高用户的观看体验,并使产品更具竞争力。
#### 更灵活的视频特效 [#更灵活的视频特效-2]
自定义视频采集功能可以帮助用户实现更丰富、更个性化的视频特效和过滤器,从而提高用户的体验和应用程序的吸引力。用户可以通过自定义视频采集功能实现各种特效,如美颜、滤镜、动态贴纸等。
#### 更适应各种场景的需求 [#更适应各种场景的需求-2]
自定义视频采集功能可以帮助应用程序更好地适应各种场景的需求,如直播、视频会议、在线教育等。用户可以根据不同的场景需求,定制不同的视频采集方案,从而提供适应性更强的应用程序。
### 注意事项 [#注意事项-2]
如果采集到的自定义视频格式为 `Texture`,并且远端用户看到的自定义采集视频画面出现闪烁、失真等异常情况时,建议先复制视频数据,再将原始视频数据和复制的视频数据发回至 SDK,从而消除内部数据编码过程中出现的异常情况。
### 示例项目 [#示例项目-2]
声网提供了开源的视频自采集示例项目供你参考,你可以前往下载或查看其中的源代码。
CustomVideoSourcePushMulti.swift} href="https://gitee.com/agoraio-community/API-Examples/blob/main/macOS/APIExample/Examples/Advanced/CustomVideoSourcePushMulti/CustomVideoSourcePushMulti.swift" />
CustomVideoSourcePushMulti.swift} href="https://github.com/Shengwang-Community/API-Examples/blob/main/macOS/APIExample/Examples/Advanced/CustomVideoSourcePushMulti/CustomVideoSourcePushMulti.swift" />
### API 参考 [#api-参考-2]
- [`createCustomVideoTrack`](/zh-CN/api-reference/rtc/macos/video/video-custom-capturenrendering#api_irtcengine_createcustomvideotrack)
- [`destroyCustomVideoTrack`](/zh-CN/api-reference/rtc/macos/video/video-custom-capturenrendering#api_irtcengine_destroycustomvideotrack)
- [`pushExternalVideoFrame`[1/2]](/zh-CN/api-reference/rtc/macos/video/video-custom-capturenrendering#api_irtcengine_pushvideoframe)
- [`getCurrentMonotonicTimeInMs`](/zh-CN/api-reference/rtc/macos/network#api_irtcengine_getcurrentmonotonictimeinms)
- [`joinChannelExByToken`[1/2]](/zh-CN/api-reference/rtc/macos/channel#api_irtcengineex_joinchannelex)