@koi-video/voice-realtime-sdk

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

English documentation

Installation

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

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

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

最小流程（方法与事件）

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

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

client.on(VoiceEvents.SESSION_CREATED, ({ sessionId }) => {
  console.log('SESSION_CREATED', sessionId);
});

client.on(VoiceEvents.SESSION_STARTED, ({ sessionId }) => {
  console.log('SESSION_STARTED', sessionId);
});

client.on(VoiceEvents.SESSION_ENDED, ({ sessionId, reason }) => {
  console.log('SESSION_ENDED', sessionId, reason);
});

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

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

client.on(VoiceEvents.INTERRUPT, ({ sessionId }) => {
  console.log('INTERRUPT', sessionId);
});

client.on(VoiceEvents.AUDIO_MUTED, ({ sessionId }) => {
  console.log('AUDIO_MUTED', sessionId);
});

client.on(VoiceEvents.AUDIO_UNMUTED, ({ sessionId }) => {
  console.log('AUDIO_UNMUTED', sessionId);
});

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

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

const sessionId = await client.startVoiceChat();

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

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?, raw }。raw 为该条消息的完整服务端 JSON；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）。