voice.on()

on() 方法用于注册各种语音事件的监听器。这对于实时语音提供商尤为重要，因为事件用于传达转录文本、音频响应以及其他状态变化。

🌐 The on() method registers event listeners for various voice events. This is particularly important for real-time voice providers, where events are used to communicate transcribed text, audio responses, and other state changes.

使用示例

🌐 Usage Example

import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
import Speaker from "@mastra/node-speaker";
import chalk from "chalk";

// Initialize a real-time voice provider
const voice = new OpenAIRealtimeVoice({
  realtimeConfig: {
    model: "gpt-5.1-realtime",
    apiKey: process.env.OPENAI_API_KEY,
  },
});

// Connect to the real-time service
await voice.connect();

// Register event listener for transcribed text
voice.on("writing", (event) => {
  if (event.role === "user") {
    process.stdout.write(chalk.green(event.text));
  } else {
    process.stdout.write(chalk.blue(event.text));
  }
});

// Listen for audio data and play it
const speaker = new Speaker({
  sampleRate: 24100,
  channels: 1,
  bitDepth: 16,
});

voice.on("speaker", (stream) => {
  stream.pipe(speaker);
});

// Register event listener for errors
voice.on("error", ({ message, code, details }) => {
  console.error(`Error ${code}: ${message}`, details);
});

参数

🌐 Parameters

event:

string

Name of the event to listen for. See the [Voice Events](./voice.events) documentation for a list of available events.

callback:

function

Callback function that will be called when the event occurs. The callback signature depends on the specific event.

返回值

🌐 Return Value

此方法不返回值。

🌐 This method does not return a value.

事件

🌐 Events

有关事件及其有效载荷结构的完整列表，请参见 Voice Events 文档。

🌐 For a comprehensive list of events and their payload structures, see the Voice Events documentation.

常见事件包括：

🌐 Common events include:

• speaking：当音频数据可用时触发
• speaker：通过可以连接到音频输出的流发出
• writing：在文本被转录或生成时触发
• error：发生错误时触发
• tool-call-start：当工具即将执行时触发
• tool-call-result：工具执行完成时触发

不同的语音提供商可能支持不同的事件集合，并具有不同的有效载荷结构。

🌐 Different voice providers may support different sets of events with varying payload structures.

与复合语音一起使用

🌐 Using with CompositeVoice

在使用 CompositeVoice 时，on() 方法会委托给配置的实时提供程序：

🌐 When using CompositeVoice, the on() method delegates to the configured real-time provider:

import { CompositeVoice } from "@mastra/core/voice";
import { OpenAIRealtimeVoice } from "@mastra/voice-openai-realtime";
import Speaker from "@mastra/node-speaker";

const speaker = new Speaker({
  sampleRate: 24100, // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
  channels: 1, // Mono audio output (as opposed to stereo which would be 2)
  bitDepth: 16, // Bit depth for audio quality - CD quality standard (16-bit resolution)
});

const realtimeVoice = new OpenAIRealtimeVoice();
const voice = new CompositeVoice({
  realtime: realtimeVoice,
});

// Connect to the real-time service
await voice.connect();

// This will register the event listener with the OpenAIRealtimeVoice provider
voice.on("speaker", (stream) => {
  stream.pipe(speaker);
});

注意

🌐 Notes

• 这种方法主要用于支持基于事件通信的实时语音提供商
• 如果调用了不支持事件的语音提供商，它会记录一条警告并且不会执行任何操作
• 应该在调用可能触发事件的方法之前注册事件监听器
• 要移除事件监听器，请使用 voice.off() 方法，并提供相同的事件名称和回调函数
• 同一个事件可以注册多个监听器
• 回调函数会根据事件类型接收不同的数据（参见[语音事件]（./voice.events））
• 为了获得最佳性能，考虑在事件监听器不再需要时将其移除