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

# voice.speak()

`speak()` 方法是所有 Mastra voice Provider 都可使用的核心函式，用於將文字轉換成語音。它接收文字輸入，並傳回可播放或儲存的音訊串流。

## 參數

**input** (`string | NodeJS.ReadableStream`): 要轉換成語音的文字。可以是字串或文字的可讀串流。

**options** (`object`): 語音合成選項

**options.speaker** (`string`): 這次請求所使用的語音 ID。會覆寫建構函式所設定的預設 speaker。

## 傳回值

傳回 `Promise<NodeJS.ReadableStream | void>`，其中：

- `NodeJS.ReadableStream`：可播放或儲存的音訊資料串流
- `void`：使用透過事件發出音訊、而非直接傳回音訊的 realtime voice Provider 時

## Provider 專用選項

每個 voice Provider 都可能支援其實作專用的其他選項。以下是一些範例：

### OpenAI

**options** (`Options`): 設定選項。

**options.speed** (`number`): 語速倍數。支援 0.25 至 4.0 的值。

### ElevenLabs

**options** (`Options`): 設定選項。

**options.stability** (`number`): 語音穩定度。值越高，語音越穩定，但表現力越低。

**options.similarity\_boost** (`number`): 語音清晰度及與原始語音的相似度。

### Google

**options** (`Options`): 設定選項。

**options.languageCode** (`string`): 語音的語言代碼（例如 '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`): 語音音高調整。

**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 Providers

你亦可直接配合 `CompositeVoice` 使用 AI SDK 語音模型：

```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,
    },
  },
})
```

詳情請參閱 [CompositeVoice 參考資料](https://mastra.zisheng.pro/zh-HK/reference/voice/composite-voice) for more details on AI SDK integration.

## Realtime voice Providers

使用 `OpenAIRealtimeVoice` 等 realtime voice Provider 時，`speak()` 方法的行為會有所不同：

- Instead of returning an audio stream, it emits a 'speaking' event with the audio data
- You need to register an event listener to receive the audio chunks

```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!')
```

## 注意事項

- The behavior of `speak()` may vary slightly between providers, but all implementations follow the same basic interface.
- When using a realtime voice provider, the method might not return an audio stream directly but instead emit a 'speaking' event.
- If a text stream is provided as input, the provider will typically convert it to a string before processing.
- The audio format of the returned stream depends on the provider. Common formats include MP3, WAV, and OGG.
- For best performance, consider closing or ending the audio stream when you're done with it.