MastraVoice

MastraVoice クラスは、Mastra の Voice サービスのコアインターフェースを定義する抽象基底クラスです。すべての Voice 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

Voice サービスの設定オブジェクト

config.speechModel?:

BuiltInModelConfig

Text-to-Speech モデルの設定

BuiltInModelConfig

name:

string

使用するモデル名

apiKey?:

string

モデルサービスの API キー

config.listeningModel?:

BuiltInModelConfig

Speech-to-Text モデルの設定

BuiltInModelConfig

name:

string

使用するモデル名

apiKey?:

string

モデルサービスの API キー

config.speaker?:

string

使用するデフォルトの Speaker／Voice ID

config.name?:

string

Voice 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 の Text-to-Speech サービスを使用して音声に変換します
• 柔軟に使用できるように、文字列とストリームの両方の入力をサポートします
• オプションでデフォルトの Speaker／Voice を上書きできます
• 再生または保存できる音声データのストリームを返します
• 'speaking' イベントの送出によって音声を処理する場合は void を返すことがあります

listen()

設定されたリスニングモデルを使用して音声をテキストに変換します。

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

目的：

• 音声ストリームを受け取り、Provider の Speech-to-Text サービスを使用してテキストに変換します
• 文字起こし設定の Provider 固有オプションをサポートします
• 完全な文字起こしテキストまたは文字起こしテキストのストリームを返せます
• すべての Provider がこの機能をサポートするわけではありません（例：PlayAI、Speechify）
• 'writing' イベントの送出によって文字起こしを処理する場合は void を返すことがあります

getSpeakers()

Provider がサポートする使用可能な Voice の一覧を返します。

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

目的：

• Provider から使用可能な Voice／Speaker の一覧を取得します
• 各 Voice には少なくとも voiceId プロパティが必要です
• Provider は各 Voice に関する追加メタデータを含められます
• Text-to-Speech 変換に使用できる Voice の検出に使用します

省略可能なメソッド

これらのメソッドにはデフォルト実装がありますが、音声間通信機能をサポートする Voice Provider で上書きできます。

connect()

通信用の WebSocket または WebRTC 接続を確立します。

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

目的：

• 通信のために Voice サービスへの接続を初期化します
• send() や answer() などの機能を使用する前に呼び出す必要があります
• 接続が確立されると解決する Promise を返します
• 設定は Provider 固有です

send()

Voice Provider に音声データをリアルタイムでストリーミングします。

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

目的：

• リアルタイム処理のために Voice Provider へ音声データを送信します
• ライブマイク入力など、継続的な音声ストリーミングで役立ちます
• ReadableStream と Int16Array の両方の音声形式をサポートします
• このメソッドを呼び出す前に接続済みの状態にする必要があります

answer()

Voice Provider に応答生成を指示します。

answer(): Promise<void>

目的：

• Voice Provider に応答を生成するシグナルを送信します
• リアルタイムの会話で AI に応答を促すために使用します
• 応答はイベントシステム（例：'speaking' イベント）を通じて送出されます

addTools()

会話中に使用できる Tool を Voice Provider に設定します。

addTools(tools: Array<Tool>): void

目的：

• Voice Provider が会話中に使用できる Tool を追加します
• Tool によって Voice Provider の機能を拡張できます
• 実装は Provider 固有です

close()

WebSocket または WebRTC 接続から切断します。

close(): void

目的：

• Voice サービスへの接続を閉じます
• リソースを解放し、進行中のリアルタイム処理を停止します
• Voice インスタンスの使用を終えたら呼び出してください

on()

Voice イベントのイベントリスナーを登録します。

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 }

Voice Provider の発話中に送出され、音声データを含みます

writing:

{ text: string, role: string }

音声からテキストが文字起こしされたときに送出されます

error:

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

エラーが発生したときに送出されます

protected プロパティ

listeningModel?:

BuiltInModelConfig | undefined

Speech-to-Text モデルの設定

speechModel?:

BuiltInModelConfig | undefined

Text-to-Speech モデルの設定

speaker?:

string | undefined

デフォルトの Speaker／Voice ID

realtimeConfig?:

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

リアルタイムの音声間通信機能の設定

Telemetry のサポート

MastraVoice には、メソッド呼び出しをパフォーマンス追跡とエラー監視でラップする traced メソッドによる Telemetry サポートが組み込まれています。

注意事項

• MastraVoice は抽象クラスであり、直接インスタンス化できません
• 実装では、すべての抽象メソッドの具象実装を提供する必要があります
• このクラスは、異なる Voice サービス Provider 間で一貫したインターフェースを提供します
• 音声間通信機能は省略可能で、Provider 固有です
• イベントシステムにより、リアルタイム対話の非同期通信が可能になります
• すべてのメソッド呼び出しで Telemetry が自動的に処理されます