问题排查手册#

1. 调试工具介绍#

1.1. 浏览器调试器#

快捷键 F12/点击右键打开检查

常用页面说明：

● lElements（元素）：用于查看或修改 HTML 元素的属性、CSS 属性、监听事件、断点

● lConsole（控制台）：一般用于执行一次性代码，查看 JavaScript 对象，查看调试日志信息或异常信息

● lSources（源代码）：该页面用于查看页面的 HTML 文件源代码、JavaScript 源代码、CSS 源代码，此外最重要的是可以调试 JavaScript 源代码，可以给 JS 代码添加断点等

● lNetwork（网络）：网络页面主要用于查看 header 等与网络连接相关的信息

1.2. 基础调试命令#

1.2.1. 版本查询#

在 Console 下执行(1.3/1.5/2.x 使用 webpak 打包方式: playerjs.version)，(1.2/1.4 使用 npm 包管理方式：playerjs_temp.version)

1.2.2. 日志开启#

在 Console 下执行(1.3/1.5 使用 webpak 打包方式: playerjs.config={logLevel:1})，(1.2/1.4 使用 npm 包管理方式：playerjs_temp.config={logLevel:1}, 2.0 系列：playerjs.logger.setPrintLevel(1))

等级说明：

日志等级 0：表示 trace，所有信息都会打印出来，如需排查算法叠加问题时，可以开启

日志等级 1：表示 debug，主要打印调试信息，如需排查数据流相关问题时，可以开启

日志等级 2：表示 info，主要打印关键信息，如需分析解码类型，分辨率等问题时，可以开启

日志等级 3：表示 error，主要打印错误信息，默认开启。

**特殊约定：**修改日志等级后，重新播放生效，刷新页面后恢复默认等级。不做自动保存，仅当前执行有效

2. 常见问题排查#

2.1. 私有限制#

调试工具网络面板（ Console ）有 CORS 字样或者控制台有 private 字样，则是 存在私有限制问题。原因是 H5 页面工具为外网访问，但是媒体服务为内网。

2.2. 跨域限制#

调试工具网络面板（ Console ）有 CORS 字样或者控制台有 access-control-allow-origin 字样，则是 存在跨域问题。请联系相关人员进行跨域访问配置。如存在 nginx，请优先检查是否允许跨域。

2.3. 请求限制#

调试工具网络面板（ Console ）有 NetWorkError 字样，并查看详情发现 HTTPS 字段，则存在请求限制。原因是工具使用 https 安全访问，但是媒体服务使用 http 非安全访问导致

2.4. 视频无法正常播放#

2.4.1. 配置问题#

• 确保正确配置了 config

在项目引入后，必须修改 config 配置。其中 httpProtocol, ip, port 根据实际项目环境进行修改，缺一不可。

• 缺少 header 配置

如果当 s17 接口 header 加参数时，需要对 defaultHeader 进行配置

• dom 外部容器没有指定宽度或高度

视频初始化后 #video 的样式会设置 width:100%;height:100%。如果 .container 没有设置高度，则 #video 的高度就为 0。

2.4.2. open 接口访问异常#

调试工具网络面板（ Network ）中过滤 open 接口，发现接口变红

该问题可能原因：

1、设置的网关 ip 以及端口不通导致。

2、域名解析不了

3、https 密钥异常等

4、防火墙策略问题，特别是 status 中提示 reset。

2.4.3. open 接口返回异常#

调试工具网络面板（ Network ）中过滤 open 接口，点击 open 请求，查看 response 如下：

常见错误码及描述：

错误码	描述	备注
20406	device is occupied	设备占用中
21700	invalid parameter	参数错误
21716	request timeout	请求超时
21717	device offline	设备不在线
21718	invalid device	设备不存在
21719	invalid protocol	协议不支持
21720	invalid function	无效操作，功能不支持
21721	invalid request	无效请求
21722	resource not found	资源不存在
21723	resource not accessable	资源拒绝
21724	server exception	服务器异常
21725	business exception	业务异常

如返回 999 错误码

可能的原因如下：

1、ms 出现了异常，未启动

2、nacos 出现了异常，无法查询 ms 节点

2.4.4. flv 访问异常#

调试工具网络面板（ Network ）中过滤 open 接口，查看 response 是否返回 flv 地址，如已经返回则过滤 flv 请求，如 flv 请求标红

可能的原因如下：

1、媒体服务配置的地址无法访问 – 需要联系运维修复

2、https 的页面返回了 http 的地址，也会导致无法访问

3、flv 地址中域名无法解析

4、域名过期

2.4.5. flv 请求后未推送数据#

调试工具网络面板（ Network ）中过滤 open 接口，查看 response 是否返回 flv 地址，如已经返回则过滤 flv 请求，如持续无数据推送过来

HTTP-FLV 请求观察，如截图处是否有数据推送：

WS-FLV 请求观察，如截图处是否有数据推送：

如无数据推送，需要取 flvurl 地址中 session 码到 S17 MS 服务日志中查询问题原因，具体参考 S17 FRQ 或者联系媒体开发人员

如有数据推送，则需要联系 H5Player 侧开发分析问题

2.5. 视频加载异常#

播放过程中，播放器提示加载失败，调试工具网络面板（ Network ）中过滤 flv 请求，获取 Session 码，参考 S17 FRQ 进行排查或联系媒体开发人员

常见问题

设备上流超时，平台主动断开链路

2.6. 视频播放卡顿#

2.6.1. wasm 软解性能不足#

首先将日志等级设置为 info，获取当前解码器、视频分辨率、视频编码信息，如下图：

当判断到解码器为 wasm 时，需查看异常收集日志中是否存在提示，存在类似 wasm 播放卡顿字样，如出现类似问题，请使用 MSE 解码方式优化，或者降低分辨率尝试。

2.6.2. 带宽传输不足#

1、从页面上开启显示分辨率、帧率、码率信息，查看当前实时传输码率，如图：

2、结合日志分析传输流量如何，将日志等级设置为 debug，上方过滤器中过滤 AddFrameData 字段，查看传输 1s 数据耗时多少，如下图所示：

也可以参考理论传输带宽：

2.7. 视频播放卡住#

目前前端支持首帧 HOOKS，业务方集成时，可能会做默认暂停方案，需结合业务分析（中台、警用都有该功能）。

该问题可通过日志分析，将日志等级调整为 info，查看 SDK 调用 pause 之后是否有调用 play，如下图所示：

2.8. 回放 seek 失败#

2.8.1. 时区问题#

时区问题。请确保 H5Player.config 的 timeZoneOffset 或者 platformTimeZoneOffset 进行了正确配置。需要和平台时区一致，单位分钟。

2.8.2. 时间点非法#

业务方集成时 seek 到无效时间点，如播放时间段为 2022-09-22 00:00:00 到 2022-09-22 10:00:00，但是 seek 到 2022-09-22 12:00:00，则会导致该问题出现。

2.9. 对讲下行无声音#

因浏览器安全限制，调用麦克风权限需要网站使用 https 协议。如果是本地开发调试，需要使用 localhost。

2.10. 音频问题#

2.10.1. 多路播放回音#

由于 SDK 未限制视频打开时声音播放权限，所以多通道一起播放的时候就会有回声，需要由集成方对各个通道的声音进行控制。如默认只打开 1 通道声音，或者按照用户使用场景切换定制

2.10.2. 无音频#

2.10.2.1. 原始数据原因#

由于 SDK 目前使用流媒体协议为 FLV，按照 FLV 规定 Header 中必须包含是否存在音频帧，然而为了保证起播时延最低，所以 S17 MS 侧校验前 5 帧来判断是否存在音频帧

如：1、前 5 帧存在音频帧，后续音频缺失；那么 H5 SDK 会在后续数据中添加静音数据，保证视频正常播放

2.10.2.2. 集成者调用原因#

在调试工具网络面板（ Console ）中执行 playerjs.operateLog，查看业务层调用逻辑，观察是否进行音量控制

2.11. 打开视频路数限制#

2.11.1. 只能打开 1 路#

1.先根据前面说明，排查是否网络问题，open 接口是否正常，flv 拉流是否正常。

2.业务层创建多通道播放器，是否传入了相同的 div。

2.11.2. 不能打开 6 路以上#

问题原因：

可能是 nginx 代理后，flv 拉流地址没有端口，http1.1 浏览器同源策略限制并发数 6 个。

解决方案：

1.放开 flv 地址的端口

2.升级 http 为 2.0,（2.0 没有同源并发限制）

2.11.3. 不能打开 16 路以上#

问题原因：

1.使用了 wasm 软解，webgl 实例在一个页面上最多存在 16 个上下文，如果继续增加，最先创建的会丢失上下文(现象黑屏)

解决方案：

1.使用 mse 硬解。

2.业务层限制最多 16 个通道

2.12. 视频有声音无画面#

问题原因：

1.传入的 dom 容器没有指定高度，导致高度坍缩。

解决方案：

1.传入的容器必须指定高度。