음성.듣기()

그만큼listen()방식은 음성을 텍스트로 변환하는 모든 Mastra 음성 Provider에서 사용할 수 있는 핵심 기능입니다. 오디오 스트림을 입력으로 사용하고 기록된 텍스트를 반환합니다.

매개변수

audioStream:

NodeJS.ReadableStream

전사할 오디오 스트림입니다. 파일 스트림이나 마이크 스트림일 수 있습니다.

options?:

object

음성 인식을 위한 Provider별 옵션

반환 값

다음 중 하나를 반환합니다.

• Promise<string>: 전사된 텍스트로 해결되는 약속
• Promise<NodeJS.ReadableStream>: 전사된 텍스트 스트림으로 해결되는 약속(스트리밍 전사의 경우)
• Promise<void>: 텍스트를 직접 반환하는 대신 '쓰기' 이벤트를 발생시키는 실시간 공급자의 경우

공급자별 옵션

각 음성 Provider는 구현에 따른 추가 옵션을 지원할 수 있습니다. 다음은 몇 가지 예입니다.

오픈AI

options?:

Options

구성 옵션입니다.

Options

filetype?:

string

오디오 파일 형식(예: 'mp3', 'wav', 'm4a')

prompt?:

string

Model의 전사를 안내할 텍스트

language?:

string

언어 코드(예: 'en', 'fr', 'de')

Google

options?:

Options

구성 옵션입니다.

Options

stream?:

boolean

스트리밍 인식을 사용할지 여부

config?:

object

Google Cloud Speech-to-Text API의 인식 구성

딥그램

options?:

Options

구성 옵션입니다.

Options

model?:

string

전사에 사용할 Deepgram Model

language?:

string

전사에 사용할 언어 코드

사용예

import { OpenAIVoice } from '@mastra/voice-openai'
import { getMicrophoneStream } from '@mastra/node-audio'
import { createReadStream } from 'fs'
import path from 'path'

// Initialize a voice provider
const voice = new OpenAIVoice({
  listeningModel: {
    name: 'whisper-1',
    apiKey: process.env.OPENAI_API_KEY,
  },
})

// Basic usage with a file stream
const audioFilePath = path.join(process.cwd(), 'audio.mp3')
const audioStream = createReadStream(audioFilePath)
const transcript = await voice.listen(audioStream, {
  filetype: 'mp3',
})
console.log('Transcribed text:', transcript)

// Using a microphone stream
const microphoneStream = getMicrophoneStream() // Assume this function gets audio input
const transcription = await voice.listen(microphoneStream)

// With provider-specific options
const transcriptWithOptions = await voice.listen(audioStream, {
  language: 'en',
  prompt: 'This is a conversation about artificial intelligence.',
})

함께 사용CompositeVoice

CompositeVoice를 사용하면 listen() 메서드가 구성된 듣기 Provider에 작업을 위임합니다.

import { CompositeVoice } from '@mastra/core/voice'
import { OpenAIVoice } from '@mastra/voice-openai'
import { PlayAIVoice } from '@mastra/voice-playai'

const voice = new CompositeVoice({
  input: new OpenAIVoice(),
  output: new PlayAIVoice(),
})

// This will use the OpenAIVoice provider
const transcript = await voice.listen(audioStream)

AI SDK Model 공급자 사용

AI SDK 전사 Model을 직접 사용할 수도 있습니다.CompositeVoice:

import { CompositeVoice } from '@mastra/core/voice'
import { openai } from '@ai-sdk/openai'
import { groq } from '@ai-sdk/groq'

// Use AI SDK transcription models
const voice = new CompositeVoice({
  input: openai.transcription('whisper-1'), // AI SDK model
  output: new PlayAIVoice(), // Mastra provider
})

// Works the same way
const transcript = await voice.listen(audioStream)

// Provider-specific options can be passed through
const transcriptWithOptions = await voice.listen(audioStream, {
  providerOptions: {
    openai: {
      language: 'en',
      prompt: 'This is about AI',
    },
  },
})

AI SDK 통합에 관한 자세한 내용은 CompositeVoice 참고 문서를 참조하세요.

실시간 음성 Provider

OpenAIRealtimeVoice와 같은 실시간 음성 Provider를 사용할 때 listen() 메서드는 다르게 동작합니다.

• 전사된 텍스트를 반환하는 대신 전사된 텍스트와 함께 '쓰기' 이벤트를 발생시킵니다.
• 텍스트 변환을 수신하려면 이벤트 리스너를 등록해야 합니다.

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

const voice = new OpenAIRealtimeVoice()
await voice.connect()

// Register event listener for transcription
voice.on('writing', ({ text, role }) => {
  console.log(`${role}: ${text}`)
})

// This will emit 'writing' events instead of returning text
const microphoneStream = getMicrophoneStream()
await voice.listen(microphoneStream)

메모

• 모든 음성 Provider가 음성-텍스트 기능을 지원하는 것은 아닙니다(예: PlayAI, Speechify).
• listen()의 동작은 Provider마다 조금씩 다를 수 있지만 모든 구현은 동일한 기본 인터페이스를 따릅니다.
• 실시간 음성 Provider를 사용할 때 메서드는 텍스트를 직접 반환하지 않고 대신 'writing' 이벤트를 방출할 수 있습니다.
• 지원되는 오디오 형식은 Provider마다 다릅니다. 일반적인 형식으로는 MP3, WAV, M4A가 있습니다.
• 일부 Provider는 텍스트가 전사되는 대로 반환하는 스트리밍 전사를 지원합니다.
• 최상의 성능을 위해 사용을 마치면 오디오 스트림을 닫거나 종료하는 것이 좋습니다.

관련 방법

• 음성.말하기(): 텍스트를 음성으로 변환합니다.
• 음성.전송(): 실시간으로 음성 제공자에게 오디오 데이터를 전송합니다.
• 음성.온(): 음성 이벤트에 대한 이벤트 리스너를 등록합니다.