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

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 參考。

即時語音 Provider

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

注意事項

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

相關方法

• voice.speak()：將文字轉換成語音
• voice.send()：即時將音訊資料傳送至語音 Provider
• voice.on()：為語音事件註冊事件監聽器