更新记录

1.0.0（2026-06-01）

• 新增 LiveKit 房间连接、断开连接 API。
• 新增麦克风和摄像头发布 API。
• 新增摄像头采集参数配置和运行时切换摄像头能力。
• 新增麦克风采集参数配置。
• 新增房间状态和本地媒体状态快照 API。
• 新增远端轨道订阅、取消订阅 API。
• 新增扬声器输出切换和原生日志开关 API。
• 新增参与者列表和轨道列表快照 API。
• 新增完整的 LiveKit 房间事件监听载荷，覆盖发言人、数据消息、连接质量、静音、元数据、名称和属性等信息。
• 新增文本数据通道发送能力。
• 新增内置 hans-livekit-video 原生视频组件。
• 新增 Android 和 iOS 原生实现。
• 新增 uni-app x App 和 uni-app App-NVue 兼容支持。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

hans-livekit

hans-livekit 是 LiveKit 的 UTS 原生能力插件，用于在 uni-app x App 和 uni-app App-NVue 中连接 LiveKit 房间、发布音视频、读取参与者和轨道信息、接收房间事件，并内置 <hans-livekit-video /> 视频渲染组件。

使用前准备

1. 在 LiveKit 服务端生成访问 token。
2. App 需要配置摄像头和麦克风权限。
3. 真机运行原生 SDK 能力时需要使用自定义基座；标准基座无法加载插件内的三方原生 SDK。
4. 如果需要显示视频画面，直接使用本插件内置的 <hans-livekit-video /> 组件。

快速开始

import {
  CommonResult,
  ConnectRoomResult,
  GetLocalMediaStateResult,
  GetParticipantsResult,
  GetRoomStateResult,
  GetTracksResult,
  LiveKitEvent,
  LiveKitFail,
  LiveKitParticipantInfo,
  LiveKitTrackInfo,
  TrackOperationResult,
  connectRoom,
  disconnectRoom,
  getLocalMediaState,
  getParticipants,
  getRoomState,
  getTracks,
  onLiveKitEvent,
  offLiveKitEvent,
  sendData,
  setCameraEnabled,
  setLiveKitLogEnabled,
  setMicrophoneEnabled,
  setSpeakerEnabled,
  setTrackSubscribed,
  switchCamera,
} from '@/uni_modules/hans-livekit'

let roomId = ''
let localVideoTrackId = ''

const handleLiveKitEvent = (event: LiveKitEvent): void => {
  console.log('LiveKit event', event)
  if (event.kind != null && event.kind == 'video' && event.trackId != null) {
    localVideoTrackId = event.trackId!
  }
}

onLiveKitEvent(handleLiveKitEvent)

connectRoom({
  url: 'wss://your-host.livekit.cloud',
  token: '<livekit-token>',
  autoSubscribe: true,
  success: (res: ConnectRoomResult) => {
    roomId = res.roomId

    setMicrophoneEnabled({
      roomId,
      enabled: true,
      captureOptions: {
        echoCancellation: true,
        autoGainControl: true,
        noiseSuppression: true,
      },
      success: (micRes: TrackOperationResult) => {
        console.log('microphone enabled', micRes.enabled)
      },
    })

    setCameraEnabled({
      roomId,
      enabled: true,
      captureOptions: {
        position: 'front',
        fps: 30,
        resolution: 'h720',
      },
      success: (cameraRes: TrackOperationResult) => {
        localVideoTrackId = cameraRes.trackId ?? ''
        console.log('local video trackId', localVideoTrackId)
      },
    })
  },
  fail: (err: LiveKitFail) => {
    console.error(err.errCode, err.errMsg)
  },
})

getRoomState({
  roomId,
  success: (res: GetRoomStateResult) => {
    console.log('room state', res.connectionState, res.participantCount)
  },
})

getLocalMediaState({
  roomId,
  success: (res: GetLocalMediaStateResult) => {
    console.log('local media', res.microphoneEnabled, res.cameraEnabled)
  },
})

switchCamera({
  roomId,
  success: (res: TrackOperationResult) => {
    localVideoTrackId = res.trackId ?? localVideoTrackId
  },
})

getParticipants({
  roomId,
  success: (res: GetParticipantsResult) => {
    const local = res.participants.find((item: LiveKitParticipantInfo): boolean => item.local)
    console.log('local participant', local?.identity)
  },
})

getTracks({
  roomId,
  success: (res: GetTracksResult) => {
    const videoTracks = res.tracks.filter((track: LiveKitTrackInfo): boolean => {
      return track.kind == 'video'
    })
    console.log(videoTracks)
  },
})

setTrackSubscribed({
  roomId,
  publicationId: '<remote-publication-id>',
  subscribed: true,
  success: (res: TrackOperationResult) => {
    console.log('subscribed', res.publicationId)
  },
})

sendData({
  roomId,
  payload: 'hello',
  topic: 'chat',
  reliable: true,
  destinationIdentities: ['user-a'],
  success: (res: CommonResult) => {
    console.log('data sent', res.ok)
  },
})

setSpeakerEnabled({
  roomId,
  enabled: true,
})

setLiveKitLogEnabled({
  enabled: false,
  level: 'info',
})

disconnectRoom({
  roomId,
  success: (res: CommonResult) => {
    console.log('disconnect', res.ok)
  },
  complete: (_res: any) => {
    roomId = ''
    localVideoTrackId = ''
    offLiveKitEvent(handleLiveKitEvent)
  },
})

API 和类型导入

在 uni-app x 的 <script setup lang="uts"> 和 uni-app App-NVue 的 <script> 中，建议和 playground 一样显式导入 API 返回类型。这样 success 回调、事件处理和页面状态都能获得明确类型。

import {
  CommonResult,
  ConnectRoomResult,
  GetLocalMediaStateResult,
  GetParticipantsResult,
  GetRoomStateResult,
  GetTracksResult,
  LiveKitEvent,
  LiveKitEventCallback,
  LiveKitFail,
  LiveKitParticipantInfo,
  LiveKitSpeakerInfo,
  LiveKitTrackInfo,
  LiveKitVideoObjectFit,
  SetLiveKitLogEnabledResult,
  TrackOperationResult,
  connectRoom,
  disconnectRoom,
  getLocalMediaState,
  getParticipants,
  getRoomState,
  getTracks,
  offLiveKitEvent,
  onLiveKitEvent,
  sendData,
  setCameraEnabled,
  setLiveKitLogEnabled,
  setMicrophoneEnabled,
  setSpeakerEnabled,
  setTrackSubscribed,
  switchCamera,
} from '@/uni_modules/hans-livekit'

页面状态类型示例

uniappx-livekit-playground/pages/index/index.uvue 使用下面这种方式保存测试页面状态。业务页面可以按需裁剪，但推荐保留 roomId、本地/远端 trackId、publicationId 和房间快照字段。

type LiveKitPlaygroundTestData = {
  statusText: string
  roomId: string
  url: string
  token: string
  micEnabled: boolean
  cameraEnabled: boolean
  speakerEnabled: boolean
  logEnabled: boolean
  selectedVideoTrackId: string
  dataPayload: string
  dataTopic: string
  destinationIdentity: string
  firstRemotePublicationId: string
  remoteVideoTrackId: string
  localVideoTrackId: string
  roomName: string
  identity: string
  tokenServerUrl: string
  participantsText: string
  tracksText: string
}

const data = reactive<LiveKitPlaygroundTestData>({
  statusText: 'Idle',
  roomId: '',
  url: 'ws://192.168.123.56:7880',
  token: '',
  micEnabled: false,
  cameraEnabled: false,
  speakerEnabled: false,
  logEnabled: true,
  selectedVideoTrackId: '',
  dataPayload: 'hello',
  dataTopic: 'chat',
  destinationIdentity: '',
  firstRemotePublicationId: '',
  remoteVideoTrackId: '',
  localVideoTrackId: '',
  roomName: 'my-room',
  identity: '',
  tokenServerUrl: 'http://192.168.123.56:3001',
  participantsText: '[]',
  tracksText: '[]',
})

常用回调建议显式声明返回类型：

const eventCallback: LiveKitEventCallback = (event: LiveKitEvent): void => {
  if (event.type == 'dataReceived') {
    console.log(event.topic ?? '', event.payload ?? '')
  }
}

connectRoom({
  url,
  token,
  autoSubscribe: true,
  success: (res: ConnectRoomResult): void => {
    roomId = res.roomId
  },
  fail: (err: LiveKitFail): void => {
    console.log(err.errCode, err.errMsg)
  },
})

setCameraEnabled({
  roomId,
  enabled: true,
  captureOptions: { position: 'front', fps: 30, resolution: 'h720' },
  success: (res: TrackOperationResult): void => {
    localVideoTrackId = res.trackId ?? ''
  },
})

核心类型速查

以下类型由 @/uni_modules/hans-livekit 导出，可直接在 .uvue / .nvue 页面中使用。

export type LiveKitErrorCode =
  9010001 | 9010002 | 9010003 | 9010004 | 9010005 |
  9010006 | 9010007 | 9010008 | 9010009 | 9010010

export interface LiveKitFail extends IUniError {
  errCode: LiveKitErrorCode
}

export type CommonResult = {
  roomId: string
  ok: boolean
}

export type ConnectRoomResult = {
  roomId: string
  name: string
  identity: string
  connectionState: string
}

export type TrackOperationResult = {
  roomId: string
  enabled: boolean
  trackId?: string | null
  publicationId?: string | null
  kind: string
  source: string
  appliedOptions?: string[] | null
  unsupportedOptions?: string[] | null
}

export type LiveKitParticipantInfo = {
  participantId: string
  identity: string
  name: string
  metadata: string
  attributes?: string | null
  local: boolean
  connectionQuality: string
}

export type LiveKitTrackInfo = {
  trackId: string
  publicationId: string
  participantId: string
  kind: string
  source: string
  name: string
  muted: boolean
  subscribed: boolean
  local: boolean
}

export type LiveKitSpeakerInfo = {
  participantId: string
  identity: string
  name?: string | null
  isSpeaking: boolean
  audioLevel: number
}

export type LiveKitEventType =
  'connected' |
  'reconnecting' |
  'reconnected' |
  'disconnected' |
  'failedToConnect' |
  'participantConnected' |
  'participantDisconnected' |
  'trackPublished' |
  'trackUnpublished' |
  'trackSubscribed' |
  'trackUnsubscribed' |
  'trackMuted' |
  'trackUnmuted' |
  'connectionQualityChanged' |
  'dataReceived' |
  'speakersChanged' |
  'participantMetadataChanged' |
  'participantNameChanged' |
  'participantAttributesChanged'

export type LiveKitEvent = {
  type: LiveKitEventType | string
  roomId: string
  participantId?: string | null
  identity?: string | null
  name?: string | null
  metadata?: string | null
  attributes?: string | null
  trackId?: string | null
  publicationId?: string | null
  kind?: string | null
  source?: string | null
  muted?: boolean | null
  subscribed?: boolean | null
  connectionState?: string | null
  connectionQuality?: string | null
  payload?: string | null
  topic?: string | null
  reliable?: boolean | null
  speakers?: LiveKitSpeakerInfo[] | null
  message?: string | null
  timestamp: number
}

export type LiveKitCameraCaptureOptions = {
  position?: string | null
  fps?: number | null
  resolution?: string | null
  width?: number | null
  height?: number | null
}

export type LiveKitMicrophoneCaptureOptions = {
  noiseSuppression?: boolean | null
  echoCancellation?: boolean | null
  autoGainControl?: boolean | null
  highpassFilter?: boolean | null
}

export type GetRoomStateResult = {
  roomId: string
  name: string
  identity: string
  connectionState: string
  participantCount: number
}

export type GetLocalMediaStateResult = {
  roomId: string
  microphoneEnabled: boolean
  cameraEnabled: boolean
  cameraPosition: string
  microphoneTrackId?: string | null
  cameraTrackId?: string | null
}

export type GetParticipantsResult = {
  roomId: string
  participants: LiveKitParticipantInfo[]
}

export type GetTracksResult = {
  roomId: string
  tracks: LiveKitTrackInfo[]
}

export type SetLiveKitLogEnabledResult = {
  enabled: boolean
  level: string
}

export type LiveKitVideoObjectFit = 'contain' | 'cover' | 'fill'
export type LiveKitEventCallback = (event: LiveKitEvent) => void

export type ConnectRoomOptions = {
  url: string
  token: string
  roomName?: string | null
  autoSubscribe?: boolean | null
  success?: (res: ConnectRoomResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type DisconnectRoomOptions = {
  roomId: string
  success?: (res: CommonResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type SetMicrophoneEnabledOptions = {
  roomId: string
  enabled: boolean
  captureOptions?: LiveKitMicrophoneCaptureOptions | null
  success?: (res: TrackOperationResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type SetCameraEnabledOptions = {
  roomId: string
  enabled: boolean
  cameraPosition?: string | null
  captureOptions?: LiveKitCameraCaptureOptions | null
  success?: (res: TrackOperationResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type SwitchCameraOptions = {
  roomId: string
  position?: string | null
  success?: (res: TrackOperationResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type GetRoomStateOptions = {
  roomId: string
  success?: (res: GetRoomStateResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type GetLocalMediaStateOptions = {
  roomId: string
  success?: (res: GetLocalMediaStateResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type GetParticipantsOptions = {
  roomId: string
  success?: (res: GetParticipantsResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type GetTracksOptions = {
  roomId: string
  success?: (res: GetTracksResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type SetTrackSubscribedOptions = {
  roomId: string
  publicationId: string
  subscribed: boolean
  success?: (res: TrackOperationResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type SendDataOptions = {
  roomId: string
  payload: string
  topic?: string | null
  reliable?: boolean | null
  destinationIdentities?: string[] | null
  destinationParticipantIds?: string[] | null
  success?: (res: CommonResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type SetSpeakerEnabledOptions = {
  roomId: string
  enabled: boolean
  success?: (res: CommonResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

export type SetLiveKitLogEnabledOptions = {
  enabled: boolean
  level?: string | null
  success?: (res: SetLiveKitLogEnabledResult) => void
  fail?: (err: LiveKitFail) => void
  complete?: (res: any) => void
}

API

connectRoom(options)

连接 LiveKit 房间。

success 返回：

{
  roomId: string
  name: string
  identity: string
  connectionState: string
}

disconnectRoom(options)

断开房间连接。

setMicrophoneEnabled(options)

开启或关闭本地麦克风。

captureOptions 字段：

返回值里的 appliedOptions 表示已应用字段，unsupportedOptions 表示当前平台未应用字段。

平台差异：

setCameraEnabled(options)

开启或关闭本地摄像头。

captureOptions 字段：

success 返回中的 trackId 可传给 <hans-livekit-video /> 渲染本地视频。

平台差异：

switchCamera(options)

运行中切换摄像头。摄像头未开启时会返回轨道不存在错误。

getRoomState(options)

获取当前房间状态快照。

返回字段：roomId、name、identity、connectionState、participantCount。

getLocalMediaState(options)

获取本地麦克风、摄像头和当前本地轨道状态。

返回字段：microphoneEnabled、cameraEnabled、cameraPosition、microphoneTrackId、cameraTrackId。

视频组件

<hans-livekit-video /> 内置在本插件中，不需要额外安装组件插件。

<template>
  <hans-livekit-video
    style="width: 320px; height: 240px;"
    :room-id="roomId"
    :track-id="videoTrackId"
    object-fit="cover"
    :mirror="mirror"
    @ready="handleVideoReady"
    @first-frame="handleVideoFirstFrame"
    @error="handleVideoError"
  />
</template>

<script setup lang="uts">
const roomId = ref('')
const videoTrackId = ref('')
const mirror = ref(true)

function handleVideoReady(_event: UniNativeViewEvent): void {
  console.log('video ready')
}

function handleVideoFirstFrame(_event: UniNativeViewEvent): void {
  console.log('video first frame')
}

function handleVideoError(event: UniNativeViewEvent): void {
  console.error('video error', event.detail)
}
</script>

getParticipants(options)

获取当前房间参与者快照。

getTracks(options)

获取当前房间轨道快照。

setTrackSubscribed(options)

手动订阅或取消订阅远端轨道。连接房间时如果 autoSubscribe 为 false，可先通过 getTracks 或轨道事件拿到 publicationId，再调用这个 API。

sendData(options)

发送文本 data channel 消息。

sendData({
  roomId,
  payload: 'hello',
  topic: 'chat',
  reliable: true,
  destinationIdentities: ['user-a'],
  success: (res: CommonResult) => {
    console.log(res.ok)
  },
})

destinationIdentities 传 LiveKit participant identity，不是 participant SID；destinationParticipantIds 仅作为旧字段兼容保留。

setSpeakerEnabled(options)

切换系统扬声器外放。

setLiveKitLogEnabled(options)

开启或关闭插件原生日志。

onLiveKitEvent(callback)

监听 LiveKit 房间事件。

事件类型：

事件对象字段：

offLiveKitEvent(callback?)

移除事件监听。不传 callback 时移除所有监听。

常见错误码

注意事项

• 插件不包含 token 生成逻辑，token 应由你的业务服务端生成。
• 标准基座只能用于基础编译检查；实际连接 LiveKit 和调用原生 SDK 需要自定义基座。
• 内联视频渲染请使用内置 <hans-livekit-video />，并传入本插件返回的 roomId 和 trackId。