---
name: "ipc-player"
mode: "component"
versionRequirements:
  - { name: "Base Library", version: "2.10.0" }
title: "ipc-player - Real-time video playback"
---

## ipc-player

> [VERSION] Base Library >= 2.10.0

### Description

IPC cloud player component for real-time video streaming.

### Props

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `device-id` | `string` | Yes | - | Unique identifier of the component; this attribute is required |
| `autoplay` | `boolean` | No | `false` | Whether to autoplay |
| `muted` | `boolean` | No | `false` | Muted |
| `sound-mode` | `string` | No | `"speaker"` | Audio output mode: speaker, ear |
| `clarity` | `string` | No | `"normal"` | Quality |
| `extProps` | `string` | No | - | Additional parameter configuration |
| `object-fit` | `string` | No | `"contain"` | Fit mode: contain, cover, fill |
| `orientation` | `string` | No | `"vertical"` | Orientation: vertical, horizontal |
| `auto-pause-if-navigate` | `boolean` | No | `true` | Whether to auto-pause when navigating to another page |
| `auto-pause-if-open-native` | `boolean` | No | `true` | Whether to auto-pause when navigating to a native page |
| `rotate-z` | `number` | No | `0` | Camera rotation angle; valid integer 0–360 |
| `scalable` | `boolean` | No | `true` | Whether zooming is enabled |
| `scale-multiple` | `number` | No | `0` | Zoom scale; effective only when scalable is true |
| `ptz-controllable` | `boolean` | No | `true` | Whether to enable cloud platform control of the video area |
| `background-color` | `string` | No | `"#ffffff"` | Background color; must be in hex |
| `border-width` | `number` | No | `0` | Border width, in px |
| `border-style` | `string` | No | `"solid"` | Border style: solid, dashed |
| `border-color` | `string` | No | `"#ffffff"` | Border color, must be in hexadecimal format |
| `border-radius` | `number` | No | `0` | Border radius, in px |
| `border-radius-top-left` | `number` | No | - | Top-left corner radius, in px |
| `border-radius-top-right` | `number` | No | - | Top-right corner radius, in px |
| `border-radius-bottom-left` | `number` | No | - | Bottom-left corner radius, in px |
| `border-radius-bottom-right` | `number` | No | - | Bottom-right corner radius, in px |

#### Events

| Event | Type | Description |
| --- | --- | --- |
| `connectchange` | `(event: IpcPlayerConnectchangeEvent) => void` | Fires when the connection state changes |
| `previewchange` | `(event: IpcPlayerPreviewchangeEvent) => void` | Fires when the preview state changes |
| `onlinechange` | `(event: IpcPlayerOnlinechangeEvent) => void` | Fires when the device online status changes |
| `initdone` | `(event: IpcPlayerInitdoneEvent) => void` | Triggered when initialization completes |
| `zoomchange` | `(event: IpcPlayerZoomchangeEvent) => void` | Fires when the video zoom scale changes |
| `videotap` | `(event: Object) => void` | Triggered when the video is clicked |
| `error` | `(event: IpcPlayerErrorEvent) => void` | Fires when an abnormal state occurs |

**IpcPlayerConnectchangeEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"connectchange"` |  |
| `detail` | `IpcPlayerStateDetail` |  |

**IpcPlayerPreviewchangeEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"previewchange"` |  |
| `detail` | `IpcPlayerStateDetail` |  |

**IpcPlayerOnlinechangeEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"onlinechange"` |  |
| `detail` | `IpcPlayerOnlinechangeDetail` |  |

**IpcPlayerInitdoneEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"initdone"` |  |
| `detail` | `IpcPlayerInitdoneDetail` |  |

**IpcPlayerZoomchangeEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"zoomchange"` |  |
| `detail` | `IpcPlayerZoomchangeDetail` |  |

**videotap callback object**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"videotap"` |  |

**IpcPlayerErrorEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"error"` |  |
| `detail` | `IpcPlayerErrorDetail` |  |

### Examples

#### Basic usage

*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('Connection state:', e.detail.state);
  },
  onInitDone(e) {
    console.log('Initialization complete, max zoom:', e.detail.maxScaleMultiple);
  },
});
```

#### Fullscreen playback and event listening

*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('Preview state:', e.detail.state);
  },
  onOnlineChange(e) {
    console.log('Device online:', e.detail.online);
  },
  onZoomChange(e) {
    console.log('Zoom level:', e.detail.zoomLevel);
  },
  onVideoTap() {
    console.log('Video tapped');
  },
  onError(e) {
    console.log('Error:', e.detail.errMsg);
  },
});
```


## Error Codes

| Value | Description                       |
| ----- | --------------------------------- |
| -1000 | Other unknown exceptions          |
| -1001 | connect failed                    |
| -1002 | Failed to start preview           |
| -1003 | Failed to stop preview            |
| -1004 | Failed to set mute                |
| -1005 | Failed to set clarity             |
| -1006 | Screenshot failed                 |
| -1007 | Invalid property                  |
| -1008 | Invalid parameter                 |
| -1009 | disconnect failed                 |
| -1010 | Network unavailable               |
| -1011 | Device offline                    |
| -1012 | Device removed                    |
| -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                 |

### Related Documents

- Related API: [ty.createIpcPlayerContext](/en/miniapp/develop/miniapp/api/media/ipc/createIpcContext)
- This is a native component rendered based on heterolayers. Take care of the [limitations of the native component](/en/miniapp/develop/miniapp/component/native-component/native-component).

### FAQ

1. ipc-player has a default width of 300px and height of 225px. You can set the dimensions via tyss.
2. Not supported on Tuya MiniApp IDE.
3. For more information about principles, see [Native component rendered based on heterolayers](/en/miniapp/develop/miniapp/component/native-component/native-component).
4. Take care of the [limitations of the native component](/en/miniapp/develop/miniapp/component/native-component/native-component).