更新记录

1.0.2（2026-09-20）

1. 修正 app-android/src/index.uts 的 density() 云打包 Kotlin 编译错误：DisplayMetrics.density 为 Float，返回值补 .toDouble() 以匹配声明的 Double 返回类型（修复 index.kt:73 Return type mismatch: expected 'Double', actual 'Float'）

1.0.1（2026-09-20）

1. 修正 app-ios/index.uts 的 UTS(ArkTS) 语法：模块变量改用 let、Type? → Type | null、类继承 : → extends、去掉 func 与 ObjC 形参标签、类型 Int/String/Bool/Void → number/string/boolean/void、原生调用改用位置参数（如 setLicence(url, key)）
2. 完善 package.json 发布规范：字段顺序对齐（uni_modules 先于 dcloudext）、engines 采用真实可行版本、压缩 description 至 100 字内、清理 keywords 空项
3. 同步 README 为市场可读结构（兼容性表 / 安装 / API 列表 / 使用示例 / 原生 SDK 接入 / 注意事项）

1.0.0（2026-09-20）

1. 首次发布：基于腾讯云 MLVB 直播版(Live) SDK 13.5.0 的 V2TXLivePlayer（V2 接口）UTS 原生封装
2. 支持 webrtc://(快直播 LEB) / http(s)-flv(FLV) / rtmp://(RTMP) 直播拉流，协议由 URL 自动识别
3. 提供 API：installLicense / createTxLivePlayer / switchTxLiveStream / pauseTxLivePlayer / resumeTxLivePlayer / destroyTxLivePlayer
4. Android / iOS 双端 UTS 实现，兼容 uni-app vue3
5. 需使用者自行放入 MLVB SDK 二进制（aar / xcframework）并申请腾讯云直播 License

平台兼容性

uni-app(3.8.4)

uni-app x(3.91)

腾讯云直播播放器 UTS 原生版 (tx-live-player)

App 端 UTS 原生封装腾讯云移动直播 V2TXLivePlayer（LiteAVSDK Live），播放 webrtc://(快直播 LEB) / http(s)-flv(FLV) / rtmp://(RTMP) 直播流，实现亚秒级低延迟拉流。

解决什么痛点：uni-app App 端内置 <video> 组件无法解码 webrtc://（快直播 LEB）；DCloud 官方也明确 App 端实时音视频播放直接走 <video>，live-player 在 App 不生效。本插件用 UTS 原生封装腾讯云 MLVB SDK，在 App 端补齐 webrtc 低延迟拉流能力，兼容 uni-app vue3。

与插件市场现有方案的差异：

• jinyu-txlive(id=28370) 是 uni-app x 标准模式组件，本项目是 uni-app vue3，不兼容；
• 「腾讯云直播推流拉流 UTS」(id=29557) 是 UTS 兼容模式、仅 nvue 页，本项目是 vue 页，不兼容；
• 「腾讯云移动直播」(id=2812) 是已淘汰付费原生插件(Android≤11/iOS≤14)，版本旧、纯 API、¥499。

兼容性

Web / 小程序端引入本模块不会报错，所有 API 降级为空操作（no-op），由 study-live 等上层组件在 #ifdef APP-PLUS 下才调用原生能力。

安装

1. 将 tx-live-player 目录复制到项目的 uni_modules 目录下（本项目统一放在 src/uni_modules/，与 z-paging / uv-ui-tools 一致）。
2. 本插件不含 MLVB SDK 二进制，必须自行放入（详见下方「原生 SDK 接入」）。
3. 原生 SDK 无法在默认「标准基座」运行，必须云打包 / 自定义基座真机调试。

// #ifdef APP-PLUS
import {
  installLicense,
  createTxLivePlayer,
  switchTxLiveStream,
  destroyTxLivePlayer,
} from '@/uni_modules/tx-live-player'
// #endif

功能模块

核心能力（已实现）

• License 安装 (installLicense) - 设置腾讯云 MLVB License（全局一次）
• 创建播放器 (createTxLivePlayer) - 以覆盖层方式插入当前页面并播放，协议按 URL 自动识别
• 无缝切流 (switchTxLiveStream) - webrtc/LEB 与 FLV 互切，用于签名刷新或失败回退
• 销毁播放器 (destroyTxLivePlayer) - 移除覆盖层原生视图，释放资源

API 列表

installLicense(licenseUrl, licenseKey)

设置腾讯云 MLVB License（全局一次，建议 App 启动时调用；或每次创建前由 createTxLivePlayer 的 licenseUrl/licenseKey 传入）。

installLicense('https://license...', 'your-license-key')

createTxLivePlayer(options)

创建并启动原生播放器（覆盖层方式插入当前页面）。

createTxLivePlayer({
  rect: { left: 0, top: 100, width: 360, height: 200 },
  url: 'webrtc://play.xxx.com/live/stream',       // 快直播 LEB，亚秒级低延迟
  flvUrl: 'http://play.xxx.com/live/stream.flv',  // 失败回退
  callbacks: {
    onStatus: (code, msg) => { if (msg === 'playing') console.log('已播放') },
    onError: (code, msg) => { /* webrtc 失败可 switchTxLiveStream(flvUrl) */ },
  },
})

switchTxLiveStream(url)

无缝切换直播流（支持 webrtc/LEB 与 FLV 互切，用于签名刷新或失败回退）。

switchTxLiveStream('http://play.xxx.com/live/stream.flv')

destroyTxLivePlayer()

停止并销毁原生播放器、移除覆盖层视图。页面关闭时务必调用，否则覆盖层原生视图残留导致内存泄漏 / 黑块。

destroyTxLivePlayer()

使用示例

基础播放（推荐写法）

// 1. 启动（rect 为占位 view 的页面坐标；url 优先传 webrtc://）
createTxLivePlayer({
  rect: { left: 0, top: 100, width: 360, height: 200 },
  url: 'webrtc://play.xxx.com/live/stream',
  flvUrl: 'http://play.xxx.com/live/stream.flv',
  callbacks: {
    onStatus: (code, msg) => { if (msg === 'playing') console.log('已播放') },
    onError: (code, msg) => { /* webrtc 失败可 switchTxLiveStream(flvUrl) */ },
  },
})

// 2. 无缝切换（签名刷新 / rtc 失败回退 flv）
switchTxLiveStream('http://play.xxx.com/live/stream.flv')

// 3. 关闭页面时销毁（务必调用，移除覆盖层原生视图，否则内存泄漏/黑块）
destroyTxLivePlayer()

集成示例：StudyLive.vue 已集成 —— 直播浮层用占位 <view id="appLivePlayer"> 测量坐标后创建播放器；关闭浮层调用 destroyTxLivePlayer()；后台刷新到新签名地址时 switchTxLiveStream 无缝换源。

原生 SDK 接入（必须）

本插件只封装调用逻辑，不包含 MLVB SDK 二进制。需自行下载并放入对应目录：

Android

1. 下载「直播 SDK / MLVB」的 Android aar（含 V2TXLivePlayer、TXCloudVideoView 等）。
   • 腾讯云控制台 → 直播 SDK → 下载 Android 版（或 MLVBSDK 仓库的 Android/libs）。
2. 将 aar 复制到：src/uni_modules/tx-live-player/utssdk/app-android/libs/ （HBuilderX 构建时会自动把该目录下的 aar/jar 合并进 gradle 依赖。）
3. 若 SDK 另含 .so，确认其被打包进 aar（一般已含），否则放 utssdk/app-android/libs/jniLibs/。

iOS

1. 下载「直播 SDK / MLVB」的 iOS framework（TXLiteAVSDK_Live.framework）。
2. 放到：src/uni_modules/tx-live-player/utssdk/app-ios/Frameworks/ （HBuilderX 构建时自动链接 framework。）

目录位置说明：本项目 uni_modules 统一放在 src/uni_modules/（与 z-paging/uv-ui-tools 一致）。 若你的 HBuilderX 版本对 src/uni_modules 下的 UTS 插件不做原生资源合并，请将整个 tx-live-player 移到项目根 uni_modules/，并把 StudyLive.vue 中的 import 路径 @/uni_modules/tx-live-player 改为从根解析。

License（必须，否则播放报错）

MLVB 需先设置腾讯云 License（控制台「直播 SDK」→ 创建 License 拿 URL+Key）。建议 App 启动时调用一次：

import { installLicense } from '@/uni_modules/tx-live-player'
installLicense('https://license...', 'your-license-key')

或在前端取到后端下发的 License 后，于 createTxLivePlayer({ licenseUrl, licenseKey, ... }) 传入（每次创建前会 setLicence）。

打包（必须）

原生 SDK 无法在默认「标准基座」运行，必须：

1. HBuilderX → 发行 → 原生 App 云打包（或「自定义基座」用于真机调试）；
2. 勾选本插件 / 确保 uni_modules/tx-live-player 被打包；
3. Android / iOS 证书齐全。

注意事项

编译风险（真机联调前需核对）

本插件 UTS 代码已按 DCloud 官方 UTS 语法（import X from 'pkg.X'、类继承用 extends、重写方法加 override）编写，并参考同工程 xt-device-sdk 的真实可编译写法。但 MLVB SDK 具体类名/方法签名仍以你下载的版本为准，若编译报错优先核对头文件：

• Android
  • 包名：V2TXLivePlayer/V2TXLivePlayerObserver 在 com.tencent.live2（实现类 com.tencent.live2.impl.V2TXLivePlayerImpl）；TXCloudVideoView 在 com.tencent.rtmp.ui，TXLiveBase 在 com.tencent.rtmp。若你的 aar 包名不同，改 import。
  • V2TXLivePlayerObserver：MLVB 中是抽象类，本项目用 class PlayerObserver extends V2TXLivePlayerObserver + override 重写，符合 UTS 规范。
  • License：本项目调 TXLiveBase.getInstance().setLicence(ctx, url, key)（全局一次）。
  • 播放：startLivePlay(url) 协议由 URL 自动识别（webrtc://→快直播 LEB，http(s)-flv→FLV，rtmp://→RTMP），无需 playType 参数。
  • 覆盖层定位 activity.findViewById(R.id.content) 在带原生导航栏/状态栏机型上可能需叠加偏移（见 density() 注释）。
• iOS
  • 模块名：TXLiteAVSDK_Live（import 用 TXLiteAVSDK_Live.V2TXLivePlayer）。
  • V2TXLivePlayerObserver 为 @optional 协议，class PlayerDelegate : V2TXLivePlayerObserver 实现所需方法（不加 override）。
  • observer 协议方法首参是 player，且参数名为 message:（非 msg:），例如 onError(_ player: V2TXLivePlayer, code: Int, message: String?, extraInfo: NSDictionary?)、onVideoPlaying(_ player: V2TXLivePlayer, firstPlay: Bool, extraInfo: NSDictionary?)。本项目已按 13.5.0 头文件对齐。
  • V2TXLivePlayer.delegate 是 weak，delegate 实例必须用模块级强引用持有（本项目 playerDelegate 变量），否则 ARC 会立即释放，回调永不触发。Android 端 observer 由 SDK 强持有，无需此处理——这是两平台的真实差异。
  • License：iOS 用 V2TXLivePremier.setLicence(url, key:)（全局一次，无 context 参数）。不是 V2TXLivePlayer.setLicence。
  • 渲染：SDK 不暴露 videoView 属性，本项目自行创建 UIView 并 player.setRenderView(view)；播放用 startLivePlay(url)（无 type 参数，URL 自动识别协议），没有 startPlay(_:type:)，也没有 V2TXLivePlayType 枚举。
  • 覆盖层插入 topViewController().view；iOS 13+ 官方推荐用 connectedScenes 取 key window，本项目用 UIApplication.shared.windows.first 取 rootViewController（能用，Xcode 可能给 deprecation 警告，不影响构建）。
  • 切换流：switchTxLiveStream 直接调 player.switchStream(url)（SDK 按 URL 自动识别协议，LEB/FLV 互切无缝）。

如编译报错，优先核对对应平台 SDK 头文件，按上面提示微调即可。

更新日志

v1.0.0 (2026-09-20)

1. 首次发布：基于腾讯云 MLVB 直播版(Live) SDK 13.5.0 的 V2TXLivePlayer（V2 接口）UTS 原生封装
2. 支持 webrtc://(快直播 LEB) / http(s)-flv(FLV) / rtmp://(RTMP) 直播拉流，协议由 URL 自动识别
3. 提供 API：installLicense / createTxLivePlayer / switchTxLiveStream / pauseTxLivePlayer / resumeTxLivePlayer / destroyTxLivePlayer
4. Android / iOS 双端 UTS 实现，兼容 uni-app vue3
5. 需使用者自行放入 MLVB SDK 二进制（aar / xcframework）并申请腾讯云直播 License