> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # 마스트라보이스 MastraVoice 클래스는 Mastra의 음성 서비스에 대한 핵심 인터페이스를 정의하는 추상 기본 클래스입니다. 모든 음성 제공자 구현(예: OpenAI, Deepgram, PlayAI, Speechify)은 이 클래스를 확장하여 특정 기능을 제공합니다. 이제 클래스에는 WebSocket 연결을 통한 실시간 음성 간 기능 지원이 포함됩니다. ## 사용예 ```typescript import { MastraVoice } from '@mastra/core/voice' // Create a voice provider implementation class MyVoiceProvider extends MastraVoice { constructor(config: { speechModel?: BuiltInModelConfig listeningModel?: BuiltInModelConfig speaker?: string realtimeConfig?: { model?: string apiKey?: string options?: unknown } }) { super({ speechModel: config.speechModel, listeningModel: config.listeningModel, speaker: config.speaker, realtimeConfig: config.realtimeConfig, }) } // Implement required abstract methods async speak( input: string | NodeJS.ReadableStream, options?: { speaker?: string }, ): Promise { // Implement text-to-speech conversion } async listen( audioStream: NodeJS.ReadableStream, options?: unknown, ): Promise { // Implement speech-to-text conversion } async getSpeakers(): Promise> { // Return list of available voices } // Optional speech-to-speech methods async connect(): Promise { // Establish WebSocket connection for speech-to-speech communication } async send(audioData: NodeJS.ReadableStream | Int16Array): Promise { // Stream audio data in speech-to-speech } async answer(): Promise { // Trigger voice provider to respond } addTools(tools: Array): void { // Add tools for the voice provider to use } close(): void { // Close WebSocket connection } on(event: string, callback: (data: unknown) => void): void { // Register event listener } off(event: string, callback: (data: unknown) => void): void { // Remove event listener } } ``` ## 생성자 매개변수 **config** (`VoiceConfig`): 음성 서비스의 구성 객체입니다. **config.speechModel** (`BuiltInModelConfig`): 텍스트 음성 변환 Model의 구성입니다. **config.speechModel.name** (`string`): 사용할 Model의 이름입니다. **config.speechModel.apiKey** (`string`): Model 서비스의 API 키입니다. **config.listeningModel** (`BuiltInModelConfig`): 음성 텍스트 변환 Model의 구성입니다. **config.listeningModel.name** (`string`): 사용할 Model의 이름 **config.listeningModel.apiKey** (`string`): Model 서비스의 API 키 **config.speaker** (`string`): 사용할 기본 화자/음성 ID **config.name** (`string`): 음성 Provider 인스턴스의 이름 **config.realtimeConfig** (`object`): 실시간 음성 대 음성 기능의 구성 **config.realtimeConfig.model** (`string`): 실시간 음성 대 음성 기능에 사용할 Model **config.realtimeConfig.apiKey** (`string`): 실시간 서비스의 API 키 **config.realtimeConfig.options** (`unknown`): 실시간 기능에 대한 Provider별 옵션 ## 추상 메소드 이러한 메서드는 MastraVoice를 확장하는 알 수 없는 클래스로 구현되어야 합니다. ### `speak()` 구성된 음성 Model을 사용하여 텍스트를 음성으로 변환합니다. ```typescript abstract speak( input: string | NodeJS.ReadableStream, options?: { speaker?: string; [key: string]: unknown; } ): Promise ``` 목적: - 공급자의 텍스트 음성 변환 서비스를 사용하여 텍스트 입력을 받아 음성으로 변환합니다. - 유연성을 위해 문자열 및 스트림 입력을 모두 지원합니다. - 옵션을 통해 기본 스피커/음성을 재정의할 수 있습니다. - 재생하거나 저장할 수 있는 오디오 데이터 스트림을 반환합니다. - '말하기' 이벤트를 발생시켜 오디오를 처리하는 경우 무효가 반환될 수 있습니다. ### `listen()` 구성된 청취 Model을 사용하여 음성을 텍스트로 변환합니다. ```typescript abstract listen( audioStream: NodeJS.ReadableStream, options?: { [key: string]: unknown; } ): Promise ``` 목적: - 오디오 스트림을 가져와 공급자의 음성-텍스트 서비스를 사용하여 텍스트로 변환합니다. - 전사 구성을 위한 공급자별 옵션 지원 - 완전한 텍스트 전사 또는 전사된 텍스트 스트림을 반환할 수 있습니다. - 모든 공급자가 이 기능을 지원하는 것은 아닙니다(예: PlayAI, Speechify) - 'writing' 이벤트를 발생시켜 전사를 처리하는 경우 void를 반환할 수 있습니다. ### `getSpeakers()` 공급자가 지원하는 사용 가능한 음성 목록을 반환합니다. ```typescript abstract getSpeakers(): Promise> ``` 목적: - 공급자로부터 사용 가능한 음성/스피커 목록을 검색합니다. - 각 음성에는 최소한 voiceId 속성이 있어야 합니다. - 공급자는 각 음성에 대한 추가 메타데이터를 포함할 수 있습니다. - 텍스트 음성 변환에 사용 가능한 음성을 검색하는 데 사용됩니다. ## 선택적 방법 이러한 메서드에는 기본 구현이 있지만 음성-음성 기능을 지원하는 음성 공급자가 재정의할 수 있습니다. ### `connect()` 통신을 위해 WebSocket 또는 WebRTC 연결을 설정합니다. ```typescript connect(config?: unknown): Promise ``` 목적: - 통신을 위해 음성 서비스 연결을 초기화합니다. - send() 또는 Answer()와 같은 기능을 사용하기 전에 호출해야 합니다. - 연결이 설정되면 해결되는 Promise를 반환합니다. - 구성은 공급자별로 다릅니다. ### `send()` 오디오 데이터를 실시간으로 음성 Provider에 스트리밍합니다. ```typescript send(audioData: NodeJS.ReadableStream | Int16Array): Promise ``` 목적: - 실시간 처리를 위해 오디오 데이터를 음성 공급자에게 보냅니다. - 라이브 마이크 입력과 같은 지속적인 오디오 스트리밍 시나리오에 유용합니다. - ReadableStream 및 Int16Array 오디오 형식을 모두 지원합니다. - 이 메서드를 호출하기 전에 연결된 상태여야 합니다. ### `answer()` 응답을 생성하기 위해 음성 제공자를 트리거합니다. ```typescript answer(): Promise ``` 목적: - 응답을 생성하기 위해 음성 제공자에게 신호를 보냅니다. - AI가 응답하도록 유도하기 위해 실시간 대화에 사용됩니다. - 응답은 이벤트 시스템(예: '말하기' 이벤트)을 통해 방출됩니다. ### `addTools()` 음성 제공자에게 대화 중에 사용할 수 있는 Tool을 제공합니다. ```typescript addTools(tools: Array): void ``` 목적: - 음성 제공자가 대화 중에 사용할 수 있는 Tool을 추가합니다. - Tool은 음성 제공자의 기능을 확장할 수 있습니다. - 구현은 공급자마다 다릅니다. ### `close()` WebSocket 또는 WebRTC 연결을 끊습니다. ```typescript close(): void ``` 목적: - 음성 서비스 연결을 종료합니다. - 리소스를 정리하고 진행 중인 실시간 처리를 중지합니다. - 음성 인스턴스가 완료되면 호출되어야 합니다. ### `on()` 음성 이벤트에 대한 이벤트 리스너를 등록합니다. ```typescript on( event: E, callback: (data: E extends keyof VoiceEventMap ? VoiceEventMap[E] : unknown) => void, ): void ``` 목적: - 특정 이벤트 발생 시 호출될 콜백 함수를 등록합니다. - 표준 이벤트에는 '말하기', '쓰기', '오류'가 포함됩니다. - 공급자는 사용자 정의 이벤트도 내보낼 수 있습니다. - 이벤트 데이터 구조는 이벤트 유형에 따라 다릅니다. ### `off()` 이벤트 리스너를 제거합니다. ```typescript off( event: E, callback: (data: E extends keyof VoiceEventMap ? VoiceEventMap[E] : unknown) => void, ): void ``` 목적: - 이전에 등록된 이벤트 리스너를 제거합니다. - 더 이상 필요하지 않은 이벤트 핸들러를 정리하는 데 사용됩니다. ## 이벤트 시스템 MastraVoice 클래스에는 실시간 통신을 위한 이벤트 시스템이 포함되어 있습니다. 표준 이벤트 유형은 다음과 같습니다. **speaking** (`{ text: string; audioStream?: NodeJS.ReadableStream; audio?: Int16Array }`): 음성 Provider가 말할 때 발생하며 오디오 데이터를 포함합니다 **writing** (`{ text: string, role: string }`): 음성이 텍스트로 변환될 때 발생합니다 **error** (`{ message: string; code?: string; details?: unknown }`): 오류가 발생할 때 발생합니다 ## 보호되는 속성 **listeningModel** (`BuiltInModelConfig | undefined`): 음성-텍스트 변환 Model의 구성 **speechModel** (`BuiltInModelConfig | undefined`): 텍스트-음성 변환 Model의 구성 **speaker** (`string | undefined`): 기본 화자/음성 ID **realtimeConfig** (`{ model?: string; apiKey?: string; options?: unknown } | undefined`): 실시간 음성 대 음성 기능의 구성 ## 원격 측정 지원 MastraVoice에는 메서드 호출을 성능 추적 및 오류 모니터링으로 래핑하는 `traced` 메서드를 통한 기본 원격 측정 지원이 포함되어 있습니다. ## 메모 - MastraVoice는 추상 클래스이므로 직접 인스턴스화할 수 없습니다. - 구현은 모든 추상 메서드에 대한 구체적인 구현을 제공해야 합니다. - 클래스는 다양한 음성 서비스 제공자 간에 일관된 인터페이스를 제공합니다. - 음성 대 음성 기능은 선택 사항이며 공급자별로 다릅니다. - 이벤트 시스템은 실시간 상호 작용을 위한 비동기 통신을 가능하게 합니다. - 모든 메서드 호출에 대해 원격 분석이 자동으로 처리됩니다.