更新记录

1.0.0（2026-05-21）

初始化版本发布。

平台兼容性

uni-app(4.83)

uni-app x(4.83)

ZF-playRtspUTS

ZF-playRtspUTS 封装 VLC 播放内核，用于在 App 端播放 RTSP、RTMP、HTTP-FLV、MP4 等视频地址。

快速使用

<template>
  <ZF-playRtspUTS
    id="playRtspView"
    :options="vlcOptions"
    :style="{ width: '750rpx', height: '220px' }"
    @loaded="onLoaded"
    @playing=""
    @timechanged="onTimeChanged"
    @error="onError"
  />
</template>

<script setup lang="uts">
import { createPlayRtspContext, type PlayOptions } from "@/uni_modules/ZF-playRtspUTS"

const vlcOptions = ref("-vvv|--network-caching=300")

function startPlay() {
  const player = createPlayRtspContext("playRtspView", getCurrentInstance()?.proxy)
  player?.playVideo({
    url: "rtsp://example.com/live/stream",
    hwAcc: 2,
    options: [":rtsp-tcp"],
    fail: (res : any) => {
      console.log(res)
    }
  } as PlayOptions)
}

function onLoaded(e : any) {
  console.log(e)
}

function (e : any) {
  console.log(e)
}

function onTimeChanged(e : any) {
  console.log(e)
}

function onError(e : any) {
  console.log(e)
}
</script>

组件

<ZF-playRtspUTS>

示例：

<ZF-playRtspUTS id="playRtspView" :options="'-vvv|--network-caching=300'" />

PlayOptions

playVideo(options) 使用的参数类型：

export type PlayOptions = {
  url : string
  hwAcc ?: number
  options ?: Array<string>
  success ?: (res : any) => void
  fail ?: (res : any) => void
  complete ?: (res : any) => void
}

事件

所有事件通过组件监听：

<ZF-playRtspUTS
  id="playRtspView"
  @loaded="onLoaded"
  @opening="onOpening"
  @paused="onPaused"
  @stopped="onStopped"
  @playing=""
  @ended=""
  @buffering="onBuffering"
  @timechanged="onTimeChanged"
  @error="onError"
  @recording="onRecording"
/>

不同 VLC 平台暴露的字段不完全一致，业务代码应按需判断字段是否存在。

组件上下文方法

通过组件 id 创建上下文后调用。第二个参数建议传入当前页面/组件实例，写法与 DCloud 标准组件文档的 createNativeButtonContext(id, component) 保持一致：

import { createPlayRtspContext } from "@/uni_modules/ZF-playRtspUTS"

const player = createPlayRtspContext("playRtspView", getCurrentInstance()?.proxy)
player?.pauseVideo()

播放控制

音量、倍速和进度

字幕轨道

音频轨道

视频轨道和画面

录制和截图

兼容模块函数

旧版本的模块函数仍可使用：

import { playVideo, pauseVideo, type PlayOptions } from "@/uni_modules/ZF-playRtspUTS"

playVideo({
  url: "rtsp://example.com/live/stream",
  options: [":rtsp-tcp"]
} as PlayOptions)

pauseVideo()

兼容函数和组件实例方法同名，包括 playVideo、pauseVideo、resumeVideo、stopVideo、isPlaying、isSeekable、setVolume、getVolume 等。

注意：

• 兼容函数只会控制最近创建的 <ZF-playRtspUTS> 实例。
• 多个播放器同时存在时，必须使用 createPlayRtspContext(id, component) 调用对应实例方法。
• 如果还没有播放器实例，playVideo 会触发 fail 和 complete，其它方法会返回 false、-1、[] 或空字符串。

HarmonyOS 说明

HarmonyOS 实现参考 @ohos/vlc，内部使用：

XComponent({ id, type: XComponentType.SURFACE, libraryname: "vlc_napi" })
mediaPlayer.setVideoOut(id)

当前 @ohos/vlc@1.0.1-rc.1 暴露的接口不包含录制、截图、Media addOption、音频/字幕 delay、视频轨道切换等能力，因此这些接口在 HarmonyOS 上会降级为 no-op 或返回默认值。Android/iOS 保持原 VLC 能力。

HarmonyOS 端已按 XComponent 生命周期绑定视频输出：

• .onLoad() 读取 getXComponentSurfaceId() 作为 native surface 已创建信号。
• MediaPlayer.setVideoOut() 传入的是 XComponent 的组件 id，不是 native surface id。
• debug 事件会输出 surface-created、surface-bind、play-request、media-parse、player-play 等阶段，便于定位播放失败发生在窗口绑定还是媒体打开。

注意：当前 @ohos/vlc@1.0.1-rc.1 包内包含 libhttps_plugin.so，但未随包提供可见的 TLS/SSL client 插件或 openssl 类库。遇到 https:// 地址，尤其是会 302 跳转到临时 CDN 域名/端口的地址，可能出现 opening -> buffering 0 -> error -> stopped。请优先用测试页里的 HTTP MP4 样例验证播放器链路；若 HTTP 可以播放而 HTTPS 失败，通常是 @ohos/vlc HTTPS/TLS 能力限制或远端跳转策略导致，不是组件窗口绑定问题。

常见问题

为什么推荐组件上下文调用？

组件上下文方式能让每个 <ZF-playRtspUTS> 拥有独立播放器实例，并且与 DCloud 标准组件文档的页面调用方式一致，避免旧版单例在多播放器场景下互相覆盖。

RTSP 播放建议怎么配置？

可优先尝试 TCP：

const player = createPlayRtspContext("playRtspView", getCurrentInstance()?.proxy)
player?.playVideo({
  url: "rtsp://example.com/live/stream",
  options: [":rtsp-tcp"]
} as PlayOptions)

HarmonyOS 如果需要 VLC 初始化参数，请通过组件 options 传入：

<ZF-playRtspUTS id="playRtspView" :options="'-vvv|--network-caching=300'" />