@video-supply/dahua-player 0.1.0 → 0.1.2

package/README.md

@@ -1,18 +1,25 @@
 # @video-supply/dahua-player
 
+- [English](#english)
+- [中文](#zh)
+
+<a id="english"></a>
+
+## English
+
 Dahua (WSPlayer) browser player wrapper. It provides a single entry API:
 
 - `DahuaPlayer.init(options)`
 
 This package includes Dahua static assets (`wsplayer-gov/`) and copies them into your app's static directory on install.
 
-## Install
+### Install
 
 ```bash
 npm i @video-supply/dahua-player
 ```
 
-## Quick Start
+### Quick Start
 
 ```ts
 import { DahuaPlayer } from '@video-supply/dahua-player';
@@ -30,7 +37,7 @@ const player = DahuaPlayer.init({
 await player.ready;
 ```
 
-### Multi-window / Record helpers
+#### Multi-window / Record helpers
 
 ```ts
 const player = DahuaPlayer.init({
@@ -55,9 +62,9 @@ player.sdk.jumpPlayByDateTime('2026-03-01 12:00:00', 0);
 player.sdk.setFullScreen();
 ```
 
-## API
+### API
 
-### DahuaPlayer.init(options)
+#### DahuaPlayer.init(options)
 
 Required:
 
@@ -88,7 +95,7 @@ Optional:
 
 Returns: `DahuaPlayerInstance`
 
-### Instance methods
+#### Instance methods
 
 - `ready: Promise<void>`
   - Resolves when WSPlayer initialization is completed (initializationCompleted).
@@ -103,7 +110,7 @@ Returns: `DahuaPlayerInstance`
   - Subscribe/unsubscribe events: `ready` / `play` / `pause` / `error` / `destroy`.
   - `play` payload: `{ mode?: 'real' | 'record' }`.
 
-### SDK methods (`instance.sdk`)
+#### SDK methods (`instance.sdk`)
 
 - `getRaw(): any`
   - Returns the underlying WSPlayer/PlayerManager instance (debugging or unwrapped methods).
@@ -144,7 +151,7 @@ Returns: `DahuaPlayerInstance`
   - Fallback to call an underlying WSPlayer method by name.
   - Throws if method is missing.
 
-### Events
+#### Events
 
 - `ready`
 - `play` (payload: `{ mode?: 'real' | 'record' }`)
@@ -152,11 +159,11 @@ Returns: `DahuaPlayerInstance`
 - `error` (payload: `unknown`)
 - `destroy`
 
-## Static assets
+### Static assets
 
 By default, on installation this package copies:
 
-- `node_modules/@company/dahua-player/wsplayer-gov`
+- `node_modules/@video-supply/dahua-player/wsplayer-gov`
 
 to your project:
 
@@ -166,27 +173,231 @@ Then the SDK is loaded from:
 
 - `/wsplayer-gov/wsplayer.min.js`
 
-### Disable postinstall copy
+#### Disable postinstall copy
 
 ```bash
 set DAHUA_PLAYER_SKIP_POSTINSTALL=1
-npm i @company/dahua-player --registry <PRIVATE_REGISTRY>
+npm i @video-supply/dahua-player
 ```
 
 Then manually copy:
 
-- `node_modules/@company/dahua-player/wsplayer-gov` → `public/wsplayer-gov`
+- `node_modules/@video-supply/dahua-player/wsplayer-gov` → `public/wsplayer-gov`
 
-### Change public dir
+#### Change public dir
 
 ```bash
 set DAHUA_PLAYER_PUBLIC_DIR=static
-npm i @company/dahua-player --registry <PRIVATE_REGISTRY>
+npm i @video-supply/dahua-player
 ```
 
-## Release (private registry)
+<a id="zh"></a>
+
+## 中文
+
+这是对大华 WSPlayer 的轻量封装，提供单入口初始化：
+
+- `DahuaPlayer.init(options)`
+
+并对外暴露常用的播放/回放/倍速/跳转/全屏/布局切换等能力。
+
+### 安装
 
 ```bash
-set NPM_REGISTRY=<PRIVATE_REGISTRY>
-npm run release:private
+npm i @video-supply/dahua-player
+```
+
+### 快速开始
+
+```ts
+import { DahuaPlayer } from '@video-supply/dahua-player';
+
+const player = DahuaPlayer.init({
+  container: 'player',
+  auth: {
+    token: 'YOUR_DAHUA_TOKEN',
+    ip: '10.3.156.238',
+    port: 8320,
+  },
+  cameraId: 'YOUR_CAMERA_ID',
+  autoPlay: true,
+  width: 'auto',
+  height: 'auto',
+});
+
+await player.ready;
+```
+
+### 初始化参数（DahuaPlayer.init）
+
+必填：
+
+- `container: HTMLElement | string`
+- `auth: { token: string; ip?: string; port?: number; protocol?: 'http' | 'https' }`
+
+字段解释：
+
+- `container`
+  - 播放器挂载容器
+  - `string`：按 DOM id 查找
+  - `HTMLElement`：直接使用该元素
+- `auth.token`
+  - 鉴权 token（必填）
+  - 仅做非空校验；内部通过 sessionStorage shim 注入给 WSPlayer 使用，避免 token 落盘
+- `auth.ip`
+  - 现场部署的大华平台 IP（可选）
+  - 用于内部拼装 `targetOrigin`，写入 `sessionStorage.wsplayer_origin`，可在网关/nginx 侧用于代理转发
+- `auth.port`
+  - 现场部署的大华平台端口（可选）
+  - 同上，用于拼装 `targetOrigin`
+- `auth.protocol`
+  - 协议（可选）：`http` 或 `https`（默认 `https`）
+
+播放相关：
+
+- `mode?: 'real' | 'record'`
+  - 播放模式：实时预览 / 录像回放（默认 `real`）
+- `cameraId?: string`
+  - 单通道编码（可选）
+- `cameraIds?: string[]`
+  - 多通道编码（可选）
+  - 最终实际播放数量会按“当前路数 num”裁剪
+- `autoPlay?: boolean`
+  - `true` 时在 `ready` 后自动触发一次播放（默认 `false`）
+  - `mode=real` 需要 `cameraId/cameraIds` 至少一个存在
+  - `mode=record` 需要 `recordStartTime/recordEndTime` 且 `cameraId/cameraIds` 至少一个存在
+- `recordStartTime?: number`
+  - 录像回放开始时间（Unix 秒）
+  - 仅 `mode=record + autoPlay=true` 使用
+- `recordEndTime?: number`
+  - 录像回放结束时间（Unix 秒）
+  - 仅 `mode=record + autoPlay=true` 使用
+- `recordSource?: number`
+  - 录像来源（透传给 WSPlayer）
+  - 仅 `mode=record + autoPlay=true` 使用
+- `streamType?: 1 | 2 | 3`
+  - 码流类型：1 主码流 / 2 辅码流1 / 3 辅码流2（默认 `2`）
+- `searchOnline?: boolean`
+  - 是否由组件内部查询在线状态（默认 `false`）
+
+布局/显示：
+
+- `num?: number`
+  - 初始显示路数（默认 `1`）
+  - 常用值：`1/4/9/16/25`
+- `maxNum?: number`
+  - 最大支持路数（默认 `1`）
+  - 上限仍受 WSPlayer 内核与浏览器性能影响
+- `showRecordProgressBar?: boolean`
+  - 是否展示录像回放时间轴
+  - 未传时：`record` 默认 `true`，`real` 默认 `false`
+- `dblClickFullscreen?: boolean`
+  - 是否启用双击切换全屏/退出全屏（默认 `true`）
+
+高级：
+
+- `staticPath?: string`
+  - 静态资源根路径（默认 `/wsplayer-gov`）
+- `sdkUrl?: string`
+  - WSPlayer 脚本地址（默认 `/wsplayer-gov/wsplayer.min.js`）
+- `playerOptions?: Record<string, unknown>`
+  - 透传给底层 `PlayerManager` 的原始配置（与内部默认配置合并）
+- `debug?: boolean`
+  - 是否打印库内部调试日志
+- 回调
+  - `onReady`：内核初始化完成（不等同于播放成功）
+  - `onPlay`：播放成功（包含 real/record）
+  - `onPause`：暂停
+  - `onError`：初始化/播放等错误
+  - `onDestroy`：销毁
+  - `onSdkMessage`：透出 WSPlayer 原始消息（排障用）
+
+### 实例与 SDK 方法
+
+```ts
+const instance = DahuaPlayer.init(...);
+await instance.ready;
+```
+
+- `instance.ready: Promise<void>`
+  - 初始化完成后 resolve（对应 WSPlayer 的 initializationCompleted）
+  - 只代表内核初始化完成，不代表已经播放成功
+- `instance.pause(): void`
+  - 暂停当前播放窗口（默认窗口 0）
+  - 语义等价于调用 `instance.sdk.pause()`（库内部做了兼容处理）
+- `instance.destroy(): void`
+  - 销毁播放器实例并释放资源
+  - 会移除 DOM、清理定时器、释放 sessionStorage shim
+- `instance.on(event, handler) / instance.off(event, handler)`
+  - 订阅/取消订阅事件：`ready` / `play` / `pause` / `error` / `destroy`
+  - `play` 事件 payload：`{ mode?: 'real' | 'record' }`
+
+`instance.sdk`：
+
+- `getRaw(): any`
+  - 获取底层 WSPlayer/PlayerManager 实例（用于排障或调用未封装能力）
+- `playRealVideo(opt: any): void`
+  - 实时预览播放
+  - `opt` 透传给底层，同时支持以下通道入参（优先级从高到低）：
+    - `opt.channelList`（数组：`[{ channelCode: string }, ...]`）
+    - `opt.cameraIds` / `opt.cameraId`（内部会转为 channelList）
+    - 初始化时的 `cameraIds/cameraId`
+  - 多通道时会按当前路数 `num` 自动裁剪（最多播放 `num` 路）
+- `playRecordVideo(opt: any): void`
+  - 录像回放播放
+  - 通道入参与裁剪规则同 `playRealVideo`
+  - 常用字段（透传底层）：`startTime/endTime/recordSource`
+- `pause(windowIndex?): void`
+  - 暂停指定窗口
+  - `windowIndex` 不传时默认暂停当前窗口（底层实现可能按 0 处理）
+- `play(windowIndex?): void`
+  - 继续播放指定窗口
+- `close(windowIndex?): void`
+  - 关闭指定窗口播放
+- `setPlayerNum(num: number): void`
+  - 切换布局路数（例如 1/4/9/16）
+  - 变更后多通道播放的最大数量会随之变化（按新路数裁剪）
+- `jumpPlayByDateTime(datetime: string | Date | number, index?: number): void`
+  - 录像跳转播放（仅 `mode=record` 可用）
+  - `datetime` 支持：
+    - `string`：推荐 `YYYY-MM-DD HH:mm:ss`
+    - `Date`
+    - `number`：时间戳（秒或毫秒，内部会自动兼容）
+  - `index`：窗口索引（默认窗口 0）
+- `playSpeed(speed: number, index: number): void`
+  - 设置录像回放倍速（仅 `mode=record` 可用）
+  - `speed` 支持：`0.125/0.25/0.5/1/1.25/1.5/2/4/8`
+  - `index`：窗口索引（通常传 0）
+- `setFullScreen(): void`
+  - 设置播放器全屏
+  - 优先调用 WSPlayer 内核全屏；如内核不支持，则回退浏览器 Fullscreen API
+- `setExitFullScreen(): void`
+  - 退出全屏
+  - 优先调用 WSPlayer 内核；如内核不支持，则回退浏览器 Fullscreen API
+- `callRaw(method: string, ...args: any[]): any`
+  - 兜底调用底层实例的方法
+  - `method` 为底层方法名字符串（不存在会抛出错误）
+
+### 录像回放示例（多路 + 跳转 + 倍速）
+
+```ts
+const player = DahuaPlayer.init({
+  container: 'player',
+  auth: { token: 'YOUR_DAHUA_TOKEN' },
+  mode: 'record',
+  cameraIds: ['ID_1', 'ID_2', 'ID_3', 'ID_4'],
+  num: 4,
+  maxNum: 16,
+});
+
+await player.ready;
+
+player.sdk.playRecordVideo({
+  startTime: Math.floor(Date.now() / 1000) - 60,
+  endTime: Math.floor(Date.now() / 1000),
+  recordSource: 2,
+});
+
+player.sdk.playSpeed(2, 0);
+player.sdk.jumpPlayByDateTime('2026-03-01 12:00:00', 0);
 ```

package/README.zh-CN.md

@@ -1,4 +1,4 @@
-# @company/dahua-player（base-player）中文接入文档
+# @video-supply/dahua-player 中文文档
 
 这是对大华 WSPlayer 的轻量封装，提供单入口初始化：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@video-supply/dahua-player",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Dahua WSPlayer wrapper for browser apps",
   "type": "module",
   "sideEffects": false,