@volcengine/speech

Volcengine Doubao speech capabilities for the browser.

@volcengine/speech 提供火山引擎豆包语音能力，支持在浏览器中接入实时语音通话链路。

Install

npm install @volcengine/speech

pnpm add @volcengine/speech

yarn add @volcengine/speech

Features

Realtime Conversation

功能说明

提供统一的 RealtimeClient 接口，用于建立实时通话会话，并完成事件发送、静音控制、播报打断、播放状态监听和会话关闭。

Usage

import { createRealtimeClient } from '@volcengine/speech';

const client = createRealtimeClient({
  url: 'wss://your-realtime-service.example.com/dialogue',
});

const offEvent = client.on('event', (event) => {
  console.log('realtime event:', event);
});

const offError = client.on('error', ({ error, event }) => {
  console.error('realtime error:', error, event);
});

const offPlaying = client.on('playing', (playing) => {
  console.log('assistant playing:', playing);
});

async function main() {
  await client.start({
    session: {
      id: 'browser-demo-session',
      model: '1.2.6.0',
      instructions: 'You are a helpful voice assistant.',
      audio: {
        input: {
          format: {
            type: 'pcm',
            rate: 16000,
          },
        },
        output: {
          format: {
            type: 'pcm_s16le',
            rate: 24000,
          },
          voice: 'zh_female_xiaohe_jupiter_bigtts',
        },
      },
      tools: [],
    },
    extension: {},
  });

  await client.send({
    type: 'conversation.item.update',
    items: [],
  });
}

async function destroy() {
  offEvent();
  offError();
  offPlaying();
  await client.stop();
}

void main();

API

createRealtimeClient(options)

创建实时通话客户端实例。

options:

• url: string | (() => string | Promise<string>)

通过 URL 的 api_key 查询参数传入 API Key：

const apiKey = 'YOUR_API_KEY';

const client = createRealtimeClient({
  url: `wss://your-realtime-service.example.com/dialogue?api_key=${encodeURIComponent(apiKey)}`,
});

也可以通过异步函数获取 API Key，再构建连接地址：

const fetchApiKey = async () => {
  // Mock：实际项目中可从业务服务获取临时 API Key。
  return 'YOUR_API_KEY';
};

const client = createRealtimeClient({
  url: async () => {
    const apiKey = await fetchApiKey();
    return `wss://your-realtime-service.example.com/dialogue?api_key=${encodeURIComponent(apiKey)}`;
  },
});

client.start({ session, extension? })

建立实时通话会话。

await client.start({
  session: {
    id: 'browser-demo-session',
    model: '1.2.6.0',
    instructions: 'You are a helpful voice assistant.',
    audio: {
      input: {
        format: {
          type: 'pcm',
          rate: 16000,
        },
      },
      output: {
        format: {
          type: 'pcm_s16le',
          rate: 24000,
        },
        voice: 'zh_female_xiaohe_jupiter_bigtts',
      },
    },
    tools: [],
  },
  extension: {},
});

client.send(event)

发送业务事件到实时通话服务。

await client.send({
  type: 'conversation.item.update',
  items: [],
});

client.mute()

将上行请求音频切换为静音状态。客户端仍持续发送 input_audio_buffer.append，但会将录音内容替换为等长静音数据，以保持音频流连续。

该状态只影响麦克风上行音频，不影响服务端下行播报。

client.unmute()

恢复发送真实的麦克风录音内容。

client.interrupt()

在助手正在播放音频时打断当前播报：

• 立即清空本地播放器，使 playing 尽快变为 false。
• 向服务端发送一次 response.cancel。
• 丢弃被打断 response 后续到达的 response.output_audio.delta 和 response.output_audio.done，避免旧音频重新触发播放。
• 重复调用不会重复取消同一轮播报。

未处于播放状态时调用不会发送 response.cancel。

const offPlaying = client.on('playing', (playing) => {
  if (playing) {
    // 此时可由按钮、用户语音检测等业务逻辑触发打断。
    void client.interrupt();
  }
});

当客户端收到 conversation.item.input_audio_transcription.started 时，会自动清空播放器以打断当前播报，并恢复接收后续有效的下行音频。该事件不会停止麦克风音频上传。

client.stop()

结束当前会话并释放资源。

client.on('event', handler)

监听服务端返回的实时事件。

client.on('error', handler)

监听实时通话链路中的错误事件。

client.on('playing', handler)

监听播放器是否正在实际输出 PCM 音频，返回取消监听函数。

const offPlaying = client.on('playing', (playing) => {
  console.log('assistant playing:', playing);
});

offPlaying();

Environment Support

• Modern browsers
• Microphone access
• WebSocket

License

MIT