MastraVoice

MastraVoice 类是一个抽象基类，定义了 Mastra 中语音服务的核心接口。所有语音 Provider 实现（如 OpenAI、Deepgram、PlayAI 和 Speechify）都扩展此类，以提供各自的特定功能。该类还支持通过 WebSocket 连接实现实时语音到语音功能。

使用示例

import { MastraVoice } from '@mastra/core/voice'

// Create a voice provider implementation
class MyVoiceProvider extends MastraVoice {
  constructor(config: {
    speechModel?: BuiltInModelConfig
    listeningModel?: BuiltInModelConfig
    speaker?: string
    realtimeConfig?: {
      model?: string
      apiKey?: string
      options?: unknown
    }
  }) {
    super({
      speechModel: config.speechModel,
      listeningModel: config.listeningModel,
      speaker: config.speaker,
      realtimeConfig: config.realtimeConfig,
    })
  }

  // Implement required abstract methods
  async speak(
    input: string | NodeJS.ReadableStream,
    options?: { speaker?: string },
  ): Promise<NodeJS.ReadableStream | void> {
    // Implement text-to-speech conversion
  }

  async listen(
    audioStream: NodeJS.ReadableStream,
    options?: unknown,
  ): Promise<string | NodeJS.ReadableStream | void> {
    // Implement speech-to-text conversion
  }

  async getSpeakers(): Promise<Array<{ voiceId: string; [key: string]: unknown }>> {
    // Return list of available voices
  }

  // Optional speech-to-speech methods
  async connect(): Promise<void> {
    // Establish WebSocket connection for speech-to-speech communication
  }

  async send(audioData: NodeJS.ReadableStream | Int16Array): Promise<void> {
    // Stream audio data in speech-to-speech
  }

  async answer(): Promise<void> {
    // Trigger voice provider to respond
  }

  addTools(tools: Array<unknown>): void {
    // Add tools for the voice provider to use
  }

  close(): void {
    // Close WebSocket connection
  }

  on(event: string, callback: (data: unknown) => void): void {
    // Register event listener
  }

  off(event: string, callback: (data: unknown) => void): void {
    // Remove event listener
  }
}

构造函数参数

config?:

VoiceConfig

语音服务的配置对象

config.speechModel?:

BuiltInModelConfig

文本转语音模型的配置

BuiltInModelConfig

name:

string

要使用的模型名称

apiKey?:

string

模型服务的 API key

config.listeningModel?:

BuiltInModelConfig

语音转文本模型的配置

BuiltInModelConfig

name:

string

要使用的模型名称

apiKey?:

string

模型服务的 API key

config.speaker?:

string

要使用的默认 speaker/音色 ID

config.name?:

string

语音 Provider 实例的名称

config.realtimeConfig?:

object

实时语音到语音功能的配置

object

model?:

string

用于实时语音到语音功能的模型

apiKey?:

string

实时服务的 API key

options?:

unknown

实时功能的 Provider 特定选项

抽象方法

这些方法必须由扩展 MastraVoice 的类实现。

speak()

使用已配置的语音模型将文本转换为语音。

abstract speak(
  input: string | NodeJS.ReadableStream,
  options?: {
    speaker?: string;
    [key: string]: unknown;
  }
): Promise<NodeJS.ReadableStream | void>

用途：

• 接收文本输入，并使用 Provider 的文本转语音服务将其转换为语音
• 同时支持字符串和流输入，使用更灵活
• 允许通过选项覆盖默认 speaker/音色
• 返回可播放或保存的音频数据流
• 如果通过触发 speaking 事件处理音频，则可能返回 void

listen()

使用已配置的监听模型将语音转换为文本。

abstract listen(
  audioStream: NodeJS.ReadableStream,
  options?: {
    [key: string]: unknown;
  }
): Promise<string | NodeJS.ReadableStream | void>

用途：

• 接收音频流，并使用 Provider 的语音转文本服务将其转换为文本
• 支持用于转写配置的 Provider 特定选项
• 可以返回完整的转写文本，也可以返回转写文本流
• 并非所有 Provider 都支持此功能（例如 PlayAI、Speechify）
• 如果通过触发 writing 事件处理转写，则可能返回 void

getSpeakers()

返回 Provider 支持的可用音色列表。

abstract getSpeakers(): Promise<Array<{ voiceId: string; [key: string]: unknown }>>

用途：

• 从 Provider 获取可用音色/speaker 列表
• 每个音色至少必须包含 voiceId 属性
• Provider 可以包含每个音色的其他元数据
• 用于查找可用于文本转语音转换的音色

可选方法

这些方法具有默认实现，但支持语音到语音功能的语音 Provider 可以覆盖它们。

connect()

建立用于通信的 WebSocket 或 WebRTC 连接。

connect(config?: unknown): Promise<void>

用途：

• 初始化与语音服务的通信连接
• 使用 send() 或 answer() 等功能前必须调用
• 返回一个在连接建立后 resolve 的 Promise
• 配置由 Provider 决定

send()

将音频数据实时流式传输到语音 Provider。

send(audioData: NodeJS.ReadableStream | Int16Array): Promise<void>

用途：

• 将音频数据发送到语音 Provider 进行实时处理
• 适用于麦克风实时输入等连续音频流场景
• 同时支持 ReadableStream 和 Int16Array 音频格式
• 调用此方法前必须处于已连接状态

answer()

触发语音 Provider 生成响应。

answer(): Promise<void>

用途：

• 向语音 Provider 发送生成响应的信号
• 在实时对话中用于提示 AI 作出响应
• 响应将通过事件系统发出（例如 speaking 事件）

addTools()

为语音 Provider 配备对话期间可使用的 Tool。

addTools(tools: Array<Tool>): void

用途：

• 添加语音 Provider 可在对话期间使用的 Tool
• Tool 可以扩展语音 Provider 的能力
• 具体实现由 Provider 决定

close()

断开 WebSocket 或 WebRTC 连接。

close(): void

用途：

• 关闭与语音服务的连接
• 清理资源并停止所有正在进行的实时处理
• 使用完语音实例后应调用

on()

注册语音事件监听器。

on<E extends VoiceEventType>(
  event: E,
  callback: (data: E extends keyof VoiceEventMap ? VoiceEventMap[E] : unknown) => void,
): void

用途：

• 注册一个回调函数，在指定事件发生时调用
• 标准事件包括 speaking、writing 和 error
• Provider 也可以触发自定义事件
• 事件数据结构取决于事件类型

off()

移除事件监听器。

off<E extends VoiceEventType>(
  event: E,
  callback: (data: E extends keyof VoiceEventMap ? VoiceEventMap[E] : unknown) => void,
): void

用途：

• 移除之前注册的事件监听器
• 用于清理不再需要的事件处理程序

事件系统

MastraVoice 类包含用于实时通信的事件系统。标准事件类型包括：

speaking:

{ text: string; audioStream?: NodeJS.ReadableStream; audio?: Int16Array }

语音 Provider 说话时触发，包含音频数据

writing:

{ text: string, role: string }

从语音转写出文本时触发

error:

{ message: string; code?: string; details?: unknown }

发生错误时触发

受保护属性

listeningModel?:

BuiltInModelConfig | undefined

语音转文本模型的配置

speechModel?:

BuiltInModelConfig | undefined

文本转语音模型的配置

speaker?:

string | undefined

默认 speaker/音色 ID

realtimeConfig?:

{ model?: string; apiKey?: string; options?: unknown } | undefined

实时语音到语音功能的配置

遥测支持

MastraVoice 通过 traced 方法提供内置遥测支持，该方法会包装方法调用以跟踪性能并监控错误。

注意事项

• MastraVoice 是抽象类，无法直接实例化
• 实现类必须为所有抽象方法提供具体实现
• 该类为不同语音服务 Provider 提供一致的接口
• 语音到语音功能是可选的，具体取决于 Provider
• 事件系统支持实时交互中的异步通信
• 所有方法调用都会自动处理遥测