跳至主要內容

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()
speak 的直接連結

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

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

用途：

  • 接收文字輸入，並使用 Provider 的文字轉語音服務將其轉換成語音
  • 同時支援字串及串流輸入，使用更靈活
  • 可透過選項覆寫預設講者／語音
  • 傳回可供播放或儲存的音訊資料串流
  • 如果音訊由發出 speaking 事件來處理，則可能傳回 void

listen()
listen 的直接連結

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

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

用途：

  • 接收音訊串流，並使用 Provider 的語音轉文字服務將其轉換成文字
  • 支援用於設定轉錄功能的 Provider 特定選項
  • 可傳回完整的文字轉錄，或經轉錄文字的串流
  • 並非所有 Provider 都支援此功能（例如 PlayAI、Speechify）
  • 如果轉錄由發出 writing 事件來處理，則可能傳回 void

getSpeakers()
getspeakers 的直接連結

傳回 Provider 支援的可用語音清單。

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

用途：

  • 從 Provider 擷取可用語音／講者清單
  • 每個語音最少必須有一個 voiceId 屬性
  • Provider 可加入每個語音的額外中繼資料
  • 用於探索可供文字轉語音使用的語音

可選方法
可選方法 的直接連結

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

connect()
connect 的直接連結

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

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

用途：

  • 初始化與語音服務的通訊連線
  • 使用 send() 或 answer() 等功能前必須呼叫此方法
  • 傳回一個在連線建立後解析的 Promise
  • 設定依 Provider 而異

send()
send 的直接連結

將音訊資料實時串流至語音 Provider。

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

用途：

  • 將音訊資料傳送至語音 Provider 作實時處理
  • 適用於即時咪高峰輸入等連續音訊串流情境
  • 同時支援 ReadableStream 及 Int16Array 音訊格式
  • 呼叫此方法前必須處於已連線狀態

answer()
answer 的直接連結

觸發語音 Provider 產生回應。

answer(): Promise<void>

用途：

  • 向語音 Provider 傳送訊號以產生回應
  • 在實時對話中用於提示 AI 回應
  • 回應會透過事件系統發出（例如 speaking 事件）

addTools()
addtools 的直接連結

為語音 Provider 配備可在對話期間使用的 Tool。

addTools(tools: Array<Tool>): void

用途：

  • 加入語音 Provider 可在對話期間使用的 Tool
  • Tool 可擴展語音 Provider 的功能
  • 實作方式依 Provider 而異

close()
close 的直接連結

中斷 WebSocket 或 WebRTC 連線。

close(): void

用途：

  • 關閉與語音服務的連線
  • 清理資源並停止任何進行中的實時處理
  • 使用完語音實例後應呼叫此方法

on()
on 的直接連結

為語音事件註冊事件監聽器。

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

用途：

  • 註冊回呼函數，在指定事件發生時呼叫
  • 標準事件包括 speaking、writing 及 error
  • Provider 亦可發出自訂事件
  • 事件資料結構取決於事件類型

off()
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 而異
  • 事件系統可為實時互動啟用非同步通訊
  • 所有方法呼叫的遙測都會自動處理
On this page