直播大屏

一、概览与架构说明

⚠️ 直播大屏涉及直播功能，必须使用 HTTPS 协议部署。HTTP 环境下浏览器安全策略会限制 WebRTC 能力，导致直播无法正常使用。所有服务地址须使用 https:// 和 wss://。

与其他组件的关键区别：

特性	说明
是否依赖 paas.js	❌ 完全独立，不依赖
多实例支持	✅ 天然支持，每个实例独立管理自己的容器和播放状态
接入方式	CDN 引入，通过 `window.DJILivePlayer` 使用
适用场景	单路直播、多路直播大屏网格
官方 Demo	`paasjs-demo/multi-stream-cdn/index.html`（Vue 3 SPA，含布局切换/OSD 设置等）

功能特性：

传入设备 sn，组件自动完成设备查询、直播源匹配、开播和渲染

工具栏：刷新、全屏、停止、画质切换

状态覆盖层：loading / error / offline / autoplay_blocked / need-auth

图传信号强度指示（飞机直播；地面站不展示）

设备离线轮询恢复、自动重试

⚠️ 同一个 sn + camera + video 组合不能重复开播，否则报 DUPLICATE_INSTANCE。

二、引入 SDK 资源

只需引入 SDK 自身两个文件，不需要 paas.js：

加载完成后，挂载在 window.DJILivePlayer，包含：

全局名	内容
`window.DJILivePlayer.initLivePlayer`	全局初始化函数
`window.DJILivePlayer.DjiLivePlayer`	播放器主类（构造函数）

三、全局初始化

渲染任何播放器之前必须调用一次。多路播放器共用同一份配置，不需要每个播放器单独初始化。

InitLivePlayerOptions 参数

字段	类型	必填	说明
`serverUrl`	string	✓	后端地址，不带 `/gateway`（内部自动追加）
`auth.authKeys`	string[]	✓	鉴权 header 名称列表
`auth.headers`	`object \| (() => object)`	✓	推荐函数形式，每次请求实时取值
`locale`	`'zh-CN' \| 'en-US'`	否	默认 `'zh-CN'`
`cameraAuthVerifyUrl`	string	否	地面站外设摄像头验密跳转链接；不传则回退到内置默认页

⚠️ auth.headers() 闭包在每次 HTTP 请求时被调用，须保证返回最新 token。

四、创建单路播放器

每个播放器需要一个有显式宽高的 DOM 容器：

LivePlayerOptions 参数

属性	类型	默认值	说明
`container`	string \| HTMLElement	—	挂载容器，CSS 选择器或 DOM 节点
`sn`	string	—	设备 SN，自动解析模式
`source`	LivePlayerSource	—	高级模式，跳过设备解析直接开播
`fillMode`	`'contain' \| 'fill'`	`'contain'`	视频填充模式
`showOsd`	boolean	`false`	是否显示 OSD 信息
`autoReconnect`	boolean	`true`	设备离线时自动轮询恢复
`pollInterval`	number	`15000`	离线轮询间隔（ms）
`retryCount`	number	`3`	异常自动重试次数
`enableQualitySwitch`	boolean	`true`	是否显示画质切换按钮
`enableCameraSwitch`	boolean	`true`	是否显示摄像头切换（仅地面站且候选摄像头 > 1 时生效）

最小可运行示例（单路）

五、组合成直播大屏（多路网格）

组件本身是单路播放器，"直播大屏"由调用方自行组合多个实例，配合 CSS Grid 拼成网格。

六、事件监听

事件	回调参数	触发时机
`ready`	—	首帧渲染完成
`error`	`LivePlayerError`	播放异常
`resolved`	`ResolvedInfo`	设备解析完成
`stateChange`	`LivePlayerState`	状态变更
`deviceOffline`	—	设备离线
`close`	—	点击关闭按钮

状态机流程：

idle → resolving → starting → playing
                             → autoplay_blocked → （手动点击）→ starting
                             → error → （自动/手动重试）→ starting
                             → offline → （轮询恢复）→ starting
any → destroyed

七、常用方法

方法	说明
`player.refresh()`	重新查询设备 + 尝试开播
`player.retry()`	手动重试
`player.stop()`	停止播放，回到 `idle` 状态
`player.switchQuality(q)`	切换画质
`player.switchCamera(camera)`	切换摄像头（地面站多摄像头场景，`camera` 为 `ResolvedInfo.cameras[].camera`）
`player.destroy()`	销毁播放器（幂等）
`player.getState()`	获取当前状态快照

八、销毁播放器

九、错误码说明

⚠️ 本组件使用独立的字符串错误码，与 WaylineEditor/FlyDataReplay 共用的数字错误码（4001/5000/6002...）完全不同。

错误码	说明
`NOT_INITIALIZED`	未调用 `initLivePlayer()`
`INVALID_SN`	SN 格式无效
`DEVICE_NOT_FOUND`	设备未找到
`AMBIGUOUS_DEVICE_MATCH`	多个设备匹配，无法确定
`DEVICE_OFFLINE`	设备离线
`NO_LIVE_CAPACITY`	设备无直播能力
`NO_LIVE_CAMERA`	无可用摄像头
`NO_VIDEO_STREAM`	无可用视频流
`START_LIVE_FAILED`	开播失败
`PLAYER_INIT_FAILED`	播放器引擎初始化失败
`CHANNEL_EXCEPTION`	直播通道异常
`TOKEN_EXPIRED`	Token 过期
`AUTH_FAILED`	认证失败
`NETWORK_DISCONNECTED`	网络连接断开
`DUPLICATE_INSTANCE`	同 SN/Camera/Video 重复实例
`DRTC_SDK_LOAD_FAILED`	DRTC SDK 加载失败
`QUALITY_SWITCH_FAILED`	画质切换失败
`CAMERA_NEED_AUTH`	外设摄像头需要验密才能播放

典型错误处理：

十、地面站设备支持

地面站设备（device_model.class === 'base_station'）与机场/飞机相比，展示和交互上有以下差异：

图传信号指示器
地面站没有 SDR 信号数据，resolved 事件回调的 ResolvedInfo.deviceType === 'base_station' 时，组件自动隐藏图传信号指示器，ISV 无需额外处理。

多摄像头切换
地面站可能挂载多个外设摄像头，当 enableCameraSwitch 为 true（默认）且候选摄像头数 > 1 时，工具栏出现摄像头切换按钮。ResolvedInfo.cameras 提供可选摄像头列表（含中文 cameraName），也可调用 player.switchCamera(camera) 手动切换。

外设摄像头验密
部分外设摄像头需要验密才能播放，命中时组件展示 need-auth 覆盖层，点击"去验证"后跳转到验密页：

跳转链接优先取 initLivePlayer({ cameraAuthVerifyUrl })

未配置则回退到内置默认页

十一、浏览器兼容性与 Token 说明

浏览器兼容：

Chrome 80+、Edge 80+、Safari 14.1+、Firefox 80+

需要 WebRTC 支持（DRTC 协议依赖）

移动端浏览器受限于自动播放策略，可能触发 autoplay_blocked 状态

Token 机制说明：

层级	说明
HTTP 层	`auth.headers()` 为函数形式，每次请求时实时取值，请确保返回有效 token
RTC 层	内部自动监听 `TOKEN_WILL_EXPIRE` 事件进行续期
组件层	仅监听 `TOKEN_EXPIRED` 事件，通过 `error` 回调通知调用方处理

Token 刷新需由调用方自行实现，请监听 error 事件处理 token 过期：

典型流程速查

场景	调用顺序
单路直播	`initLivePlayer()`（一次）→ `new DjiLivePlayer({ container, sn })`
多路直播大屏	`initLivePlayer()`（一次）→ 遍历 SN 分别 `new DjiLivePlayer()`
切换设备	`player.destroy()` → `new DjiLivePlayer({ container, sn: newSn })`
鉴权刷新	`auth.headers` 传函数形式，每次请求实时取值
卸载单个	`player.destroy()`
卸载全部	遍历调用每个实例的 `destroy()`

目录#

一、概览与架构说明#

二、引入 SDK 资源#

三、全局初始化#

四、创建单路播放器#

五、组合成直播大屏（多路网格）#

六、事件监听#

七、常用方法#

八、销毁播放器#

九、错误码说明#

十、地面站设备支持#

十一、浏览器兼容性与 Token 说明#

典型流程速查#

目录