更新记录

1.0.2（2026-07-04）

新增发送消息接口和本地视频推流宽高、帧率、码率参数等。

1.0.1（2026-05-17）

三端同步日志显示逻辑。

1.0.0（2026-05-16）

初始化版本发布。

平台兼容性

uni-app(5.0)

uni-app x(5.0)

概述

XF-liveKitUTS 封装了 LiveKit 音视频房间的基础能力，当前提供：

• Android、iOS、Harmony 的 App 原生端音视频连接能力
• 本地音频、视频发布
• 本地视频推流宽高、帧率、码率参数
• LiveKit data message 发布与接收
• 远端音视频订阅
• 本地/远端视频原生渲染组件
• 麦克风、摄像头开关与前后摄切换

说明：当前插件主要面向 uni-app x 项目使用。

模块调用

视频渲染组件示例：

<XF-liveKitUTS :track="snapshot.localVideoTrack" :mirror="true"></XF-liveKitUTS>

客户端调用示例：

import { LiveKitClient, type LiveKitClientSnapshot } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()
const snapshot = ref<LiveKitClientSnapshot>(client.getSnapshot())

client.onSnapshot((value : LiveKitClientSnapshot) => {
  snapshot.value = value
})

参数说明

XF-liveKitUTS 组件参数

track

• 类型：LiveKitNativeTrackRef | null
• 描述：要渲染的音视频轨道引用。一般传本地视频轨道或远端视频轨道。

mirror

• 类型：boolean
• 描述：是否镜像显示。前置摄像头本地预览通常传 true，远端视频通常传 false。

插件接口

LiveKitClient

创建 LiveKit 客户端实例。

uni-app x 项目（uvue）中调用示例

import {
  LiveKitClient,
  type LiveKitClientSnapshot,
  type LiveKitConnectOptions
} from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()
const snapshot = ref<LiveKitClientSnapshot>(client.getSnapshot())

client.onSnapshot((value : LiveKitClientSnapshot) => {
  snapshot.value = value
})

const options : LiveKitConnectOptions = {
  serverUrl: "wss://your-livekit-server",
  token: "your-livekit-token",
  autoPublishAudio: true,
  autoPublishVideo: true,
  autoSubscribe: true,
  cameraFacing: "user",
  publishOptions: {
    width: 1280,
    height: 720,
    frameRate: 30,
    bitrate: 1500000
  }
}

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

connect

连接 LiveKit 房间。

uni-app x 项目（uvue）中调用示例

import {
  LiveKitClient,
  type LiveKitConnectOptions
} from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

const options : LiveKitConnectOptions = {
  serverUrl: "wss://your-livekit-server",
  token: "your-livekit-token",
  autoPublishAudio: true,
  autoPublishVideo: true,
  autoSubscribe: true,
  cameraFacing: "user",
  publishOptions: {
    width: 1280,
    height: 720,
    frameRate: 30,
    bitrate: 1500000
  }
}

await client.connect(options)

参数说明

serverUrl

• 类型：string
• 描述：LiveKit 服务地址，例如 wss://your-livekit-server

token

• 类型：string
• 描述：LiveKit access token

roomName

• 类型：string
• 描述：可选，房间名。是否生效取决于服务端 token 配置。

identity

• 类型：string
• 描述：可选，用户标识。是否生效取决于服务端 token 配置。

autoPublishAudio

• 类型：boolean
• 描述：可选，是否自动发布本地音频

autoPublishVideo

• 类型：boolean
• 描述：可选，是否自动发布本地视频

autoSubscribe

• 类型：boolean
• 描述：可选，是否自动订阅远端轨道

cameraFacing

• 类型：'user' | 'environment'
• 描述：可选，初始摄像头方向

publishOptions

• 类型：LiveKitVideoPublishOptions
• 描述：可选，本地视频发布参数。width、height 控制采集/发布分辨率，frameRate 控制采集帧率和编码最大帧率，bitrate 控制编码最大码率，单位为 bps。

Harmony 说明：width、height、frameRate 进入本地采集和发布信令；bitrate 会在视频 sender 创建后通过 sender parameters 设置。

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

publishData

发布 LiveKit data message。

uni-app x 项目（uvue）中调用示例

import {
  LiveKitClient,
  type LiveKitPublishDataOptions
} from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

const options : LiveKitPublishDataOptions = {
  data: "hello",
  reliable: true,
  topic: "chat",
  destinationIdentities: []
}

await client.publishData(options)

参数说明

data

• 类型：string
• 描述：要发送的数据内容，插件会按 UTF-8 转为 LiveKit data payload。

reliable

• 类型：boolean
• 描述：可选，是否可靠发送。默认 true。

topic

• 类型：string
• 描述：可选，LiveKit data topic。

destinationIdentities

• 类型：string[]
• 描述：可选，目标参与者 identity。为空时发送给房间内所有参与者。

Harmony 说明：Harmony 端通过 publisher peer connection 的 _reliable / _lossy DataChannel 发送 LiveKit data message。

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

onDataReceived

监听 LiveKit data message。

uni-app x 项目（uvue）中调用示例

import {
  LiveKitClient,
  type LiveKitDataReceivedEvent
} from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

client.onDataReceived((event : LiveKitDataReceivedEvent) => {
  console.log(event.participantIdentity, event.topic, event.data)
})

回调参数说明

data

• 类型：string
• 描述：收到的 UTF-8 文本数据。

topic

• 类型：string
• 描述：LiveKit data topic。未设置时为空字符串。

participantSid / participantIdentity / participantName

• 类型：string
• 描述：发送方信息。不同平台和服务端回包时机下可能部分为空，建议优先使用 participantIdentity。

reliable

• 类型：boolean
• 描述：是否来自可靠 data channel。

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

disconnect

退出房间并断开连接。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

await client.disconnect()

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

setMicrophoneEnabled

打开或关闭本地麦克风。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

await client.setMicrophoneEnabled(true)
await client.setMicrophoneEnabled(false)

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

setCameraEnabled

打开或关闭本地摄像头。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

await client.setCameraEnabled(true)
await client.setCameraEnabled(false)

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

switchCamera

切换前后摄像头。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

await client.switchCamera()

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

getSnapshot

获取当前房间状态快照。

返回值说明

返回 LiveKitClientSnapshot，主要字段包括：

• connected：是否已连接
• connectionState：连接状态
• roomName：房间名
• micEnabled：麦克风是否开启
• camEnabled：摄像头是否开启
• cameraFacing：当前摄像头方向
• localAudioTrack：本地音频轨道
• localVideoTrack：本地视频轨道
• participants：参与者列表
• remoteVideoTracks：远端视频轨道列表

uni-app x 项目（uvue）中调用示例

import { LiveKitClient, type LiveKitClientSnapshot } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()
const snapshot : LiveKitClientSnapshot = client.getSnapshot()
console.log(snapshot.connectionState)

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

onSnapshot

监听快照推送。

说明：推荐三端统一通过 onSnapshot 被动接收最新快照，页面无需主动调用 getSnapshot() 轮询或同步。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient, type LiveKitClientSnapshot } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

client.onSnapshot((value : LiveKitClientSnapshot) => {
  console.log(value.connectionState)
})

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

onSnapshotRefresh

监听“快照已变化”的通知。

说明：该接口保留用于兼容旧写法或特殊场景。常规页面建议优先使用 onSnapshot，不再需要主动调用 getSnapshot() 拉取状态。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient, type LiveKitClientSnapshot } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()
client.onSnapshotRefresh(() => {
  console.log("snapshot changed")
})

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

onLog

监听插件内部日志输出。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

client.onLog((message : string) => {
  console.log(message)
})

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本

destroy

销毁客户端实例，页面卸载时建议调用。

uni-app x 项目（uvue）中调用示例

import { LiveKitClient } from "@/uni_modules/XF-liveKitUTS"

const client = new LiveKitClient()

onUnmounted(() => {
  client.destroy()
})

可用性

Android、iOS、Harmony 系统

可提供的 1.0.0 及更高版本