更新记录

0.1.0（2026-08-10）

初始化版本

平台兼容性

uni-app(4.45)

其他

yt-uts-vlc

基于 LibVLC 的 Android App 内嵌播放器组件，支持 RTSP、HTTP-FLV、M3U8、RTMP 及常见 HTTP 视频地址。

平台支持

• Android App：支持 vlcOptions、mediaOptions、statuschange 和原生 loading。
• iOS App：支持 vlcOptions、mediaOptions、statuschange 和原生 loading，基于 MobileVLCKit 3.6.0。
• H5、小程序、鸿蒙：不支持。

Android 需要使用包含 LibVLC 依赖的自定义基座，最低 Android 版本为 5.0（API 21）。

基本使用

<template>
  <yt-uts-vlc
    ref="vlc"
    class="player"
    :play="videoUrl"
    :vlcOptions="vlcOptions"
    :mediaOptions="mediaOptions"
    @statuschange="onStatusChange" />
</template>

<script>
export default {
  data() {
    return {
      videoUrl: 'rtsp://example.com/live',
      vlcOptions: [
        '--avcodec-hw=any',
        '--drop-late-frames',
        '--skip-frames'
      ],
      mediaOptions: [
        ':rtsp-tcp',
        ':network-caching=300',
        ':live-caching=300',
        ':rtsp-caching=300',
        ':rtsp-frame-buffer-size=1000000'
      ]
    }
  },
  methods: {
    onStatusChange(event) {
      const detail = event && event.detail ? event.detail : event
      const status = detail && detail.get ? detail.get('status') : detail.status
      console.log('VLC status:', status)
    }
  }
}
</script>

<style>
.player {
  width: 750rpx;
  height: 422rpx;
}
</style>

设置 play 属性会自动开始播放。切换地址时直接更新 videoUrl，不要在同一时刻再调用 setUrl()，否则会重复建连。

属性

vlcOptions 在播放器首次初始化时生效。修改它后需要销毁并重新创建组件，或调用 destroyPlayer() 后重新进入页面。

mediaOptions 会在每次切换播放地址时应用，可按 RTSP、FLV、M3U8 等协议切换不同配置。

两个数组均为空时，Android 实现会使用内置的兼容默认参数。生产环境建议始终显式传入协议对应的 mediaOptions，避免将 RTSP 默认项应用到 FLV 或 M3U8。

方法

通过 ref 调用：

状态回调

使用 @statuschange 接收播放器状态：

回调数据包含：

{
  status: 'videooutput',
  eventType: 274,
  buffering: -1,
  url: 'rtsp://example.com/live',
  isPlaying: true
}

其中 eventType 是 LibVLC 原始事件编号，适合日志排查；业务逻辑应使用 status。buffering 仅在 buffering 状态下有实际百分比，其他状态为 -1。

组件内置白色原生 loading。开始打开和首帧输出前会显示，收到 videooutput 后隐藏。HTTP-FLV 即使后续继续派发 buffering，也不会再次显示 loading。

推荐参数

通用内核参数

vlcOptions: [
  '--avcodec-hw=any',
  '--drop-late-frames',
  '--skip-frames'
]

需要排查协议或解码问题时，可临时增加 --verbose=2，问题定位后应移除。

RTSP

mediaOptions: [
  ':rtsp-tcp',
  ':network-caching=300',
  ':live-caching=300',
  ':rtsp-caching=300',
  ':rtsp-frame-buffer-size=1000000'
]

推荐摄像机输出 H.264、关键帧间隔 1 秒。rtsp-frame-buffer-size 单位为字节，不能设置为 100 这类过小数值。

HTTP-FLV

mediaOptions: [
  ':network-caching=150',
  ':live-caching=150',
  ':clock-jitter=0',
  ':clock-synchro=0',
  ':http-reconnect',
  ':http-continuous'
]

网络不稳定时将两个缓存值提高到 200-300。服务器应输出 H.264 + AAC，并以关键帧开始推送；关键帧间隔建议为 1 秒。

M3U8

mediaOptions: [
  ':network-caching=500',
  ':live-caching=500',
  ':http-reconnect'
]

不要为 M3U8 设置 :http-continuous，它适用于 HTTP-FLV 这类持续字节流，会影响 M3U8 分片请求。

RTMP

mediaOptions: [
  ':network-caching=300',
  ':live-caching=300',
  ':clock-jitter=0',
  ':clock-synchro=0'
]

协议切换示例

不同协议不要共用同一组媒体参数。切换地址时同步更新 mediaOptions，再更新 videoUrl：

playFlv(url) {
  this.mediaOptions = [
    ':network-caching=150',
    ':live-caching=150',
    ':http-reconnect',
    ':http-continuous'
  ]
  this.videoUrl = url
}

常见问题

RTSP 已进入 playing 但仍是黑屏

playing 不代表首帧已渲染。以 videooutput 作为画面就绪信号。若长期没有该事件，检查编码是否为 H.264/H.265、关键帧间隔、RTSP TCP 支持和设备硬解能力。

HTTP-FLV 首帧慢

优先检查服务端关键帧间隔。播放器通常需要等待关键帧，建议 GOP 为 1 秒；继续降低缓存无法解决等待关键帧的问题。

切流出现 stopped 和 opening 两次

不要同时更新 play 属性并调用 setUrl()。二者任选其一即可。