---
name: "ipc-player"
mode: "component"
versionRequirements:
  - { name: "基础库", version: "2.10.0" }
title: "ipc-player - 实时视频播放"
---

## ipc-player

> [VERSION] 基础库 >= 2.10.0

### 描述

IPC 云播放器组件，用于实时视频流播放。

### 属性

| 属性 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `device-id` | `string` | 是 | - | 组件的唯一标识符，必须设置该属性 |
| `autoplay` | `boolean` | 否 | `false` | 是否自动播放 |
| `muted` | `boolean` | 否 | `false` | 是否静音 |
| `sound-mode` | `string` | 否 | `"speaker"` | 声音输出方式：speaker、ear |
| `clarity` | `string` | 否 | `"normal"` | 清晰度 |
| `extProps` | `string` | 否 | - | 额外参数配置 |
| `object-fit` | `string` | 否 | `"contain"` | 填充模式：contain、cover、fill |
| `orientation` | `string` | 否 | `"vertical"` | 画面方向：vertical、horizontal |
| `auto-pause-if-navigate` | `boolean` | 否 | `true` | 跳转其他页面时是否自动暂停 |
| `auto-pause-if-open-native` | `boolean` | 否 | `true` | 跳转原生页面时是否自动暂停 |
| `rotate-z` | `number` | 否 | `0` | 摄像头旋转角度，有效值 0~360 的整数 |
| `scalable` | `boolean` | 否 | `true` | 是否可缩放 |
| `scale-multiple` | `number` | 否 | `0` | 缩放比例，仅 scalable 为 true 时生效 |
| `ptz-controllable` | `boolean` | 否 | `true` | 是否开启视频区域云平台控制 |
| `background-color` | `string` | 否 | `"#ffffff"` | 背景颜色，必须为十六进制格式 |
| `border-width` | `number` | 否 | `0` | 边框宽度，单位 px |
| `border-style` | `string` | 否 | `"solid"` | 边框样式：solid、dashed |
| `border-color` | `string` | 否 | `"#ffffff"` | 边框颜色，必须为十六进制格式 |
| `border-radius` | `number` | 否 | `0` | 边框圆角，单位 px |
| `border-radius-top-left` | `number` | 否 | - | 左上角圆角，单位 px |
| `border-radius-top-right` | `number` | 否 | - | 右上角圆角，单位 px |
| `border-radius-bottom-left` | `number` | 否 | - | 左下角圆角，单位 px |
| `border-radius-bottom-right` | `number` | 否 | - | 右下角圆角，单位 px |

#### 事件

| 事件名 | 类型 | 描述 |
| --- | --- | --- |
| `connectchange` | `(event: IpcPlayerConnectchangeEvent) => void` | 连接状态发生变化时触发 |
| `previewchange` | `(event: IpcPlayerPreviewchangeEvent) => void` | 预览状态发生变化时触发 |
| `onlinechange` | `(event: IpcPlayerOnlinechangeEvent) => void` | 设备在线状态变化时触发 |
| `initdone` | `(event: IpcPlayerInitdoneEvent) => void` | 初始化完成时触发 |
| `zoomchange` | `(event: IpcPlayerZoomchangeEvent) => void` | 视频缩放比例变化时触发 |
| `videotap` | `(event: Object) => void` | 点击视频时触发 |
| `error` | `(event: IpcPlayerErrorEvent) => void` | 状态异常时触发 |

**IpcPlayerConnectchangeEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"connectchange"` |  |
| `detail` | `IpcPlayerStateDetail` |  |

**IpcPlayerPreviewchangeEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"previewchange"` |  |
| `detail` | `IpcPlayerStateDetail` |  |

**IpcPlayerOnlinechangeEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"onlinechange"` |  |
| `detail` | `IpcPlayerOnlinechangeDetail` |  |

**IpcPlayerInitdoneEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"initdone"` |  |
| `detail` | `IpcPlayerInitdoneDetail` |  |

**IpcPlayerZoomchangeEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"zoomchange"` |  |
| `detail` | `IpcPlayerZoomchangeDetail` |  |

**videotap 的回调参数对象**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"videotap"` |  |

**IpcPlayerErrorEvent**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `"error"` |  |
| `detail` | `IpcPlayerErrorDetail` |  |

### 示例代码

#### 基础用法

*index.tyml*

```xml
<ipc-player
  device-id="{{deviceId}}"
  autoplay="{{true}}"
  class="player"
  bindconnectchange="onConnectChange"
  bindinitdone="onInitDone"
></ipc-player>
```

*index.tyss*

```css
.player {
  width: 100%;
  height: 500rpx;
}
```

*index.js*

```javascript
Page({
  data: {
    deviceId: 'your-device-id',
  },
  onConnectChange(e) {
    console.log('连接状态:', e.detail.state);
  },
  onInitDone(e) {
    console.log('初始化完成, 最大缩放:', e.detail.maxScaleMultiple);
  },
});
```

#### 全屏播放与事件监听

*index.tyml*

```xml
<ipc-player
  device-id="{{deviceId}}"
  autoplay="{{true}}"
  orientation="horizontal"
  object-fit="cover"
  muted="{{false}}"
  sound-mode="speaker"
  scalable="{{true}}"
  ptz-controllable="{{true}}"
  class="player-full"
  bindpreviewchange="onPreviewChange"
  bindonlinechange="onOnlineChange"
  bindzoomchange="onZoomChange"
  bindvideotap="onVideoTap"
  binderror="onError"
></ipc-player>
```

*index.tyss*

```css
.player-full {
  width: 100%;
  height: 100vh;
}
```

*index.js*

```javascript
Page({
  data: {
    deviceId: 'your-device-id',
  },
  onPreviewChange(e) {
    console.log('预览状态:', e.detail.state);
  },
  onOnlineChange(e) {
    console.log('设备在线:', e.detail.online);
  },
  onZoomChange(e) {
    console.log('缩放倍数:', e.detail.zoomLevel);
  },
  onVideoTap() {
    console.log('点击视频');
  },
  onError(e) {
    console.log('错误:', e.detail.errMsg);
  },
});
```

## 错误码

| 值    | 说明                              |
| ----- | --------------------------------- |
| -1000 | 其他未知异常                      |
| -1001 | connect 失败                      |
| -1002 | 开启预览失败                      |
| -1003 | 结束预览失败                      |
| -1004 | 设置静音失败                      |
| -1005 | 设置清晰度失败                    |
| -1006 | 截图失败                          |
| -1007 | 属性不合法                        |
| -1008 | 设置参数不合法                    |
| -1009 | disconnect 失败                   |
| -1010 | 网络状态不可用                    |
| -1011 | 设备离线                          |
| -1012 | 设备被移除                        |
| -1013 | startTalk fail                    |
| -1014 | StopTalk fail                     |
| -1015 | StartRecord fail                  |
| -1016 | StopRecord fail                   |
| -1017 | IsTalkBacking fail                |
| -1018 | SetAvailableRockerDirections fail |
| -1019 | IsPTZControllable fail            |
| -1020 | SetTrackingStatus fail            |
| -1021 | GetVideoInfo fail                 |

### 相关文档

- 相关 API：[ty.createIpcPlayerContext](/cn/miniapp/develop/miniapp/api/media/ipc/createIpcContext)
- 这是基于异层渲染的原生组件，请注意 [原生组件使用限制](/cn/miniapp/develop/miniapp/component/native-component/native-component)

### 常见问题

1. ipc-player 默认宽度 300px、高度 225px，可通过 tyss 设置宽高。
2. Tuya MiniApp IDE 上暂不支持。
3. 相关原理请参考 [基于异层渲染的原生组件](/cn/miniapp/develop/miniapp/component/native-component/native-component)。
4. 请注意 [原生组件使用限制](/cn/miniapp/develop/miniapp/component/native-component/native-component)。