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

# 음성.온()

그만큼`on()`메소드는 음성 이벤트에 대한 이벤트 리스너를 등록합니다. 이는 기록된 텍스트, 오디오 응답 및 기타 상태 변경을 전달하는 데 이벤트가 사용되는 실시간 음성 제공자에게 특히 중요합니다.

## 사용예

```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`): 수신할 이벤트의 이름입니다. 사용 가능한 이벤트 목록은 음성 이벤트 문서를 참조하세요.

**callback** (`function`): 이벤트가 발생할 때 호출되는 콜백 함수입니다. 콜백 시그니처는 특정 이벤트에 따라 달라집니다.

## 반환 값

이 메서드는 값을 반환하지 않습니다.

## 이벤트

이벤트 및 해당 페이로드 구조의 자세한 목록은 다음을 참조하세요.[Voice Events](https://mastra.zisheng.pro/ko/reference/voice/voice.events) documentation.

일반적인 이벤트는 다음과 같습니다.

- `speaking`: 오디오 데이터를 사용할 수 있을 때 발생합니다.
- `speaker`: 오디오 출력으로 파이프될 수 있는 스트림으로 방출됩니다.
- `writing`: 텍스트가 복사되거나 생성될 때 발생합니다.
- `error`: 오류 발생 시 발생
- `tool-call-start`: Tool이 실행되려고 할 때 발생합니다.
- `tool-call-result`: Tool 실행이 완료되면 발생합니다.

다양한 음성 제공자는 다양한 페이로드 구조로 다양한 이벤트 세트를 지원할 수 있습니다.

## 함께 사용`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)
})
```

## 메모

- 이 메서드는 주로 이벤트 기반 통신을 지원하는 실시간 음성 Provider와 함께 사용됩니다.
- 이벤트를 지원하지 않는 음성 Provider에서 호출하면 경고를 기록하고 아무 작업도 수행하지 않습니다.
- 이벤트를 생성할 수 있는 메서드를 호출하기 전에 이벤트 리스너를 등록해야 합니다.
- 이벤트 리스너를 제거하려면 동일한 이벤트 이름과 콜백 함수로 [voice.off()](https://mastra.zisheng.pro/ko/reference/voice/voice.off) 메서드를 호출하세요.
- 동일한 이벤트에 여러 리스너를 등록할 수 있습니다.
- 콜백 함수는 이벤트 유형에 따라 서로 다른 데이터를 수신합니다([음성 이벤트](https://mastra.zisheng.pro/ko/reference/voice/voice.events) 참조).
- 최상의 성능을 위해 더 이상 필요하지 않은 이벤트 리스너는 제거하는 것이 좋습니다.