# 设备端 API (/zh-CN/api-reference/teleoperation/iot/api/device)

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

平行操控 SDK 为设备端提供实时音视频和实时控制信令功能，本页介绍实现相关功能的 API。

## 总览 [#总览]

下表展示设备端各功能 API 文档的对应链接：

| 功能    | API 文档                                          |
| :------ | :----------------------------------------------------------- |
| 实时音视频 | 点击 [RTC 服务端 C++ API 参考](/zh-CN/api-reference/rtc-server-sdk/cpp/overview)查看发送音视频流的相关 API 文档。此外，如需通过摄像头采集视频流，查看[摄像头采集 (YuvCapturer)](/zh-CN/api-reference/teleoperation/iot/api/device#yuvcapturer)。 |
| 实时控制信令   | 点击 [Linux API 参考](https://docs-preprod.agora.io/cn/rtm-2.x/api-overview-linux?platform=Linux)查看收发控制信令的相关 API 文档。 |

<a id="yuvcapturer"></a>
## 摄像头采集 (YuvCapturer) [#摄像头采集-yuvcapturer]

设备端 SDK 封装了一个 `YuvCapturer` 类，提供摄像头采集视频流的方法。

```cpp
class YuvCapturer
{
public:
    YuvCapturer(resolution s);
    YuvCapturer(resolution s,std::string deviceName);
    YuvCapturer();
    ~YuvCapturer();

    void init();
    int camera_capture_start();
    void set_resolution(int width,int height);
    void set_device(std::string name);
    void set_frame_rate(int fps);
    resolution get_resolution() {
      return resolution_;
    };
    Buffer get_one_frame();
    void clear_one_frame();
};
```

<a id="set_resolution"></a>
### set_resolution [#set_resolution]

设置摄像头采集的视频流的宽高。

```cpp
void set_resolution(int width,int height);
```

摄像头采集视频流的默认宽高设置为 640 × 480。如果你的摄像头不支持采集 640 × 480 的视频流，你需要调用该方法修改采集视频流的宽高。

该方法需要在 [`init`](/zh-CN/api-reference/teleoperation/iot/api/device#init) 之前调用。

**参数**

| 参数   | 类型 | 描述                            |
| :----- | :--- | :------------------------------ |
| `width`  | int  | 宽，单位为像素。默认值为 640。 |
| `height` | int  | 高，单位为像素。默认值为 480。  |

<a id="set_device"></a>
### set_device [#set_device]

指定采集视频流的摄像头。

```cpp
void set_device(std::string name);
```

如果你的设备上连接了多个摄像头，你需要调用该方法指定采集视频流的摄像头。

该方法需要在 [`init`](/zh-CN/api-reference/teleoperation/iot/api/device#init) 之前调用。

**参数**

| 参数 | 类型   | 描述                                                         |
| :--- | :----- | :----------------------------------------------------------- |
| `name` | string | 摄像头名称。默认值为 `/dev/video0`。你可以通过 `ls /dev/video*` 命令查看当前设备上所有摄像头的名称。 |

<a id="set_frame_rate"></a>
### set_frame_rate [#set_frame_rate]

设置摄像头采集的视频帧率。

```cpp
void set_frame_rate(int frame_rate);
```

默认的视频采集帧率是 30 fps。如果你的摄像头不支持该帧率，你需要调用该方法修改摄像头采集的视频帧率。

该方法需要在 [`init`](/zh-CN/api-reference/teleoperation/iot/api/device#init) 之前调用。

**参数**

| 参数         | 类型 | 描述                                              |
| :----------- | :--- | :------------------------------------------------ |
| `frame_rate` | int  | 摄像头采集的视频帧率，单位为 fps。默认值为 `30`。 |

<a id="init"></a>
### init [#init]

初始化摄像头采集。

```cpp
int init();
```

该方法需要在 [`set_resolution`](/zh-CN/api-reference/teleoperation/iot/api/device#set_resolution)、[`set_device`](/zh-CN/api-reference/teleoperation/iot/api/device#set_device) 和 [`set_frame_rate`](/zh-CN/api-reference/teleoperation/iot/api/device#set_frame_rate) 后调用。

:::warning[注意]
如果初始化失败，你需要检查在 `set_resolution`、`set_device` 和 `set_frame_rate` 中的设置是否与摄像头实际支持的参数匹配。
:::

**返回值**

- 0: 调用成功。
- < 0: 调用失败。

<a id="camera_capture_start"></a>
### camera_capture_start [#camera_capture_start]

开始通过摄像头采集 YUV 视频流。

```cpp
int camera_capture_start();
```

该方法需要在 [`init`](/zh-CN/api-reference/teleoperation/iot/api/device#init) 之后调用。

**返回值**

- 0: 调用成功。
- < 0: 调用失败。可能的原因是摄像头未采集视频流，你需要检查在 [`set_device`](/zh-CN/api-reference/teleoperation/iot/api/device#set_device) 中指定的摄像头是否正确。

<a id="get_resolution"></a>
### get_resolution [#get_resolution]

获取摄像头采集的 YUV 视频流的宽高。

```cpp
resolution get_resolution() { return resolution_; };
```

声网推荐在加入频道前调用该方法。

**返回值**

一个包含如下成员的 `resolution` 结构体：

| 参数   | 类型 | 描述             |
| :----- | :--- | :--------------- |
| `width`  | int  | 宽。单位为像素。 |
| `height` | int  | 高。单位为像素。 |

<a id="get_one_frame"></a>
### get_one_frame [#get_one_frame]

从摄像头获取 YUV 视频帧。

```cpp
Buffer get_one_frame();
```

该方法需要在 [`camera_capture_start`](/zh-CN/api-reference/teleoperation/iot/api/device#camera_capture_start) 之后调用。

一般摄像头采集的是 YUV422 格式的视频帧，成功调用该方法后，获取到的视频帧会存储到设备内存中，你需要按照如下步骤转换并发布视频帧：

1. 自行实现将视频帧转换为 YUV420 格式。
2. 调用 [`clear_one_frame`](/zh-CN/api-reference/teleoperation/iot/api/device#clear_one_frame) 释放设备内存。成功释放设备内存后，你才能调用 `get_one_frame` 获取下一帧视频。
3. 调用 [`sendVideoFrame`](/zh-CN/api-reference/rtc-server-sdk/cpp/classagora-1-1rtc-1-1-i-video-frame-sender#sendvideoframe)) 将 YUV420 格式的视频帧发送到 SDK 的视频轨道。

**返回值**

一个包含如下成员的 Buffer 结构体：

| 参数   | 类型 | 描述                      |
| :----- | :--- | :------------------------ |
| `data`   | void | 指向 YUV 视频数据的指针。 |
| `length` | int  | YUV 视频数据的长度。      |

<a id="clear_one_frame"></a>
### clear_one_frame [#clear_one_frame]

清除摄像头获取的 YUV 视频帧。

```cpp
void clear_one_frame();
```

调用该方法清除摄像头获取的 YUV 视频帧后，设备内存会被释放，你可以继续调用 [`get_one_frame`](/zh-CN/api-reference/teleoperation/iot/api/device#get_one_frame) 获取下一帧视频。