更新记录

1.1.3（2026-09-22）

1. 修复 iOS 云打包在 Xcode 26.5 / Swift 6 下的 NSNumber 构造编译失败（致命）：new NSNumber(value: x) / new NSNumber(integer: x) / new NSNumber(int: x) 三种写法均无法通过云打包——Xcode 26.5 已将 NSNumber 的全部定型 init（init(integer:)/init(int:)/init(long:)…）重命名为 init(value:)，而当前 UTS 转译器无法生成 init(value:)（写成 value:/value = 都会被丢冒号、生成非法的 NSNumber(value x)）。改为用 UTS 桥接转型 x as NSNumber：Int/Int32 经 _ObjectiveCBridgeable 桥接为 NSNumber 是 Swift 合法写法，不调用任何被判名的 init，生成的 x as NSNumber 在 Xcode 26.5 直接通过，同时仍产出 NSNumber 满足 number 回调边界。涉及 14 处：播放/推流 observer 的 onError/onStatus 回调参数，以及 isTxPushing() 返回值
2. 本问题为「UTS 转译器版本 vs 云打包 Xcode 26.5」的 NSNumber API 不兼容；若后续 UTS 转译器升级能正确生成 init(value:)，可把 14 处 as NSNumber 回退为更直观的 new NSNumber(value: x)
3. 仅影响 iOS 云打包；Android 不受影响。详见插件内 iOS云打包NSNumber编译问题总结.md

1.1.2（2026-09-20）

1. 修复推流连接状态不更新：真机验证推流实际成功（腾讯云流管理「直播中」、实时播放有画面），但 onPushStatusUpdate 的 ConnectSuccess(2) 未透传到 JS（Connecting(1) 正常），App 状态一直停在「正在连接」。新增 isTxPushing() API（透出 SDK isPushing()），前端在 Connecting 后每 2 秒轮询兜底，推流真正建立即把状态修正为「推流中」；停止/出错时停止轮询
2. Android onPushStatusUpdate 增加 console 日志（ordinal+枚举名+msg），便于后续用 logcat 定位回调透传问题
3. 已 javap 反编译确认 V2TXLivePushStatus 声明顺序：Disconnected(0)/Connecting(1)/ConnectSuccess(2)/Reconnecting(3)，status.ordinal 映射无误
4. iOS 编译通过并真机跑通：修复 iOS 端编译错误——① Int has no member rawValue / cannot convert V2TXLiveCode to NSNumber：observer 回调的 code/status 与 startLivePlay/switchStream/startPush 返回值须声明为原生枚举 V2TXLiveCode/V2TXLivePushStatus（import 自框架根模块），用 .rawValue 取 NSInteger；② nil requires contextual type：UTS 会优化掉「只写不读」的模块级变量声明，delegate 强引用变量改为判空读取保留声明；③ destroy 补 setObserver(null) 断开 observer 引用（对齐 Android，规避潜在内存泄漏）
5. 修复回调「已释放」：HBuilderX 4.25+ 回调默认一次性回收，createTxLivePlayer/createTxLivePusher 加 @UTSJS.keepAlive（Android+iOS 两端），使 onStatus/onError 可多次触发
6. 修复首次推流 License -5：MLVB License 为联网校验（异步），前端 live-push.vue 在拿到 licenceUrl/licenceKey 后立即 installLicense 提前设置，规避「首次安装+首次推流 -5、之后再点即正常」的时序问题
7. package.json 权限/数据声明补充相机、麦克风权限（推流采集所需），修正过时的「不涉及相机」描述

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'）

平台兼容性

uni-app(3.8.4)

uni-app x(3.91)

其他

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

App 端 UTS 原生封装腾讯云移动直播 V2TXLivePlayer（拉流播放）与 V2TXLivePusher（讲师开播推流）（LiteAVSDK Live），播放 webrtc://(快直播 LEB) / http(s)-flv(FLV) / rtmp://(RTMP) 直播流实现亚秒级低延迟观看，并支持摄像头/麦克风采集 RTMP 推流开播。

解决什么痛点：uni-app App 端内置 <video> 组件无法解码 webrtc://（快直播 LEB）；内置 <live-pusher> 在部分基座上不自动起流、且与「关闭内置直播模块」后的 SDK 独占方案冲突。本插件用 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（aar 位于 utssdk/app-android/libs/，以 implementation 打包进 APK，作为唯一 SDK 来源；宿主项目 manifest.json 需关闭内置 LivePusher/LivePlayer 模块，避免重复类/重复 .so 冲突）。
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) - 移除覆盖层原生视图，释放资源
• 讲师开播推流 (createTxLivePusher) - 摄像头/麦克风采集 + 覆盖层预览 + RTMP 推流开播
• 推流控制 - stopTxLivePush(停流) / switchTxCamera(前后置) / enableTxCamera(采集开关) / muteTxPushAudio(静音) / destroyTxLivePusher(销毁)

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()

createTxLivePusher(options)

创建推流器并开播（讲师开播）：渲染覆盖层插入当前页面 → 开启摄像头/麦克风 → startPush。回调 onStatus 的 code 为连接状态（0 断开 / 1 连接中 / 2 连接成功 / 3 重连中）。

createTxLivePusher({
  rect: { left: 0, top: 100, width: 360, height: 260 },
  pushUrl: 'rtmp://push.xxx.com/live/stream?txSecret=...',
  frontCamera: true,
  callbacks: {
    onStatus: (code, msg) => { if (code === 2) console.log('已连接推流服务器') },
    onError: (code, msg) => { /* 提示并销毁 */ },
  },
})

stopTxLivePush() / switchTxCamera(front) / enableTxCamera(enable) / muteTxPushAudio(mute) / destroyTxLivePusher()

推流控制：停止推流与采集（保留实例可重开）/ 前后置切换（成对 stop/start 采集源）/ 摄像头采集开关 / 静音（pauseAudio 停采集但继续发静音包，比 stopMicrophone 更适合直播）/ 销毁推流器与覆盖层（页面关闭时务必调用）。

使用示例

基础播放（推荐写法）

// 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

插件已内置腾讯云 MLVB SDK aar（LiteAVSDK_Live_13.5.0.20670.aar，位于 utssdk/app-android/libs/，以 implementation 打包进 APK，作为唯一 SDK 来源）。宿主项目 manifest.json 必须关闭内置 LivePusher / LivePlayer 模块（否则与插件 SDK 重复类/重复 .so 冲突），相机/麦克风权限由宿主 manifest 配置（CAMERA、RECORD_AUDIO）。

• 升级 SDK 版本：把新版 aar 替换 utssdk/app-android/libs/ 下同名文件即可。
• .so 已打包进 aar（一般无需额外处理）。详见下方「SDK 冲突」章节。

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 是 Objective-C 的 @protocol（不是 class），UTS 里要用 implements 遵循协议：class PlayerDelegate implements V2TXLivePlayerObserver（不能用 extends，否则会被编译成 Swift 的类继承、把协议当父类而报 NSObject/@objc 错误）。
  • observer 协议方法首参是 player，且参数名为 message:（非 msg:）、code 类型为 V2TXLiveCode(NSInteger)，例如 onError(_ player: V2TXLivePlayer, code: V2TXLiveCode, message: String?, extraInfo: NSDictionary?)。UTS 实现时需用 @argumentLabel 还原参数标签，并用原生类型 Int(对应 code)、NSDictionary(对应 extraInfo)——见 utssdk/app-ios/index.uts。
  • V2TXLivePlayer 没有 delegate 属性，只有 setObserver:（- (void)setObserver:(id<V2TXLivePlayerObserver>)observer），UTS 里用 p.setObserver(delegate) 注册；observer 为 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 互切无缝）。
  • iOS 云打包若使用 Xcode 26.5 / Swift 6：NSNumber 的定型构造器 init(integer:)/init(int:) 已被重命名为 init(value:)，而当前 UTS 转译器无法生成 init(value:)；index.uts 统一用 as NSNumber 桥接转型传 number 回调（如 code.rawValue as NSNumber、(-1) as NSNumber、ret as NSNumber），避免任何被判名的 NSNumber 构造器。涉及 14 处回调/返回值。详见插件内 iOS云打包NSNumber编译问题总结.md。

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

SDK 冲突（重要）：插件 SDK 与内置 live 模块并存方案

本插件自带腾讯云 MLVB SDK（LiteAVSDK_Live_13.5.0.20670.aar，含 com.tencent.rtmp / com.tencent.liteav / com.tencent.ugc 与 libliteavsdk.so）。uni-app App 内置的 LivePusher / LivePlayer 模块同样内嵌同一份腾讯 LiteAV SDK（weex_livepusher），若插件把 aar 直接打包进 APK，会触发 checkReleaseDuplicateClasses（重复类）与 mergeReleaseNativeLibs（重复 libliteavsdk.so）编译失败。

当前方案（SDK 独占，讲师开播推流的必要条件）：插件 aar 位于 utssdk/app-android/libs/，以 implementation 打包进 APK，作为腾讯 LiteAV SDK 的唯一来源；宿主 manifest.json 必须关闭内置 LivePusher / LivePlayer 模块（本项目已关闭）。关闭后 App 端内置 <live-pusher> 不可用——讲师开播已改由本插件 createTxLivePusher 原生推流替代，播放与微信小程序端不受影响。

• 优点：插件推流/播放不依赖基座内置模块，行为确定（不再受部分基座 live-pusher 不自动起流等问题影响）；采集与推流时序完全自控。
• 若宿主确需保留内置 LivePusher/LivePlayer 模块（如仍有其他页面用内置组件），则须改用 1.0.4 的 compileOnly 方案（aar 移至 compileOnlyLibs/ + build.gradle 以 compileOnly 引用，运行时复用基座 SDK），但该方案下插件推流与内置组件共享同一份底层 SDK 实例，须自行评估并存风险。

更新日志

v1.1.0 (2026-09-20)

1. 新增讲师开播推流：三端封装 MLVB V2TXLivePusher，API：createTxLivePusher / stopTxLivePush / switchTxCamera / enableTxCamera / muteTxPushAudio / destroyTxLivePusher
2. iOS：V2TXLivePusherObserver 用 implements + @argumentLabel 精确匹配 selector；V2TXLivePusher 用指定构造器 initWithLiveMode:（new/init 被 NS_UNAVAILABLE）
3. Android：V2TXLivePusherImpl(context, V2TXLiveMode.RTMP) + 抽象类 Observer（extends + override）
4. aar 回归 libs/ 独占打包，宿主 manifest 须关闭内置 LivePusher/LivePlayer（本项目已关闭）

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