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

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

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

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

```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/ja/reference/voice/composite-voice)を参照してください。

## リアルタイム Voice Provider

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

## 注意事項

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

## 関連メソッド

- [voice.speak()](https://mastra.zisheng.pro/ja/reference/voice/voice.speak)：テキストを音声に変換します
- [voice.send()](https://mastra.zisheng.pro/ja/reference/voice/voice.send)：Voice Provider に音声データをリアルタイムで送信します
- [voice.on()](https://mastra.zisheng.pro/ja/reference/voice/voice.on)：Voice イベントのイベントリスナーを登録します