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

# voice.listen()

`listen()` 方法是所有 Mastra 語音 Provider 均提供的核心函式，可將語音轉換為文字。它以音訊串流作為輸入，並傳回轉錄文字。

## 參數

**audioStream** (`NodeJS.ReadableStream`): 要轉錄的音訊串流，可以是檔案串流或咪高峰串流。

**options** (`object`): Provider 專用的語音識別選項

## 傳回值

傳回以下其中一項：

- `Promise<string>`：解析為轉錄文字的 promise
- `Promise<NodeJS.ReadableStream>`：解析為轉錄文字串流的 promise（用於串流轉錄）
- `Promise<void>`：用於發出 'writing' 事件而非直接傳回文字的即時 Provider

## Provider 專用選項

每個語音 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/zh-HK/reference/voice/composite-voice)。

## 即時語音 Provider

使用 `OpenAIRealtimeVoice` 等即時語音 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)
```

## 注意事項

- 並非所有語音 Provider 均支援語音轉文字功能（例如 PlayAI、Speechify）
- 不同 Provider 的 `listen()` 行為可能略有不同，但所有實作均遵循相同的基本介面
- 使用即時語音 Provider 時，此方法可能不會直接傳回文字，而是發出 'writing' 事件
- 支援的音訊格式視乎 Provider 而定，常見格式包括 MP3、WAV 及 M4A
- 部分 Provider 支援串流轉錄，可在轉錄文字產生時即時傳回
- 為獲得最佳效能，請考慮在使用完畢後關閉或結束音訊串流

## 相關方法

- [voice.speak()](https://mastra.zisheng.pro/zh-HK/reference/voice/voice.speak)：將文字轉換為語音
- [voice.send()](https://mastra.zisheng.pro/zh-HK/reference/voice/voice.send)：即時向語音 Provider 傳送音訊資料
- [voice.on()](https://mastra.zisheng.pro/zh-HK/reference/voice/voice.on)：為語音事件註冊事件監聽器