voice.speak()

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

參數

input:

string | NodeJS.ReadableStream

要轉換成語音的文字。可以是字串或可讀取的文字串流。

options?:

object

語音合成選項

object

speaker?:

string

此特定要求所使用的語音 ID。會覆寫建構函式中設定的預設 speaker。

傳回值

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

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

Provider 特定選項

各語音 Provider 可能會依其實作支援額外選項。以下是部分範例：

OpenAI

options?:

Options

設定選項。

Options

speed?:

number

語速倍數。支援 0.25 到 4.0 之間的值。

ElevenLabs

options?:

Options

設定選項。

Options

stability?:

number

語音穩定性。值越高，語音越穩定，但表現力越低。

similarity_boost?:

number

語音清晰度及與原始語音的相似度。

Google

options?:

Options

設定選項。

Options

languageCode?:

string

語音的語言程式碼（例如 'en-US'）。

audioConfig?:

object

Google Cloud Text-to-Speech API 的音訊設定選項。

Murf

options?:

Options

設定選項。

Options

properties?:

object

properties 設定。

object

rate?:

number

語速倍數。

pitch?:

number

語音音高調整。

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 使用

使用 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

你也可以直接搭配 CompositeVoice 使用 AI SDK 語音模型：

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 參考。

即時語音 Provider

使用 OpenAIRealtimeVoice 等即時語音 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!')

注意事項

• 各 Provider 的 speak() 行為可能略有不同，但所有實作都遵循相同的基本介面。
• 使用即時語音 Provider 時，此方法可能不會直接傳回音訊串流，而是發出 'speaking' 事件。
• 若輸入是文字串流，Provider 通常會先將它轉換成字串，再進行處理。
• 傳回串流的音訊格式取決於 Provider，常見格式包括 MP3、WAV 和 OGG。
• 為獲得最佳效能，使用完音訊串流後，請考慮將其關閉或結束。