@video-supply/dahua-player 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: `DahuaPlayer.init(options)` wrapper
+- Built-in `wsplayer-gov` assets with install-time copy to `public/wsplayer-gov`
+- Jest + Puppeteer integration tests
+- Vite example app
+

package/LICENSE

@@ -0,0 +1 @@
+UNLICENSED

package/README.md

@@ -0,0 +1,192 @@
+# @video-supply/dahua-player
+
+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
+
+```bash
+npm i @video-supply/dahua-player
+```
+
+## Quick Start
+
+```ts
+import { DahuaPlayer } from '@video-supply/dahua-player';
+
+const player = DahuaPlayer.init({
+  container: 'player',
+  auth: { token: 'YOUR_DAHUA_TOKEN' },
+  cameraId: 'YOUR_CAMERA_ID',
+  autoPlay: true,
+  width: 'auto',
+  height: 'auto',
+  onError: (e) => console.error(e),
+});
+
+await player.ready;
+```
+
+### Multi-window / Record helpers
+
+```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);
+player.sdk.setFullScreen();
+```
+
+## API
+
+### DahuaPlayer.init(options)
+
+Required:
+
+- `container: HTMLElement | string`
+- `auth: { token: string; ip?: string; port?: number; protocol?: 'http' | 'https' }`
+
+Optional:
+
+- `cameraId?: string` (default `undefined`)
+- `cameraIds?: string[]` (default `undefined`)
+- `auth.ip/auth.port/auth.protocol` are used to generate `targetOrigin` for proxy forwarding
+- `autoPlay?: boolean` (default `false`)
+- `recordStartTime?: number` (unix seconds, required for `mode=record` + `autoPlay`)
+- `recordEndTime?: number` (unix seconds, required for `mode=record` + `autoPlay`)
+- `recordSource?: number` (optional, only for `mode=record` + `autoPlay`)
+- `width?: number | 'auto'` (default `auto`)
+- `height?: number | 'auto'` (default `auto`)
+- `streamType?: 1 | 2 | 3` (default `2`)
+- `searchOnline?: boolean` (default `false`)
+- `num?: number` (initial window count, default `1`)
+- `maxNum?: number` (max window count, default `1`)
+- `showRecordProgressBar?: boolean` (default `true` in `mode=record`, otherwise `false`)
+- `dblClickFullscreen?: boolean` (default `true`)
+- `staticPath?: string` (default `/wsplayer-gov`)
+- `sdkUrl?: string` (default `/wsplayer-gov/wsplayer.min.js`)
+- `debug?: boolean` (default `false`)
+- callbacks: `onReady/onPlay/onPause/onError/onDestroy`
+
+Returns: `DahuaPlayerInstance`
+
+### Instance methods
+
+- `ready: Promise<void>`
+  - Resolves when WSPlayer initialization is completed (initializationCompleted).
+  - This does not mean playback has started successfully.
+- `pause(): void`
+  - Pauses the current window (defaults to window 0).
+  - Equivalent to calling `sdk.pause()` (compat wrapper).
+- `destroy(): void`
+  - Destroys the instance and releases resources.
+  - Removes DOM nodes, clears timers, and releases sessionStorage shims.
+- `on(event, handler) / off(event, handler)`
+  - Subscribe/unsubscribe events: `ready` / `play` / `pause` / `error` / `destroy`.
+  - `play` payload: `{ mode?: 'real' | 'record' }`.
+
+### SDK methods (`instance.sdk`)
+
+- `getRaw(): any`
+  - Returns the underlying WSPlayer/PlayerManager instance (debugging or unwrapped methods).
+- `playRealVideo(opt: any): void`
+  - Starts live preview playback.
+  - Channel inputs are accepted in the following order:
+    - `opt.channelList` (array of `{ channelCode: string }`)
+    - `opt.cameraIds` / `opt.cameraId` (converted internally)
+    - init `cameraIds/cameraId`
+  - Multi-channel playback is capped by current layout (`num`).
+- `playRecordVideo(opt: any): void`
+  - Starts record playback.
+  - Same channel input and capping rules as `playRealVideo`.
+  - Common passthrough fields: `startTime/endTime/recordSource`.
+- `pause(windowIndex?): void`
+  - Pauses the given window.
+- `play(windowIndex?): void`
+  - Resumes the given window.
+- `close(windowIndex?): void`
+  - Closes the given window.
+- `setPlayerNum(num: number): void`
+  - Changes layout window count (e.g. 1/4/9/16).
+  - The multi-channel cap updates accordingly.
+- `jumpPlayByDateTime(datetime: string | Date | number, index?: number): void`
+  - Seeks and plays at the given datetime (record mode only).
+  - `datetime` supports `YYYY-MM-DD HH:mm:ss` string, `Date`, or epoch seconds/milliseconds.
+  - `index` is the window index (defaults to 0).
+- `playSpeed(speed: number, index: number): void`
+  - Sets record playback speed (record mode only).
+  - Allowed speeds: `0.125/0.25/0.5/1/1.25/1.5/2/4/8`.
+- `setFullScreen(): void`
+  - Enters fullscreen.
+  - Prefers WSPlayer core method, falls back to browser Fullscreen API when unavailable.
+- `setExitFullScreen(): void`
+  - Exits fullscreen.
+  - Prefers WSPlayer core method, falls back to browser Fullscreen API when unavailable.
+- `callRaw(method: string, ...args: any[]): any`
+  - Fallback to call an underlying WSPlayer method by name.
+  - Throws if method is missing.
+
+### Events
+
+- `ready`
+- `play` (payload: `{ mode?: 'real' | 'record' }`)
+- `pause`
+- `error` (payload: `unknown`)
+- `destroy`
+
+## Static assets
+
+By default, on installation this package copies:
+
+- `node_modules/@company/dahua-player/wsplayer-gov`
+
+to your project:
+
+- `<INIT_CWD>/public/wsplayer-gov`
+
+Then the SDK is loaded from:
+
+- `/wsplayer-gov/wsplayer.min.js`
+
+### Disable postinstall copy
+
+```bash
+set DAHUA_PLAYER_SKIP_POSTINSTALL=1
+npm i @company/dahua-player --registry <PRIVATE_REGISTRY>
+```
+
+Then manually copy:
+
+- `node_modules/@company/dahua-player/wsplayer-gov` → `public/wsplayer-gov`
+
+### Change public dir
+
+```bash
+set DAHUA_PLAYER_PUBLIC_DIR=static
+npm i @company/dahua-player --registry <PRIVATE_REGISTRY>
+```
+
+## Release (private registry)
+
+```bash
+set NPM_REGISTRY=<PRIVATE_REGISTRY>
+npm run release:private
+```

package/README.zh-CN.md

@@ -0,0 +1,202 @@
+# @company/dahua-player（base-player）中文接入文档
+
+这是对大华 WSPlayer 的轻量封装，提供单入口初始化：
+
+- `DahuaPlayer.init(options)`
+
+并对外暴露常用的播放/回放/倍速/跳转/全屏/布局切换等能力。
+
+## 快速开始
+
+```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/dist/bin/copy-assets.cjs

@@ -0,0 +1,51 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/bin/copy-assets.ts
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+function resolveInitCwd() {
+  const initCwd = process.env.INIT_CWD;
+  if (initCwd && initCwd.trim()) return initCwd.trim();
+  return process.cwd();
+}
+function ensureDir(dir) {
+  import_node_fs.default.mkdirSync(dir, { recursive: true });
+}
+function copyDir(src, dest) {
+  if (!import_node_fs.default.existsSync(src)) return;
+  ensureDir(import_node_path.default.dirname(dest));
+  import_node_fs.default.cpSync(src, dest, { recursive: true, force: true });
+}
+function main() {
+  if (process.env.DAHUA_PLAYER_SKIP_POSTINSTALL === "1") return;
+  const pkgRoot = import_node_path.default.resolve(__dirname, "..", "..");
+  const srcDir = import_node_path.default.join(pkgRoot, "wsplayer-gov");
+  const initCwd = resolveInitCwd();
+  const publicDir = process.env.DAHUA_PLAYER_PUBLIC_DIR?.trim() || "public";
+  const destDir = import_node_path.default.join(initCwd, publicDir, "wsplayer-gov");
+  copyDir(srcDir, destDir);
+}
+main();
+//# sourceMappingURL=copy-assets.cjs.map

package/dist/bin/copy-assets.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/bin/copy-assets.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\n\nfunction resolveInitCwd() {\n  const initCwd = process.env.INIT_CWD;\n  if (initCwd && initCwd.trim()) return initCwd.trim();\n  return process.cwd();\n}\n\nfunction ensureDir(dir: string) {\n  fs.mkdirSync(dir, { recursive: true });\n}\n\nfunction copyDir(src: string, dest: string) {\n  if (!fs.existsSync(src)) return;\n  ensureDir(path.dirname(dest));\n  fs.cpSync(src, dest, { recursive: true, force: true });\n}\n\nfunction main() {\n  if (process.env.DAHUA_PLAYER_SKIP_POSTINSTALL === '1') return;\n\n  const pkgRoot = path.resolve(__dirname, '..', '..');\n  const srcDir = path.join(pkgRoot, 'wsplayer-gov');\n  const initCwd = resolveInitCwd();\n  const publicDir = process.env.DAHUA_PLAYER_PUBLIC_DIR?.trim() || 'public';\n  const destDir = path.join(initCwd, publicDir, 'wsplayer-gov');\n\n  copyDir(srcDir, destDir);\n}\n\nmain();\n\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAAA,qBAAe;AACf,uBAAiB;AAEjB,SAAS,iBAAiB;AACxB,QAAM,UAAU,QAAQ,IAAI;AAC5B,MAAI,WAAW,QAAQ,KAAK,EAAG,QAAO,QAAQ,KAAK;AACnD,SAAO,QAAQ,IAAI;AACrB;AAEA,SAAS,UAAU,KAAa;AAC9B,iBAAAA,QAAG,UAAU,KAAK,EAAE,WAAW,KAAK,CAAC;AACvC;AAEA,SAAS,QAAQ,KAAa,MAAc;AAC1C,MAAI,CAAC,eAAAA,QAAG,WAAW,GAAG,EAAG;AACzB,YAAU,iBAAAC,QAAK,QAAQ,IAAI,CAAC;AAC5B,iBAAAD,QAAG,OAAO,KAAK,MAAM,EAAE,WAAW,MAAM,OAAO,KAAK,CAAC;AACvD;AAEA,SAAS,OAAO;AACd,MAAI,QAAQ,IAAI,kCAAkC,IAAK;AAEvD,QAAM,UAAU,iBAAAC,QAAK,QAAQ,WAAW,MAAM,IAAI;AAClD,QAAM,SAAS,iBAAAA,QAAK,KAAK,SAAS,cAAc;AAChD,QAAM,UAAU,eAAe;AAC/B,QAAM,YAAY,QAAQ,IAAI,yBAAyB,KAAK,KAAK;AACjE,QAAM,UAAU,iBAAAA,QAAK,KAAK,SAAS,WAAW,cAAc;AAE5D,UAAQ,QAAQ,OAAO;AACzB;AAEA,KAAK;","names":["fs","path"]}