メインコンテンツへ移動

voice.speak()

speak() メソッドは、テキストを音声に変換する、すべての Mastra Voice Provider で利用可能なコア関数です。テキスト入力を受け取り、再生または保存できる音声ストリームを返します。

パラメーター
パラメーターへの直接リンク

input:

string | NodeJS.ReadableStream
音声に変換するテキスト。文字列またはテキストの読み取り可能なストリームを指定できます。

options?:

object
音声合成のオプション
object

speaker?:

string
このリクエストに使用する Voice ID。コンストラクターで設定したデフォルトの Speaker を上書きします。

戻り値
戻り値への直接リンク

次のいずれかとなる Promise<NodeJS.ReadableStream | void> を返します。

  • NodeJS.ReadableStream：再生または保存できる音声データのストリーム
  • void：音声を直接返さず、イベントで送出するリアルタイム Voice Provider を使用する場合

Provider 固有のオプション
Provider 固有のオプションへの直接リンク

各 Voice Provider は、その実装に固有の追加オプションをサポートする場合があります。以下に例を示します。

OpenAI
OpenAIへの直接リンク

options?:

Options
設定オプション。
Options

speed?:

number
発話速度の倍率。0.25～4.0 の値をサポートします。

ElevenLabs
ElevenLabsへの直接リンク

options?:

Options
設定オプション。
Options

stability?:

number
Voice の安定性。値が高いほど安定し、表現の変化が少ない発話になります。

similarity_boost?:

number
Voice の明瞭さと元の Voice との類似度。

Google
Googleへの直接リンク

options?:

Options
設定オプション。
Options

languageCode?:

string
Voice の言語コード（例：'en-US'）。

audioConfig?:

object
Google Cloud Text-to-Speech API の音声設定オプション。

Murf
Murfへの直接リンク

options?:

Options
設定オプション。
Options

properties?:

object
properties の設定。
object

rate?:

number
発話速度の倍率。

pitch?:

number
Voice のピッチ調整。

format?:

'MP3' | 'WAV' | 'FLAC' | 'ALAW' | 'ULAW'
出力音声形式。

使用例
使用例への直接リンク

import { OpenAIVoice } from '@mastra/voice-openai'
// Initialize a voice provider
const voice = new OpenAIVoice({
  speaker: 'alloy', // Default voice
})
// Basic usage with default settings
const audioStream = await voice.speak('Hello, world!')
// Using a different voice for this specific request
const audioStreamWithDifferentVoice = await voice.speak('Hello again!', {
  speaker: 'nova',
})
// Using provider-specific options
const audioStreamWithOptions = await voice.speak('Hello with options!', {
  speaker: 'echo',
  speed: 1.2, // OpenAI-specific option
})
// Using a text stream as input
import { Readable } from 'stream'
const textStream = Readable.from(['Hello', ' from', ' a', ' stream!'])
const audioStreamFromTextStream = await voice.speak(textStream)

CompositeVoice での使用
using-with-compositevoiceへの直接リンク

CompositeVoice を使用する場合、speak() メソッドは設定された発話 Provider に処理を委譲します。

import { CompositeVoice } from '@mastra/core/voice'
import { OpenAIVoice } from '@mastra/voice-openai'
import { PlayAIVoice } from '@mastra/voice-playai'

const voice = new CompositeVoice({
  output: new PlayAIVoice(),
  input: new OpenAIVoice(),
})

// This will use the PlayAIVoice provider
const audioStream = await voice.speak('Hello, world!')

AI SDK Model Provider の使用
AI SDK Model Provider の使用への直接リンク

AI SDK の音声モデルを CompositeVoice で直接使用することもできます。

import { CompositeVoice } from '@mastra/core/voice'
import { openai } from '@ai-sdk/openai'
import { elevenlabs } from '@ai-sdk/elevenlabs'

// Use AI SDK speech models
const voice = new CompositeVoice({
  output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK model
  input: openai.transcription('whisper-1'), // AI SDK model
})

// Works the same way
const audioStream = await voice.speak('Hello from AI SDK!')

// Provider-specific options can be passed through
const audioWithOptions = await voice.speak('Hello with options!', {
  speaker: 'Rachel', // ElevenLabs voice
  providerOptions: {
    elevenlabs: {
      stability: 0.5,
      similarity_boost: 0.75,
    },
  },
})

AI SDK 統合の詳細については、CompositeVoice リファレンスを参照してください。

リアルタイム Voice Provider
リアルタイム Voice Providerへの直接リンク

OpenAIRealtimeVoice などのリアルタイム Voice Provider を使用する場合、speak() メソッドの動作は異なります。

  • 音声ストリームを返す代わりに、音声データを含む 'speaking' イベントを送出します
  • 音声チャンクを受け取るには、イベントリスナーを登録する必要があります
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
import Speaker from '@mastra/node-speaker'

const speaker = new Speaker({
  sampleRate: 24100, // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
  channels: 1, // Mono audio output (as opposed to stereo which would be 2)
  bitDepth: 16, // Bit depth for audio quality - CD quality standard (16-bit resolution)
})

const voice = new OpenAIRealtimeVoice()
await voice.connect()
// Register event listener for audio chunks
voice.on('speaker', stream => {
  // Handle audio chunk (e.g., play it or save it)
  stream.pipe(speaker)
})
// This will emit 'speaking' events instead of returning a stream
await voice.speak('Hello, this is realtime speech!')

注意事項
注意事項への直接リンク

  • speak() の動作は Provider によって多少異なる場合がありますが、すべての実装は同じ基本インターフェースに従います。
  • リアルタイム Voice Provider を使用する場合、メソッドは音声ストリームを直接返さず、代わりに 'speaking' イベントを送出することがあります。
  • テキストストリームを入力として指定すると、通常、Provider は処理前に文字列へ変換します。
  • 返されるストリームの音声形式は Provider によって異なります。一般的な形式には MP3、WAV、OGG があります。
  • 最良のパフォーマンスを得るため、使用後は音声ストリームを閉じるか終了することを検討してください。
On this page