WebSocket 传输层

SDK 默认使用 WebRTC 进行实时语音对话。在 WebRTC 不可用的环境中，你可以改用基于 WebSocket 的传输方式。

WebSocket 传输在受 WebRTC 限制的移动 webview、阻止 UDP 的企业网络，或任何不支持 WebRTC 的平台上都很有用。它底层使用 Pipecat，并且完全按需启用——除非你显式导入传输子路径，否则 pipecat 包绝不会被打包。

---

何时使用 WebSocket 传输

情况	建议
标准 Web 应用	WebRTC（默认）— 更低延迟，更好的音频质量
受 WebRTC 限制的移动 webview	WebSocket
阻止 UDP/STUN/TURN 的企业网络	WebSocket
Bundle 中不得包含 @pipecat-ai	WebRTC（默认——无需额外导入）
回退或测试路径	WebSocket

---

设置

WebSocket 传输是 按需启用. pipecat 包（@pipecat-ai/client-js, @pipecat-ai/websocket-transport）绝不会被打包，除非你显式导入传输子路径。

React

// 1. 注册传输——必须在调用 connect() 之前导入
import '@convai/web-sdk/vanilla/websocket';

import { useConvaiClient, ConvaiWidget } from '@convai/web-sdk/react';

export default function App() {
  const client = useConvaiClient({
    apiKey: '...',
    characterId: '...',
    transport: 'websocket',
  });

  return <ConvaiWidget convaiClient={client} />;
}

原生 JS

// 1. 注册传输
import '@convai/web-sdk/vanilla/websocket';

import { ConvaiClient } from '@convai/web-sdk/vanilla';
import { createConvaiWidget } from '@convai/web-sdk/vanilla';

const client = new ConvaiClient({
  apiKey: '...',
  characterId: '...',
  transport: 'websocket',
});

createConvaiWidget(document.body, { convaiClient: client as any });

导入顺序很重要——构造客户端之前必须先注册。

---

包隔离

ConvaiClient 本身不包含任何 pipecat 导入。WebSocket 实现完全位于 @convai/web-sdk/vanilla/websocket 子路径中。未看到导入该子路径的打包工具（Vite、webpack、Rollup）不会将 @pipecat-ai/client-js 或 @pipecat-ai/websocket-transport 添加到任何 chunk 中。

@convai/web-sdk/vanilla         → 零 pipecat 代码
@convai/web-sdk/react           → 零 pipecat 代码
@convai/web-sdk/vanilla/websocket → pipecat 代码（仅按需启用）

如果您调用 connect() 其带有 transport: "websocket" 在未先导入子路径的情况下，SDK 会抛出清晰的错误：

[ConvaiClient] WebSocket 传输未注册。
在调用 connect() 之前添加 `import '@convai/web-sdk/vanilla/websocket'`。

---

功能对比

功能	WebRTC（默认）	WebSocket
无需 UDP 即可工作	✗	✓
需要 @pipecat-ai	✗	✓（按需启用子路径）
移动 webview 支持	因平台而异	更好

WebSocket 传输层的文件上传：即将推出

---

麦克风行为

在 WebRTC 下，麦克风会通过以下方式显式激活： audioControls.enableAudio() 或 startWithAudioOn 配置标志。

在 WebSocket 下，Pipecat 传输会在……期间初始化音频流。 connect()SDK 在连接时默认开启麦克风，并会在 startWithAudioOn: false:

// 麦克风初始为静音——用户可通过小组件或 audioControls 取消静音
const client = new ConvaiClient({
  transport: 'websocket',
  startWithAudioOn: false,
  ...
});

---

API 参考

Config

字段	类型	默认值	说明
transport	"livekit" | "websocket"	"livekit"	默认使用 WebRTC； "websocket" 选择 Pipecat WebSocket 传输

静态方法

import { ConvaiClient } from '@convai/web-sdk/vanilla';

// 由 websocket 子路径导入自动调用。
// 仅在你注册自定义的 WebSocket 传输实现时需要。
ConvaiClient.registerWebSocketTransport(factory);

registerWebSocketTransport 接受一个签名如下的工厂函数：

(onMessage: (payload: Uint8Array) => void, enableMic: boolean) => IWebSocketSession

如果需要，这让你可以替换为自定义的 WebSocket 会话实现。