更新记录

1.0.0（2026-06-27） 下载此版本

初次提交

平台兼容性

uni-app x(4.73)

laoqianjunzi-vlc

laoqianjunzi-vlc 是一个面向 uni-app x 的 VLC 播放器组件插件，提供统一的组件标签、统一的上下文方法和统一的事件回调入口，用来承载以下视频场景：

• RTSP 实时预览
• HTTP / HTTPS 视频播放
• HLS 流媒体播放
• 截图、录制、全屏、重连
• 音轨 / 字幕轨 / 视频轨切换
• 网络缓存、连接超时、倍速、硬解与 VLC 原始参数调优

文档只描述当前插件目录内已经导出的正式 API、示例页和实际行为，不包含旧插件说明，也不包含旧 API 兼容层。

适用场景

• 监控摄像头、NVR、IPC 的 RTSP 预览
• 局域网或公网视频源的拉流播放
• 需要截图、录像、全屏切换的安防页面
• 需要播放器状态、缓冲进度、连接状态回调的业务页
• 需要对 VLC 参数做精细调优的诊断页或工程页

能力概览

组件层能力

• laoqianjunzi-vlc 组件统一承载播放器视图
• src、autoplay、player-options 三个属性即可完成基础接入
• 统一通过 @event 输出播放器事件
• 通过组件 ref 直接拿到 ILqjVlcViewContext，调用播放、截图、录制、全屏、查询状态等方法

上下文能力

• playVideo()、pauseVideo()、resumeVideo()、stopVideo()、replay()
• seekTo()、fastForward()、fastBackward()
• setVolume()、mute()、unmute()、setPlaybackRate()
• startRecording()、stopRecording()、takeSnapshot()
• openFullscreen()、exitFullscreen()、reconnect()
• setVlcOptions()、setHardwareAccelerationMode()、setVlcIntOption()、setVlcBooleanOption()、setVlcStringOption()
• getPlatformCapabilities()、getVideoInfo()、getConfig()、getCurrentTime()、getDuration() 等查询方法

权限代理能力

• getLqjVlcPermissionAgent() 返回统一权限代理
• requestRuntimePermissions() 主动触发运行时权限申请
• setListener() 接收权限结果和运行状态事件

平台支持

说明：

• Android 与 iOS 是完整 VLC 播放形态，最适合 RTSP、录像、截图、轨道能力验证。
• Harmony 与 Web 继续保留相同标签、方法和事件入口，便于页面联调，但录制、部分轨道控制、部分 VLC 高级参数会按平台能力降级。
• 最稳妥的做法是在页面启动后调用 getPlatformCapabilities()，按返回值决定是否展示截图、录制、字幕轨、原始参数等按钮。

安装与引入

将插件放入项目 uni_modules 目录后即可使用。

组件标签名：

<laoqianjunzi-vlc />

如果页面侧需要调用上下文方法或权限代理，可以从模块入口引入：

import {
  getLqjVlcPermissionAgent,
  type ILqjVlcPermissionAgent,
  type ILqjVlcViewContext,
  type LqjVlcBridgePayload,
  type LqjVlcPlatformCapabilities
} from "@/uni_modules/laoqianjunzi-vlc"

快速开始

组件接入

<template>
  <laoqianjunzi-vlc
    ref="playerRef"
    class="player-view"
    :src="source"
    :player-options="playerOptions"
    @event="onPlayerEvent"
  />
</template>

<script lang="uts">
  import { ILqjVlcViewContext } from "@/uni_modules/laoqianjunzi-vlc"

  export default {
    data() {
      return {
        source: "http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4",
        playerOptions: {
          autoplay: false,
          autoReconnect: true,
          networkCache: 300,
          connectionTimeout: 8000,
          playbackProfile: "smooth"
        }
      }
    },
    methods: {
      getPlayer() : ILqjVlcViewContext | null {
        return this.$refs["playerRef"] as ILqjVlcViewContext | null
      },
      playNow() {
        this.getPlayer()?.playVideo(this.source)
      },
      onPlayerEvent(payload : UTSJSONObject | null) {
        if (payload == null) {
          return
        }
        console.log("vlc event", JSON.stringify(payload))
      }
    }
  }
</script>

页面侧播放控制

const player = this.$refs["playerRef"] as ILqjVlcViewContext | null
player?.playVideo(this.source)
player?.pauseVideo()
player?.resumeVideo()
player?.seekTo(15 * 1000)
player?.takeSnapshot()

权限代理接入

const permissionAgent = getLqjVlcPermissionAgent()

permissionAgent.setListener((payload : LqjVlcBridgePayload) => {
  console.log("permission code", payload.code)
  console.log("permission event", JSON.stringify(payload.data))
})

permissionAgent.requestRuntimePermissions()

组件属性

src

播放器资源地址。

autoplay

基础自动播放标记。

说明：

• 组件层 autoplay 是 number 类型。
• player-options 中的 autoplay 是 boolean 类型。
• 两者同时存在时，页面应保持语义一致，避免一个传 1、另一个传 false。
• 如果业务页已经统一通过 player-options.autoplay 管理自动播放，可以不额外传组件层 autoplay。

player-options

播放器初始化与运行期调优配置。

建议：

• 业务页只需要常规播放时，优先传 autoplay、autoReconnect、networkCache、connectionTimeout、playbackProfile。
• 需要更强控制时，再叠加 volume、playbackRate、aspectRatio、loop 等参数。
• 需要 VLC 原始参数时，不建议混在 player-options 中，应直接调用 setVlcOptions()、setVlcIntOption()、setVlcBooleanOption()、setVlcStringOption()。

事件模型

组件统一通过 @event 抛出 UTSJSONObject。

所有事件都会包含：

• event：事件名

常见附加字段：

• oldState、newState
• currentTime、duration、bufferProgress
• progress
• url
• path
• base64
• message
• isInitialized
• isReadyToPlay
• isRecording

常用播放器事件

播放状态参考

页面侧通常会收到这些状态值：

• idle
• opening
• ready
• playing
• paused
• buffering
• stopped
• ended
• error

权限代理事件

getLqjVlcPermissionAgent() 的监听回调与播放器事件分开，它会返回 LqjVlcBridgePayload：

上下文方法速查

通过组件 ref 可以拿到 ILqjVlcViewContext。

一、播放控制

二、进度与时间

三、声音与画面

四、轨道与字幕

五、截图、录制与全屏

六、配置与调优

七、状态与生命周期

VLC 原始参数与硬解模式

setVlcOptions(options)

接受 Array<string>，适合批量传入原始 VLC 参数。

支持的写法包括：

• --rtsp-tcp
• --network-caching=500
• --no-drop-late-frames

示例：

player?.setVlcOptions([
  "--rtsp-tcp",
  "--network-caching=500",
  "--clock-jitter=0"
])

setHardwareAccelerationMode(mode)

建议约定：

• 0：关闭硬解
• 1：启用硬解但关闭直接渲染
• 2：启用硬解并打开直接渲染

示例：

player?.setHardwareAccelerationMode(2)

平台能力判断

建议把页面按钮显示与 getPlatformCapabilities() 返回值绑定，而不是按平台名写死。

示例：

const caps = player?.getPlatformCapabilities()
if (caps != null && caps.supportsRecording) {
  player.startRecording()
}

常用能力位：

• supportsSnapshotPath
• supportsSnapshotBase64
• supportsRecording
• supportsFullscreen
• supportsAudioTrack
• supportsSpuTrack
• supportsVideoTrack
• supportsAudioDelay
• supportsSpuDelay
• supportsExternalTracks
• supportsRuntimePermissions
• supportsRawVlcOptions

内置演示页

插件已经在 uni_modules/laoqianjunzi-vlc/pages/index.uvue 提供完整演示页，覆盖以下内容：

• HTTP MP4、HLS、RTSP 占位地址切换
• 自动播放、自动重连、网络缓存、超时、倍速、画面比例、音量等配置演示
• 播放、暂停、恢复、停止、重播、快进、快退、重连
• 截图、录制、全屏、权限申请、硬解模式切换、原始 VLC 参数注入
• 平台能力读取、配置快照读取、视频信息读取、音轨信息读取
• 统一事件日志输出与实时状态展示

推荐联调顺序：

1. 先打开演示页，点击“MP4 预设”完成基础接入验证
2. 点击“平滑预设”或“低码预设”写入一组可见配置
3. 使用“应用配置”把页面参数同步到播放器
4. 再验证播放、暂停、截图、全屏、重连和事件日志
5. 最后再替换成真实 RTSP 地址和原始 VLC 参数做现场调优

Android 权限与清单

插件内 Android 清单已声明以下关键权限：

• INTERNET
• ACCESS_NETWORK_STATE
• ACCESS_WIFI_STATE
• RECORD_AUDIO
• MODIFY_AUDIO_SETTINGS
• READ_MEDIA_AUDIO
• READ_MEDIA_IMAGES
• READ_MEDIA_VIDEO
• POST_NOTIFICATIONS
• WAKE_LOCK
• CAMERA

低版本 Android 还声明了：

• READ_EXTERNAL_STORAGE
• WRITE_EXTERNAL_STORAGE

如果你的业务页需要截图、录制、媒体读取，建议在进入播放器页后主动调用一次 requestRuntimePermissions()，并把结果展示给用户。

使用建议

• 业务页初版优先只接 src、autoplay、player-options、@event 四个入口，先跑通主链路。
• 事件日志中要重点关注 componentReady、playStateChanged、connectionStateChanged、videoLoadFailed。
• 要做跨端页面联调时，先根据 getPlatformCapabilities() 控制按钮显隐，再验证具体能力。
• RTSP、硬解、网络缓存与重连策略通常需要结合真实设备环境反复调参，推荐直接使用示例页中的原始参数输入区。
• 需要截图或录制落盘时，优先读取 getLastSnapshotPath()、getLastRecordingPath()，不要只依赖界面提示。