更新记录

1.0.0（2025-12-23）

首发

平台兼容性

uni-app(4.85)

uni-app x(4.85)

UTS环境兼容性

sn-tx-player

这是一个基于腾讯云视立方播放器 SDK 的 UniApp UTS 原生插件，支持 iOS 和 Android 平台。

功能特性

模块功能 (SnTxPlayerModule)

• License 授权管理
• 缓存配置
• 视频预下载管理

组件功能 (SnTxPlayerComponent)

• 视频播放控制
• 播放状态监听
• 网络状态监控
• 画面调整
• 变速播放
• 硬件加速
• 码率切换
• 精确跳转

字幕组件功能 (SnTxPlayerSubtitleComponent)

• 字幕显示支持
• 自动关联播放器组件
• 支持内嵌字幕和外挂字幕

安装配置

1. 添加插件到项目

• 将 uni_modules/sn-tx-player 添加到项目中。

2. 获取 License

在 腾讯云视立方控制台 获取 License URL 和 License Key。

使用方法

App.vue 导入

import * as Tx from '@/uni_modules/sn-tx-player'

初始化 License

const txPlayerModule = uni.requireNativePlugin('tx-player');

// 设置 License
txPlayerModule.setLicence('YOUR_LICENSE_URL', 'YOUR_LICENSE_KEY', (result) => {
  console.log('License 设置结果:', result);
  // result: { result: 0, reason: "success" }
});

// 获取 License 信息
txPlayerModule.getLicenceInfo((info) => {
  console.log('License 信息:', info);
});

缓存配置

// 设置缓存文件夹路径
txPlayerModule.setCacheFolderPath('/path/to/cache');

// 设置最大缓存大小 (MB)
txPlayerModule.setMaxCacheSize(500);

视频预下载

// 设置预下载回调
txPlayerModule.onPreDownloadCallback((event) => {
  console.log('预下载事件:', event);
  // event: { event: "start|complete|error", data: {...} }
});

// 开始预下载
// 参数: url(视频URL), maxSize(最大预下载大小MB), preferredResolution(期望分辨率)
txPlayerModule.startPreload('VIDEO_URL', 100, 720);

// 停止预下载
txPlayerModule.stopPreload(taskId);

使用播放器组件

<template>
  <view>
    <tx-player-view 
      ref="player"
      :autoPlay="false"
      @created="onCreated"
      @playevent="onPlayEvent"
      @netstatus="onNetStatus"
    >
      <!-- 字幕组件 -->
      <tx-player-subtitle-view />
    </tx-player-view>
    <button @click="startPlay">开始播放</button>
    <button @click="pause">暂停</button>
    <button @click="resume">恢复</button>
  </view>
</template>

<script>
export default {
  methods: {
    onCreated() {
      console.log('播放器创建完成');
    },

    startPlay() {
      const player = this.$refs.player;
      // 方式1: 直接播放URL
      player.startPlay('https://example.com/video.mp4');

      // 方式2: 使用fileId方式播放
      player.startPlayWithParams({
        appId: 123456789,
        fileId: 'your_file_id',
        sign: 'your_sign'
      });
    },

    pause() {
      const player = this.$refs.player;
      player.pause();
    },

    resume() {
      const player = this.$refs.player;
      player.resume();
    },

    onPlayEvent(event) {
      console.log('播放事件:', event);
      // event.detail: { event: 事件码, param: 参数对象 }
    },

    onNetStatus(status) {
      console.log('网络状态:', status);
      // status.detail: { param: 状态参数对象 }
    }
  }
}
</script>

API 详细说明

SnTxPlayerModule API

License 管理

• setLicence(url: String, key: String, callback: Function) - 设置 License

  • url: License URL
  • key: License Key
  • callback: 回调函数，返回 {result: 0, reason: "success"}

• getLicenceInfo(callback: Function) - 获取 License 信息

  • callback: 回调函数，返回 License 信息对象

缓存配置

• setCacheFolderPath(path: String) - 设置缓存文件夹路径
• setMaxCacheSize(size: Number) - 设置最大缓存大小(MB)

预下载管理

• onPreDownloadCallback(callback: Function) - 设置预下载回调

  • 回调事件: start, complete, error
  • 数据格式: {event: "事件类型", data: {...}}

• startPreload(url: String, maxSize: Number, preferredResolution: Number) - 开始预下载

  • url: 视频URL
  • maxSize: 最大预下载大小(MB)
  • preferredResolution: 期望分辨率

• stopPreload(taskId: Number) - 停止预下载

  • taskId: 预下载任务ID

SnTxPlayerSubtitleComponent API

字幕组件会自动查找父级的播放器组件并设置字幕视图，无需手动调用方法。

使用方式

<tx-player-view ref="player">
  <tx-player-subtitle-view />
</tx-player-view>

字幕相关方法 (在播放器组件中调用)

• setSubtitleStyle(params: Object) - 设置字幕样式

  • params.fontSize: 字体大小
  • params.fontColor: 字体颜色
  • params.backgroundColor: 背景颜色
  • params.backgroundOpacity: 背景透明度
  • params.fontOpacity: 字体透明度
  • params.fontFamily: 字体族
  • params.borderWidth: 边框宽度
  • params.borderColor: 边框颜色
  • params.borderOpacity: 边框透明度
  • params.startMargin: 开始边距
  • params.endMargin: 结束边距
  • params.verticalMargin: 垂直边距

• getSubtitleTrackInfo(callback: Function) - 获取字幕轨道信息

  • 返回: [{trackType, trackIndex, name, isSelected, isExclusive, isInternal}]

• selectTrack(index: Number) - 选择字幕轨道

• deselectTrack(index: Number) - 取消选择字幕轨道

SnTxPlayerComponent API

播放控制

• startPlay(url: String) - 开始播放URL视频

• startPlayWithParams(params: Object) - 使用fileId方式播放

  • params.appId: 应用ID
  • params.fileId: 文件ID
  • params.sign: 签名

• stopPlay() - 停止播放(清除最后一帧画面)

• pause() - 暂停播放

• resume() - 恢复播放

• seek(time: Number) - 跳转到指定时间(秒)

• seekAccurate(time: Number, accurateSeek: Boolean) - 精确跳转

• seekToPdtTime(time: Number) - 跳转到PDT时间(毫秒)

• setStartTime(startTime: Number) - 设置开始播放时间(秒)

播放设置

• enableHWAcceleration(enable: Boolean) - 启用硬件加速
• setMute(mute: Boolean) - 设置静音
• setRate(rate: Number) - 设置播放速率
• setLoop(loop: Boolean) - 设置循环播放
• setRenderMode(mode: Number) - 设置渲染模式
• setRenderRotation(rotation: Number) - 设置旋转角度
• setAutoPlay(autoPlay: Boolean) - 设置自动播放

播放器配置

• setConfig(params: Object) - 设置播放器配置
  • params.maxBufferSize: 最大缓冲大小
  • params.maxPreloadSize: 最大预加载大小
  • params.progressInterval: 进度回调间隔
  • params.enableAccurateSeek: 启用精确跳转
  • params.preferredResolution: 期望分辨率
  • params.smoothSwitchBitrate: 平滑切换码率
  • params.mediaType: 媒体类型
  • params.headers: 请求头

状态获取

• isPlaying(callback: Function) - 检查是否正在播放
• getCurrentPlaybackTime(callback: Function) - 获取当前播放时间(秒)
• getDuration(callback: Function) - 获取视频总时长(秒)
• getPlayableDuration(callback: Function) - 获取可播放时长(秒)

码率管理

• getSupportedBitrates(callback: Function) - 获取支持的码率列表
  • 返回: [{index: 码率下标, bitrate: 码率, width: 宽度, height: 高度}]
• getBitrateIndex(callback: Function) - 获取当前码率索引
• setBitrateIndex(index: Number) - 设置码率索引

事件说明

播放器创建事件 (created)

通过 @created 监听，播放器创建完成时触发。

播放事件 (playevent)

通过 @playevent 监听，事件数据格式：

{
  detail: {
    event: 事件码,
    param: 参数对象
  }
}

主要事件码：

• 2003 - 网络接收到首个可渲染的视频数据包（IDR）
• 2004 - 开始播放
• 2005 - 播放进度
• 2006 - 播放结束
• 2007 - 播放进度（另一种格式）
• 2008 - 加载中
• 2013 - 播放器准备完成

网络状态 (netstatus)

通过 @netstatus 监听，状态数据格式：

{
  detail: {
    param: 状态参数对象
  }
}

主要状态参数：

• CPU_USAGE - CPU 使用率
• VIDEO_WIDTH - 视频宽度
• VIDEO_HEIGHT - 视频高度
• NET_SPEED - 网络速度
• VIDEO_FPS - 视频帧率
• VIDEO_BITRATE - 视频码率
• AUDIO_BITRATE - 音频码率

字幕数据事件 (subtitledata)

通过 @subtitledata 监听，字幕数据格式：

{
  trackIndex: 轨道索引,
  subtitleData: 字幕内容,
  startPositionMs: 开始时间(毫秒),
  durationMs: 持续时间(毫秒)
}

预下载事件

通过 onPreDownloadCallback 监听：

{
  event: "start|complete|error",
  data: {
    taskID: 任务ID,
    url: 视频URL,
    code: 错误码(仅error事件),
    msg: 错误信息(仅error事件)
  }
}

完整使用示例

<template>
  <view class="container">
    <tx-player-view 
      ref="player"
      :autoPlay="false"
      @created="onCreated"
      @playevent="onPlayEvent"
      @netstatus="onNetStatus"
      @subtitledata="onSubtitleData"
    >
      <!-- 字幕组件 -->
      <tx-player-subtitle-view />
    </tx-player-view>

    <view class="controls">
      <button @click="startPlay">开始播放</button>
      <button @click="pause">暂停</button>
      <button @click="resume">恢复</button>
      <button @click="stopPlay">停止</button>
      <button @click="seek">跳转到30秒</button>
      <button @click="setMute">静音切换</button>
      <button @click="setRate">2倍速</button>
    </view>

    <view class="info">
      <text>播放时间: {{currentTime}}s</text>
      <text>总时长: {{duration}}s</text>
      <text>播放状态: {{isPlaying ? '播放中' : '已停止'}}</text>
    </view>
  </view>
</template>

<script>
export default {
  data() {
    return {
      currentTime: 0,
      duration: 0,
      isPlaying: false
    }
  },

  mounted() {
    this.initPlayer();
  },

  methods: {
    initPlayer() {
      const txPlayerModule = uni.requireNativePlugin('tx-player');

      // 设置License
      txPlayerModule.setLicence('YOUR_LICENSE_URL', 'YOUR_LICENSE_KEY', (result) => {
        console.log('License设置结果:', result);
      });

      // 配置缓存
      txPlayerModule.setCacheFolderPath('/storage/emulated/0/Android/data/cache');
      txPlayerModule.setMaxCacheSize(500);

      // 设置预下载回调
      txPlayerModule.onPreDownloadCallback((event) => {
        console.log('预下载事件:', event);
      });
    },

    onCreated() {
      console.log('播放器创建完成');
    },

    startPlay() {
      const player = this.$refs.player;

      // 配置播放器
      player.setConfig({
        maxBufferSize: 10,
        maxPreloadSize: 10,
        progressInterval: 1000,
        enableAccurateSeek: true,
        preferredResolution: 720,
        smoothSwitchBitrate: true
      });

      // 启用硬件加速
      player.enableHWAcceleration(true);

      // 开始播放
      player.startPlay('https://example.com/video.mp4');
    },

    pause() {
      this.$refs.player.pause();
    },

    resume() {
      this.$refs.player.resume();
    },

    stopPlay() {
      this.$refs.player.stopPlay();
    },

    seek() {
      this.$refs.player.seekAccurate(30, true);
    },

    setMute() {
      this.$refs.player.setMute(true);
    },

    setRate() {
      this.$refs.player.setRate(2.0);
    },

    onPlayEvent(event) {
      const { event: eventCode, param } = event.detail;

      switch(eventCode) {
        case 2004: // 开始播放
          console.log('开始播放');
          this.isPlaying = true;
          break;
        case 2006: // 播放结束
          console.log('播放结束');
          this.isPlaying = false;
          break;
        case 2005: // 播放进度
        case 2007: // 播放进度
          this.currentTime = param.progress || (param.EVT_PLAY_PROGRESS_MS / 1000) || 0;
          break;
        case 2008: // 加载中
          console.log('加载中...');
          break;
        case 2013: // 播放器准备完成
          this.$refs.player.getDuration((duration) => {
            this.duration = duration;
          });
          break;
      }
    },

    onNetStatus(status) {
      const { param } = status.detail;
      console.log('网络状态:', param);
    },

    onSubtitleData(data) {
      console.log('字幕数据:', data);
      // data: { trackIndex, subtitleData, startPositionMs, durationMs }
    }
  }
}
</script>

注意事项

1. License 配置: 确保已正确配置 License，否则播放器无法正常工作
2. 权限配置:
   • iOS 平台需要配置网络访问权限
   • Android 平台需要确保网络权限已添加
3. 资源管理: 建议在组件销毁时调用 stopPlay() 方法释放资源
4. 码率切换: 只有在收到 2013 事件（播放器准备完成）后才能获取支持的码率
5. 预下载: 预下载功能需要先设置回调函数才能正常工作
6. 硬件加速: 建议在播放前启用硬件加速以提升性能
7. 字幕支持: 字幕组件需要作为播放器组件的子组件使用，会自动关联到播放器
8. 字幕轨道: 只有在视频加载完成后才能获取字幕轨道信息
9. 组件名称: 播放器组件名称为 tx-player-view，字幕组件名称为 tx-player-subtitle-view
10. 触摸组件: 如需处理触摸事件，可使用 tx-player-touch 组件包裹需要响应触摸的元素

参考文档

• 腾讯云播放器 SDK 文档
• UniApp 原生插件开发指南