开始使用
  • English
  • 简体中文
前往官网
开始使用
  • English
  • 简体中文
前往官网
  • 开始使用
  • 核心概念
  • 开发指南
  • 设备能力与事件参考
  • API 参考
  • SDK 与工具
    • Android SDK
    • iOS SDK
    • PC SDK
    • ImouPlayer 轻应用 JavaScript SDK
    • SDK 隐私政策
    • Postman 调试
    • 图片解密
  • 方案
  • 平台与支持
本页目录
ImouPlayer - 组件说明
产品介绍
适用浏览器
体验产品
1. 基本用法
1.1 引入 imou-player.js
1.3 初始化 imouPlayer
1.4 imouPlayer 初始化参数说明
1.5 getKitToken 接口协议说明
详细说明
请求地址
入参说明
请求示例
响应示例
2. imouPlayer 方法
2.1 相关示例代码
常见问题

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>

#### 1.2 引入必要的依赖库 [重要且必选] [参见多线程模式设置](#section1)

请将 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 初始化参数说明

参数名类型默认值必填说明
idString/是容器挂载 DOM 的 id
widthNumber/是容器宽度
heightNumber/是容器高度
deviceIdString/是设备 SN
channelIdString/是设备通道号
tokenString/是轻应用使用的 KitToken,可通过 1.5 节 getKitToken 接口获取
typeString/是播放模式:1:实时预览;2:录像回放;
recordTypeString/否cloud-云录像;localRecord-本地录像;nvrDisk-NVR 录像。默认云录像
beginTimeString/否回放开始时间 YYYY-MM-DD HH:mm:ss
endTimeString/否回放结束时间 YYYY-MM-DD HH:mm:ss
streamIdString0否视频清晰度,0:高清;1:标清
mutedBooleanfalse否静音
codeString/否设备视频解密密钥。设备已开启视频加密时必填。
若设备设置了自定义音视频加密密钥,请填写该密钥;
若仅设置了设备密码,请填写设备密码;
其他情况使用默认设备 SN。
handleErrorFunction/否播放错误回调,见 1.4.1 handleError 播放错误回调
handleCallBackFunction/否播放事件回调,见 1.4.2 handleCallBack 播放事件回调
videoTalkBooleanfalse否视频对讲
controlsBooleantrue否控件显示 true / 隐藏 false
controlsConfigArray["play", "volume", "talk", "capture", "videoRecord", "ptz", "resolution", "fullPageScreen", "fullScreen", "speed", "recordChange", "recordTimeLine","calendar","digitalZoom"]否控件配置,配置项见 1.4.3 controlsConfig 配置
controlsSizeNumberPC 端:35;移动端:32否控件尺寸
controlsColorString#ffffff否控件颜色
controlsActiveColorString#f18d00否控件高亮颜色
templateModeStringpc否UI 模板
PC 端:pc,移动端:mobile
titleStringSN-通道号否标题内容
titleColorString#ffffff否标题颜色
WasmLibPathString""否WasmLib 资源访问路径,默认为相对路径;可配置绝对路径如 "/",具体路径请按项目 public 目录调整
dprNumber0否V1.3.0 及以上支持。当监控画面清晰度超过当前终端显示分辨率时,可减轻锯齿。默认 0,按原始码流分辨率渲染。

##### 1.4.1 handleError 播放错误回调
errCodeerrMsg
1001解密失败,请重新输入密钥
1002设备响应异常,请检查后重试
2001获取对讲地址失败,请检查设备
2002对讲连接建立失败,语音对讲流源已存在
2003设备不支持视频对讲
2004麦克风被占用或无法获取麦克风权限
2005客户端摄像头被占用或无法获取摄像头权限
2006对讲失败,请稍后重试
2007视频通话过程中,设备端挂断
2008对讲忙线
2009对讲已关闭

##### 1.4.2 handleCallBack 播放事件回调
typedesc
playStart开始播放
talkStart开始对讲
talkEnd对讲结束

##### 1.4.3 controlsConfig 配置 > 仅在 controls 设为 true 时生效。
typedesc
play播放 / 暂停
volume声音开关
talk双向对讲
resolution清晰度切换
capture抓图
ptz镜头云台转动
videoRecord录屏
fullPageScreen网页全屏
fullScreen全屏
speed倍速
recordChange云录像与本地录像切换
recordTimeLine录像时间轴
calendar日历
digitalZoom电子变倍

1.5 getKitToken 接口协议说明

详细说明

为轻应用播放生成具备指定权限的设备令牌(kitToken),可为不同终端用户分配不同权限以便管理。

说明:

  1. 开发者调用 Imou 开放平台 API 时的域名与签名计算,请参阅:开发规范
  2. kitToken 有效期为 2 小时。建议在自有服务中缓存约 1 小时,而非每次播放都请求开放平台接口。
请求地址

https://openapi-[DataCenter].easy4ip.com/openapi/getKitToken

入参说明
参数列表说明参数类型必填默认值取值说明
token管理员 accessTokenString是accessToken 获取协议见:accessToken
nvrDeviceIdImou NVR 设备 SNString否IPC 仅本地关联 Imou NVR 时必填
nvrProductIdImou NVR 产品 IdString否IPC 仅本地关联 Imou NVR 时必填
deviceId设备 SNString是通过 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结束播放并销毁 DOMplayer.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;
}

### 3. 多线程模式设置

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";

常见问题

  1. 实时/录像播放、对讲等场景建立 WebSocket 连接时返回 404?

404 可能表示流源已超时失效。实时录像、对讲、直播、录像下载等请勿提前拉流,仅在需要时再请求接口获取流地址,避免流源超时失效,以及同时请求多个流源造成混淆。

  1. 发起对讲后设备端无声音?

可能是通道音频格式为 AAC,但 RTSP 信令返回 L16。当前通过 NVR 与通道 IPC 的对讲不支持 L16。

  1. 页面放置多个播放器出现卡顿?

码流需解密且渲染层使用 canvas,性能要求高于纯视频播放。多路同时播放时,若电脑性能不足或浏览器版本过低,多画面易出现卡顿。

  1. 移动端访问轻应用,iOS 调高音量后仍无声?

受 iOS 权限限制,需关闭手机系统静音(响铃)模式。

  1. 移动端打开对讲无响应?

请先在浏览器中开启麦克风(Mic)权限。

  1. 移动端已配置抓图、录屏功能,但未显示对应按钮?

iOS、Android 微信小程序 web-view 以及 Android 内置浏览器不支持抓图与录屏,故不显示相关按钮。

  1. 移动端访问轻应用时录屏受内存限制,录屏文件上限约 100M。

  2. 录屏下载的文件无法播放,如何处理?

录屏数据不足,建议录屏时长超过 5 秒。

  1. 录屏结束后未下载 MP4 到本地,如何处理?

可能是浏览器内存不足导致文件写入失败;可重启浏览器以保证足够内存。

  1. 移动端退出浏览器后仍在播放,如何处理?

可监听页面可见性变化,执行暂停/恢复播放等操作。示例见 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();
 }
 }
 });
}
  1. 接入过程中出现 Uncaught SyntaxError: Unexpected token '<'、WasmLib 加载失败等报错?

多为 WasmLib 路径引入错误。可通过初始化参数 WasmLibPath 配置资源路径;若需绝对路径可设为 "/"(具体路径请按项目 public 目录调整)。

  1. 视频清晰度较高时画面出现锯齿?

屏幕分辨率高于客户端渲染分辨率时,canvas 渲染会丢失部分像素。 建议:获取设备像素比 var pixelRatio = window.devicePixelRatio,初始化时配置 [dpr: pixelRatio]

桌面体验 Demo
SDK 隐私政策