ConvaiClient 参考
无框架 Convai Web SDK 客户端参考,包括其属性、方法、媒体控制、唇形同步队列和错误。
ConvaiClient 是 Convai Web SDK 的无框架客户端。它从 @convai/web-sdk/core 和 @convai/web-sdk/vanilla,实现了 IConvaiClient 接口,并扩展了 SDK 的 EventEmitter。React 钩子 useConvaiClient 封装了同一个类。
构造函数
new ConvaiClient(config?: ConvaiConfig)配置
ConvaiConfig
可选。由其存储并用于 connect() 和 reconnect() 当它们在未传入 config 的情况下被调用时。
构造函数会创建 WebRTC 房间,但不会建立连接。对于每个 ConvaiConfig 字段,参见 配置和类型参考.
静态方法
registerWebSocketTransport(factory)
static registerWebSocketTransport(factory: WebSocketSessionFactory): void注册在以下情况下使用的实现: transport is "websocket"。导入 @convai/web-sdk/vanilla/websocket 会使用 SDK 自己的 WebSocket 会话为你调用它。仅在需要提供自定义实现时才直接调用 IWebSocketSession.
WebSocket 会话工厂 is (onMessage: (payload: Uint8Array) => void, enableMic: boolean) => IWebSocketSession.
属性
所有属性均为只读。
状态
Convai 客户端状态
当前连接和活动状态的副本。
connectionType
'audio' | 'video' | 'text' | null
'video' 在与 enableVideo: true, 'audio' 否则, 'text' 用于发布聊天会话时,且 null 当断开连接时。
apiKey
string | null
当前连接的 API 密钥,或 null.
authToken
string | null
当前连接的 Auth 令牌,或 null.
characterId
string | null
当前连接的角色 ID,或 null.
characterSessionId
string | null
连接时由 Convai 返回的会话 ID。 '-1' 在首次连接之前以及在 resetSession().
requestTraceId
string | null
最近一次连接请求的 Trace ID(如果 Convai 返回了它)。
isBotReady
布尔值
true 在角色发出已准备接收消息的信号后。
isPublishedChatSession
布尔值
true 当上一次连接使用 connectWithPublicationGrant().
chatMessages
ChatMessage[]
当前对话中的每一条消息。
userTranscription
字符串
当前用户话语的实时语音转文本。
conversationSessionId
number
回合计数器,每次回合开始时递增。由 conversationStart 和 turnEnd.
room
房间
底层的 LiveKit 房间,用于高级用法。
连接方法
connect(config?)
连接到角色。使用 配置 (如果提供),否则使用传给构造函数的配置,并将结果存储以供 reconnect().
客户端发送 POST {url}/connect中, url 默认为 https://realtime-api.convai.com。它使用 API-AUTH-TOKEN 标头,当 authToken 已设置时使用,否则使用 X-API-Key 标头。当两者都设置时, authToken 被使用。然后它会加入 WebRTC 房间,或者在 transport is "websocket",并发出 connect.
在 connect 客户端会等待角色报告其已就绪,并发出 botReady。在 WebRTC 传输上,如果这在 45 秒内没有发生,客户端会发出 error 与 未在 45000ms 内收到 bot-ready.
未传入配置且未存储任何配置
抛出 未提供配置。请将 config 传给 connect(),或将其存储在客户端中
既不是 apiKey 也不是 authToken,或者没有 characterId
抛出 需要 apiKey 或 authToken,且 characterId 是必需的
Convai 拒绝该请求
抛出一个 错误 其消息是 Convai 返回的原因,或者 HTTP <status>
transport: "websocket" 而未注册传输
抛出 [ConvaiClient] WebSocket transport is not registered. Add `import '@convai/web-sdk/vanilla/websocket'` before calling connect().
在连接完成前 WebSocket 关闭
抛出 connect 完成前 WebSocket 已断开连接
除这两个配置检查外,每次失败也会发出 error ,并在 Promise 拒绝前以相同的错误发出。
reconnect()
调用 connect() 以及存储的配置。存储的配置会携带 characterSessionId 来自上一次连接的内容,因此会话会恢复。抛出 没有可用于重连的存储配置 当没有存储内容时。
disconnect()
离开房间或关闭 WebSocket 会话,并清除连接的凭据、控制项和记忆管理器。客户端在任何断开连接后都不会自动重新连接。
resetSession()
将 characterSessionId 重置回 '-1' ,以便下一次连接开始一个新会话,清除聊天历史和唇同步队列,并清除 指标 和 断开原因 在 状态.
connectWithPublicationGrant(launchToken, options?)
使用一次性 launchToken 连接到已发布的文本聊天,而不是使用 API 密钥或 authToken。该会话仅支持文本:没有麦克风、摄像头、语音或唇同步。 options 接受 url, signal (一个 AbortSignal),以及 connectAttemptId。抛出 在任何请求之前 当令牌短于 32 或长于 512 个字符时,以及 再次连接前先断开当前会话 当会话已打开时。
消息方法
除非某一行另有说明,这些方法返回 void 并且在传输未就绪时不执行任何操作。
sendUserTextMessage(text: string, options?: SendUserTextMessageOptions)
发送文本消息并开启一个新回合。忽略空文本。 options.logicalTurnId 用于关联模型输出版本 2 的信封;它必须非空且最多 128 个 UTF-8 字节,否则该方法会抛出 logicalTurnId 必须非空且最多 128 个 UTF-8 字节.
sendTriggerMessage(triggerName?: string, triggerMessage?: string)
触发一个命名触发器,可选附带消息,并开启一个新回合。
sendInterruptMessage()
请求 Convai 停止当前回复,并停止本地唇同步播放。
sendActionResult(result: ActionResult)
返回客户端工具调用的结果。不会静默无操作,而是抛出: 在会话就绪前无法发送操作结果 当传输未就绪时,以及对空的 id、未知的 状态, error 在一个 已完成的 结果,或非 JSON 值的验证错误。参见 处理角色动作.
updateContext(options: ContextUpdateOptions)
追加、替换或重置运行时上下文,或设置 current_attention_object。当没有文本、没有 attention 对象且 模式 不在 "reset".
updateDynamicInfo(dynamicInfo: string)
发送动态信息文本。忽略空文本。
updateTemplateKeys(templateKeys: Record<string, string>)
替换实时会话的 Narrative Design 模板键。忽略空对象。
updateEmotion(stateOfMind: string | null)
设置角色的临时心境而不触发回复。 null、空字符串,或 "neutral" 会将其清除。该值还会被保存用于下一次 connect(),即使当前没有打开会话。
updateSceneMetadata(items: Array<{ name: string; description: string }>, options?: UpdateSceneMetadataOptions)
描述当前可见或附近的内容。不更改 actionConfig. options.respondMode 设置该更新是否可触发回复。
toggleTts(enabled: boolean)
开启或关闭角色的语音输出。
toggleStt(enabled: boolean)
开启或关闭语音转文本。发送给 Convai 时为 muted: !enabled.
resetIdleTimer()
重置该会话的 Convai 空闲计时器。
参见 在运行时更新角色上下文 了解它们如何配合。
视觉和响应模式方法
每个方法都会返回其发送的更新 ID,或者 null 在传输未就绪时返回。当 updateId 被省略时,客户端会生成一个。
visionStatus(options?: VisionStatusOptions): string | null
请求服务器确认并报告视觉帧缓冲区。 options.updateId 是可选项。
visionTrigger(options?: VisionTriggerOptions): string | null
将缓冲的帧附加到对话中,并可选触发回复。 options 接受 updateId, 文本, respondMode, frameIndices ([start, end]),以及 frameIds.
respondModeUpdate(options: RespondModeUpdateOptions): string | null
为一种模态更改会话的响应模式。 options 接受 模态 ("text", "audio", "vision", "context_update", "trigger",或 "scene_metadata"), 模式 ("必须响应", "自动",或 "静默"),以及一个可选的 updateId.
Convai 会在 serverResponse 事件携带。
文件上传
uploadFile(file, options?)
通过 WebRTC 传输向角色发送文件。上传完成时解析。
主题
字符串
"file-upload"
上传的路由主题。
onProgress
(progressPercent: number) => void
无
以 0 到 100 的整数百分比调用。
抛出 [ConvaiClient] uploadFile: not connected to a LiveKit room 当没有 WebRTC 房间参与者时。
事件
on(event, callback)
订阅某个事件,并返回一个取消订阅的函数。
off(event, callback)
移除订阅。每个事件名称和负载请参见 Web SDK 事件参考.
音频控制
client.audioControls 实现 音频控制。这些方法会抛出 房间未初始化 当没有可用房间时。
isAudioEnabled
布尔值
麦克风是否已启用。
isAudioMuted
布尔值
麦克风是否已静音。
audioLevel
number
麦克风级别。本版本未实现级别监测,因此该值保持 0.
enableAudio()
Promise<void>
启用麦克风。
disableAudio()
Promise<void>
禁用麦克风并停止轨道,释放设备。
muteAudio()
Promise<void>
与 disableAudio().
unmuteAudio()
Promise<void>
与 enableAudio().
toggleAudio()
Promise<void>
静音时取消静音,否则静音。
setAudioDevice(deviceId: string)
Promise<void>
在给定的输入设备上启用麦克风。
getAudioDevices()
Promise<MediaDeviceInfo[]>
列出音频输入设备。
startAudioLevelMonitoring()
void
保留给级别监测。本版本中无作用。
stopAudioLevelMonitoring()
void
停止级别监测并设置 audioLevel 为 0.
on(event, callback), off(event, callback)
订阅 audioStateChange,其负载携带 isAudioMuted, isAudioEnabled,以及 audioLevel.
视频控制
client.videoControls 实现 视频控制。摄像头、屏幕共享和视觉源都是视频连接的一部分,您可通过以下方式打开: enableVideo: true.
isVideoEnabled
布尔值
摄像头是否已启用。
isVideoHidden
布尔值
本地视频是否已隐藏。
activeVisionSource
VisionSourceHandle | null
帧所取自的源。
hasActiveVisionSource
布尔值
是否有视觉源处于活动状态。
visionSourceState
视觉源状态
active, source, sourceName, trackState,并可选地 transport 和 原因.
enableVideo(), disableVideo(), toggleVideo()
Promise<void>
打开、关闭或切换摄像头。
hideVideo(), showVideo()
Promise<void>
隐藏或显示本地视频。
setVideoDevice(deviceId: string)
Promise<void>
切换摄像头。
getVideoDevices()
Promise<MediaDeviceInfo[]>
列出视频输入设备。
setVideoQuality(quality: 'low' | 'medium' | 'high')
Promise<void>
接受一个质量级别。本版本不会更改已发布的视频。
publishCanvas(canvas: HTMLCanvasElement, options?: PublishCanvasOptions)
Promise<VisionSourceHandle>
将画布发布为视觉源。 options 接受 fps, name, source,以及 stopTrackOnUnpublish。抛出 此浏览器不支持 canvas captureStream() 当画布无法被捕获时。
publishVideoTrack(track: MediaStreamTrack, options?: PublishVideoTrackOptions)
Promise<VisionSourceHandle>
将任意视频轨道发布为视觉源。
unpublishVisionSource(source?: VisionSourceHandle | MediaStreamTrack)
Promise<void>
停止发布视觉源。
on(event, callback), off(event, callback)
订阅 videoStateChange.
屏幕共享控制
client.screenShareControls 实现 屏幕共享控制。这些方法会抛出 房间未初始化 当没有可用房间时。
isScreenShareEnabled
布尔值
屏幕共享是否已启用。
isScreenShareActive
布尔值
是否正在共享屏幕。
enableScreenShare(), disableScreenShare(), toggleScreenShare()
Promise<void>
开始、停止或切换屏幕共享。
enableScreenShareWithAudio()
Promise<void>
开始带音频的屏幕共享。
getScreenShareTracks()
Promise<any[]>
返回屏幕共享轨道。
on(event, callback), off(event, callback)
订阅 screenShareStateChange.
BlendshapeQueue
client.blendshapeQueue 在 enableLipsync is true时缓冲唇同步帧。该类从 @convai/web-sdk/core导出。帧以 10 为一批到达,并在一个时间线中播放,该时间线的速率为 getPlaybackFps(),默认回退为 60。
isBotSpeaking()
布尔值
true 在角色音频播放期间。
isConversationActive()
布尔值
true 从回合开始到 Convai 发送该回合的结束统计信息之间。
hasReceivedEndSignal()
布尔值
true 一旦该回合的结束统计信息到达并且音频播放已开始。
isConversationEnded()
布尔值
true 一旦结束信号到达、角色停止说话且帧已播放完或消失。
hasFrames()
布尔值
是否缓冲了可播放的帧。
hasBufferedFrames()
布尔值
是否缓冲了任何帧,包括尚未按播放顺序排列的帧。
长度
number
队列中可播放帧的数量。
getFrame(index)
Float32Array | null
位于 index,或 null 超出范围时。
getFrameWithAlpha(index)
Float32Array | null
同一帧,在该回合的前 10 帧渐入,并在最后 10 帧渐出。
getFrameAtTime(elapsedSeconds)
{ frame, frameIndex } | null
位于 elapsedSeconds 乘以播放速率后,限制到最后一帧。不会消耗。
getFrames()
Float32Array[]
所有可播放的帧。
consumeFrames(count)
void
移除 count 前端的帧,并将其加入已消耗总量。
getFramesConsumed()
number
本回合已消耗的帧。
getPlaybackFps()
number
当前回合的播放速率。
getTurnStats()
TurnStats | null
fps, total_audio_bytes, total_audio_duration_ms, total_blendshapes,以及 total_turn_duration_ms.
getTimeLeftMs()
number | null
估算的剩余播放时间,或 null 在统计数据到达之前。
isAllFramesConsumed()
布尔值
已消耗总量是否达到 total_blendshapes.
consumeNormalizationSignal()
布尔值
返回 true 在中断或取消的响应之后仅调用一次,用作让面部恢复到中立状态的信号。
setMapper(mapper), clearMapper(), hasMapper()
设置、移除或检查每个帧进入队列时所应用的函数。
reset()
void
清空队列并清除回合状态。
getDebugInfo()
对象
用于日志记录的队列状态快照。
客户端会在队列本身上开始、中断和结束回合。请参见 在原生 TypeScript 中添加口型同步 以了解播放循环。
相关参考
配置和类型参考Web SDK 事件参考处理错误和断开连接最后更新于
这有帮助吗?