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

# OpenAI 실시간 음성

OpenAIRealtimeVoice 클래스는 OpenAI의 WebSocket 기반 API를 사용하여 실시간 음성 상호 작용 기능을 제공합니다. 실시간 음성 대 음성, 음성 활동 감지 및 이벤트 기반 오디오 스트리밍을 지원합니다.

## 사용예

```typescript
import { OpenAIRealtimeVoice } from '@mastra/voice-openai-realtime'
import { playAudio, getMicrophoneStream } from '@mastra/node-audio'

// Initialize with default configuration using environment variables
const voice = new OpenAIRealtimeVoice()

// Or initialize with specific configuration
const voiceWithConfig = new OpenAIRealtimeVoice({
  apiKey: 'your-openai-api-key',
  model: 'gpt-5.1-realtime-preview-2024-12-17',
  speaker: 'alloy', // Default voice
})

voiceWithConfig.updateSession({
  turn_detection: {
    type: 'server_vad',
    threshold: 0.6,
    silence_duration_ms: 1200,
  },
})

// Establish connection
await voice.connect()

// Set up event listeners
voice.on('speaker', ({ audio }) => {
  // Handle audio data (Int16Array) pcm format by default
  playAudio(audio)
})

voice.on('writing', ({ text, role }) => {
  // Handle transcribed text
  console.log(`${role}: ${text}`)
})

// Convert text to speech
await voice.speak('Hello, how can I help you today?', {
  speaker: 'echo', // Override default voice
})

// Process audio input
const microphoneStream = getMicrophoneStream()
await voice.send(microphoneStream)

// When done, disconnect
voice.connect()
```

## 구성

### 생성자 옵션

**model** (`string`): 실시간 음성 상호 작용에 사용할 Model ID입니다. (Default: `'gpt-5.1-realtime-preview-2024-12-17'`)

**apiKey** (`string`): OpenAI API 키입니다. 지정하지 않으면 OPENAI\_API\_KEY 환경 변수를 사용합니다.

**speaker** (`string`): 음성 합성의 기본 음성 ID입니다. (Default: `'alloy'`)

### 음성 활동 감지(VAD) 구성

**type** (`string`): 사용할 VAD 유형입니다. 서버 측 VAD가 더 높은 정확도를 제공합니다. (Default: `'server_vad'`)

**threshold** (`number`): 음성 감지 민감도입니다(0.0\~1.0). (Default: `0.5`)

**prefix\_padding\_ms** (`number`): 음성이 감지되기 전 포함할 오디오 길이(밀리초)입니다. (Default: `1000`)

**silence\_duration\_ms** (`number`): 턴을 종료하기 전 무음 길이(밀리초)입니다. (Default: `1000`)

## 행동 양식

### `connect()`

OpenAI Realtime 서비스에 대한 연결을 설정합니다. 말하기, 듣기, 보내기 기능을 사용하기 전에 호출해야 합니다.

**returns** (`Promise<void>`): 연결이 설정되면 이행되는 Promise입니다.

### `speak()`

구성된 음성 Model을 사용하여 말하기 이벤트를 내보냅니다. 문자열이나 읽기 가능한 스트림을 입력으로 받아들일 수 있습니다.

**input** (`string | NodeJS.ReadableStream`): 음성으로 변환할 텍스트 또는 텍스트 스트림입니다.

**options** (`Options`): 구성 옵션입니다.

**options.speaker** (`string`): 이 음성 요청에 사용할 음성 ID입니다.

보고:`Promise<void>`

### `listen()`

음성 인식을 위해 오디오 입력을 처리합니다. 읽을 수 있는 오디오 데이터 스트림을 가져와서 기록된 텍스트와 함께 '듣기' 이벤트를 내보냅니다.

**audioData** (`NodeJS.ReadableStream`): 텍스트로 변환할 오디오 스트림입니다.

보고:`Promise<void>`

### `send()`

라이브 마이크 입력과 같은 지속적인 오디오 스트리밍 시나리오를 위해 오디오 데이터를 OpenAI 서비스에 실시간으로 스트리밍합니다.

**audioData** (`NodeJS.ReadableStream`): 서비스로 전송할 오디오 스트림입니다.

보고:`Promise<void>`

### `updateConfig()`

음성 인스턴스에 대한 세션 구성을 업데이트합니다. 이를 통해 음성 설정을 수정하고 감지를 설정할 수 있습니다. 또한 다른 매개변수를 수정할 수도 있습니다.

**sessionConfig** (`Realtime.SessionConfig`): 적용할 새 세션 구성입니다.

보고:`void`

### `addTools()`

음성 인스턴스에 Tool 세트를 추가합니다. Tool을 사용하면 Model이 대화 중에 추가 작업을 수행할 수 있습니다. OpenAIRealtimeVoice가 Agent에 추가되면 Agent용으로 구성된 모든 Tool을 자동으로 음성 인터페이스에서 사용할 수 있습니다.

**tools** (`ToolsInput`): 장착할 Tool 구성입니다.

보고:`void`

### `close()`

OpenAI Realtime 세션 연결을 끊고 리소스를 정리합니다. 음성 인스턴스가 완료되면 호출되어야 합니다.

보고:`void`

### `getSpeakers()`

사용 가능한 음성 스피커 목록을 반환합니다.

보고:`Promise<Array<{ voiceId: string; [key: string]: any }>>`

### `on()`

음성 이벤트에 대한 이벤트 리스너를 등록합니다.

**event** (`string`): 수신 대기할 이벤트의 이름입니다.

**callback** (`Function`): 이벤트 발생 시 호출할 함수입니다.

보고:`void`

### `off()`

이전에 등록된 이벤트 리스너를 제거합니다.

**event** (`string`): 수신 대기를 중지할 이벤트의 이름입니다.

**callback** (`Function`): 제거할 특정 콜백 함수입니다.

보고:`void`

## 이벤트

OpenAIRealtimeVoice 클래스는 다음 이벤트를 내보냅니다.

**speaking** (`event`): Model에서 오디오 데이터를 수신할 때 발생합니다. 콜백은 { audio: Int16Array }를 받습니다.

**writing** (`event`): 변환된 텍스트를 사용할 수 있을 때 발생합니다. 콜백은 { text: string, role: string }을 받습니다.

**error** (`event`): 오류가 발생할 때 발생합니다. 콜백은 오류 객체를 받습니다.

### OpenAI 실시간 이벤트

'openAIRealtime:' 접두사를 추가하여 [OpenAI Realtime 유틸리티 이벤트](https://github.com/openai/openai-realtime-api-beta#reference-client-utility-events)를 수신할 수도 있습니다.

**openAIRealtime:conversation.created** (`event`): 새 대화가 생성될 때 발생합니다.

**openAIRealtime:conversation.interrupted** (`event`): 대화가 중단될 때 발생합니다.

**openAIRealtime:conversation.updated** (`event`): 대화가 업데이트될 때 발생합니다.

**openAIRealtime:conversation.item.appended** (`event`): 대화에 항목이 추가될 때 발생합니다.

**openAIRealtime:conversation.item.completed** (`event`): 대화의 항목이 완료될 때 발생합니다.

## 사용 가능한 음성

다음과 같은 음성 옵션을 사용할 수 있습니다.

- `alloy`: 중립적이고 균형 잡힌
- `ash`: 명확하고 정확함
- `ballad`: 선율적이고 부드러움
- `coral`: 따뜻하고 친근함
- `echo`: 공명적이고 깊은
- `sage`: 차분하고 사려 깊다
- `shimmer`: 밝고 활기차다
- `verse`: 다재다능하고 표현력이 풍부함

## 메모

- API 키는 생성자 옵션 또는 `OPENAI_API_KEY` 환경 변수를 통해 제공할 수 있습니다.
- OpenAI Realtime Voice API는 실시간 통신을 위해 WebSocket을 사용합니다.
- 서버 측 음성 활동 감지(VAD)는 음성 감지의 정확성을 향상시킵니다.
- 모든 오디오 데이터는 Int16Array 형식으로 처리됩니다.
- 다른 메서드를 사용하기 전에 음성 인스턴스에서 `connect()`를 호출해 연결해야 합니다.
- 완료 후에는 리소스를 올바르게 정리할 수 있도록 항상 `close()`를 호출하세요.
- Memory 관리는 OpenAI Realtime API에서 처리합니다.