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

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 の使用

AI SDK の文字起こしモデルを CompositeVoice で直接使用することもできます。

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 リファレンスを参照してください。

リアルタイム Voice Provider

OpenAIRealtimeVoice などのリアルタイム Voice 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)

注意事項

• すべての Voice Provider が Speech-to-Text 機能をサポートするわけではありません（例：PlayAI、Speechify）
• listen() の動作は Provider によって多少異なる場合がありますが、すべての実装は同じ基本インターフェースに従います
• リアルタイム Voice Provider を使用する場合、メソッドはテキストを直接返さず、代わりに 'writing' イベントを送出することがあります
• サポートされる音声形式は Provider によって異なります。一般的な形式には MP3、WAV、M4A があります
• 一部の Provider は、文字起こしに合わせてテキストを返すストリーミング文字起こしをサポートします
• 最良のパフォーマンスを得るため、使用後は音声ストリームを閉じるか終了することを検討してください

関連メソッド

• voice.speak()：テキストを音声に変換します
• voice.send()：Voice Provider に音声データをリアルタイムで送信します
• voice.on()：Voice イベントのイベントリスナーを登録します