MastraVoice
MastraVoice クラスは、Mastra における音声サービスのコアインターフェースを定義する抽象基底クラスです。すべての音声プロバイダー実装（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
テキスト読み上げモデルの設定
config.listeningModel?:
BuiltInModelConfig
音声認識モデルの設定
config.speaker?:
string
デフォルトで使用する話者／音声ID
config.name?:
string
音声プロバイダーインスタンスの名前
config.realtimeConfig?:
object
リアルタイム音声変換機能の設定
BuiltInModelConfig
name:
string
使用するモデルの名前
apiKey?:
string
モデルサービス用のAPIキー
RealtimeConfig
model?:
string
リアルタイム音声変換機能で使用するモデル
apiKey?:
string
リアルタイムサービス用のAPIキー
options?:
unknown
リアルタイム機能のプロバイダー固有のオプション
抽象メソッド
これらのメソッドは、MastraVoice を拡張する未知のクラスによって実装される必要があります。
speak()
設定された音声モデルを使用してテキストを音声に変換します。
abstract speak(
input: string | NodeJS.ReadableStream,
options?: {
speaker?: string;
[key: string]: unknown;
}
): Promise<NodeJS.ReadableStream | void>目的：
- テキスト入力を受け取り、プロバイダーのテキスト読み上げサービスを使って音声に変換します
- 柔軟性のため、文字列とストリームの両方の入力に対応しています
- オプションでデフォルトの話者や声を上書きできます
- 再生や保存が可能な音声データのストリームを返します
- 音声が ‘speaking’ イベントの発火によって処理される場合は void を返すことがあります
listen()
設定されたリスニングモデルを使用して音声をテキストに変換します。
abstract listen(
audioStream: NodeJS.ReadableStream,
options?: {
[key: string]: unknown;
}
): Promise<string | NodeJS.ReadableStream | void>目的：
- 音声ストリームを受け取り、プロバイダーの音声認識サービスを使ってテキストに変換します
- 書き起こし設定のためにプロバイダー固有のオプションに対応しています
- 完全なテキスト書き起こし、または書き起こしテキストのストリームのいずれかを返すことができます
- すべてのプロバイダーがこの機能に対応しているわけではありません（例：PlayAI、Speechify）
- 書き起こしが ‘writing’ イベントの発火によって処理される場合は void を返すことがあります
getSpeakers()
プロバイダーがサポートする利用可能な声のリストを返します。
abstract getSpeakers(): Promise<Array<{ voiceId: string; [key: string]: unknown }>>目的：
- プロバイダーから利用可能な声や話者のリストを取得します
- 各声には少なくとも voiceId プロパティが必要です
- プロバイダーは各声に関する追加のメタデータを含めることができます
- テキスト読み上げ変換のために利用可能な声を見つける際に使用されます
オプションのメソッド
これらのメソッドにはデフォルトの実装がありますが、音声から音声への機能をサポートするプロバイダーによってオーバーライドすることができます。
connect()
通信のために WebSocket または WebRTC 接続を確立します。
connect(config?: unknown): Promise<void>目的：
- 通信のために音声サービスへの接続を初期化します
- send() や answer() などの機能を使用する前に呼び出す必要があります
- 接続が確立されたときに解決される Promise を返します
- 設定内容はプロバイダーごとに異なります
send()
音声データをリアルタイムで音声プロバイダーにストリーミングします。
send(audioData: NodeJS.ReadableStream | Int16Array): Promise<void>目的：
- 音声データをリアルタイムで音声プロバイダーに送信します
- ライブマイク入力など、継続的な音声ストリーミングのシナリオに便利です
- ReadableStream と Int16Array の両方の音声フォーマットをサポートします
- このメソッドを呼び出す前に接続状態である必要があります
answer()
音声プロバイダーに応答の生成を促します。
answer(): Promise<void>目的：
- 音声プロバイダーに応答を生成するシグナルを送信します
- AI に応答を促すリアルタイム会話で使用されます
- 応答はイベントシステム（例: ‘speaking’ イベント）を通じて発信されます
addTools()
会話中に使用できるツールを音声プロバイダーに装備します。
addTools(tools: Array<Tool>): void目的：
- 会話中に音声プロバイダーが使用できるツールを追加します
- ツールによって音声プロバイダーの機能を拡張できます
- 実装はプロバイダーごとに異なります
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’ などがあります
- プロバイダーはカスタムイベントも発行できます
- イベントデータの構造はイベントタイプによって異なります
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 }
音声プロバイダーが話しているときに発生し、音声データを含みます
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は抽象クラスであり、直接インスタンス化することはできません
- 実装クラスは、すべての抽象メソッドに対して具体的な実装を提供する必要があります
- このクラスは、さまざまな音声サービスプロバイダー間で一貫したインターフェースを提供します
- 音声から音声への機能はオプションであり、プロバイダーごとに異なります
- イベントシステムにより、リアルタイムのやり取りのための非同期通信が可能になります
- テレメトリはすべてのメソッド呼び出しで自動的に処理されます