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

# voice.listen()

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

## 參數

**audioStream** (`NodeJS.ReadableStream`): 要轉錄的音訊串流。可以是檔案串流或麥克風串流。

**options** (`object`): Provider 特定的語音辨識選項

## 傳回值

傳回下列其中一種值：

- `Promise<string>`：此 Promise 會 resolve 為轉錄文字
- `Promise<NodeJS.ReadableStream>`：此 Promise 會 resolve 為轉錄文字的串流（用於串流轉錄）
- `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-TW/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-TW/reference/voice/voice.speak)：將文字轉換成語音
- [voice.send()](https://mastra.zisheng.pro/zh-TW/reference/voice/voice.send)：即時將音訊資料傳送至語音 Provider
- [voice.on()](https://mastra.zisheng.pro/zh-TW/reference/voice/voice.on)：為語音事件註冊事件監聽器