> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# MastraVoice

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

## 使用示例

```typescript
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`): 文本转语音模型的配置

**config.speechModel.name** (`string`): 要使用的模型名称

**config.speechModel.apiKey** (`string`): 模型服务的 API key

**config.listeningModel** (`BuiltInModelConfig`): 语音转文本模型的配置

**config.listeningModel.name** (`string`): 要使用的模型名称

**config.listeningModel.apiKey** (`string`): 模型服务的 API key

**config.speaker** (`string`): 要使用的默认 speaker/音色 ID

**config.name** (`string`): 语音 Provider 实例的名称

**config.realtimeConfig** (`object`): 实时语音到语音功能的配置

**config.realtimeConfig.model** (`string`): 用于实时语音到语音功能的模型

**config.realtimeConfig.apiKey** (`string`): 实时服务的 API key

**config.realtimeConfig.options** (`unknown`): 实时功能的 Provider 特定选项

## 抽象方法

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

### `speak()`

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

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

用途：

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

### `listen()`

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

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

用途：

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

### `getSpeakers()`

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

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

用途：

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

## 可选方法

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

### `connect()`

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

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

用途：

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

### `send()`

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

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

用途：

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

### `answer()`

触发语音 Provider 生成响应。

```typescript
answer(): Promise<void>
```

用途：

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

### `addTools()`

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

```typescript
addTools(tools: Array<Tool>): void
```

用途：

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

### `close()`

断开 WebSocket 或 WebRTC 连接。

```typescript
close(): void
```

用途：

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

### `on()`

注册语音事件监听器。

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

用途：

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

### `off()`

移除事件监听器。

```typescript
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
- 事件系统支持实时交互中的异步通信
- 所有方法调用都会自动处理遥测