hikvision-h5player

v2.5.3

Published

16 days ago

Hikvision H5 streaming video player SDK wrapper with TypeScript declarations and Vite asset plugin

0High
0Medium
0Low

qin_sunrise

hikvision h5player video streaming websocket surveillance wasm vite-plugin

hikvision-h5player

海康威视 H5player 2.5.1 的 npm 封装。包含原始 SDK、Worker/WASM 解码运行时、完整 TypeScript 声明，以及 Vite 静态资源插件。

许可说明：SDK 二进制文件版权归海康威视所有。发布前请确认你已获得合法的重分发授权；本包仅提供工程化封装，不改变 SDK 本身的许可条款。

安装

npm install hikvision-h5player
# 或
pnpm add hikvision-h5player

若使用 Vite 插件，项目需已安装 vite（peer dependency，optional）。

快速开始

// 1. HTML 中准备容器
<div id="player" style={{ width: 800, height: 600 }} />

// 2. 业务代码
import {
  createH5Player,
  resolveH5PlayerBasePath,
  type H5PlayerInstance,
} from "hikvision-h5player";

const player: H5PlayerInstance = createH5Player({
  szId: "player",
  szBasePath: resolveH5PlayerBasePath(import.meta.env.BASE_URL),
  iMaxSplit: 4,
  iCurrentSplit: 1,
});

// 注册事件
await player.JS_SetWindowControlCallback({
  pluginErrorHandler: (index, code, error) => {
    console.error("播放错误", index, code, error);
  },
  firstFrameDisplay: (index, w, h) => {
    console.log("首帧", index, w, h);
  },
});

// 预览
await player.JS_Play(
  "wss://example.com/stream",
  { playURL: "wss://example.com/stream", mode: 0 },
  0,
);

// 停止
await player.JS_Stop(0);

典型调用顺序：

JS_SetWindowControlCallback → JS_Play → 其他控制接口 → JS_Stop

Vite 集成

// vite.config.ts
import { defineConfig } from "vite";
import { h5playerAssets } from "hikvision-h5player/vite";

export default defineConfig({
  plugins: [
    h5playerAssets(),
    // 需要 SharedArrayBuffer 时：
    // h5playerAssets({ crossOriginIsolation: true }),
  ],
});

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | assetDirectory | string | "h5player" | 资源输出目录，需与 resolveH5PlayerBasePath 一致 | | crossOriginIsolation | boolean | false | 是否注入 COOP/COEP 响应头 |

插件行为：

开发环境：通过中间件直接托管 sdk/ 目录下的资源
构建时：将所有 SDK 文件复制到 dist/{assetDirectory}/

生产环境需在 Web 服务器上同样提供 /h5player/** 静态资源，.wasm 文件的 MIME 需为 application/wasm。

创建实例

createH5Player(options: H5PlayerOptions): H5PlayerInstance

H5PlayerOptions

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | szId | string | 是 | 容器 DOM 元素 id，需英文字母开头 | | szBasePath | string | 是 | SDK 资源根路径，与解码器目录实际访问路径一致 | | iWidth | number | 否 | 宽度（px），容器有固定尺寸时可省略 | | iHeight | number | 否 | 高度（px） | | iMaxSplit | 1\|2\|3\|4 | 否 | 最大分屏，4 = 最多 4×4，默认 4 | | iCurrentSplit | 1\|2\|3\|4 | 否 | 当前分屏，默认 1（1×1） | | openDebug | boolean | 否 | 开启 SDK 调试日志 | | mseWorkerEnable | boolean | 否 | 多线程 MSE 解码，>1080P 建议开启 | | bSupporDoubleClickFull | boolean | 否 | 双击全屏，默认 true | | oStyle | H5PlayerStyle | 否 | 窗口边框/背景样式 |

分屏对应关系：1→1×1，2→2×2，3→3×3，4→4×4。

事件回调

通过 JS_SetWindowControlCallback(callbacks) 注册，建议在 JS_Play 之前调用。

| 回调 | 参数 | 说明 | |------|------|------| | windowEventSelect | (windowIndex) | 窗口被选中 | | pluginErrorHandler | (windowIndex, errorCode, error) | 取流失败、流中断等错误 | | windowEventOver | (windowIndex) | 鼠标移入 | | windowEventOut | (windowIndex) | 鼠标移出 | | windowEventUp | (windowIndex) | 鼠标 mouseup | | windowFullCcreenChange | (isFullScreen) | 全屏状态变化 | | firstFrameDisplay | (windowIndex, width, height) | 首帧显示 | | performanceLack | (windowIndex?) | 性能不足 | | StreamEnd | (windowIndex) | 回放结束 | | StreamHeadChanged | (windowIndex) | 流头信息变化 | | InterruptStream | (windowIndex, interruptTime) | 断流，interruptTime 为无码流秒数 | | talkPluginErrorHandler | (errorCode, error) | 对讲错误 | | ThumbnailsEvent | (windowIndex, eventType, eventCode) | 缩略图事件 | | ElementChanged | (windowIndex, elementType) | 渲染元素变化（video/canvas） |

播放器 API

所有方法均返回 Promise。以下 windowIndex 均指窗口下标，从 0 开始。

播放控制

JS_GetSdkVersion()

获取 SDK 版本号。

const version = player.JS_GetSdkVersion();

JS_Play(url, config, windowIndex, startTime?, endTime?)

开始预览或回放。

| 参数 | 类型 | 必需 | 说明 | |------|------|------|------| | url | string | 是 | 流媒体 WebSocket URL | | config | H5PlayerPlayConfig | 是 | 播放配置，见下表 | | windowIndex | number | 是 | 目标窗口下标 | | startTime | string | 回放必填 | 开始时间，如 2021-06-29T00:00:00Z | | endTime | string | 回放必填 | 结束时间 |

H5PlayerPlayConfig：

| 字段 | 类型 | 说明 | |------|------|------| | playURL | string | 流媒体地址，必传 | | mode | 0 \| 1 | 0=普通模式（默认），1=高级模式 | | PlayBackMode | 1 \| 3 | 1=正放（默认），3=倒放 | | keepDecoder | 0 \| 1 | 0=回收解码器（默认），1=切换不黑屏 | | token | string | 安全认证 token |

// 预览
await player.JS_Play(url, { playURL: url, mode: 0 }, 0);

// 回放
await player.JS_Play(
  url,
  { playURL: url, mode: 0, PlayBackMode: 1 },
  0,
  "2024-01-01T00:00:00Z",
  "2024-01-01T23:59:59Z",
);

JS_Stop(windowIndex?)

停止指定窗口播放。

JS_StopRealPlayAll()

停止所有窗口的实时预览。

声音

一个实例仅支持一路声音；倍速和倒放不支持声音。

JS_OpenSound(windowIndex?)

开启声音。不传 windowIndex 则操作当前选中窗口。

JS_CloseSound(windowIndex?)

关闭声音。

JS_SetVolume(windowIndex, volume)

设置音量，范围 1~100，默认 50。

JS_GetVolume(windowIndex)

获取当前音量。

录像与抓图

JS_StartSaveEx(windowIndex, fileName, destinationType)

开始录像。倒放状态下不支持。

| 参数 | 说明 | |------|------| | fileName | 文件名，需全局唯一，可不带后缀 | | destinationType | 2=PS，5=MP4（音频限 AAC/G711A/G711U） |

JS_StopSave(windowIndex)

停止录像并保存。

JS_CapturePicture(windowIndex, fileName, fileType, callback?)

抓图。

| 参数 | 说明 | |------|------| | fileType | 固定 'JPEG' | | callback | 可选；传入则返回图片数据而不自动下载 |

// 下载到本地
await player.JS_CapturePicture(0, "snapshot", "JPEG");

// 获取数据
await player.JS_CapturePicture(0, "snapshot", "JPEG", (data) => {
  console.log(data); // 2.1.0+ 为 base64
});

回放控制

JS_Pause(windowIndex)

暂停回放。

JS_Resume(windowIndex, forward?)

恢复回放。单帧模式下 forward=true 正向恢复，false 倒向恢复。

JS_Fast(windowIndex?)

快放，当前速度 ×2，最大 8 倍。

JS_Slow(windowIndex?)

慢放，当前速度 ×1/2，最小 1/8 倍。

JS_Speed(windowIndex, rate)

直接设置倍速。支持 -8 | -4 | -2 | 1 | 2 | 4 | 8 | 16 | 32 | 64（负数表示慢放）。

JS_Seek(windowIndex, startTime, endTime)

回放定位。时间格式 2021-06-29T00:00:00Z。

JS_FrameForward(windowIndex)

单帧前进。需 HTTPS + Chrome 94+ + 普通模式；>1 倍速不支持。

JS_FrameBack(windowIndex)

单帧后退。高级模式每次约跳 12 帧；>1 倍速不支持。

JS_ChangeMode(windowIndex)

正倒放切换。

对讲

仅 HTTPS 下可用，只支持一路对讲。

JS_StartTalk(url, options?)

开始对讲。options.token 为安全认证 token。

JS_StopTalk()

停止对讲。

JS_TalkSetVolume(volume)

设置对讲音量，0~100。

JS_TalkGetVolume()

获取对讲音量。

JS_StartSaveTalk(fileName, type?)

录制对讲音频。type：0=设备端，1=客户端，2=双向（默认）。

JS_StopSaveTalk()

停止录制对讲。

窗口与布局

JS_ArrangeWindow(split)

切换分屏：1=1×1，2=2×2，3=3×3，4=4×4。

JS_SelectWnd(windowIndex)

切换选中窗口。

JS_FullScreenDisplay(isFull)

整体全屏/退出。

JS_FullScreenSingle(windowIndex)

单窗口全屏。

JS_Resize(width?, height?)

调整尺寸，不传则自适应父容器。容器 resize 后应主动调用。

JS_GetOSDTime(windowIndex)

获取 OSD 时间，返回自 1970-01-01 起的毫秒数（精度到秒）。

JS_GetVideoInfo(windowIndex)

获取音视频信息（编码格式、分辨率、帧率、码率等）。

高级功能

JS_SetConnectTimeOut(windowIndex, seconds)

设置取流超时（秒），需在 JS_Play 之前调用，默认 12 秒。

JS_SetTraceId(windowIndex, enabled)

是否自动拼接 traceId 到 URL。建议在业务层自行拼接以便管理。

JS_GetTraceId(windowIndex)

获取当前 traceId。

JS_SetInterruptTime(windowIndex, seconds)

断流检测间隔（秒），超时触发 InterruptStream 回调，默认 5 秒。

JS_SetAdditionDataCB(windowIndex, dataType, callback)

私有数据回调。常见 dataType：

| 值 | 说明 | |----|------| | 0x0101 | 定制温度 | | 0x0103 | 基线温度裸数据 | | 0x0006 | 车载行车信息 | | 0x0007 | POS 信息 | | 0x0010 | 汽车电子私有信息 | | 0x0011 | 无人机私有信息 | | 0x0804 | 立体云防私有数据 | | 0x000B | 设备扩展信息 |

JS_OptimizeCapability(windowIndex, url)

判断 URL 是否支持回放优化。

JS_RenderALLPrivateData(windowIndex, enabled)

开启/关闭智能信息展示（高级模式）。

JS_EnableZoom(windowIndex?)

开启电子放大（鼠标框选）。需 HTTPS + Chrome 94+ + 普通模式。

JS_DisableZoom(windowIndex?)

关闭电子放大。

缩略图

需对应媒体组件版本（vnsc/mgc/dac/vod/sac/ncg 等 1.16+）。

JS_StartVideoThumbnails(windowIndex, url, startTime, endTime, options)

开始缩略图服务。

await player.JS_StartVideoThumbnails(0, url, start, end, {
  snapwidth: 500,
  snapheight: 400,
  token: "",
});

JS_GetVideoThumbnails(windowIndex, videoTime, callback)

获取指定时间点缩略图。时间格式如 2022-10-09T08:47:36.000+08:00。

JS_StopVideoThumbnails(windowIndex)

停止缩略图服务。

即时回放

需 HTTPS + Chrome 94+ + H5player 2.5.0+ 普通模式。预览成功后配置一次即可。

JS_InstantSetParam(windowIndex, options)

await player.JS_InstantSetParam(0, {
  bOpenflag: true,   // 开启缓冲
  bInstantTime: 10,  // 缓冲 10/20/30 秒
});

JS_StartInstant(windowIndex)

开始即时回放。须先调用 JS_InstantSetParam 并等待 2 秒以上。

JS_StopInstant(windowIndex)

停止即时回放，回到正常预览。

JS_InstantTotalDuration(windowIndex)

获取缓冲总时长（秒）。

JS_InstantCurrDuration(windowIndex)

获取当前播放进度（秒），从 1 开始。

画面变换

JS_Rotate(windowIndex, degree)

旋转画面，支持 0 | 90 | 180 | 270（顺时针）。旋转后抓图也是旋转后的。

JS_Scale(windowIndex, ratio)

缩放："original" | "fill" | "16:9" | "4:3" | "9:16" | "3:4"。

JS_ScaleCancel(windowIndex)

同时取消缩放和旋转。

水印

JS_SetWatermarkConfig(config)

设置抓图水印，对所有窗口生效。

await player.JS_SetWatermarkConfig({
  text: "hikvision-h5player",
  color: "rgba(255, 255, 255, 0.5)",
  font: "24px 微软雅黑",
  rotateDegree: -15,
  space: 240,
});
await player.JS_CapturePicture(0, "watermarked", "JPEG");

JS_CancelWatermarkConfig()

取消水印。

工具函数

resolveH5PlayerBasePath(baseUrl?, assetDirectory?)

解析 SDK 静态资源根路径，默认 {baseUrl}h5player。

resolveH5PlayerBasePath("/app/");           // → "/app/h5player"
resolveH5PlayerBasePath("/", "h5player");   // → "/h5player"

createH5Player(options)

创建播放器实例的推荐方式，内部加载 SDK 并注册 JSPlugin。

JSPlugin

SDK 原生构造函数，也可 new JSPlugin(options) 直接使用。

常见错误码

| 错误码 | 描述 | |--------|------| | 0x12f900001 | 接口调用参数错误 | | 0x12f900002 | 不在播放状态 | | 0x12f900003 | 仅回放支持该功能 | | 0x12f900004 | 普通模式不支持该功能 | | 0x12f900005 | 高级模式不支持该功能 | | 0x12f900006 | 高级模式的解码库加载失败 | | 0x12f900008 | URL 格式错误（null 或非 ws/wss） | | 0x12f900009 | 取流超时 | | 0x12f900010 | 设置/获取音量失败（未开启音频窗口） | | 0x12f900011 | 音量不在 1~100 范围 | | 0x12f900012 | 打开声音失败（需首帧显示后；倍速不支持声音） | | 0x12f910000 | WebSocket 连接失败 | | 0x12f910010 | 取流失败 | | 0x12f910011 | 流中断 |

完整错误码请参考海康官方开发指南。

发布

淘宝/npmmirror 镜像仅用于安装加速，发布必须走 npm 官方源。本包已在 package.json 中配置 publishConfig.registry：

cd libs/h5player
npm login --registry=https://registry.npmjs.org
npm publish

发布前验证：

npm pack --dry-run

版本

当前封装版本 2.5.1，对应海康 H5player SDK 2.5.1。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

hikvision-h5player

目录

安装

快速开始

Vite 集成

创建实例

H5PlayerOptions

事件回调

播放器 API

播放控制

JS_GetSdkVersion()

JS_Play(url, config, windowIndex, startTime?, endTime?)

JS_Stop(windowIndex?)

JS_StopRealPlayAll()

声音

JS_OpenSound(windowIndex?)

JS_CloseSound(windowIndex?)

JS_SetVolume(windowIndex, volume)

JS_GetVolume(windowIndex)

录像与抓图

JS_StartSaveEx(windowIndex, fileName, destinationType)

JS_StopSave(windowIndex)

JS_CapturePicture(windowIndex, fileName, fileType, callback?)

回放控制

JS_Pause(windowIndex)

JS_Resume(windowIndex, forward?)

JS_Fast(windowIndex?)

JS_Slow(windowIndex?)

JS_Speed(windowIndex, rate)

JS_Seek(windowIndex, startTime, endTime)

JS_FrameForward(windowIndex)

JS_FrameBack(windowIndex)

JS_ChangeMode(windowIndex)

对讲

JS_StartTalk(url, options?)

JS_StopTalk()

JS_TalkSetVolume(volume)

JS_TalkGetVolume()

JS_StartSaveTalk(fileName, type?)

JS_StopSaveTalk()

窗口与布局

JS_ArrangeWindow(split)

JS_SelectWnd(windowIndex)

JS_FullScreenDisplay(isFull)

JS_FullScreenSingle(windowIndex)

JS_Resize(width?, height?)

JS_GetOSDTime(windowIndex)

JS_GetVideoInfo(windowIndex)

高级功能

JS_SetConnectTimeOut(windowIndex, seconds)

JS_SetTraceId(windowIndex, enabled)

JS_GetTraceId(windowIndex)

JS_SetInterruptTime(windowIndex, seconds)

JS_SetAdditionDataCB(windowIndex, dataType, callback)

JS_OptimizeCapability(windowIndex, url)

JS_RenderALLPrivateData(windowIndex, enabled)

JS_EnableZoom(windowIndex?)

JS_DisableZoom(windowIndex?)

缩略图

JS_StartVideoThumbnails(windowIndex, url, startTime, endTime, options)

JS_GetVideoThumbnails(windowIndex, videoTime, callback)

JS_StopVideoThumbnails(windowIndex)

即时回放

JS_InstantSetParam(windowIndex, options)

JS_StartInstant(windowIndex)

JS_StopInstant(windowIndex)

JS_InstantTotalDuration(windowIndex)

JS_InstantCurrDuration(windowIndex)

画面变换

JS_Rotate(windowIndex, degree)

JS_Scale(windowIndex, ratio)

JS_ScaleCancel(windowIndex)

水印

JS_SetWatermarkConfig(config)