NodePlayer API

16 次浏览 2026年 6月 3日下午10:23

# NodePlayer API 参考

NodePlayer 是一款适用于 HarmonyOS NEXT / OpenHarmony 5.0 的音视频播放组件，支持 RTSP、RTMP、HTTP(S)-FLV、HLS、KMP 和 UDP-MPEGTS 等流媒体协议。

---

## 概述

NodePlayer 基于原生 C++ 后端（`nodemediaclient`）构建，通过 ArkTS `@Component` 暴露给 ArkUI 应用，实现无缝集成。

组件能力：
- 多协议音视频播放
- 硬件加速解码
- RTSP 传输协议选择（UDP/TCP）
- 音量控制、静音、缓冲管理
- 画面缩放模式配置
- 加密流支持（crypto key）
- 自定义 User-Agent 和 Referer 头

---

## 属性

### 源与播放

| 属性         | 类型      | 默认值    | 说明                                       |
|--------------|-----------|-----------|--------------------------------------------|
| `src`        | `string`  | `''`      | 媒体源 URL（RTSP、RTMP、HLS、FLV 等）      |
| `autoplay`   | `boolean` | `false`   | 组件挂载后自动开始播放                      |
| `bufferTime` | `number`  | `1000`    | 缓冲时长，单位毫秒（ms）                    |
| `clearScreen`| `boolean` | `false`   | 停止播放时清除显示画面                      |

> `bufferTime` 使用 `@Watch('onPropUpdated')` 装饰——修改后动态生效。

### 流配置

| 属性            | 类型      | 默认值                 | 说明                                      |
|-----------------|-----------|------------------------|-------------------------------------------|
| `cryptoKey`     | `string`  | `''`                   | 加密流的解密密钥                          |
| `ua`            | `string`  | `'NMC/3.0 NMCH/1.0'`  | 自定义 HTTP User-Agent 头                 |
| `referer`       | `string`  | `'http://localhost/'`  | 自定义 HTTP Referer 头                    |
| `rtspTransport` | `string`  | `'udp'`                | RTSP 传输协议（`'udp'` 或 `'tcp'`）       |
| `hwaccel`       | `boolean` | `true`                 | 启用硬件加速视频解码                      |

### 显示与音频

| 属性        | 类型      | 默认值 | 说明                                                    |
|-------------|-----------|--------|--------------------------------------------------------|
| `volume`    | `number`  | `1.0`  | 音量等级（0.0 – 1.0）。`@Watch` 响应式                  |
| `muted`     | `boolean` | `false`| 静音音频输出。`@Watch` 响应式                           |
| `scaleMode` | `number`  | `0`    | 画面缩放模式（0=填充，1=适应，2=裁剪填充等）。`@Watch` 响应式 |

> `volume`、`muted`、`scaleMode` 和 `bufferTime` 使用 `@Watch('onPropUpdated')` 装饰，修改后无需重启播放即可实时生效。

### License

| 属性      | 类型     | 默认值 | 说明            |
|-----------|----------|--------|-----------------|
| `license` | `string` | `''`   | SDK 授权密钥    |

---

## Controller

### NodePlayerController

`controller` 属性提供对播放的编程控制：

| 方法    | 签名                           | 说明           |
|---------|--------------------------------|----------------|
| `start` | `(url?: string) => void`       | 开始或恢复播放 |
| `stop`  | `() => void`                   | 停止播放       |
| `pause` | `() => void`                   | 暂停播放       |

```typescript
// 使用示例
let playerController = new NodePlayerController();

NodePlayer({
  controller: playerController,
  src: 'rtsp://example.com/stream'
});

playerController.start();
playerController.pause();
playerController.stop();
```

---

## 事件

### onEvent

| 类型                                              | 说明                         |
|---------------------------------------------------|------------------------------|
| `(code: number, msg: string) => void`             | 接收播放器状态/错误事件      |

```typescript
NodePlayer({
  onEvent: (code: number, msg: string) => {
    console.info(`播放器事件 [${code}]: ${msg}`);
  }
})
```

### 事件码说明

#### 播放相关事件

| Code | 名称             | 说明                           |
|------|------------------|--------------------------------|
| 1000 | 连接中           | 正在连接视频源                 |
| 1001 | 连接成功         | 视频连接成功，开始播放         |
| 1002 | 连接失败         | 视频连接失败（自动重连中）     |
| 1003 | 重连中           | 视频开始重新连接               |
| 1004 | 播放结束         | 视频播放正常结束               |
| 1005 | 网络异常         | 网络异常（自动重连中）         |
| 1006 | 连接超时         | 网络连接超时（自动重连中）     |

#### 缓冲相关事件

| Code | 名称             | 说明                              |
|------|------------------|-----------------------------------|
| 1100 | 缓冲区空         | 播放缓冲区为空                    |
| 1101 | 缓冲中           | 播放缓冲区正在缓冲数据            |
| 1102 | 缓冲完成         | 缓冲完成，开始播放                |
| 1103 | 流统计信息       | 流统计信息（每秒回调一次）        |
| 1104 | 视频分辨率       | 解码后得到视频宽高（`msg` 格式为 `width x height`） |

---

## 生命周期

NodePlayer 是标准 ArkUI `@Component`，生命周期集成如下：

| 生命周期钩子        | 行为                                               |
|---------------------|----------------------------------------------------|
| `aboutToAppear()`   | 初始化原生播放器，绑定 controller 方法；若 `autoplay = true` 则自动开始播放 |
| `aboutToDisappear()`| 停止正在进行的播放，释放原生播放器资源             |

当组件从 UI 树中移除时，原生播放器会自动停止并释放，无需通过 controller 手动清理。

---

### 响应式属性

使用 `@Watch` 装饰的属性（`volume`、`muted`、`scaleMode`、`bufferTime`）可实时更新：

```typescript
NodePlayer({
  src: 'rtmp://example.com/live/stream',
  volume: 0.5,
  muted: false,
  scaleMode: 1,
  bufferTime: 2000
})
```

这些属性在组件挂载后的修改会通过 `onPropUpdated()` 立即生效。

---

## 缩放模式

| 值  | 模式         | 说明                               |
|-----|--------------|-----------------------------------|
| `0` | 填充（Fill） | 拉伸填满整个显示区域（可能裁剪）  |
| `1` | 适应（Aspect Fit）| 保持宽高比完整显示（留黑边） |
| `2` | 裁剪填充（Aspect Fill）| 保持宽高比填满区域（可能裁剪） |

> 具体模式可用性取决于原生解码器实现。

---

## 注意事项

- **权限要求**：网络流需要在 `module.json5` 中添加 `ohos.permission.INTERNET` 权限。
- **硬件加速**：默认启用。如遇兼容性问题可设为 `hwaccel: false` 使用软件解码。
- **RTSP 传输**：默认为 UDP。在不稳定网络中建议切换为 TCP 以获得更好可靠性。
- **缓冲时间**：默认 1000ms。连接不稳定时可增大，追求低延迟时可减小。
- `XComponent` 默认渲染为 100% 宽高。如需自定义尺寸，请在外层包裹容器。

---

## 原生 API 映射

ArkTS 组件通过 `NodeMediaClient` 接口委托给原生 `libnodemediaclient.so` 库。以下为原生函数调用关系：

| 原生函数                          | 触发时机                                    |
|-----------------------------------|---------------------------------------------|
| `player_init`                     | `aboutToAppear()`                           |
| `player_start`                    | `start()`                                   |
| `player_stop`                     | `stop()`、`aboutToDisappear()`              |
| `player_pause`                    | `pause()`                                   |
| `player_free`                     | `aboutToDisappear()`                        |
| `player_set_volume`               | `setVolume()`、`setMuted()`、`start()`      |
| `player_set_scaleMode`            | `setScaleMode()`、`start()`                 |
| `player_set_bufferTime`           | `setBufferTime()`、`start()`                |
| `player_set_cryptoKey`            | `start()`                                   |
| `player_set_ua`                   | `start()`                                   |
| `player_set_referer`              | `start()`                                   |
| `player_set_rtspTransport`        | `start()`                                   |
| `player_set_hwaccel`              | `start()`                                   |
| `player_set_clearScreen`          | `start()`                                   |

> 配置属性（`cryptoKey`、`ua`、`referer`、`rtspTransport`、`hwaccel`、`clearScreen`）仅在 `start()` 时生效。如需修改，请先调用 `stop()` 再重新 `start()`。

文档

NodePlayer API