跳到主要内容

Mastra 中的 Voice

Mastra 的 Voice 系统为语音交互提供统一接口，让应用能够使用文本转语音（TTS）、语音转文本（STT）和实时语音转语音（STS）能力。

为 Agent 添加语音能力
为 Agent 添加语音能力的直接链接

通过 voice 属性将语音 Provider 传给 Agent。根据配置的 Provider，同一属性支持文本转语音（TTS）、语音转文本（STT）和实时语音转语音（STS）。

import { Agent } from '@mastra/core/agent'
import { OpenAIVoice } from '@mastra/voice-openai'

// Initialize OpenAI voice for TTS

const voiceAgent = new Agent({
  id: 'voice-agent',
  name: 'Voice Agent',
  instructions: 'You are a voice assistant that can help users with their tasks.',
  model: 'openai/gpt-5.6-sol',
  voice: new OpenAIVoice(),
})

随后可以使用以下语音能力：

文本转语音（TTS）
文本转语音（TTS）的直接链接

使用 Mastra 的 TTS 能力将 Agent 响应转换为自然流畅的语音。 可以选择 OpenAI、ElevenLabs 等多个 Provider。

有关详细配置选项和高级功能，请参阅文本转语音指南。

import { Agent } from '@mastra/core/agent'
import { OpenAIVoice } from '@mastra/voice-openai'
import { playAudio } from '@mastra/node-audio'

const voiceAgent = new Agent({
  id: 'voice-agent',
  name: 'Voice Agent',
  instructions: 'You are a voice assistant that can help users with their tasks.',
  model: 'openai/gpt-5.6-sol',
  voice: new OpenAIVoice(),
})

const { text } = await voiceAgent.generate('What color is the sky?')

// Convert text to speech to an Audio Stream
const audioStream = await voiceAgent.voice.speak(text, {
  speaker: 'default', // Optional: specify a speaker
  responseFormat: 'wav', // Optional: specify a response format
})

playAudio(audioStream)

有关 OpenAI 语音 Provider 的更多信息，请参阅 OpenAI Voice 参考。

语音转文本（STT）
语音转文本（STT）的直接链接

使用 OpenAI、ElevenLabs 等 Provider 转录语音内容。有关详细配置选项等内容，请参阅语音转文本。

你可以从这里下载示例音频文件。


import { Agent } from '@mastra/core/agent'
import { OpenAIVoice } from '@mastra/voice-openai'
import { createReadStream } from 'fs'

const voiceAgent = new Agent({
  id: 'voice-agent',
  name: 'Voice Agent',
  instructions: 'You are a voice assistant that can help users with their tasks.',
  model: 'openai/gpt-5.6-sol',
  voice: new OpenAIVoice(),
})

// Use an audio file from a URL
const audioStream = await createReadStream('./how_can_i_help_you.mp3')

// Convert audio to text
const transcript = await voiceAgent.voice.listen(audioStream)
console.log(`User said: ${transcript}`)

// Generate a response based on the transcript
const { text } = await voiceAgent.generate(transcript)

有关 OpenAI 语音 Provider 的更多信息，请参阅 OpenAI Voice 参考。

语音转语音（STS）
语音转语音（STS）的直接链接

使用语音转语音能力创建对话体验。统一 API 可实现用户与 AI Agent 之间的实时语音交互。 有关详细配置选项和高级功能，请参阅语音转语音。

import { Agent } from '@mastra/core/agent'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'

const voiceAgent = new Agent({
  id: 'voice-agent',
  name: 'Voice Agent',
  instructions: 'You are a voice assistant that can help users with their tasks.',
  model: 'openai/gpt-5.6-sol',
  voice: new OpenAIRealtimeVoice(),
})

// Listen for agent audio responses
voiceAgent.voice.on('speaker', ({ audio }) => {
  playAudio(audio)
})

// Initiate the conversation
await voiceAgent.voice.speak('How can I help you today?')

// Send continuous audio from the microphone
const micStream = getMicrophoneStream()
await voiceAgent.voice.send(micStream)

有关 OpenAI 语音 Provider 的更多信息，请参阅 OpenAI Voice 参考。

实时语音
实时语音的直接链接

在浏览器或电话中运行可由用户打断的实时通话。Mastra 将音频循环交给 LiveKit，由它处理语音活动检测、语义轮次检测和插话；Agent 则使用自己的模型、Tool 和 memory 生成每条回复。有关设置和配置选项，请参阅实时语音。

Voice 配置
Voice 配置的直接链接

每个语音 Provider 都可以配置不同的模型和选项。以下是所有受支持 Provider 的详细配置选项：

// OpenAI Voice Configuration
const voice = new OpenAIVoice({
  speechModel: {
    name: 'gpt-3.5-turbo', // Example model name
    apiKey: process.env.OPENAI_API_KEY,
    language: 'en-US', // Language code
    voiceType: 'neural', // Type of voice model
  },
  listeningModel: {
    name: 'whisper-1', // Example model name
    apiKey: process.env.OPENAI_API_KEY,
    language: 'en-US', // Language code
    format: 'wav', // Audio format
  },
  speaker: 'alloy', // Example speaker name
})

有关 OpenAI 语音 Provider 的更多信息，请参阅 OpenAI Voice 参考。

使用多个语音 Provider
使用多个语音 Provider的直接链接

此示例演示如何在 Mastra 中创建并使用两个不同的语音 Provider：使用 OpenAI 进行语音转文本（STT），使用 PlayAI 进行文本转语音（TTS）。

首先使用所需配置创建语音 Provider 实例。

import { OpenAIVoice } from '@mastra/voice-openai'
import { PlayAIVoice } from '@mastra/voice-playai'
import { CompositeVoice } from '@mastra/core/voice'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'

// Initialize OpenAI voice for STT
const input = new OpenAIVoice({
  listeningModel: {
    name: 'whisper-1',
    apiKey: process.env.OPENAI_API_KEY,
  },
})

// Initialize PlayAI voice for TTS
const output = new PlayAIVoice({
  speechModel: {
    name: 'playai-voice',
    apiKey: process.env.PLAYAI_API_KEY,
  },
})

// Combine the providers using CompositeVoice
const voice = new CompositeVoice({
  input,
  output,
})

// Implement voice interactions using the combined voice provider
const audioStream = getMicrophoneStream() // Assume this function gets audio input
const transcript = await voice.listen(audioStream)

// Log the transcribed text
console.log('Transcribed text:', transcript)

// Convert text to speech
const responseAudio = await voice.speak(`You said: ${transcript}`, {
  speaker: 'default', // Optional: specify a speaker,
  responseFormat: 'wav', // Optional: specify a response format
})

// Play the audio response
playAudio(responseAudio)

使用 AI SDK 模型 Provider
使用 AI SDK 模型 Provider的直接链接

也可以直接将 AI SDK 模型与 CompositeVoice 配合使用：

import { CompositeVoice } from '@mastra/core/voice'
import { openai } from '@ai-sdk/openai'
import { elevenlabs } from '@ai-sdk/elevenlabs'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'

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

// Works the same way as Mastra providers
const audioStream = getMicrophoneStream()
const transcript = await voice.listen(audioStream)

console.log('Transcribed text:', transcript)

// Convert text to speech
const responseAudio = await voice.speak(`You said: ${transcript}`, {
  speaker: 'Rachel', // ElevenLabs voice
})

playAudio(responseAudio)

还可以混合使用 AI SDK 模型和 Mastra Provider：

import { CompositeVoice } from '@mastra/core/voice'
import { PlayAIVoice } from '@mastra/voice-playai'
import { groq } from '@ai-sdk/groq'

const voice = new CompositeVoice({
  input: groq.transcription('whisper-large-v3'), // AI SDK for STT
  output: new PlayAIVoice(), // Mastra provider for TTS
})

有关 CompositeVoice 的更多信息，请参阅 CompositeVoice 参考。

更多资源
更多资源的直接链接

On this page