English | 简体中文

@ray-js/lock-video-player

Real-time IPC video player for smart lock panels. Exposes talk, recording, snapshot, voice-effect, and full-screen APIs via ref.

Installation

npm install @ray-js/lock-video-player
# or
yarn add @ray-js/lock-video-player

Dependencies

| Package | Notes | | ------------------------------------------------ | -------------------------------------------- | | @ray-js/ray | peerDependency — install in your app | | @ray-js/components | dependency — provides the native IpcPlayer | | @ray-js/panel-sdk | dependency — i18n | | ahooks, use-immer, immer, lodash, clsx | dependencies — installed with the package |

For camera rotation in lock panels, optionally install @ray-js/lock-sdk (see Example).

Quick start

import React, { useRef } from 'react';
import LockVideoPlayer, { type ILockVideoPlayerRef } from '@ray-js/lock-video-player';

export default function VideoPage() {
  const playerRef = useRef<ILockVideoPlayerRef>(null);

  return (
    <LockVideoPlayer
      ref={playerRef}
      devId="your-device-id"
      className="video-area"
      rotateZ={0}
      awakeStatus
      reConnect
      onCtx={ctx => {
        console.log('ipc ctx', ctx);
      }}
      onChangeStreamStatus={data => {
        console.log('stream status', data);
      }}
    />
  );
}

Props

Besides the table below, most props of the vendored player core are forwarded (e.g. awakeStatus, reConnect, scalable). See src/ipc-player/typings/index.d.ts for the full list.

| Prop | Type | Default | Description | | ---------------------- | ---------------------------------------------------------------- | ------------ | ------------------------- | | devId | string | required | Device ID | | className | string | - | Root class name | | style | CSSProperties | - | Root inline style | | onlineStatus | boolean | true | Whether device is online | | privateState | boolean | false | Privacy mode | | defaultMute | boolean | false | Mute by default | | clarity | 'normal' \| 'hd' \| 'ss' \| 'ud' \| 'ssp' \| 'auto' \| 'audio' | 'hd' | Stream clarity | | rotateZ | number | 0 | Video rotation (degrees) | | objectFit | 'contain' \| 'fillCrop' | 'contain' | Object fit mode | | brandColor | string | '#FF592A' | Brand color | | onChangeStreamStatus | (data: any) => void | - | Stream status callback | | onCtx | (ctx: ILockVideoPlayerCtx) => void | - | Underlying player context |

Ref API

Call methods on ref after the player is mounted (or after onCtx fires).

startTalk / stopTalk

Two-way audio. startTalk requests scope.record first.

playerRef.current?.startTalk({
  success: () => setIsTalking(true),
  fail: () => showToast({ title: 'start talk failed' }),
});

playerRef.current?.stopTalk({
  success: () => setIsTalking(false),
  fail: () => showToast({ title: 'stop talk failed' }),
});

startRecord / stopRecord

Screen recording. startRecord requests scope.writePhotosAlbum first.

| Param | Type | Default | Description | | ------------------------------- | ------------------ | ------- | ----------------------------------- | | saveToAlbum | 0 \| 1 | 0 | 0 = system album, 1 = IPC album | | rotate | 0 \| 1 \| 2 \| 3 | - | Rotation | | success / fail / complete | function | - | Callbacks |

snapshot

Takes a snapshot. Requests scope.writePhotosAlbum first. When saveToAlbum is 0, saves to the system album via saveImageToPhotosAlbum after capture.

success may receive tempImagePath or filePath.

changeVoiceEffect

Calls ipc.enableVoiceEffect using the component devId.

| effectType | Effect | | ------------ | ---------- | | 0 | Original | | 1 | Young male | | 2 | Uncle | | 3 | Robot | | 4 | Loli |

playerRef.current?.changeVoiceEffect({
  effectType: 0,
  success: () => showToast({ title: 'voice effect updated' }),
  fail: () => showToast({ title: 'voice effect failed' }),
});

setPageOrientation

Set the page orientation (landscape / portrait). pageOrientation defaults to 'landscape'. Wraps Ray's setPageOrientation; the player layout and the built-in back button adapt automatically via onResize.

| Param | Type | Default | Description | | ------------------------------- | --------------------------- | ------------- | ------------------ | | pageOrientation | 'portrait' \| 'landscape' | 'landscape' | Target orientation | | success / fail / complete | function | - | Callbacks |

// enter landscape (full screen)
playerRef.current?.setPageOrientation();

// back to portrait
playerRef.current?.setPageOrientation({
  pageOrientation: 'portrait',
  success: () => showToast({ title: 'back to portrait' }),
  fail: () => showToast({ title: 'orientation change failed' }),
});

onCtx & retry

onCtx provides the underlying player context (retry, startTalk, stopRecord, etc.). Use retry() when the stream fails to connect:

const ipcCtxRef = useRef<ILockVideoPlayerCtx | null>(null);

<LockVideoPlayer
  devId={deviceId}
  onCtx={ctx => {
    ipcCtxRef.current = ctx;
  }}
/>;

useEffect(() => {
  const timer = setTimeout(() => ipcCtxRef.current?.retry?.(), 800);
  return () => clearTimeout(timer);
}, [connected]);

Permissions

| Feature | Scope | | ------------------------- | ------------------------ | | startTalk | scope.record | | startRecord, snapshot | scope.writePhotosAlbum |

Authorization is handled inside the component. Denied permission triggers the method fail callback.

Callback pattern

All ref methods support success, fail, and complete (Ray miniapp style). Recommended:

• Update UI in success (e.g. talking / recording state)
• Show errors in fail; avoid optimistic UI updates on click

Types

import LockVideoPlayer, {
  type IProps,
  type ILockVideoPlayerRef,
  type ILockVideoPlayerCtx,
} from '@ray-js/lock-video-player';

Full example

See the example/ app for:

• deviceId from route query → devId
• MQTT doorbell → open live view
• Talk / original voice / record / snapshot
• Enter / exit landscape (setPageOrientation)
• onCtx + retry

yarn
yarn start:tuya
yarn start:wechat
yarn start:web

Develop the component

yarn
yarn dev
yarn build

License

MIT