跳到主要内容

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的直接链接

还可以直接在 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 参考。

实时 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