voice.on()

on() 方法用于注册 Voice 事件监听器。对于实时 Voice Provider，此方法尤其重要，因为它们使用事件来传递转录文本、音频响应和其他状态变化。

使用示例

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)
})

参数

event:

string

要监听的事件名称。可用事件列表请参阅 Voice 事件文档。

callback:

function

事件发生时调用的回调函数。callback 签名取决于具体事件。

返回值

此方法不返回值。

事件

有关事件及其 payload 结构的详细列表，请参阅 Voice 事件文档。

常见事件包括：

• speaking：有音频数据可用时发出
• speaker：随可输送到音频输出的流一起发出
• writing：转录或生成文本时发出
• error：发生错误时发出
• tool-call-start：即将执行 Tool 时发出
• tool-call-result：Tool 执行完成时发出

不同 Voice Provider 可能支持不同的事件集合，其 payload 结构也可能有所差异。

与 CompositeVoice 配合使用

使用 CompositeVoice 时，on() 方法会委托给已配置的实时 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)
})

注意事项

• 此方法主要用于支持事件式通信的实时 Voice Provider
• 如果在不支持事件的 Voice Provider 上调用此方法，它会记录警告且不执行任何操作
• 应在调用可能发出事件的方法之前注册事件监听器
• 要移除事件监听器，请使用 voice.off() 方法，并传入相同的事件名称和回调函数
• 可以为同一事件注册多个监听器
• callback 函数会根据事件类型接收不同的数据（请参阅 Voice 事件）
• 为获得最佳性能，不再需要事件监听器时，建议将其移除