OpenAI 실시간 음성
OpenAIRealtimeVoice 클래스는 OpenAI의 WebSocket 기반 API를 사용하여 실시간 음성 상호 작용 기능을 제공합니다. 실시간 음성 대 음성, 음성 활동 감지 및 이벤트 기반 오디오 스트리밍을 지원합니다.
사용예사용예에 대한 직접 링크
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?:
apiKey?:
speaker?:
음성 활동 감지(VAD) 구성음성 활동 감지(VAD) 구성에 대한 직접 링크
type?:
threshold?:
prefix_padding_ms?:
silence_duration_ms?:
행동 양식행동 양식에 대한 직접 링크
connect()connect에 대한 직접 링크
OpenAI Realtime 서비스에 대한 연결을 설정합니다. 말하기, 듣기, 보내기 기능을 사용하기 전에 호출해야 합니다.
returns:
speak()speak에 대한 직접 링크
구성된 음성 Model을 사용하여 말하기 이벤트를 내보냅니다. 문자열이나 읽기 가능한 스트림을 입력으로 받아들일 수 있습니다.
input:
options?:
speaker?:
보고:Promise<void>
listen()listen에 대한 직접 링크
음성 인식을 위해 오디오 입력을 처리합니다. 읽을 수 있는 오디오 데이터 스트림을 가져와서 기록된 텍스트와 함께 '듣기' 이벤트를 내보냅니다.
audioData:
보고:Promise<void>
send()send에 대한 직접 링크
라이브 마이크 입력과 같은 지속적인 오디오 스트리밍 시나리오를 위해 오디오 데이터를 OpenAI 서비스에 실시간으로 스트리밍합니다.
audioData:
보고:Promise<void>
updateConfig()updateconfig에 대한 직접 링크
음성 인스턴스에 대한 세션 구성을 업데이트합니다. 이를 통해 음성 설정을 수정하고 감지를 설정할 수 있습니다. 또한 다른 매개변수를 수정할 수도 있습니다.
sessionConfig:
보고:void
addTools()addtools에 대한 직접 링크
음성 인스턴스에 Tool 세트를 추가합니다. Tool을 사용하면 Model이 대화 중에 추가 작업을 수행할 수 있습니다. OpenAIRealtimeVoice가 Agent에 추가되면 Agent용으로 구성된 모든 Tool을 자동으로 음성 인터페이스에서 사용할 수 있습니다.
tools?:
보고:void
close()close에 대한 직접 링크
OpenAI Realtime 세션 연결을 끊고 리소스를 정리합니다. 음성 인스턴스가 완료되면 호출되어야 합니다.
보고:void
getSpeakers()getspeakers에 대한 직접 링크
사용 가능한 음성 스피커 목록을 반환합니다.
보고:Promise<Array<{ voiceId: string; [key: string]: any }>>
on()on에 대한 직접 링크
음성 이벤트에 대한 이벤트 리스너를 등록합니다.
event:
callback:
보고:void
off()off에 대한 직접 링크
이전에 등록된 이벤트 리스너를 제거합니다.
event:
callback:
보고:void
이벤트이벤트에 대한 직접 링크
OpenAIRealtimeVoice 클래스는 다음 이벤트를 내보냅니다.
speaking:
writing:
error:
OpenAI 실시간 이벤트OpenAI 실시간 이벤트에 대한 직접 링크
'openAIRealtime:' 접두사를 추가하여 OpenAI Realtime 유틸리티 이벤트를 수신할 수도 있습니다.
openAIRealtime:conversation.created:
openAIRealtime:conversation.interrupted:
openAIRealtime:conversation.updated:
openAIRealtime:conversation.item.appended:
openAIRealtime:conversation.item.completed:
사용 가능한 음성사용 가능한 음성에 대한 직접 링크
다음과 같은 음성 옵션을 사용할 수 있습니다.
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에서 처리합니다.