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

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()：為語音事件註冊事件監聽器