마스트라보이스

MastraVoice 클래스는 Mastra의 음성 서비스에 대한 핵심 인터페이스를 정의하는 추상 기본 클래스입니다. 모든 음성 제공자 구현(예: OpenAI, Deepgram, PlayAI, Speechify)은 이 클래스를 확장하여 특정 기능을 제공합니다. 이제 클래스에는 WebSocket 연결을 통한 실시간 음성 간 기능 지원이 포함됩니다.

사용예

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<NodeJS.ReadableStream | void> {
    // Implement text-to-speech conversion
  }

  async listen(
    audioStream: NodeJS.ReadableStream,
    options?: unknown,
  ): Promise<string | NodeJS.ReadableStream | void> {
    // Implement speech-to-text conversion
  }

  async getSpeakers(): Promise<Array<{ voiceId: string; [key: string]: unknown }>> {
    // Return list of available voices
  }

  // Optional speech-to-speech methods
  async connect(): Promise<void> {
    // Establish WebSocket connection for speech-to-speech communication
  }

  async send(audioData: NodeJS.ReadableStream | Int16Array): Promise<void> {
    // Stream audio data in speech-to-speech
  }

  async answer(): Promise<void> {
    // Trigger voice provider to respond
  }

  addTools(tools: Array<unknown>): 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의 구성입니다.

BuiltInModelConfig

name:

string

사용할 Model의 이름입니다.

apiKey?:

string

Model 서비스의 API 키입니다.

config.listeningModel?:

BuiltInModelConfig

음성 텍스트 변환 Model의 구성입니다.

BuiltInModelConfig

name:

string

사용할 Model의 이름

apiKey?:

string

Model 서비스의 API 키

config.speaker?:

string

사용할 기본 화자/음성 ID

config.name?:

string

음성 Provider 인스턴스의 이름

config.realtimeConfig?:

object

실시간 음성 대 음성 기능의 구성

object

model?:

string

실시간 음성 대 음성 기능에 사용할 Model

apiKey?:

string

실시간 서비스의 API 키

options?:

unknown

실시간 기능에 대한 Provider별 옵션

추상 메소드

이러한 메서드는 MastraVoice를 확장하는 알 수 없는 클래스로 구현되어야 합니다.

speak()

구성된 음성 Model을 사용하여 텍스트를 음성으로 변환합니다.

abstract speak(
  input: string | NodeJS.ReadableStream,
  options?: {
    speaker?: string;
    [key: string]: unknown;
  }
): Promise<NodeJS.ReadableStream | void>

목적:

• 공급자의 텍스트 음성 변환 서비스를 사용하여 텍스트 입력을 받아 음성으로 변환합니다.
• 유연성을 위해 문자열 및 스트림 입력을 모두 지원합니다.
• 옵션을 통해 기본 스피커/음성을 재정의할 수 있습니다.
• 재생하거나 저장할 수 있는 오디오 데이터 스트림을 반환합니다.
• '말하기' 이벤트를 발생시켜 오디오를 처리하는 경우 무효가 반환될 수 있습니다.

listen()

구성된 청취 Model을 사용하여 음성을 텍스트로 변환합니다.

abstract listen(
  audioStream: NodeJS.ReadableStream,
  options?: {
    [key: string]: unknown;
  }
): Promise<string | NodeJS.ReadableStream | void>

목적:

• 오디오 스트림을 가져와 공급자의 음성-텍스트 서비스를 사용하여 텍스트로 변환합니다.
• 전사 구성을 위한 공급자별 옵션 지원
• 완전한 텍스트 전사 또는 전사된 텍스트 스트림을 반환할 수 있습니다.
• 모든 공급자가 이 기능을 지원하는 것은 아닙니다(예: PlayAI, Speechify)
• 'writing' 이벤트를 발생시켜 전사를 처리하는 경우 void를 반환할 수 있습니다.

getSpeakers()

공급자가 지원하는 사용 가능한 음성 목록을 반환합니다.

abstract getSpeakers(): Promise<Array<{ voiceId: string; [key: string]: unknown }>>

목적:

• 공급자로부터 사용 가능한 음성/스피커 목록을 검색합니다.
• 각 음성에는 최소한 voiceId 속성이 있어야 합니다.
• 공급자는 각 음성에 대한 추가 메타데이터를 포함할 수 있습니다.
• 텍스트 음성 변환에 사용 가능한 음성을 검색하는 데 사용됩니다.

선택적 방법

이러한 메서드에는 기본 구현이 있지만 음성-음성 기능을 지원하는 음성 공급자가 재정의할 수 있습니다.

connect()

통신을 위해 WebSocket 또는 WebRTC 연결을 설정합니다.

connect(config?: unknown): Promise<void>

목적:

• 통신을 위해 음성 서비스 연결을 초기화합니다.
• send() 또는 Answer()와 같은 기능을 사용하기 전에 호출해야 합니다.
• 연결이 설정되면 해결되는 Promise를 반환합니다.
• 구성은 공급자별로 다릅니다.

send()

오디오 데이터를 실시간으로 음성 Provider에 스트리밍합니다.

send(audioData: NodeJS.ReadableStream | Int16Array): Promise<void>

목적:

• 실시간 처리를 위해 오디오 데이터를 음성 공급자에게 보냅니다.
• 라이브 마이크 입력과 같은 지속적인 오디오 스트리밍 시나리오에 유용합니다.
• ReadableStream 및 Int16Array 오디오 형식을 모두 지원합니다.
• 이 메서드를 호출하기 전에 연결된 상태여야 합니다.

answer()

응답을 생성하기 위해 음성 제공자를 트리거합니다.

answer(): Promise<void>

목적:

• 응답을 생성하기 위해 음성 제공자에게 신호를 보냅니다.
• AI가 응답하도록 유도하기 위해 실시간 대화에 사용됩니다.
• 응답은 이벤트 시스템(예: '말하기' 이벤트)을 통해 방출됩니다.

addTools()

음성 제공자에게 대화 중에 사용할 수 있는 Tool을 제공합니다.

addTools(tools: Array<Tool>): void

목적:

• 음성 제공자가 대화 중에 사용할 수 있는 Tool을 추가합니다.
• Tool은 음성 제공자의 기능을 확장할 수 있습니다.
• 구현은 공급자마다 다릅니다.

close()

WebSocket 또는 WebRTC 연결을 끊습니다.

close(): void

목적:

• 음성 서비스 연결을 종료합니다.
• 리소스를 정리하고 진행 중인 실시간 처리를 중지합니다.
• 음성 인스턴스가 완료되면 호출되어야 합니다.

on()

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

on<E extends VoiceEventType>(
  event: E,
  callback: (data: E extends keyof VoiceEventMap ? VoiceEventMap[E] : unknown) => void,
): void

목적:

• 특정 이벤트 발생 시 호출될 콜백 함수를 등록합니다.
• 표준 이벤트에는 '말하기', '쓰기', '오류'가 포함됩니다.
• 공급자는 사용자 정의 이벤트도 내보낼 수 있습니다.
• 이벤트 데이터 구조는 이벤트 유형에 따라 다릅니다.

off()

이벤트 리스너를 제거합니다.

off<E extends VoiceEventType>(
  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는 추상 클래스이므로 직접 인스턴스화할 수 없습니다.
• 구현은 모든 추상 메서드에 대한 구체적인 구현을 제공해야 합니다.
• 클래스는 다양한 음성 서비스 제공자 간에 일관된 인터페이스를 제공합니다.
• 음성 대 음성 기능은 선택 사항이며 공급자별로 다릅니다.
• 이벤트 시스템은 실시간 상호 작용을 위한 비동기 통신을 가능하게 합니다.
• 모든 메서드 호출에 대해 원격 분석이 자동으로 처리됩니다.