更新记录

1.0.1（2026-01-21）

一、文档细则更新

1.0.0（2026-01-21）

首次发布

• 基于 VLC 核心实现 RTSP 流媒体播放
• 支持基本的播放控制：播放、暂停、停止、快进、快退
• 支持视频截图和录制功能
• 支持 Android 和 iOS 双平台
• 提供完整的事件回调机制
• 支持全屏播放模式

平台兼容性

uni-app(4.73)

hl-vlc-view 视频播放插件

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

功能说明

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

平台支持

使用方法

基础用法

<template>
  <view class="container">
    <hl-vlc-view 
      ref="player" 
      :src="rtspUrl" 
      :autoplay="1"
      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 handleEvent = (e) => {
  const { event, data } = e.detail;
  // console.log('收到事件:', event, data);

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

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

组件 API 列表

通过 ref 调用组件方法：

播放控制

声音与画面

录制与截图

网络与配置

状态查询 (同步返回)

事件文档

组件通过 @event 回调对外发送事件。e.detail 包含 event (事件名) 和 data (数据对象)。

开发注意事项

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 流的码率和分辨率是否合适

Q: 如何处理连接断开？

A: 插件支持自动重连：

player.value.setAutoReconnect(true)

或监听连接状态事件手动重连：

if (event === 'connectionStateChanged' && data.newState === 'disconnected') {
  player.value.reconnect()
}

Q: 录制的视频保存在哪里？

A: 录制结束后，recordingStopped 事件会返回绝对路径：

• Android: /storage/emulated/0/Android/data/[packageName]/files/recordings/
• iOS: NSDocumentDirectory/recordings/