@koi-video/voice-realtime-sdk-beta

浏览器端实时语音 SDK：HTTP 会话（/start、/stop）配合 Robot-Key / Robot-Token，以及 WebRTC（麦克风、远端音频、流消息）。Agora Web SDK 为本包依赖，随安装一并拉取。

English documentation

Installation

pnpm add @koi-video/voice-realtime-sdk-beta

import {
  ChatClient,
  VoiceEvents
} from '@koi-video/voice-realtime-sdk-beta';

| 导出 | 说明 | |------|------| | ChatClient | 主客户端。 | | VoiceEvents | 事件名常量（见 Events）。 |

默认情况下，HTTP 请求使用 SDK 内置的语音网关根地址，无需额外配置。

麦克风与 RTC 需要 HTTPS 或 localhost。

最小流程

import { ChatClient, VoiceEvents } from '@koi-video/voice-realtime-sdk-beta';

const client = new ChatClient(
  {
    robotKey: process.env.ROBOT_KEY,
    robotToken: process.env.ROBOT_TOKEN
  },
  {
    userName: 'demo-user-1'
  }
);

client.on(VoiceEvents.ERROR, err => {
  console.error(err.code, err.message);
});

client.on(VoiceEvents.ROBOT_MESSAGE, ({ sessionId, content, segmentId }) => {
  console.log('bot:', content, segmentId);
});

client.on(VoiceEvents.USER_MESSAGE, ({ content, segmentId }) => {
  console.log('user:', content, segmentId);
});

const sessionId = await client.startVoiceChat();

client.interrupt();
await client.setAudioEnabled({ bool: false });
await client.setAudioEnabled({ bool: true });
await client.stopVoiceChat();

startVoiceChat 返回的 sessionId 与后端 room_name 相同。每个 ChatClient 同时仅一段会话；需先 stopVoiceChat()（或收到 SESSION_ENDED）再重新发起。

全局监听

client.on(VoiceEvents.ALL, (eventName, data) => {
  console.log(eventName, data);
});

Events

使用 client.on(VoiceEvents.XXX, handler) 或 client.on(VoiceEvents.ALL, (eventName, data) => ...)。

VoiceEvents

| 常量 | 触发 / 载荷 | |------|----------------| | SESSION_CREATED | /start 成功且 RTC 就绪 — { sessionId }。 | | SESSION_STARTED | 紧接 SESSION_CREATED，相同 { sessionId }。 | | SESSION_ENDED | 挂断、RTC 断开、远端超时等 — { sessionId, reason }。含 user_stop、disconnected、remote_join_timeout、remote_rejoin_timeout 等。 | | USER_MESSAGE | 流 topic === 'chat'，用户 — { sessionId, content, segmentId?, timestamp? }。 | | ROBOT_MESSAGE | 流 topic === 'chat'，助手 — 同上。 | | AUDIO_MUTED / AUDIO_UNMUTED | setAudioEnabled 之后 — { sessionId }。 | | INTERRUPT | 流 topic === 'interrupt' — { sessionId }。 | | ERROR | 接口 / RTC / 解析错误 — code、message 等。 | | ALL | 所有事件：(eventName, data)。 |

订阅 ALL 时，第一个参数还可能是 FLOW_DEBUG、SIDE_INFO、STREAM_MESSAGE。

常见 ERROR.code：HTTP_*、NETWORK、RTC_ERROR、STREAM_PARSE、CHAT_ERROR、RTC_STOP、STOP_API，以及 REMOTE_JOIN_TIMEOUT（本地 RTC 进房后 15s 内仍无任何远端 user-joined）、REMOTE_REJOIN_TIMEOUT（最后一个远端离开后 30s 内无远端再次进房）。

Demo (this repo)

cd packages/voice-realtime-sdk
pnpm install
pnpm demo
pnpm demo:build
pnpm demo:preview

完整示例见 demo/（demo/vite.config.js 中可选 HTTPS）。