voice.listen()

listen() 方法是所有 Mastra Voice Provider 都提供的核心函数，用于将语音转换为文本。它以音频流作为输入，并返回转录文本。

参数

audioStream:

NodeJS.ReadableStream

要转录的音频流，可以是文件流或麦克风流。

options?:

object

特定于 Provider 的语音识别选项

返回值

返回以下值之一：

• Promise<string>：解析为转录文本的 Promise
• Promise<NodeJS.ReadableStream>：解析为转录文本流的 Promise（用于流式转录）
• Promise<void>：适用于发出 'writing' 事件而不直接返回文本的实时 Provider

特定于 Provider 的选项

每个 Voice Provider 都可能支持其实现特有的其他选项。以下是一些示例：

OpenAI

options?:

Options

配置选项。

Options

filetype?:

string

音频文件格式（例如 'mp3'、'wav'、'm4a'）

prompt?:

string

用于引导模型转录的文本

language?:

string

语言代码（例如 'en'、'fr'、'de'）

Google

options?:

Options

配置选项。

Options

stream?:

boolean

是否使用流式识别

config?:

object

Google Cloud Speech-to-Text API 的识别配置

Deepgram

options?:

Options

配置选项。

Options

model?:

string

用于转录的 Deepgram 模型

language?:

string

转录所用的语言代码

使用示例

import { OpenAIVoice } from '@mastra/voice-openai'
import { getMicrophoneStream } from '@mastra/node-audio'
import { createReadStream } from 'fs'
import path from 'path'

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

// Basic usage with a file stream
const audioFilePath = path.join(process.cwd(), 'audio.mp3')
const audioStream = createReadStream(audioFilePath)
const transcript = await voice.listen(audioStream, {
  filetype: 'mp3',
})
console.log('Transcribed text:', transcript)

// Using a microphone stream
const microphoneStream = getMicrophoneStream() // Assume this function gets audio input
const transcription = await voice.listen(microphoneStream)

// With provider-specific options
const transcriptWithOptions = await voice.listen(audioStream, {
  language: 'en',
  prompt: 'This is a conversation about artificial intelligence.',
})

与 CompositeVoice 配合使用

使用 CompositeVoice 时，listen() 方法会委托给已配置的语音输入 Provider：

import { CompositeVoice } from '@mastra/core/voice'
import { OpenAIVoice } from '@mastra/voice-openai'
import { PlayAIVoice } from '@mastra/voice-playai'

const voice = new CompositeVoice({
  input: new OpenAIVoice(),
  output: new PlayAIVoice(),
})

// This will use the OpenAIVoice provider
const transcript = await voice.listen(audioStream)

使用 AI SDK Model Provider

还可以直接在 CompositeVoice 中使用 AI SDK 转录模型：

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

// Use AI SDK transcription models
const voice = new CompositeVoice({
  input: openai.transcription('whisper-1'), // AI SDK model
  output: new PlayAIVoice(), // Mastra provider
})

// Works the same way
const transcript = await voice.listen(audioStream)

// Provider-specific options can be passed through
const transcriptWithOptions = await voice.listen(audioStream, {
  providerOptions: {
    openai: {
      language: 'en',
      prompt: 'This is about AI',
    },
  },
})

有关 AI SDK 集成的更多详情，请参阅 CompositeVoice 参考。

实时 Voice Provider

使用 OpenAIRealtimeVoice 等实时 Voice Provider 时，listen() 方法的行为有所不同：

• 它不会返回转录文本，而是发出包含转录文本的 'writing' 事件
• 你需要注册事件监听器来接收转录结果

import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
import { getMicrophoneStream } from '@mastra/node-audio'

const voice = new OpenAIRealtimeVoice()
await voice.connect()

// Register event listener for transcription
voice.on('writing', ({ text, role }) => {
  console.log(`${role}: ${text}`)
})

// This will emit 'writing' events instead of returning text
const microphoneStream = getMicrophoneStream()
await voice.listen(microphoneStream)

注意事项

• 并非所有 Voice Provider 都支持语音转文本功能（例如 PlayAI、Speechify）
• listen() 的行为在不同 Provider 之间可能略有不同，但所有实现都遵循相同的基本接口
• 使用实时 Voice Provider 时，此方法可能不会直接返回文本，而是发出 'writing' 事件
• 支持的音频格式取决于 Provider。常见格式包括 MP3、WAV 和 M4A
• 某些 Provider 支持流式转录，会在转录过程中持续返回文本
• 为获得最佳性能，使用完音频流后，建议将其关闭或结束

相关方法

• voice.speak()：将文本转换为语音
• voice.send()：将音频数据实时发送到 Voice Provider
• voice.on()：为 Voice 事件注册事件监听器