ImouPlayer 轻应用 JavaScript SDK
ImouPlayer - 组件说明
产品介绍
轻应用 UIKit 是 Imou 开放平台面向 Web 与移动端浏览器推出的对接组件,具备接入快、即点即播、低延迟等特点。轻应用支持 H.264、H.265 编码下的视频预览、双向对讲、录像回放、云台控制、抓图与录屏等功能,帮助开发者在更短时间、更低成本内完成集成并达成业务目标。
适用浏览器
| 浏览器 | 版本 |
|---|---|
| Chrome | >= 55 |
| Firefox | >= 55 |
| Edge | >= 55 |
体验产品
可在线体验产品能力,再基于轻应用 Demo 进行二次开发。体验地址:
- PC 端:点击体验轻应用
2024 年 12 月 31 日之后接入的版本,请务必关注 1.2 引入必要的依赖库
1. 基本用法
1.1 引入 imou-player.js
// Need to synchronize the introduction of the CSS style file.
<link href="./imou-player.css" rel="stylesheet" />
<script src="./imou-player.js"></script>
Example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" />
<title>imouPlayer</title>
<link href="./imou-player.css" rel="stylesheet" />
<script src="./imou-player.js"></script>
</head>
<body>
<!-- Provide an empty div Tag in the Page for the Generation of the lightweight application Play Element -->
<div id="root"></div>
</body>
</html>
请将 WasmLib 放入您项目 public 目录下。imouPlayer 初始化支持配置 WasmLib 访问路径,参数名:WasmLibPath。可按项目需要配置相对路径(默认)或绝对路径。
1.3 初始化 imouPlayer
// Add DOM Container
const player = new imouPlayer({
id: "root",
width: 800,
height: 400,
// Device SN
deviceId: "7H0B18XXXXXXXX",
// Device channel number
channelId: "0",
// kitToken, obtain through the getKitToken API
token: "Kt_hz00e4c3XXXXXXXXXXX",
// 1-Live, 2-Playback
type: "1",
// Live 0-HD; 1-SD
streamId: "0",
// Playback, cloud-Cloud Video; localRecord-Local Video; nvrDisk-NVR Video. Default Cloud Video
recordType: "cloud",
// Default Relative Path, Absolute Path can be configured as "/", specific path should be adjusted according to the project's public file path
WasmLibPath: "",
// If the device has set a custom audio and video encryption key, please input this key;
// If the device is only set with a Device Password, then enter the Device Password; in other cases, use the Default device SN.
code: "xxxxxx",
});
1.4 imouPlayer 初始化参数说明
| 参数名 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| id | String | / | 是 | 容器挂载 DOM 的 id |
| width | Number | / | 是 | 容器宽度 |
| height | Number | / | 是 | 容器高度 |
| deviceId | String | / | 是 | 设备 SN |
| channelId | String | / | 是 | 设备通道号 |
| token | String | / | 是 | 轻应用使用的 KitToken,可通过 1.5 节 getKitToken 接口获取 |
| type | String | / | 是 | 播放模式:1:实时预览;2:录像回放; |
| recordType | String | / | 否 | cloud-云录像;localRecord-本地录像;nvrDisk-NVR 录像。默认云录像 |
| beginTime | String | / | 否 | 回放开始时间 YYYY-MM-DD HH:mm:ss |
| endTime | String | / | 否 | 回放结束时间 YYYY-MM-DD HH:mm:ss |
| streamId | String | 0 | 否 | 视频清晰度,0:高清;1:标清 |
| muted | Boolean | false | 否 | 静音 |
| code | String | / | 否 | 设备视频解密密钥。设备已开启视频加密时必填。 若设备设置了自定义音视频加密密钥,请填写该密钥; 若仅设置了设备密码,请填写设备密码; 其他情况使用默认设备 SN。 |
| handleError | Function | / | 否 | 播放错误回调,见 1.4.1 handleError 播放错误回调 |
| handleCallBack | Function | / | 否 | 播放事件回调,见 1.4.2 handleCallBack 播放事件回调 |
| videoTalk | Boolean | false | 否 | 视频对讲 |
| controls | Boolean | true | 否 | 控件显示 true / 隐藏 false |
| controlsConfig | Array | ["play", "volume", "talk", "capture", "videoRecord", "ptz", "resolution", "fullPageScreen", "fullScreen", "speed", "recordChange", "recordTimeLine","calendar","digitalZoom"] | 否 | 控件配置,配置项见 1.4.3 controlsConfig 配置 |
| controlsSize | Number | PC 端:35;移动端:32 | 否 | 控件尺寸 |
| controlsColor | String | #ffffff | 否 | 控件颜色 |
| controlsActiveColor | String | #f18d00 | 否 | 控件高亮颜色 |
| templateMode | String | pc | 否 | UI 模板 PC 端:pc,移动端:mobile |
| title | String | SN-通道号 | 否 | 标题内容 |
| titleColor | String | #ffffff | 否 | 标题颜色 |
| WasmLibPath | String | "" | 否 | WasmLib 资源访问路径,默认为相对路径;可配置绝对路径如 "/",具体路径请按项目 public 目录调整 |
| dpr | Number | 0 | 否 | V1.3.0 及以上支持。当监控画面清晰度超过当前终端显示分辨率时,可减轻锯齿。默认 0,按原始码流分辨率渲染。 |
| errCode | errMsg |
|---|---|
| 1001 | 解密失败,请重新输入密钥 |
| 1002 | 设备响应异常,请检查后重试 |
| 2001 | 获取对讲地址失败,请检查设备 |
| 2002 | 对讲连接建立失败,语音对讲流源已存在 |
| 2003 | 设备不支持视频对讲 |
| 2004 | 麦克风被占用或无法获取麦克风权限 |
| 2005 | 客户端摄像头被占用或无法获取摄像头权限 |
| 2006 | 对讲失败,请稍后重试 |
| 2007 | 视频通话过程中,设备端挂断 |
| 2008 | 对讲忙线 |
| 2009 | 对讲已关闭 |
| type | desc |
|---|---|
| playStart | 开始播放 |
| talkStart | 开始对讲 |
| talkEnd | 对讲结束 |
| type | desc |
|---|---|
| play | 播放 / 暂停 |
| volume | 声音开关 |
| talk | 双向对讲 |
| resolution | 清晰度切换 |
| capture | 抓图 |
| ptz | 镜头云台转动 |
| videoRecord | 录屏 |
| fullPageScreen | 网页全屏 |
| fullScreen | 全屏 |
| speed | 倍速 |
| recordChange | 云录像与本地录像切换 |
| recordTimeLine | 录像时间轴 |
| calendar | 日历 |
| digitalZoom | 电子变倍 |
1.5 getKitToken 接口协议说明
详细说明
为轻应用播放生成具备指定权限的设备令牌(kitToken),可为不同终端用户分配不同权限以便管理。
说明:
- 开发者调用 Imou 开放平台 API 时的域名与签名计算,请参阅:开发规范
- kitToken 有效期为 2 小时。建议在自有服务中缓存约 1 小时,而非每次播放都请求开放平台接口。
请求地址
https://openapi-[DataCenter].easy4ip.com/openapi/getKitToken
入参说明
| 参数列表 | 说明 | 参数类型 | 必填 | 默认值 | 取值说明 |
|---|---|---|---|---|---|
| token | 管理员 accessToken | String | 是 | accessToken 获取协议见:accessToken | |
| nvrDeviceId | Imou NVR 设备 SN | String | 否 | IPC 仅本地关联 Imou NVR 时必填 | |
| nvrProductId | Imou NVR 产品 Id | String | 否 | IPC 仅本地关联 Imou NVR 时必填 | |
| deviceId | 设备 SN | String | 是 | 通过 onvif 接入 NVR 下摄像机时,取值格式为 nvrSN_nvrProductId_deviceSN,例如 C5B2510ETEST123_45893BGYTEST2123_9CTEST123 | |
| channelId | 通道号 | String | 是 | ||
| type | 权限类型 | String | 是 | 0:全部权限;1:实时预览;2:录像回放(云录像 + 本地录像);6:云台转动。 默认为 0 |
请求示例
system.sign 为 HMAC-SHA256 后 Base64,须按 HTTP 开发规范 实时计算,勿照抄固定值。
{
"system": {
"ver": "1.0",
"appId": "lcxxxxxxxxxxxxxx",
"sign": "xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=",
"time": 1626313677,
"nonce": "1686f6f4-dec7-486e-93e3-6b2740577259"
},
"id": "0f935cb0XXX",
"params": {
"token": "At_000085fa18f0319046199b2138c04e54",
"deviceId": "TEST1234567QWER",
"channelId": "0",
"type": "0"
}
}
响应示例
{
"result": {
"msg": "Operation is successful.",
"code": "0",
"data": {
"expireTime": 7199,
"kitToken": "Kt_xxxxxxxxxxxxxxxxxxxx"
}
},
"id": "0f935cb0XXX"
}
expireTime 为 KitToken 剩余有效时间(秒);kitToken 为令牌值。
2. imouPlayer 方法
| 方法名 | 功能说明 | 调用示例 |
|---|---|---|
| play | 开始播放 | player.play() |
| pause | 暂停播放 | player.pause() |
| start | 暂停后继续播放 | player.start() |
| destroy | 结束播放并销毁 DOM | player.destroy() |
| capture | 抓图 | player.capture() |
| startTalk | 开始对讲 | player.startTalk() // Audio Talk player.startTalk("video") // Video Talk |
| stopTalk | 结束对讲 | player.stopTalk() |
| volume | 设置音量(0/1) | player.volume(0) // Shut Down Volume player.volume(1) // Turn On Volume |
| fullScreen | 全屏 | player.fullScreen() |
| exitFullScreen | 退出全屏 | player.exitFullScreen() |
| startRecord | 开始录屏 | player.startRecord() |
| stopRecord | 结束录屏 | player.stopRecord() |
| setSpeed | 录像回放倍速(0.5/1/2/4/8/16/32),本地录像不支持 32 倍 | player.setSpeed(2) |
| answerVideoTalk | 收到设备发起的视频对讲,进入接听/拒接状态 | player.answerVideoTalk() |
| zoomIn | 电子变倍 - 放大 | player.zoomIn() |
| zoomOut | 电子变倍 - 缩小 | player.zoomOut() |
| resetZoom | 电子变倍 - 重置 | player.resetZoom() |
2.1 相关示例代码
const text = e.target.innerText;
switch (text) {
case "Play":
player.play();
break;
case "Pause":
player.pause();
break;
case "Pause and then Play":
player.start();
break;
case "Take Screenshot":
player.capture();
break;
case "Full Screen":
player.fullScreen();
break;
case "Exit Full Screen":
player.exitFullScreen();
break;
case "Sound - On":
player.volume(1);
break;
case "Sound - Shut Down":
player.volume(0);
break;
case "Audio Talk - Start Intercom":
player.startTalk();
break;
case "Audio Talk - End Talk":
player.stopTalk();
break;
case "2x speed":
player.setSpeed(2);
break;
default:
break;
}
ImouPlayer JSSDK 支持在 Web 端免插件播放 H264/H265 实时/录像码流。默认采用多线程解码(Google Chrome >= 91;Firefox >= 97;Edge >= 91);不满足条件时回退为单线程。
同一环境下多线程模式性能更好,但需为前端服务配置跨域嵌入策略(COOP/COEP)。
可先浏览 Demo 快速上手:轻应用 Web Video SDK&Demo 包内的 demo 见 资源下载。
将 WasmLib 放入项目 public 目录(重要且必选)
在前端服务响应头中配置 Cross-Origin-Opener-Policy 与 Cross-Origin-Embedder-Policy:
node 服务
response.setHeader("Cross-Origin-Opener-Policy", "same-origin");
response.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
- nginx 服务
add_header Cross-Origin-Opener-Policy "same-origin";
add_header Cross-Origin-Embedder-Policy "require-corp";
常见问题
- 实时/录像播放、对讲等场景建立 WebSocket 连接时返回 404?
404 可能表示流源已超时失效。实时录像、对讲、直播、录像下载等请勿提前拉流,仅在需要时再请求接口获取流地址,避免流源超时失效,以及同时请求多个流源造成混淆。
- 发起对讲后设备端无声音?
可能是通道音频格式为 AAC,但 RTSP 信令返回 L16。当前通过 NVR 与通道 IPC 的对讲不支持 L16。
- 页面放置多个播放器出现卡顿?
码流需解密且渲染层使用 canvas,性能要求高于纯视频播放。多路同时播放时,若电脑性能不足或浏览器版本过低,多画面易出现卡顿。
- 移动端访问轻应用,iOS 调高音量后仍无声?
受 iOS 权限限制,需关闭手机系统静音(响铃)模式。
- 移动端打开对讲无响应?
请先在浏览器中开启麦克风(Mic)权限。
- 移动端已配置抓图、录屏功能,但未显示对应按钮?
iOS、Android 微信小程序 web-view 以及 Android 内置浏览器不支持抓图与录屏,故不显示相关按钮。
移动端访问轻应用时录屏受内存限制,录屏文件上限约 100M。
录屏下载的文件无法播放,如何处理?
录屏数据不足,建议录屏时长超过 5 秒。
- 录屏结束后未下载 MP4 到本地,如何处理?
可能是浏览器内存不足导致文件写入失败;可重启浏览器以保证足够内存。
- 移动端退出浏览器后仍在播放,如何处理?
可监听页面可见性变化,执行暂停/恢复播放等操作。示例见 Live Kit 中
demos/vue3-mobile-demo/src/views/Player.vue,Demo 包见 资源下载
// When the Page is in Play state, monitor changes in Visibility.
if (player.status.playing) {
// Monitor changes in page visibility (including home key, switching applications, etc.)
document.addEventListener("visibilitychange", () => {
if (document.hidden) {
// Page enters the background (including tapping the home key)
if (player) {
player.pause();
}
} else {
// Page is now visible
if (player) {
player.start();
}
}
});
}
- 接入过程中出现 Uncaught SyntaxError: Unexpected token '<'、WasmLib 加载失败等报错?
多为 WasmLib 路径引入错误。可通过初始化参数 WasmLibPath 配置资源路径;若需绝对路径可设为 "/"(具体路径请按项目 public 目录调整)。
- 视频清晰度较高时画面出现锯齿?
屏幕分辨率高于客户端渲染分辨率时,canvas 渲染会丢失部分像素。 建议:获取设备像素比
var pixelRatio = window.devicePixelRatio,初始化时配置[dpr: pixelRatio]
