---
name: "IpcPlayer"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.6.9" }
title: "IpcPlayer - Real-time video playback"
---

## IpcPlayer

> [VERSION] @ray-js/ray >= 0.6.9

### Description

Real-time video playback component. A native component with separate-layer rendering; be aware of the limitations on native components.

### Props

| Property | Type | Required | Default | Since | Description |
| --- | --- | --- | --- | --- | --- |
| `deviceId` | `string` | Yes | `""` | - | Device ID; the component's unique identifier; required |
| `autoplay` | `boolean` | No | `false` | - | Autoplay |
| `muted` | `boolean` | No | - | - | Whether to mute |
| `clarity` | `"ss" \| "normal" \| "hd" \| "ud" \| "ssp" \| "auto" \| "audio"` | No | `"normal"` | - | Quality: ss (data saver), normal (SD), hd (HD), ud (UHD), ssp (extra HD), auto (auto), audio (audio mode) |
| `soundMode` | `"speaker" \| "ear"` | No | `"speaker"` | - | Audio output: speaker (loudspeaker), ear (earpiece) |
| `orientation` | `"vertical" \| "horizontal"` | No | `"vertical"` | - | Screen orientation: vertical (portrait), horizontal (landscape) |
| `objectFit` | `"contain" \| "fillCrop"` | No | `"contain"` | - | Fill mode: contain (fit long edge), fillCrop (cover and crop) |
| `autoPauseIfNavigate` | `boolean` | No | `true` | - | Whether to auto-pause real-time audio/video when navigating to another page within this mini program |
| `autoPauseIfOpenNative` | `boolean` | No | `true` | - | Whether to auto-pause real-time audio/video when navigating to other native pages in the app |
| `rotateZ` | `number` | No | `0` | - | Camera rotation angle, 0–360 |
| `scalable` | `boolean` | No | `true` | - | Whether zoom is currently enabled |
| `scaleMultiple` | `number` | No | `0` | - | Zoom ratio; takes effect only when scalable is true |
| `ptzControllable` | `boolean` | No | `true` | - | Whether to enable cloud platform control for the video area |
| `borderWidth` | `number \| string` | No | `0` | - | Border width, in px |
| `borderStyle` | `"solid" \| "dashed"` | No | `"solid"` | - | Border style: solid, dashed |
| `borderColor` | `string` | No | `"#ffffff"` | - | Border color, hex |
| `borderRadius` | `number \| string` | No | `0` | - | Border radius, in px |
| `backgroundColor` | `string` | No | `"#ffffff"` | - | Background color, hex |
| `extProps` | `string \| Record<string, any>` | No | - | `@ray-js/ray 1.7.79` | Additional properties |
| `onConnectchange` | `(event: IpcPlayerConnectChangeEvent) => void` | No | - | - | Fires when the connection state changes; use onConnectChange |
| `onPreviewchange` | `(event: IpcPlayerPreviewChangeEvent) => void` | No | - | - | Fires when the preview state changes; use onPreviewChange |
| `onOnlinechange` | `(event: IpcPlayerOnlineChangeEvent) => void` | No | - | - | Fires when the device online status changes; use onOnlineChange |
| `onInitdone` | `(event: IpcPlayerInitDoneEvent) => void` | No | - | - | Fires when initialization completes; use onInitDone |
| `onZoomchange` | `(event: IpcPlayerZoomChangeEvent) => void` | No | - | - | Fires when the video zoom ratio changes; use onZoomChange |
| `onVideotap` | `(event: IpcPlayerVideotapEvent) => void` | No | - | - | Fires when the video is tapped; use onVideoTap |
| `onConnectChange` | `(event: IpcPlayerConnectChangeEvent) => void` | No | - | - | Fires when the connection state changes; state = 0 indicates connection successful |
| `onPreviewChange` | `(event: IpcPlayerPreviewChangeEvent) => void` | No | - | - | Fires when the preview state changes; state = 1 indicates preview started successfully, 0 indicates preview ended successfully |
| `onOnlineChange` | `(event: IpcPlayerOnlineChangeEvent) => void` | No | - | - | Fires when the IPC device online status changes |
| `onInitDone` | `(event: IpcPlayerInitDoneEvent) => void` | No | - | - | Triggered when initialization completes |
| `onZoomChange` | `(event: IpcPlayerZoomChangeEvent) => void` | No | - | - | Fires when the video zoom ratio and current zoom factor change |
| `onVideoTap` | `(event: IpcPlayerVideotapEvent) => void` | No | - | - | Fires when the video is tapped |
| `onError` | `(event: IpcPlayerErrorEvent) => void` | No | - | - | Fires when the state is abnormal |
| `onSessionDidDisconnected` | `(event: IpcPlayerSessionDidDisconnectedEvent) => void` | No | - | - | Disconnected (⚠️ Not delivered on Android; disconnection is reflected via onConnectChange with state < 0) |
| `onCameraPreviewFailure` | `(event: IpcPlayerCameraPreviewFailureEvent) => void` | No | - | `IPCKit 6.1.4` | Preview failed (fires when P2P sessionStatus < 0; shared by normal and multi-lens preview) |
| `onCameraNotifyWeakNetwork` | `(event: IpcPlayerCameraNotifyWeakNetworkEvent) => void` | No | - | `IPCKit 6.1.4` | Weak network notification |
| `onCreateViewSuccess` | `(event: IpcPlayerCreateViewSuccessEvent) => void` | No | - | `IPCKit 6.2.3` | Fires when the overlay component is created successfully |
| `onSelectVideoIndex` | `(event: IpcPlayerSelectVideoIndexEvent) => void` | No | - | `IPCKit 7.3.3` | Fires when a video index is selected |
| `onLayoutStatusChanged` | `(event: IpcPlayerLayoutStatusChangedEvent) => void` | No | - | `IPCKit 7.3.3` | Fires when the layout state changes |
| `onLocalizerViewLocated` | `(event: IpcPlayerLocalizerViewLocatedEvent) => void` | No | - | `IPCKit 7.3.3` | Fires when the locator positions |
| `onSwipeAtVideoIndex` | `(event: IpcPlayerSwipeAtVideoIndexEvent) => void` | No | - | `IPCKit 7.3.3` | Fires when a swipe gesture on the player is reported and PTZ rotation is required |
| `updateLayout` | `unknown` | No | - | - | Used for cross-layer components to notify the container layer to update styles |

### Referenced Types

##### `interface` IpcPlayerConnectChangeEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerStateDetail` | Event detail data |

##### `interface` IpcPlayerPreviewChangeEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerStateDetail` | Event detail data |

##### `interface` IpcPlayerOnlineChangeEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerOnlineChangeDetail` | Event detail data |

##### `interface` IpcPlayerInitDoneEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerInitDoneDetail` | Event detail data |

##### `interface` IpcPlayerZoomChangeEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerZoomChangeNormalDetail \| IpcPlayerZoomChangeCloudDetail` | Event detail data |

##### `interface` IpcPlayerVideotapEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `Record<string, never>` | Event detail data |

##### `interface` IpcPlayerErrorEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerErrorDetail` | Event detail data |

##### `interface` IpcPlayerSessionDidDisconnectedEvent

```typescript
export interface IpcPlayerSessionDidDisconnectedEvent extends BaseEvent {
  /** 事件类型 */
  type: 'sessionDidDisconnected';
}
```

##### `interface` IpcPlayerCameraPreviewFailureEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerCameraPreviewFailureDetail` | Event detail data |

##### `interface` IpcPlayerCameraNotifyWeakNetworkEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerWeakNetworkDetail` | Event detail data |

##### `interface` IpcPlayerCreateViewSuccessEvent

```typescript
export interface IpcPlayerCreateViewSuccessEvent extends BaseEvent {
  /** 事件类型 */
  type: 'createViewSuccess';
}
```

##### `interface` IpcPlayerSelectVideoIndexEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerSelectVideoIndexDetail` | Event detail data |

##### `interface` IpcPlayerLayoutStatusChangedEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerLayoutStatusChangedDetail` | Event detail data |

##### `interface` IpcPlayerLocalizerViewLocatedEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerLocalizerViewLocatedDetail` | Event detail data |

##### `interface` IpcPlayerSwipeAtVideoIndexEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `IpcPlayerSwipeAtVideoIndexDetail` | Event detail data |

##### `interface` IpcPlayerStateDetail

| Property | Type | Description |
| --- | --- | --- |
| `state` | `number` | Connection status: 0 means connected, <0 means error; Preview status: 1 start preview, 0 stop preview |

##### `interface` BaseEvent

| Property | Type | Description |
| --- | --- | --- |
| `type` | `string` | Event type |
| `timeStamp` | `number` | Time in milliseconds since the page opened |
| `target` | `Target` | Source component of the event |
| `currentTarget` | `Target` | Collection of property values for the current component |
| `mark` | `any` | Event mark data |

##### `interface` IpcPlayerOnlineChangeDetail

| Property | Type | Description |
| --- | --- | --- |
| `online` | `boolean` | Whether online |

##### `interface` IpcPlayerInitDoneDetail

| Property | Type | Description |
| --- | --- | --- |
| `maxScaleMultiple` | `number` | Maximum zoom factor (may be null) |
| `obtainCameraConfig` | `any` | Device camera configuration (parsed JSON object) |

##### `interface` IpcPlayerZoomChangeNormalDetail

| Property | Type | Description |
| --- | --- | --- |
| `zoomLevel` | `number` | Current zoom factor |
| `scaleMode` | `number` | Free-zoom state flag |

##### `interface` IpcPlayerZoomChangeCloudDetail

| Property | Type | Description |
| --- | --- | --- |
| `zoom_level` | `number` | Free-zoom state flag |
| `scale` | `number` | Current zoom factor |

##### `interface` IpcPlayerErrorDetail

| Property | Type | Description |
| --- | --- | --- |
| `errCode` | `number` | Error code |
| `errMsg` | `string` | Error description |

##### `interface` IpcPlayerCameraPreviewFailureDetail

| Property | Type | Description |
| --- | --- | --- |
| `errCode` | `number` | Error code |
| `deviceId` | `string` | Device ID |

##### `interface` IpcPlayerWeakNetworkDetail

| Property | Type | Description |
| --- | --- | --- |
| `netValue` | `number` | Network quality value (native Long type, may exceed 32-bit) |
| `devId` | `string` | Device ID |

##### `interface` IpcPlayerSelectVideoIndexDetail

| Property | Type | Description |
| --- | --- | --- |
| `index` | `number` | Lens index |
| `name` | `string` | Lens name |
| `supportPTZ` | `boolean` | Whether PTZ control is supported |
| `supportLocalizer` | `boolean` | Whether locator is supported |
| `supportZoom` | `boolean` | Whether zoom is supported |

##### `interface` IpcPlayerLayoutStatusChangedDetail

| Property | Type | Description |
| --- | --- | --- |
| `screenMode` | `number` | Screen mode (enum ordinal): 0 short screen, 1 full screen, 2 landscape |
| `layoutStyle` | `number` | Layout style (enum ordinal): -1 invalid, 0 picture-in-picture, 1 tiled, 2 grid, 3 thumbnail |

##### `interface` IpcPlayerLocalizerViewLocatedDetail

| Property | Type | Description |
| --- | --- | --- |
| `index` | `string` | Linked PTZ camera index (Note: this is a string, different from selectVideoIndex which is a number) |
| `coor` | `string` | x, y coordinates |

##### `interface` IpcPlayerSwipeAtVideoIndexDetail

| Property | Type | Description |
| --- | --- | --- |
| `index` | `number` | Swiped lens index |
| `direction` | `number` | Swipe direction: up/down/left/right, enum 0/1/2/3 |
| `isStop` | `number` | Gesture state: 1 start, 0 end |

##### `interface` Target

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | id of the event source component |
| `dataset` | `Record<string, unknown>` | Collection of custom attributes from the `dataset` on the event source component |


### Examples

#### Basic usage

```tsx
import React from 'react';
import { IpcPlayer, View, Text } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <Text style={{ marginBottom: '10px' }}>IPC Live Video</Text>
      <IpcPlayer
        deviceId="your-device-id"
        autoplay
        style={{ width: '100%', height: '300px' }}
        onInitDone={(e) => {
          console.log('Initialization complete, max zoom scale:', e.detail.maxScaleMultiple);
        }}
        onError={(e) => {
          console.log('Error:', e.detail);
        }}
      />
    </View>
  );
}
```

#### IPC playback control

```tsx
import React, { useState } from 'react';
import { IpcPlayer, View, Text, Button, createIpcPlayerContext } from '@ray-js/ray';

export default function () {
  const [isOnline, setIsOnline] = useState(false);
  const [connectState, setConnectState] = useState(-1);
  const [previewState, setPreviewState] = useState(-1);
  const playerId = 'myIpcPlayer';

  const handleStartPreview = () => {
    const ctx = createIpcPlayerContext(playerId);
    ctx.startPreview();
  };

  const handleStopPreview = () => {
    const ctx = createIpcPlayerContext(playerId);
    ctx.stopPreview();
  };

  return (
    <View style={{ padding: '20px' }}>
      <IpcPlayer
        id={playerId}
        deviceId="your-device-id"
        autoplay={false}
        muted={false}
        clarity="hd"
        soundMode="speaker"
        orientation="vertical"
        objectFit="contain"
        scalable
        ptzControllable
        borderRadius={8}
        style={{ width: '100%', height: '300px' }}
        onConnectChange={(e) => {
          console.log('Connection status changed:', e.detail.state);
          setConnectState(e.detail.state);
        }}
        onPreviewChange={(e) => {
          console.log('Preview status changed:', e.detail.state);
          setPreviewState(e.detail.state);
        }}
        onOnlineChange={(e) => {
          console.log('Online status changed:', e.detail.online);
          setIsOnline(e.detail.online);
        }}
        onZoomChange={(e) => {
          if ('zoomLevel' in e.detail) {
            console.log('Zoom changed:', e.detail.zoomLevel);
          }
        }}
        onVideoTap={() => {
          console.log('Video tapped');
        }}
        onError={(e) => {
          console.log('Error:', e.detail);
        }}
      />
      <View style={{ marginTop: '10px' }}>
        <Text>Device online: {isOnline ? 'Yes' : 'No'}</Text>
        <Text>Connection status: {connectState === 0 ? 'Connected' : 'Not connected'}</Text>
        <Text>Preview status: {previewState === 1 ? 'Previewing' : 'Not previewing'}</Text>
      </View>
      <View style={{ marginTop: '10px', display: 'flex', flexDirection: 'row', gap: '8px' }}>
        <Button size="mini" onClick={handleStartPreview}>Start preview</Button>
        <Button size="mini" onClick={handleStopPreview}>Stop preview</Button>
      </View>
    </View>
  );
}
```


## Error Codes

| Value | Description                       |
| ----- | --------------------------------- |
| -1000 | Other unknown exception           |
| -1001 | connect failed                    |
| -1002 | Start preview failed              |
| -1003 | Stop preview failed               |
| -1004 | Set mute failed                   |
| -1005 | Set clarity failed                |
| -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 Links

Related API: [createIpcPlayerContext](/en/miniapp/develop/miniapp/api/media/ipc/createIpcContext). This is a native component based on off-screen rendering. Please note the [native component usage restrictions](/en/miniapp/develop/miniapp/component/native-component/native-component).

### FAQ

1. `ipc-player` default width is 300px and height is 225px. You can set the width and height via tyss.
2. Not supported in the Tuya MiniApp IDE.
3. For related principles, refer to [Native components based on off-screen rendering](/en/miniapp/develop/miniapp/component/native-component/native-component).
4. Please note the [native component usage restrictions](/en/miniapp/develop/miniapp/component/native-component/native-component).