# wrs-uts-videoplayer 集成与验证清单

> 你已经装好 `uni_modules/wrs-uts-videoplayer`。本文档讲剩下要做的事，
> 以及怎么验证 IjkPlayer 内核真的在工作。

## 一句话原理

`<wrs-uts-videoplayer>` 标签底层有 4 个 Android 内核可选，1 个 iOS 内核可选：

| 平台 | 内核选项 | RTMP 支持 |
|---|---|---|
| Android | Exo2Player | ❌ 不行 |
| Android | SystemPlayer | ❌ 不行 |
| Android | **IjkPlayer** | ✅ **能播** |
| Android | AliPlayer | ⚠️ 看版本 |
| iOS | SystemPlayer | ❌ 不行 |
| iOS | **IjkPlayer** | ✅ **能播** |

我们已经在 `stream-player-external.nvue` 把 `playerCore` 硬编码成 `"IjkPlayer"`。

## 集成 4 步

### Step 1 · 拷贝资源文件到项目根目录

按 `wrs-uts-videoplayer/readme.md` 的"集成步骤"第 1 条：

> 拷贝 demo 里的 `AndroidManifest.xml`、`Info.plist`、`nativeResources` 文件到项目根目录

如果 demo 没下载，可以从 [https://www.cnblogs.com/wenrisheng/p/18323027](https://www.cnblogs.com/wenrisheng/p/18323027) 看作者博客指引。

> ⚠️ 如果你的项目已经有 `AndroidManifest.xml`，**不要直接覆盖**，要把 demo 里的 `<activity>` / `<service>` / `<receiver>` 节点**合并**进来。否则你现有的 push / IM 等模块会失效。

### Step 2 · 打自定义调试基座

HBuilderX 顶部菜单：
- **发行 → 原生 App-本地打包 → 制作 App-Android 自定义调试基座**
- iOS 同理：**制作 App-iOS 自定义调试基座**

> 标准基座**不包含**任何 UTS 原生组件，必须打自定义基座。

### Step 3 · 用自定义基座跑真机

HBuilderX 右上角：**运行 → 运行到手机或模拟器 → 使用自定义调试基座**

### Step 4 · 验证 IjkPlayer 真的在用

打开任意直播间，控制台 Console 应该能看到：

```
=== [STREAM-PLAYER:NVUE] mounted === { strategy: "external", hasExternalLivePlayer: true, ... }
[STREAM-PLAYER:EXT] mounted { hasPlugin: true, source: "rtmp://...", playerCore: "IjkPlayer" }
[STREAM-PLAYER:EXT] wrs event onReadyToPlay { totalTime: ... }
[STREAM-PLAYER:APP] external play
```

画面应该流畅播放，**不再出现"播一会停一会"**。

## 常见问题

### Q: strategy 是 `video` 而不是 `external`，怎么回事？

A: 两种可能：
1. 自定义基座没打成功，`require('@/uni_modules/wrs-uts-videoplayer')` 抓不到 → 重新打基座
2. 当前流不是 RTMP/FLV 而是 m3u8/mp4 → 这是**正确的**，录播本来就走原生 `<video>`

### Q: strategy=external 但显示"未安装 wrs-uts-videoplayer 插件"

A: 探测脚本 `external-player-detect.js` 用的是 `require('@/uni_modules/wrs-uts-videoplayer')`。
检查：
- 路径是否正确（`uni_modules/wrs-uts-videoplayer` 而不是别的拼写）
- HBuilderX 是否重启过（webpack require 会缓存）
- 自定义基座是否包含这个插件（manifest 里有没有勾掉它）

### Q: onError 报"播放失败"

A: 看 `e.detail` 里的具体错误。常见原因：
- 推流不在线（去直播后台确认推流端正在推）
- 网络 ATS 限制（iOS 上明文 RTMP 需要 `NSAllowsArbitraryLoads`，wrs 插件已带）
- IjkPlayer .so 没正确链接（自定义基座可能缺 abi）

### Q: 自定义基座很大（70+ MB），能不能优化？

A: IjkPlayer 自带 .so 库就是这个量级。生产正式包 release 后会瘦身一些，调试基座大一点正常。
如果只针对 arm64-v8a 架构，可以在 manifest 里关掉 armeabi-v7a。

### Q: H5 怎么办？

A: H5 不走这条链。H5 用 `components/live-watch/stream-player.vue`（AliPlayer/hls.js）。
`wrs-uts-videoplayer` 只能用于 nvue + APP-PLUS。

### Q: 这个插件要钱（299元），免费替代有吗？

A: 同作者 wrs 还有一些免费版本（功能少），插件市场搜"wrs ijkplayer"。
但 299 元相比自研 UTS 插件的工作量（按时薪算至少几十小时），值得。

## 切流时的细节

业务层切流（比如换房间）时，`stream-player.nvue` 会因为 `source` 变化触发 watcher。
`stream-player-external.nvue` 已经把 `paramsStr` 做成 computed，
`source` 变化时 `params` 自动重新计算，wrs 内部会感知到 props 变化重新走 setUrl。

如果发现切流不重连，看 wrs 文档第 116 行起的 `setUrl` 业务定义。
必要时可以在 watcher 里强制 `:key="source"` 来 remount。

## 下一步可优化方向

| 优化项 | 思路 |
|---|---|
| 自动重连 | 监听 `onError` 后延迟 3s 重新 setUrl |
| 截屏分享 | 调用 `business: "getImage"`，回调里拿 path |
| 弹幕浮层 | nvue z-index 比 `<wrs-uts-videoplayer>` 高即可 |
| 画中画 | `business: "startPicInPic"`，先检查 `UTSVideoPlayer.canDrawOverlays()` |
