自定义 UI 与高级用法

在使用 Convai 的音频管线和消息系统的同时，构建你自己的 UI。

自定义 UI 所需：AudioRenderer

如果你不使用该组件，请包含 AudioRenderer 以确保机器人音频正常工作。

import { useConvaiClient, AudioRenderer, AudioContext } from '@convai/web-sdk';

function CustomApp() {
  const convaiClient = useConvaiClient({
    apiKey: 'your-api-key',
    characterId: 'your-character-id'
  });

  return (
    <AudioContext.Provider value={convaiClient.room}>
      <AudioRenderer />       {/* 音频播放所需 */}
      <YourCustomUI />
    </AudioContext.Provider>
  );
}

---

自定义消息列表

function Messages({ convaiClient }) {
  return convaiClient.chatMessages.map(msg => (
    <div key={msg.id} className={msg.type}>
      {msg.content}
    </div>
  ));
}

---

自定义控件

function Controls({ convaiClient }) {
  const { audioControls, videoControls, screenShareControls } = convaiClient;

  return (
    <>
      <button onClick={audioControls.toggleAudio}>
        {audioControls.isAudioMuted ? '取消静音' : '静音'}
      </button>

      <button onClick={videoControls.toggleVideo}>
        {videoControls.isVideoEnabled ? '停止摄像头' : '启动摄像头'}
      </button>

      <button onClick={screenShareControls.toggleScreenShare}>
        {screenShareControls.isScreenShareActive ? '停止共享' : '共享屏幕'}
      </button>
    </>
  );
}

---

消息类型

中的常见消息类型 convaiClient.chatMessages:

type ChatMessageType =
  | "user"               // 用户发送的消息（原始）
  | "user-transcription" // 用户实时语音转文本
  | "user-llm-text"      // 经 LLM 处理后的最终用户文本
  | "convai"             // 角色原始消息
  | "bot-llm-text"       // 角色生成的 LLM 文本
  | "bot-emotion"        // 角色的情绪状态
  | "emotion"            // 通用情绪消息
  | "behavior-tree"      // 行为树 / 决策输出
  | "action"             // 动作执行
  | "interrupt-bot";     // 中断消息

对于聊天 UI，通常只显示：

const displayMessages = chatMessages.filter(
  (msg) => msg.type === "user-llm-text" || msg.type === "bot-llm-text"
);

---

最佳实践

1. 使用一个 单独的 useConvaiClient() 用于每个应用。
2. 始终检查 state.isConnected 在发送消息之前。
3. 调用 resetSession() 在切换场景或流程时。
4. 使用 <AudioRenderer /> 用于自定义 UI。
5. 提供 endUserId 在生产环境中用于记忆和分析。
6. 将 connect/disconnect 包裹在 try/catch.