更新记录

0.1.0（2026-06-26）

初版发布

平台兼容性

uni-app x(4.87)

ff-vlc-video-player

基于 VideoLAN libVLC / MobileVLCKit 的 uni-app x UTS 视频播放器插件。

特性

• ✅ 多协议支持：RTSP / RTMP / HTTP / HTTPS / HLS(m3u8) / 本地文件
• ✅ 原生渲染：Android VLCVideoLayout + TextureView，iOS VLCMediaPlayer.drawable
• ✅ 播放控制：播放/停止/暂停/恢复/跳转(时间&进度)
• ✅ 高级功能：倍速、音量、画面缩放模式、宽高比
• ✅ 录制功能：Android/iOS 均支持录制到本地
• ✅ 抓图功能：iOS 原生支持；Android 通过 TextureView 位图实现
• ✅ 事件回调：播放状态、进度、错误事件回调

平台依赖

⚠️ 重要提示

• Android 引入原生依赖需提交云端打包生成自定义基座后生效
• iOS 真机运行需 Mac 安装 Xcode + CocoaPods；Windows 或无 Xcode 环境需云打包自定义基座

Android 权限

插件自动申请以下权限：

安装

将 ff-vlc-video-player 目录放置于项目的 uni_modules/ 目录下。

使用方式

方式一：组件方式（推荐）

<template>
  <view style="flex:1;">
    <ff-vlc-video-player
      ref="player"
      url="rtsp://192.168.1.100:554/stream"
      :auto-play="true"
      :options="{ networkCaching: 3000, rtspTcp: true }"
      @state-change="onStateChange"
      @time-change="onTimeChange"
      @error="onError"
    />
  </view>
</template>

<script setup lang="uts">
const player = ref()

// 状态变化回调
function onStateChange(e: VlcStateChangeEvent): void {
  console.log('播放状态:', e.state)
}

// 进度变化回调
function onTimeChange(e: VlcTimeChangeEvent): void {
  console.log('当前时间:', e.time, '总时长:', e.duration)
}

// 错误回调
function onError(e: VlcErrorEvent): void {
  console.log('播放错误:', e.message)
}

// 调用组件方法
function handleStop(): void {
  player.value?.stop()
}

function handleSeek(): void {
  player.value?.seekTo(30000) // 跳转到30秒
}
</script>

方式二：Context API 方式

<template>
  <view style="flex:1;">
    <ff-vlc-video-player ref="player" />
  </view>
</template>

<script setup lang="uts">
import { createVlcVideoPlayerContext, IVlcVideoPlayerContext } from '@/uni_modules/ff-vlc-video-player'

const player = ref()
let ctx: IVlcVideoPlayerContext | null = null

onReady(() => {
  ctx = createVlcVideoPlayerContext('player', getCurrentInstance().proxy)
  if (ctx != null) {
    ctx!.onStateChange((e) => { console.log('状态:', e.state) })
    ctx!.onTimeChange((e) => { console.log('进度:', e.time) })
    // 开始播放
    ctx!.play('rtsp://192.168.1.100:554/stream', { networkCaching: 5000 })
  }
})

onUnmounted(() => {
  ctx?.destroy()
})
</script>

组件 Props

组件 Events

组件 Methods（通过 ref 调用）

播放选项 VlcMediaOptions

播放器状态 VlcPlayerState

画面缩放模式 VlcScaleType

错误码

Context API（IVlcVideoPlayerContext）

通过 createVlcVideoPlayerContext(id, component) 获取播放器上下文实例，支持以下方法：

播放控制

// 播放网络流
ctx.play('rtsp://...', { networkCaching: 5000 })

// 播放本地文件
ctx.playFile('/path/to/video.mp4')

// 停止/暂停/恢复
ctx.stop()
ctx.pause()
ctx.resume()

// 跳转
ctx.seekTo(30000)       // 跳转到30秒
ctx.seekToPosition(0.5) // 跳转到50%位置

播放参数

// 倍速播放
ctx.setRate(2.0) // 2倍速

// 音量控制
ctx.setVolume(50)    // 设置音量50%
ctx.enableAudio(false) // 静音

画面控制

// 缩放模式
ctx.setScaleType('R16_9')

// 宽高比
ctx.setAspectRatio('16:9')
ctx.setAspectRatio(null) // 还原默认

信息获取

const duration = ctx.getDuration()    // 总时长(毫秒)
const time = ctx.getCurrentTime()     // 当前时间(毫秒)
const position = ctx.getPosition()    // 进度比例(0~1)
const playing = ctx.isPlaying()       // 是否播放中

录制与抓图

// 开始录制
ctx.startRecord('/path/to/record/dir')
ctx.stopRecord()

// 抓图
ctx.screenshot('/path/to/screenshot.jpg')

事件监听

// 注册回调
ctx.onStateChange((e) => { console.log('状态:', e.state) })
ctx.onTimeChange((e) => { console.log('时间:', e.time) })
ctx.onPositionChange((e) => { console.log('位置:', e.position) })
ctx.onError((e) => { console.log('错误:', e.message) })

// 取消回调
ctx.offStateChange()
ctx.offTimeChange()
ctx.offPositionChange()
ctx.offError()

// 释放资源
ctx.destroy()

常见问题

Q: Android 云打包后播放失败？

确保在 HBuilderX 中正确提交云打包，选择「使用原生插件」选项，并等待自定义基座生成完成后再运行。

Q: RTSP 播放花屏/卡顿？

尝试增大 networkCaching 值（如 5000ms），并确保 rtspTcp: true 以使用 TCP 协议降低丢包：

ctx.play('rtsp://...', { networkCaching: 5000, rtspTcp: true })

Q: iOS 真机调试报错？

确保 Mac 已安装 Xcode 和 CocoaPods，并执行 pod install 后再运行。

Q: 录制文件找不到？

录制功能需要应用有存储权限，且传入的目录路径必须存在。建议使用应用私有目录：

// Android
const recordDir = `${uni.env.USER_DATA_PATH}/record`

// iOS
const recordDir = `${uni.env.USER_DATA_PATH}/record`

相关链接

• VideoLAN libVLC Android
• MobileVLCKit iOS
• libVLC 文档

版本历史

许可证

本插件基于 libVLC，遵循 LGPL v2.1 许可证。