> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 金鑰

**config.listeningModel** (`BuiltInModelConfig`): 語音轉文字模型的設定

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

**config.listeningModel.apiKey** (`string`): 模型服務的 API 金鑰

**config.speaker** (`string`): 要使用的預設說話者／語音 ID

**config.name** (`string`): 語音 Provider 執行個體的名稱

**config.realtimeConfig** (`object`): 即時語音對語音功能的設定

**config.realtimeConfig.model** (`string`): 即時語音對語音功能要使用的模型

**config.realtimeConfig.apiKey** (`string`): 即時服務的 API 金鑰

**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 的文字轉語音服務將其轉換成語音
- 同時支援字串與串流輸入，使用方式更有彈性
- 可透過選項覆寫預設的說話者／語音
- 傳回可播放或儲存的音訊資料串流
- 若音訊是透過發出 '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 取得可用的語音／說話者清單
- 每個語音至少必須有一個 voiceId 屬性
- Provider 可加入各語音的其他中繼資料
- 用於尋找文字轉語音轉換可使用的語音

## 選用方法

這些方法具有預設實作，但支援語音對語音功能的語音 Provider 可以將其覆寫。

### `connect()`

建立用於通訊的 WebSocket 或 WebRTC 連線。

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

用途：

- 初始化語音服務的通訊連線
- 使用 send() 或 answer() 等功能前必須先呼叫
- 傳回一個 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`): 預設的說話者／語音 ID

**realtimeConfig** (`{ model?: string; apiKey?: string; options?: unknown } | undefined`): 即時語音對語音功能的設定

## 遙測支援

MastraVoice 透過 `traced` 方法內建遙測支援；此方法會包裝方法呼叫，以追蹤效能及監控錯誤。

## 注意事項

- MastraVoice 是抽象類別，無法直接建立執行個體
- 實作必須為所有抽象方法提供具體實作
- 此類別為不同語音服務 Provider 提供一致的介面
- 語音對語音功能是選用功能，並因 Provider 而異
- 事件系統可為即時互動進行非同步通訊
- 所有方法呼叫都會自動處理遙測