> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 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'）

**options.prompt** (`string`): 用于引导模型转录的文本

**options.language** (`string`): 语言代码（例如 'en'、'fr'、'de'）

### Google

**options** (`Options`): 配置选项。

**options.stream** (`boolean`): 是否使用流式识别

**options.config** (`object`): Google Cloud Speech-to-Text API 的识别配置

### Deepgram

**options** (`Options`): 配置选项。

**options.model** (`string`): 用于转录的 Deepgram 模型

**options.language** (`string`): 转录所用的语言代码

## 使用示例

```typescript
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：

```typescript
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 转录模型：

```typescript
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 参考](https://mastra.zisheng.pro/reference/voice/composite-voice)。

## 实时 Voice Provider

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

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

```typescript
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()](https://mastra.zisheng.pro/reference/voice/voice.speak)：将文本转换为语音
- [voice.send()](https://mastra.zisheng.pro/reference/voice/voice.send)：将音频数据实时发送到 Voice Provider
- [voice.on()](https://mastra.zisheng.pro/reference/voice/voice.on)：为 Voice 事件注册事件监听器