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 金鑰

config.listeningModel?:

BuiltInModelConfig

語音轉文字模型的設定

BuiltInModelConfig

name:

string

要使用的模型名稱

apiKey?:

string

模型服務的 API 金鑰

config.speaker?:

string

要使用的預設說話者／語音 ID

config.name?:

string

語音 Provider 執行個體的名稱

config.realtimeConfig?:

object

即時語音對語音功能的設定

object

model?:

string

即時語音對語音功能要使用的模型

apiKey?:

string

即時服務的 API 金鑰

options?:

unknown

即時功能的 Provider 特定選項

抽象方法

任何擴充 MastraVoice 的類別都必須實作這些方法。

speak()

使用已設定的語音模型將文字轉換成語音。

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

用途：

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

選用方法

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

connect()

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

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

用途：

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

預設的說話者／語音 ID

realtimeConfig?:

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

即時語音對語音功能的設定

遙測支援

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

注意事項

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