> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# voice.speak()

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

## パラメーター

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

**options** (`object`): 音声合成のオプション

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

## 戻り値

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

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

## Provider 固有のオプション

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

### OpenAI

**options** (`Options`): 設定オプション。

**options.speed** (`number`): 発話速度の倍率。0.25～4.0 の値をサポートします。

### ElevenLabs

**options** (`Options`): 設定オプション。

**options.stability** (`number`): Voice の安定性。値が高いほど安定し、表現の変化が少ない発話になります。

**options.similarity\_boost** (`number`): Voice の明瞭さと元の Voice との類似度。

### Google

**options** (`Options`): 設定オプション。

**options.languageCode** (`string`): Voice の言語コード（例：'en-US'）。

**options.audioConfig** (`object`): Google Cloud Text-to-Speech API の音声設定オプション。

### Murf

**options** (`Options`): 設定オプション。

**options.properties** (`object`): properties の設定。

**options.properties.rate** (`number`): 発話速度の倍率。

**options.properties.pitch** (`number`): Voice のピッチ調整。

**options.properties.format** (`'MP3' | 'WAV' | 'FLAC' | 'ALAW' | 'ULAW'`): 出力音声形式。

## 使用例

```typescript
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` での使用

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

```typescript
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 の音声モデルを `CompositeVoice` で直接使用することもできます。

```typescript
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 リファレンス](https://mastra.zisheng.pro/ja/reference/voice/composite-voice)を参照してください。

## リアルタイム Voice Provider

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

- 音声ストリームを返す代わりに、音声データを含む 'speaking' イベントを送出します
- 音声チャンクを受け取るには、イベントリスナーを登録する必要があります

```typescript
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 があります。
- 最良のパフォーマンスを得るため、使用後は音声ストリームを閉じるか終了することを検討してください。