跳至主要內容

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 Voice Reference，了解更多有關OpenAI 語音 Provider 的資料。

語音轉文字（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 Voice Reference，了解更多有關OpenAI 語音 Provider 的資料。

語音轉語音（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 Voice Reference，了解更多有關OpenAI 語音 Provider 的資料。

即時語音
即時語音 的直接連結

在瀏覽器或電話上進行即時通話，使用者可以隨時插話。Mastra 會將音訊迴路交由 LiveKit 處理語音活動偵測、語意輪次偵測及插話，而你的 Agent 則會以本身的模型、Tool 及記憶產生每個回應。如要了解安裝及設定選項，請參閱即時語音。

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 Voice Reference，了解更多有關OpenAI 語音 Provider 的資料。

使用多個語音 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 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'
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 Reference。

更多資源
更多資源 的直接連結

On this page