更新记录

1.0.9（2026-06-03）

支持vlc自定义参数

1.0.8（2026-06-03）

退出/打开全屏的续播能力优化

1.0.7（2026-06-02）

增加全屏退出事件

平台兼容性

uni-app(4.73)

hl-vlc-view 视频播放插件

基于 VLC 的 RTSP 视频流播放 UniApp UTS 原生插件

功能说明

本插件专注于 RTSP 视频流播放，支持海康威视等摄像头的实时视频预览。

平台支持

使用方法

基础用法 需要在nvue页面中使用

<template>
  <view class="container">
    <hl-vlc-view 
      ref="player" 
      :src="rtspUrl" 
      :player-options="playerInitOptions"
      class="video-player"
      @event="handleEvent" 
    />
  </view>
</template>

<script setup>
const player = ref(null);
const rtspUrl = ref('rtsp://admin:pass@ip:554/Streaming/Channels/101');
const playerInitOptions = {
  autoplay: true,
  autoReconnect: true,
  networkCache: 600,
  playbackProfile: 'smooth'
};

// 事件处理
const handleEvent = (e) => {
  const fields = e.detail?.dynamicJSONFields ?? e.detail ?? e;
  const event = fields.event;

  switch(event) {
    case 'timeUpdate':
      console.log(`当前时间: ${fields.currentTime}ms, 总时长: ${fields.duration}ms`);
      break;
    case 'playStateChanged':
      console.log('播放状态变更:', fields.description);
      break;
  }
};
</script>

<style>
.video-player {
  width: 100%;
  height: 225px;
}
</style>

初始化配置对象

推荐通过 playerOptions 统一传入初始化参数，而不是拆成多个独立属性。

const playerInitOptions = {
  autoplay: false,
  networkCache: 600,
  autoReconnect: true,
  connectionTimeout: 8000,
  soundEnabled: true,
  volume: 100,
  playbackRate: 1.0,
  aspectRatio: 'auto',
  videoScale: 1.0,
  audioTrack: 0,
  loop: false,
  playbackProfile: 'smooth'
};

支持的 playerOptions 字段：

高级 VLC 参数

如果基础参数还不够，可以继续在 playerOptions 里传入更细的 VLC 调优字段。

const playerInitOptions = {
  autoplay: false,
  playbackProfile: 'smooth',
  networkCache: 600,
  liveCache: 180,
  audioCache: 240,
  rtspTcp: true,
  rtspTimeout: 3000,
  rtspFrameBufferSize: 262144,
  clockJitter: 600,
  clockSynchro: 1,
  dropLateFrames: true,
  skipFrames: true,
  decoderThreads: 6,
  hardwareDecoding: true,
  fastDecode: true,
  directRendering: true
};

常用高级字段：

说明：网络建连、缓冲、解码类参数建议在播放前设置；如果在播放中动态修改，通常需要执行 reconnect()、replay() 或重新 setSource() 后才会对新的媒体会话生效。

组件 API 列表

通过 ref 调用组件方法：

播放控制

声音与画面

录制与截图

网络与配置

状态查询 (同步返回)

事件文档

组件通过 @event 回调对外发送事件。e.detail 为平铺后的事件对象，至少包含 event 字段，其他数据字段与事件名处于同一层级。

开发注意事项

1. 文件路径：recordingStopped 和 snapshotTaken 返回的都是绝对路径。在 UniApp 中使用时，可能需要转换为 file:// 协议或使用相对路径（取决于具体 API 要求），但在本插件中直接返回原生路径。

2. 权限要求：

   • Android：需要 INTERNET 权限，插件已自动配置。
   • iOS：不需要特殊权限即可播放，但录制可能涉及文件写入权限。

3. 生命周期管理：建议在页面 onUnload 或组件销毁时主动调用 stopVideo()，虽然插件会自动处理，但主动释放资源是个好习惯。

4. RTSP 协议：

   • 支持 RTSP/TCP 和 RTSP/UDP 两种传输协议
   • 支持 H.264/H.265 编码格式
   • 建议使用 TCP 协议以获得更稳定的连接

5. 性能优化：

   • timeUpdate 事件默认每 500ms 触发一次
   • 如果不需要实时进度，可以不监听此事件以减少开销
   • 建议根据网络情况调整 setNetworkCache 参数

6. 错误处理：

   • 建议监听 error 和 videoLoadFailed 事件
   • 可以通过 setAutoReconnect(true) 启用自动重连
   • 连接超时后可以调用 reconnect() 手动重试

全屏模式

插件支持全屏播放功能，两端实现方式不同：

• iOS：调用 openFullscreen() 会在当前视图基础上全屏，支持手势控制。
• Android：调用 openFullscreen() 会启动一个新的 Activity (FullscreenActivity) 进行沉浸式播放，支持自动隐藏状态栏和导航栏。

核心特性

1. 低延迟播放：基于 VLC 引擎，支持低延迟的 RTSP 流播放
2. 实时进度回调：通过 timeUpdate 事件实时获取播放进度
3. 录制与截图：支持边播边录，单帧截图功能
4. 状态管理：完善的播放状态机，支持多种播放状态回调
5. 网络优化：支持自动重连、网络缓存调整、连接超时设置
6. 音频控制：支持音量调节、静音、多音轨切换
7. 画面调整：支持画面比例、缩放、倍速播放

常见问题

Q: 为什么播放卡顿或延迟高？

A: 可以尝试以下方法：

1. 调整网络缓存：setNetworkCache(300) （单位：毫秒）
2. 检查网络连接质量
3. 确认 RTSP 流的码率和分辨率是否合适