@ray-js/ipc-player-integration 0.0.38 → 0.0.39

package/README.md

@@ -4,7 +4,37 @@ English | [简体中文](./README-zh_CN.md)
 
 [![latest](https://img.shields.io/npm/v/@ray-js/ipc-player-integration/latest.svg)](https://www.npmjs.com/package/@ray-js/ipc-player-integration) [![download](https://img.shields.io/npm/dt/@ray-js/ipc-player-integration.svg)](https://www.npmjs.com/package/@ray-js/ipc-player-integration)
 
-> IPC 播放器功能集成
+> IPC integrated player — an all-in-one IPC (camera) player feature integration component for the Tuya Ray framework.
+
+Built on top of [`@ray-js/ray-ipc-player`](https://www.npmjs.com/package/@ray-js/ray-ipc-player), it wraps a complete set of upper-layer player capabilities: resolution switching, screenshot, recording, mute, two-way talk, PTZ control, zoom, battery / temperature & humidity / signal status display, portrait–landscape switching, multi-camera layouts and more — ready to use out of the box, while remaining highly customizable for both widgets and styles.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [API](#api)
+  - [`<IPCPlayerIntegration />`](#ipcplayerintegration-)
+  - [`useCtx(options)`](#usectxoptions)
+  - [`useStore(atoms)`](#usestoreatoms)
+  - [`Features`](#features-1)
+  - [`Widgets`](#widgets)
+  - [`Hooks`](#hooks)
+  - [`Utils` & device helpers](#utils--device-helpers)
+- [Custom Styling](#custom-styling)
+- [Events](#events)
+- [Multi-Camera](#multi-camera)
+- [Develop](#develop)
+
+## Features
+
+- 🎥 **Integrated player**: encapsulates preview, connection and play-state management on top of `@ray-js/ray-ipc-player`.
+- 🧩 **Declarative widget orchestration**: initialize default widgets with one call to `Features.initPlayerWidgets`, or add/remove widgets in the four corners and the absolute-positioned area on demand.
+- 🛠 **Rich built-in widgets**: resolution, screenshot, recording, mute, intercom, PTZ, zoom, battery, temperature & humidity, 4G signal, floodlight, siren, trial, and more.
+- 🎨 **Customizable**: tailor brand color, icons and fonts via `brandColor` and `CSSVariable`.
+- 📱 **Portrait / landscape / multi-camera**: supports portrait, fullscreen, landscape, and PiP / tile / grid multi-camera layouts.
+- 🪝 **Hook toolkit**: `useBattery`, `usePtz`, `useTemperature` and others for convenient device-state access.
 
 ## Installation
 
@@ -14,19 +44,318 @@ $ npm install @ray-js/ipc-player-integration
 $ yarn add @ray-js/ipc-player-integration
 ```
 
+> This component requires `ahooks` (a peerDependency); make sure it is installed in the host project.
+
+## Quick Start
+
+```tsx
+import React, { useEffect, useRef } from 'react';
+import { View } from '@ray-js/components';
+import {
+  IPCPlayerIntegration,
+  useCtx,
+  useStore,
+  Features,
+  EventInstance,
+} from '@ray-js/ipc-player-integration';
+
+export default function Home(props) {
+  const devId = props.location.query?.deviceId;
+  // 1. Create the player context instance
+  const instance = useCtx({ devId });
+  // 2. Subscribe to the state you want to render reactively
+  const { screenType } = useStore({ screenType: instance.screenType });
+  const eventRef = useRef<EventInstance>();
+
+  // 3. Initialize default widgets (resolution / screenshot / record / fullscreen ...)
+  useEffect(() => {
+    Features.initPlayerWidgets(instance, {
+      hideRecordVideoMenu: false,
+      hideScreenShotMenu: false,
+      hideResolutionMenu: false,
+      showToggleVerticalFull: true,
+    });
+  }, []);
+
+  return (
+    <View>
+      <IPCPlayerIntegration
+        instance={instance}
+        devId={instance.devId}
+        eventRef={eventRef}
+        deviceOnline
+        brandColor="#FF592A"
+        landscapeMode="fill"
+        playerFit="contain"
+        style={{ height: screenType === 'vertical' ? 'calc(100vw * 0.56)' : '100vh' }}
+      />
+    </View>
+  );
+}
+```
+
+## Core Concepts
+
+| Concept           | Description                                                                                                                                                                                          |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **instance**      | Created by `useCtx({ devId })`, it spans the whole player and manages state atoms, the player instance, widget content and the event bus. Pass it to `<IPCPlayerIntegration instance={instance} />`. |
+| **atom**          | Based on [jotai](https://jotai.org/). State on the `instance` (e.g. `screenType`, `mute`, `resolution`) are atoms; subscribe via `useStore` to render reactively.                                    |
+| **content areas** | Widgets on the player are distributed across 5 areas: `topLeft`, `topRight`, `bottomLeft`, `bottomRight`, `absolute`. Managed via `addContent` / `deleteContent` / `updateContent`, etc.             |
+| **event**         | `instance.event` provides `on/off/emit`. Expose it to the page through `eventRef` to listen for clicks, resolution switches and other events.                                                        |
+
+## API
+
+### `<IPCPlayerIntegration />`
+
+The main player component.
+
+| Prop                     | Type                             | Default              | Description                                                       |
+| ------------------------ | -------------------------------- | -------------------- | ----------------------------------------------------------------- |
+| `devId`                  | `string`                         | —                    | Device ID (required)                                              |
+| `instance`               | `ReturnType<useCtx>`             | —                    | The context instance from `useCtx`; created internally if omitted |
+| `eventRef`               | `React.RefObject<EventInstance>` | —                    | Event-bus ref for listening on the page side                      |
+| `playerFit`              | `'contain' \| 'cover'`           | `'contain'`          | Video fit mode                                                    |
+| `landscapeMode`          | `'fill' \| 'standard'`           | `'standard'`         | Landscape display mode                                            |
+| `brandColor`             | `string`                         | `'#FF592A'`          | Brand color                                                       |
+| `CSSVariable`            | `Partial<CSSVariable>`           | —                    | Custom CSS variables, see [Custom Styling](#custom-styling)       |
+| `deviceOnline`           | `boolean`                        | `true`               | Whether the device is online                                      |
+| `privateState`           | `boolean`                        | `false`              | Whether privacy mode (mask) is on                                 |
+| `verticalMic`            | `boolean`                        | `true`               | Whether to show the mic intercom in portrait                      |
+| `isShare`                | `boolean`                        | `false`              | Whether it is a shared device                                     |
+| `ignoreHideStopPreview`  | `boolean`                        | `false`              | Ignore stop-preview when widgets hide                             |
+| `awakeStatus`            | `boolean`                        | `undefined`          | Wake-up status for low-power devices                              |
+| `autoWakeUp`             | `boolean`                        | `false`              | Auto wake up the device                                           |
+| `limitFlow`              | `boolean`                        | `false`              | Whether flow is limited                                           |
+| `showFlowLowTip`         | `boolean`                        | `false`              | Show the low-flow tip                                             |
+| `previewEnabled`         | `boolean`                        | `undefined`          | Controlled preview switch                                         |
+| `refreshElement`         | `boolean`                        | `false`              | Trigger a CoverView height refresh                                |
+| `playerRoute`            | `string`                         | `'pages/home/index'` | Route the player lives on                                         |
+| `style` / `className`    | `CSSProperties` / `string`       | —                    | Container style / className                                       |
+| `onPlayStatus`           | `(data: PlayStatusData) => void` | —                    | Play-state change callback                                        |
+| `onPlayerTap`            | `(data) => void`                 | —                    | Tap-on-video callback                                             |
+| `onPreviewEnabledChange` | `(enabled: boolean) => void`     | —                    | Preview-switch change callback                                    |
+
+### `useCtx(options)`
+
+Creates the player context instance.
+
+```ts
+const instance = useCtx({
+  devId: string,                       // Device ID (required)
+  saveToAlbum?: 0 | 1,                 // 0: system album; 1: IPC album
+  showPtzControlTip?: boolean,         // Show the PTZ control guide
+  videoSplitProtocol?: VideoSplitProtocol, // Multi-camera split protocol
+  initTopLeftContent?: ComponentConfig[],     // Initial widgets per area
+  initTopRightContent?: ComponentConfig[],
+  initBottomLeftContent?: ComponentConfig[],
+  initBottomRightContent?: ComponentConfig[],
+  initAbsoluteContent?: ComponentConfig[],
+});
+```
+
+The returned `instance` provides:
+
+- **State atoms**: `screenType`, `mute`, `intercom`, `recording`, `resolution`, `resolutionList`, `playState`, `brandColor`, `verticalMic`, `isVerticalFullLayout`, etc. (subscribe via `useStore`).
+- **State setters**: `setMute`, `setIntercom`, `setRecording`, `setResolution`, `setScreenType`, `setBrandColor`, `setPlayState`, `changeStreamStatus`, `getStreamStatus`, etc.
+- **Content management**: `addContent(type, config, position?)`, `deleteContent(type, id)`, `updateContent(type, data)`, `getContent()`, `hasContent`, `hideContent`, `showContent`.
+- **Misc**: `IPCPlayerInstance` (the underlying player instance), `event` (event bus), `toast`, `multiCameraCtx` (multi-camera context).
+
+### `useStore(atoms)`
+
+Subscribes to state atoms on the `instance` and returns a reactive value object.
+
+```tsx
+const { screenType, mute, resolution } = useStore({
+  screenType: instance.screenType,
+  mute: instance.mute,
+  resolution: instance.resolution,
+});
+```
+
+### `Features`
+
+Widget-orchestration capabilities, imported via `import { Features } from '@ray-js/ipc-player-integration'`.
+
+#### `Features.initPlayerWidgets(instance, options)`
+
+Initializes the default widgets based on the device's DP info. Common `options`:
+
+| Option                                                                                                | Type                | Description                                      |
+| ----------------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------ |
+| `hideScreenShotMenu`                                                                                  | `boolean`           | Hide the screenshot button                       |
+| `hideRecordVideoMenu`                                                                                 | `boolean`           | Hide the record button                           |
+| `hideResolutionMenu`                                                                                  | `boolean`           | Hide the resolution button                       |
+| `hideKbsMenu`                                                                                         | `boolean`           | Hide the bitrate display                         |
+| `hideSignalMenu`                                                                                      | `boolean`           | Hide the signal-strength button                  |
+| `hideHorizontalMenu`                                                                                  | `boolean`           | Hide the enter-landscape button                  |
+| `verticalResolutionCustomClick`                                                                       | `boolean`           | Custom click for portrait resolution             |
+| `showToggleVerticalFull`                                                                              | `boolean`           | Show the single-cam portrait-fullscreen toggle   |
+| `showRealTimeMagnification`                                                                           | `boolean`           | Show the real-time magnification button          |
+| `hideSmartImageQualityState`                                                                          | `boolean`           | Hide the smart image-quality state               |
+| `directionControlProps`                                                                               | `object`            | Pass-through props for the PTZ direction control |
+| `topLeftContent` / `topRightContent` / `bottomLeftContent` / `bottomRightContent` / `absoluteContent` | `ComponentConfig[]` | Override default widget config                   |
+
+#### `Features.updatePlayerWidgetProps(ctx, area, widgetId, newProps)`
+
+Dynamically updates props of a widget in a given area.
+
+```ts
+Features.updatePlayerWidgetProps(instance, 'topRight', 'VideoBitKBP', {
+  hideKbsMenu: true,
+});
+```
+
+> `area`: `'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'absolute'`; for `widgetId` see the widget list below.
+
+### `Widgets`
+
+Imported via `import { Widgets } from '@ray-js/ipc-player-integration'`; each widget can be used standalone. Common widgets:
+
+| Widget                          | WidgetId                                      | Description                |
+| ------------------------------- | --------------------------------------------- | -------------------------- |
+| `Widgets.VoiceIntercom`         | `FullSmallIntercom` / `VerticalSmallIntercom` | Two-way talk button        |
+| `Widgets.Screenshot`            | `Screenshot`                                  | Screenshot                 |
+| `Widgets.RecordVideo`           | `RecordVideo`                                 | Recording                  |
+| `Widgets.Muted`                 | `Muted`                                       | Mute                       |
+| `Widgets.Resolution`            | `Resolution`                                  | Resolution switch          |
+| `Widgets.FullScreen`            | `FullScreen`                                  | Fullscreen / landscape     |
+| `Widgets.Ptz`                   | `Ptz`                                         | PTZ control                |
+| `Widgets.VideoBitKBP`           | `VideoBitKBP`                                 | Bitrate / signal           |
+| `Widgets.BatteryFull`           | `BatteryFull`                                 | Battery                    |
+| `Widgets.TempHumidity`          | `TempHumidity`                                | Temperature & humidity     |
+| `Widgets.Floodlight`            | `Floodlight`                                  | Floodlight                 |
+| `Widgets.Siren`                 | `Siren`                                       | Siren                      |
+| `Widgets.TryExperience`         | `TryExperience`                               | Trial                      |
+| `Widgets.PtzControlTip`         | —                                             | PTZ control guide dialog   |
+| `Widgets.RealTimeMagnification` | —                                             | Real-time magnification    |
+| `Widgets.ToggleVerticalFull`    | —                                             | Portrait-fullscreen toggle |
+| `Widgets.FlowLowTip`            | —                                             | Low-flow tip               |
+
+Standalone `VoiceIntercom` example:
+
+```tsx
+<Widgets.VoiceIntercom
+  ref={intercomRef}
+  IPCPlayerContext={instance?.IPCPlayerInstance}
+  {...instance}
+  mode="circle" // 'verticalSmall' | 'fullSmall' | 'circle'
+  disabled={false}
+  icon={intercomLightSvg}
+  talkingColor="#440F7C"
+/>
+```
+
+Insert the PTZ guide dialog into the `absolute` area:
+
+```tsx
+instance.addContent('absolute', {
+  id: 'ptzControlTipId',
+  content: props => <Widgets.PtzControlTip {...props} />,
+  absoluteContentClassName: 'ipc-player-plugin-ptz-control-tip-wrap',
+  initProps: { ...props },
+});
+```
+
+### `Hooks`
+
+Convenient device-state access (all exported from the package root):
+
+| Hook             | Signature                                      | Description                    |
+| ---------------- | ---------------------------------------------- | ------------------------------ |
+| `useBattery`     | `(devId) => { batteryValue, batteryCharging }` | Battery level / charging state |
+| `usePtz`         | `(devId) => boolean`                           | Whether PTZ is supported       |
+| `useTemperature` | `(devId) => number`                            | Temperature                    |
+| `useHumidity`    | `() => number`                                 | Humidity                       |
+| `useSignal4G`    | `(devId) => { dpValue, signalKey }`            | 4G signal strength             |
+| `useDpState`     | —                                              | Read/write DP state            |
+| `useDpSupport`   | —                                              | DP support check               |
+| `useSchemaInfo`  | —                                              | Device schema info             |
+| `useMemoizedFn`  | —                                              | Stable function reference      |
+
+### `Utils` & device helpers
+
+```ts
+import { Utils } from '@ray-js/ipc-player-integration';
+// Device helpers are imported from a sub-path
+import {
+  getDpValue,
+  getDeviceInfo,
+  getDpSchemaByCodes,
+  getDpSchemaByCodesSync,
+  hasDpCode,
+} from '@ray-js/ipc-player-integration/utils/device';
+```
+
+- `getDpSchemaByCodes(devId, codes)`: batch-fetch schema by DP code.
+- `hasDpCode(devId, code)`: check whether the device has a given DP.
+- `Utils.radialGradient(color)` / `Utils.adjustBrightness(hex, factor)`: color helpers.
+
+## Custom Styling
+
+### Brand color
+
+Set via the `brandColor` prop or `instance.setBrandColor(color)`.
+
+### CSS variables
+
+Override via the `CSSVariable` prop:
+
+```tsx
+<IPCPlayerIntegration
+  CSSVariable={{
+    '--iconColor': '#fff',
+    '--iconActiveColor': '#ec653c',
+    '--iconFontSize': '20px',
+    '--bg-color': '#000',
+    '--fontColor': '#fff',
+    '--fontSize': '12px',
+  }}
+/>
+```
+
+Available variables: `--iconColor`, `--iconActiveColor`, `--iconFontSize`, `--iconPlayerSize`, `--iconBoxSize`, `--bg-color`, `--shot-card-bg-color`, `--fontColor`, `--fontSize`.
+
+## Events
+
+Once you have the event bus through `eventRef`, you can listen to internal player events:
+
+```tsx
+const eventRef = useRef<EventInstance>();
+
+useEffect(() => {
+  const onResolutionClick = () => console.log('resolution button clicked');
+  const onWidgetClick = data => console.log('widget clicked', data);
+  eventRef.current.on('resolutionBtnControlClick', onResolutionClick);
+  eventRef.current.on('widgetClick', onWidgetClick);
+  return () => {
+    eventRef.current.off('resolutionBtnControlClick', onResolutionClick);
+    eventRef.current.off('widgetClick', onWidgetClick);
+  };
+}, []);
+```
+
+## Multi-Camera
+
+Supports PiP, tile, grid and thumbnail multi-camera layouts. Related types are exported from the package root:
+
+- `MultiCameraScreenMode`: screen mode (`short` / `full` / `landscape`).
+- `MultiCameraLayoutStyle`: layout style (`pip` / `tile` / `grid` / `thumbnail`).
+- `VideoSplitProtocol`: the multi-camera split protocol, passed via `useCtx({ videoSplitProtocol })`.
+- `MultiCameraLenInfo`: lens info (index, name, whether PTZ / Zoom / Localizer is supported).
+
+The multi-camera context is accessible via `instance.multiCameraCtx`.
+
 ## Develop
 
 ```sh
 # install deps
 yarn
 
-# watch compile demo
+# watch & preview the demo (Tuya target)
 yarn start:tuya
-```
-
-## Usage
 
-```tsx
-import Foo from '@ray-js/ipc-player-integration';
-export default () => <Foo />;
+# build the component
+yarn build
 ```
+
+Other available scripts: `start:wechat`, `start:web`, `start:native`, `build:tuya`, `build:wechat`, `build:web`, `build:native`.

package/lib/ctx/ctx.js

@@ -11,7 +11,7 @@ import { PlayState, IntercomMode } from '../interface';
 import { changeIgnoreHideStopPreview } from '../ui/constant';
 import { ClarityType } from '@ray-js/ray-ipc-utils/lib/interface';
 import { getEventInstance } from './event';
-import { useMultiCameraCtx } from './multiCameraCtx';
+import { isMultiCameraTileSupported, useMultiCameraCtx } from './multiCameraCtx';
 const SAVE_TO_ALBUM = 1;
 export const createUseCtx = _ref => {
   let {
@@ -42,9 +42,16 @@ export const createUseCtx = _ref => {
     const streamStatus = useRef();
     // 全屏、竖屏
     const [screenType, setScreenType] = useAtom('vertical');
+    const IPCPlayerInstance = useRef();
+    if (!IPCPlayerInstance.current) {
+      IPCPlayerInstance.current = createPlayContext(devId);
+    }
 
-    // 是否处于竖屏填充布局
-    const [isVerticalFullLayout, setIsVerticalFullLayout] = useAtom(false);
+    // 是否处于竖屏填充布局。
+    // 多目平铺设备首帧即按竖屏填充渲染：screenMode 初始就是 full（multiCameraCtx），
+    // 若此处初始为 false，首帧会以 16:9 短屏渲染、effect 后才切全高，
+    // 原生层在该尺寸跳变窗口内可能丢失 viewPos 更新，残留短屏尺寸。
+    const [isVerticalFullLayout, setIsVerticalFullLayout] = useAtom(isMultiCameraTileSupported(videoSplitProtocol, IPCPlayerInstance.current));
 
     // 录像中
     const [recording] = useAtom(false);
@@ -184,10 +191,6 @@ export const createUseCtx = _ref => {
 
     // 判断是否已经有了对应id的content
 
-    const IPCPlayerInstance = useRef();
-    if (!IPCPlayerInstance.current) {
-      IPCPlayerInstance.current = createPlayContext(devId);
-    }
     const _setMute = async function (target) {
       let onlyUpdateAtom = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
       if (onlyUpdateAtom) {

package/lib/ctx/multiCameraCtx.d.ts

@@ -16,6 +16,10 @@ interface Props {
     IPCPlayerInstance: IpcContext;
     videoSplitProtocol?: VideoSplitProtocol;
 }
+/**
+ * 是否支持多目平铺布局（协议 + 基础库能力），首次渲染即可同步判定
+ */
+export declare const isMultiCameraTileSupported: (videoSplitProtocol?: VideoSplitProtocol, IPCPlayerInstance?: IpcContext) => boolean;
 /**
  * 多目摄像头相关状态、方法维护
  */

package/lib/ctx/multiCameraCtx.js

@@ -25,6 +25,13 @@ const DEFAULT_SELECTED_LEN_INFO = {
   supportLocalizer: false,
   supportZoom: false
 };
+/**
+ * 是否支持多目平铺布局（协议 + 基础库能力），首次渲染即可同步判定
+ */
+export const isMultiCameraTileSupported = (videoSplitProtocol, IPCPlayerInstance) => {
+  return (videoSplitProtocol === null || videoSplitProtocol === void 0 ? void 0 : videoSplitProtocol.total_split_num) > 1 && (videoSplitProtocol === null || videoSplitProtocol === void 0 ? void 0 : videoSplitProtocol.p_v) >= 3 && typeof (IPCPlayerInstance === null || IPCPlayerInstance === void 0 ? void 0 : IPCPlayerInstance.switchLayoutStyle) === 'function';
+};
+
 /**
  * 多目摄像头相关状态、方法维护
  */
@@ -35,7 +42,7 @@ export const useMultiCameraCtx = props => {
     videoSplitProtocol = DEFAULT_VIDEO_SPLIT_PROTOCOL
   } = props;
   const isSupport = useMemo(() => {
-    return (videoSplitProtocol === null || videoSplitProtocol === void 0 ? void 0 : videoSplitProtocol.total_split_num) > 1 && (videoSplitProtocol === null || videoSplitProtocol === void 0 ? void 0 : videoSplitProtocol.p_v) >= 3 && typeof (IPCPlayerInstance === null || IPCPlayerInstance === void 0 ? void 0 : IPCPlayerInstance.switchLayoutStyle) === 'function';
+    return isMultiCameraTileSupported(videoSplitProtocol, IPCPlayerInstance);
   }, [IPCPlayerInstance, videoSplitProtocol]);
   const dpSupportMap = useDpSupport({
     devId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ray-js/ipc-player-integration",
-  "version": "0.0.38",
+  "version": "0.0.39",
   "description": "IPC 融合播放器",
   "main": "lib/index",
   "files": [
@@ -37,7 +37,7 @@
   "dependencies": {
     "@ray-js/direction-control": "^0.0.8",
     "@ray-js/ipc-ptz-zoom": "^0.0.3",
-    "@ray-js/ray-ipc-player": "^2.1.2",
+    "@ray-js/ray-ipc-player": "^2.1.3",
     "@ray-js/ray-ipc-utils": "^1.1.15",
     "@ray-js/svg": "0.2.0",
     "clsx": "^1.2.1",