更新记录

1.0.0（2026-06-14）

发布1.0.0，基于腾讯云直播推拉流SDK封装的直播推流与拉流组件

平台兼容性

uni-app x(4.87)

jinyu-txlive

jinyu-txlive 是基于腾讯云 LiteAVSDK Live / V2TXLive 封装的 uni-app x UTS 原生组件插件，提供推拉流直播播放和直播推流能力。

插件当前包含两个可直接在页面中使用的组件：

• txlive-player：直播播放组件，底层封装 V2TXLivePlayer
• txlive-pusher：直播推流组件，底层封装 V2TXLivePusher

同时提供 API：

• installTxLive(licenceURL, licenceKey)：初始化腾讯云直播 License
• requestPusherPermissions(onGranted)：申请推流需要的相机和麦克风权限
• createPlayerContent(element)：创建播放器原生对象，通常由组件内部使用
• createPusherContent(element)：创建推流器原生对象，通常由组件内部使用

平台支持

初始化 License

使用播放或推流前，先调用 installTxLive 设置腾讯云直播 License。

建议在 App.uvue、应用启动页，或直播页面进入前执行一次。

import { installTxLive } from '@/uni_modules/jinyu-txlive'

installTxLive(
  '你的 licenceURL',
  '你的 licenceKey'
)

说明：

• onLicenceLoaded 中 result == 0 表示 License 加载成功，非 0 表示失败
• License 参数为空时，插件会直接返回，不会调用 SDK 初始化

播放直播

页面中使用 txlive-player 组件，并通过 ref 调用播放方法。

<template>
  <view class="page">
    <txlive-player
      ref="playerRef"
      class="player"
      :keep-screen-always-on="true"
      @event="onPlayerEvent"
    />

    <button class="button" @click="startPlay">开始播放</button>
    <button class="button" @click="stopPlay">停止播放</button>
  </view>
</template>

<script setup lang="uts">
  import { installTxLive } from '@/uni_modules/jinyu-txlive'
  import { TxLiveEvent } from '@/uni_modules/jinyu-txlive/utssdk/interface.uts'

  const playerRef = ref<any | null>(null)
  const playUrl = 'https://example.com/live.flv'

  installTxLive('你的 licenceURL', '你的 licenceKey')

  const startPlay = () : void => {
    playerRef.value?.startLivePlay(playUrl)
  }

  const stopPlay = () : void => {
    playerRef.value?.stopPlay()
  }

  const onPlayerEvent = (event : TxLiveEvent) : void => {
    console.log('player event: ' + event.type)
    if (event.type == 'error') {
      console.log('播放错误 code=' + event.code + ' msg=' + event.msg)
    }
  }
</script>

<style>
  .page {
    flex: 1;
    flex-direction: column;
  }
  .player {
    width: 100%;
    height: 420px;
  }
  .button {
    margin-top: 16px;
  }
</style>

播放器方法

setRenderFillMode(model) 参数说明：

• 0：Fill，铺满容器，可能裁剪画面
• 1：Fit，完整显示，可能有黑边
• 2：ScaleFill，拉伸铺满

推流直播

推流前建议先申请相机和麦克风权限。

<template>
  <view class="page">
    <txlive-pusher
      ref="pusherRef"
      class="pusher"
      :keep-screen-always-on="true"
      @event="onPusherEvent"
    />

    <button class="button" @click="startPush">开始推流</button>
    <button class="button" @click="stopPush">停止推流</button>
    <button class="button" @click="switchCamera">切换摄像头</button>
  </view>
</template>

<script setup lang="uts">
  import { installTxLive, requestPusherPermissions } from '@/uni_modules/jinyu-txlive'
  import { TxLiveEvent } from '@/uni_modules/jinyu-txlive/utssdk/interface.uts'

  const pusherRef = ref<any | null>(null)
  const pushUrl = 'rtmp://example.com/live/stream'

  installTxLive('你的 licenceURL', '你的 licenceKey')

  const startPush = () : void => {
    requestPusherPermissions(() : void => {
      pusherRef.value?.startCamera(0)
      pusherRef.value?.startMicrophone()
      pusherRef.value?.startPush(pushUrl)
    })
  }

  const stopPush = () : void => {
    pusherRef.value?.stopPush()
    pusherRef.value?.stopCamera()
    pusherRef.value?.stopMicrophone()
  }

  const switchCamera = () : void => {
    pusherRef.value?.switchCamera(null)
  }

  const onPusherEvent = (event : TxLiveEvent) : void => {
    console.log('pusher event: ' + event.type)
    if (event.type == 'error') {
      console.log('推流错误 code=' + event.code + ' msg=' + event.msg)
    }
  }
</script>

<style>
  .page {
    flex: 1;
    flex-direction: column;
  }
  .pusher {
    width: 100%;
    height: 420px;
  }
  .button {
    margin-top: 16px;
  }
</style>

推流器方法

事件回调

txlive-player 和 txlive-pusher 都通过 @event 向页面派发事件。

事件类型定义：

export type TxLiveEvent = {
  type : string,
  code ?: number,
  msg ?: string,
  descriptionInfo ?: string,
  data ?: UTSJSONObject
}

播放事件

推流事件

返回值说明

大多数方法直接返回腾讯云 V2TXLive SDK 的状态码。

插件额外约定：

• 0：调用成功或当前状态无需重复操作
• -1：传入参数为空，例如播放地址或推流地址为空
• -999：原生播放器或推流器对象尚未创建，通常是组件还没有触发 native-view @init

如果调用方法返回 -999，通常需要确认：

• 组件是否已经渲染
• 是否通过 ref 在组件初始化后调用方法
• 播放器或推流器是否已经被 destroy()

权限与打包配置

Android

插件会通过 requestPusherPermissions 申请：

• android.permission.CAMERA
• android.permission.RECORD_AUDIO

Android 最低版本为 minSdkVersion 21。

iOS

iOS 推流需要相机和麦克风权限。请确保项目配置了权限描述：

• NSCameraUsageDescription
• NSMicrophoneUsageDescription

iOS 最低版本为 12.0。

生命周期建议

播放页面离开时建议停止播放或销毁播放器：

onUnload(() => {
  playerRef.value?.destroy()
})

推流页面离开时建议停止推流、关闭摄像头和麦克风：

onUnload(() => {
  pusherRef.value?.destroy()
})

组件默认 keepScreenAlwaysOn = true，页面加载时会保持屏幕常亮状态，卸载时会自动恢复屏幕常亮状态。

常见问题

1. 为什么调用播放或推流返回 -999？

说明原生对象还没有创建。

播放器组件已支持 startLivePlay 的延迟播放：如果初始化前调用，会先缓存播放地址，初始化完成后自动播放。其他方法建议在页面渲染完成后调用。

2. License 加载成功怎么判断？

onLicenceLoaded(result, reason) 中 result == 0 表示成功，非 0 表示失败。失败时请检查 licenceURL、licenceKey、包名或 Bundle ID 是否和腾讯云控制台配置一致。

3. 直播播放成功应该看哪个事件？

建议以 videoPlaying 作为视频真正开始渲染的判断依据。connected 只表示连接建立，不代表已经有视频画面。

4. 推流前必须调用哪些方法？

普通摄像头推流的推荐顺序：

1. installTxLive
2. requestPusherPermissions
3. startCamera
4. startMicrophone
5. startPush

停止推流的推荐顺序：

1. stopPush
2. stopCamera
3. stopMicrophone
4. destroy

参考文档

• 腾讯云直播 推拉流SDK 文档