更新记录

1.0.0（2026-09-05）

无

平台兼容性

uni-app(4.62)

uni-app x(5.21)

tencentcloud-liteav · 腾讯云直播（推流 / 拉流）UTS 插件

基于 腾讯云 LiteAVSDK_Live（V2TXLive） 二次封装的 uni-app UTS 组件插件（uni-app 兼容模式，面向 nvue 页面）。 提供「主播推流」与「观众拉流」两个全局组件，开箱即用，一套代码双端（Android / iOS）运行。

特性

• �� 直播推流：RTMP 推流、自动开相机/麦克风、切前后摄、闪光灯、美颜、静音
• �� 直播拉流：FLV / RTMP / LEB(WebRTC) 播放、暂停/恢复、铺满/完整切换、静音
• ⚡ 事件驱动：所有结果（成功/失败/状态/网速）都通过 @statechange / @netstatus 回调，任何操作必有回调（含 SDK 同步失败的主动 error 上报）
• �� 轻量精简：使用直播专用 LiteAVSDK_Live（Android aar ≈24MB / iOS CocoaPods），体积远小于全功能 Professional 版
• �� 纯 UTS：无 requireNativePlugin 依赖、无遗留 JS 桥接，直接编译为原生（Kotlin / Swift）

目录结构

uni_modules/tencentcloud-liteav/
├── package.json                     # 插件清单（HBuilderX >= 3.6.18）
├── index.uts                        # 插件根入口（页面 import 到这里）
├── readme.md                        # 本文档
└── utssdk/
    ├── interface.uts                # 跨端能力声明（License 参数类型等）
    ├── index.uts                    # 跨端入口：setLicence（按平台派发）
    ├── app-android/
    │   ├── config.json              # minSdk 21 / abis(arm64-v8a, armeabi-v7a)
    │   ├── AndroidManifest.xml      # 相机/麦克风/网络等权限声明
    │   ├── index.uts                # Android setLicence 实现
    │   ├── index.vue                # ★ 推流组件 <tencentcloud-pusher>
    │   ├── tencentcloud-player.vue  # 拉流组件 <tencentcloud-player>
    │   └── libs/LiteAVSDK_Live_*.aar# 直播精简 SDK（双 ABI so）
    └── app-ios/
        ├── config.json              # deploymentTarget 11.0 / arm64 / CocoaPods TXLiteAVSDK_Live
        ├── info.plist               # 相机/麦克风权限用途描述
        ├── index.uts                # iOS setLicence 实现
        ├── index.vue                # ★ 推流组件 <tencentcloud-pusher>
        └── tencentcloud-player.vue  # 拉流组件 <tencentcloud-player>

环境要求

一、快速接入

1. 安装插件

将 uni_modules/tencentcloud-liteav 目录放入项目 uni_modules/ 下（HBuilderX 导入本地插件目录亦可）。

2. 申请 License

腾讯云控制台 → 云直播/移动直播 → 申请（或测试）License，得到一对：

• licenseUrl（形如 https://xxx/license/v2/<AppId>_1/v_cube.license）
• licenseKey

⚠️ License 按应用包名绑定：Android 绑 applicationId、iOS 绑 Bundle ID。调试基座的包名也必须与 License 绑定的包名一致，否则推/拉流返回 -5。

3. 注册 License（推/拉流前调用一次）

// 建议放 App.vue onLaunch；也可在页面 startPush/startPlay 前调用
import { setLicence } from '@/uni_modules/tencentcloud-liteav'

setLicence({
    licenseUrl: 'https://your.license.url/v_cube.license',
    licenseKey: 'your-license-key'
})

⚠️ setLicence 只是「注册」，同步返回、不做校验。License 是否有效，以首次 startPush/startPlay 的返回（@statechange 事件）为准：收到 error code=-5 即为「License 无效或包名不匹配」。

4. 相机 / 麦克风权限

• Android：插件已声明权限；运行期需页面主动请求运行时权限。App 端不能使用 uni.authorize（仅小程序端支持），请用 plus.android.requestPermissions(['android.permission.CAMERA','android.permission.RECORD_AUDIO'], cb, err)（详见下方示例）。
• iOS：插件 info.plist 已含用途描述，首次推流时系统自动弹框授权；若曾被拒绝，需在 系统设置 → 隐私与安全性 → 相机/麦克风 手动开启。

5. 自定义基座（必须）

UTS 插件编译为原生代码，标准基座不含，调试/打包必须走自定义基座：

• 调试：HBuilderX → 运行 → 运行到手机或模拟器 → 制作自定义调试基座
• 发布：云打包 / 离线打包（自动携带插件原生代码）

二、页面使用（nvue）

组件为 uni-app 兼容模式 UTS 组件，全局注册，模板直接使用标签；必须设置宽高。示例（推流 + 观看同页）：

<template>
    <view>
        <!-- 主播推流 -->
        <tencentcloud-pusher ref="pusher" style="width:750rpx;height:420rpx;background:#000;"
            @statechange="onPushState" @netstatus="onPushNet" />
        <button @click="start">开始推流</button>
        <button @click="stop">停止</button>
        <button @click="camera">切换摄像头</button>

        <!-- 观众观看 -->
        <tencentcloud-player ref="player" style="width:750rpx;height:420rpx;background:#000;"
            @statechange="onPlayState" @netstatus="onPlayNet" />
        <button @click="play">开始播放</button>
    </view>
</template>

<script>
import { setLicence } from '@/uni_modules/tencentcloud-liteav'

export default {
    onLoad() {
        setLicence({ licenseUrl: 'https://.../v_cube.license', licenseKey: '...' })
        // #ifdef APP-ANDROID
        plus.android.requestPermissions(
            ['android.permission.CAMERA', 'android.permission.RECORD_AUDIO'],
            () => {}, () => {}
        )
        // #endif
    },
    methods: {
        start()  { this.$refs.pusher.startPush('rtmp://推流域名/live/streamKey') },
        stop()   { this.$refs.pusher.stopPush() },
        camera() { this.$refs.pusher.switchCamera() },
        play()   { this.$refs.player.startPlay('https://拉流域名/live/stream.flv') },

        onPushState(e) { /* e: Map<string,any>，见下方事件说明 */ },
        onPushNet(e)   { /* 实时推流网络状态 */ },
        onPlayState(e) { /* e: Map<string,any> */ },
        onPlayNet(e)   { /* 实时播放网络状态 */ }
    }
}
</script>

三、API 一览

setLicence(options)

注册腾讯云直播 License（全局，App 生命周期内调用一次即可）。

tencentcloud-pusher（推流组件）

tencentcloud-player（拉流组件）

组件方法均无回调：结果统一通过下方事件返回。

四、事件说明

事件载荷为 Map<string, any>，页面可用 .get(key) 读取；若拿到的是 {detail:…} 或普通对象（不同端桥接差异），请做一次归一化：e.detail ?? e（Map 则 forEach 展开）。

@statechange（状态/结果，必看）

推流端 type：

播放端 type：

@netstatus（实时网络状态）

字段：fps、videoBitrate、audioBitrate、rtt、netSpeed、appCpu、systemCpu、width、height。

五、常见问题 FAQ

六、版本记录

兼容与许可

• 插件内嵌腾讯云 LiteAVSDK_Live，其能力与合规要求遵循腾讯云移动直播官方条款
• 使用前请在腾讯云开通/绑定 License，正式商用需购买相应套餐
• 支持 uni-app（Vue2/Vue3 编译器均可，nvue 页面）；如需 uni-app x（uvue）支持请联系作者适配