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

# voice.on()

`on()` メソッドは、Voice イベントのイベントリスナーを登録します。イベントを使用して文字起こしテキスト、音声応答、その他の状態変化を伝達するリアルタイム Voice Provider では特に重要です。

## 使用例

```typescript
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
import Speaker from '@mastra/node-speaker'
import chalk from 'chalk'

// Initialize a real-time voice provider
const voice = new OpenAIRealtimeVoice({
  realtimeConfig: {
    model: 'gpt-5.1-realtime',
    apiKey: process.env.OPENAI_API_KEY,
  },
})

// Connect to the real-time service
await voice.connect()

// Register event listener for transcribed text
voice.on('writing', event => {
  if (event.role === 'user') {
    process.stdout.write(chalk.green(event.text))
  } else {
    process.stdout.write(chalk.blue(event.text))
  }
})

// Listen for audio data and play it
const speaker = new Speaker({
  sampleRate: 24100,
  channels: 1,
  bitDepth: 16,
})

voice.on('speaker', stream => {
  stream.pipe(speaker)
})

// Register event listener for errors
voice.on('error', ({ message, code, details }) => {
  console.error(`Error ${code}: ${message}`, details)
})
```

## パラメーター

**event** (`string`): リッスンするイベントの名前。使用可能なイベントの一覧については、Voice イベントのドキュメントを参照してください。

**callback** (`function`): イベント発生時に呼び出されるコールバック関数。コールバックのシグネチャはイベントによって異なります。

## 戻り値

このメソッドは値を返しません。

## イベント

イベントとそのペイロード構造の詳細な一覧については、[Voice イベント](https://mastra.zisheng.pro/ja/reference/voice/voice.events)のドキュメントを参照してください。

一般的なイベントは次のとおりです。

- `speaking`：音声データを利用できるときに送出されます
- `speaker`：音声出力にパイプできるストリームとともに送出されます
- `writing`：テキストが文字起こしまたは生成されたときに送出されます
- `error`：エラーが発生したときに送出されます
- `tool-call-start`：Tool の実行直前に送出されます
- `tool-call-result`：Tool の実行が完了したときに送出されます

Voice Provider ごとにサポートするイベントの組み合わせやペイロード構造が異なる場合があります。

## `CompositeVoice` での使用

`CompositeVoice` を使用する場合、`on()` メソッドは設定されたリアルタイム Provider に処理を委譲します。

```typescript
import { CompositeVoice } from '@mastra/core/voice'
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
import Speaker from '@mastra/node-speaker'

const speaker = new Speaker({
  sampleRate: 24100, // Audio sample rate in Hz - standard for high-quality audio on MacBook Pro
  channels: 1, // Mono audio output (as opposed to stereo which would be 2)
  bitDepth: 16, // Bit depth for audio quality - CD quality standard (16-bit resolution)
})

const realtimeVoice = new OpenAIRealtimeVoice()
const voice = new CompositeVoice({
  realtime: realtimeVoice,
})

// Connect to the real-time service
await voice.connect()

// This will register the event listener with the OpenAIRealtimeVoice provider
voice.on('speaker', stream => {
  stream.pipe(speaker)
})
```

## 注意事項

- 主に、イベントベースの通信をサポートするリアルタイム Voice Provider で使用します
- イベントをサポートしない Voice Provider で呼び出すと、警告を記録して何も実行しません
- イベントを送出する可能性があるメソッドを呼び出す前に、イベントリスナーを登録してください
- イベントリスナーを削除するには、同じイベント名とコールバック関数を指定して [voice.off()](https://mastra.zisheng.pro/ja/reference/voice/voice.off) メソッドを使用します
- 同じイベントに複数のリスナーを登録できます
- コールバック関数が受け取るデータはイベントの種類によって異なります（[Voice イベント](https://mastra.zisheng.pro/ja/reference/voice/voice.events)を参照）
- 最良のパフォーマンスを得るため、不要になったイベントリスナーの削除を検討してください