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

# 음성.듣기()

그만큼`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')

**options.prompt** (`string`): Model의 전사를 안내할 텍스트

**options.language** (`string`): 언어 코드(예: 'en', 'fr', 'de')

### Google

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

**options.stream** (`boolean`): 스트리밍 인식을 사용할지 여부

**options.config** (`object`): Google Cloud Speech-to-Text API의 인식 구성

### 딥그램

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

**options.model** (`string`): 전사에 사용할 Deepgram Model

**options.language** (`string`): 전사에 사용할 언어 코드

## 사용예

```typescript
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에 작업을 위임합니다.

```typescript
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`:

```typescript
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 참고 문서](https://mastra.zisheng.pro/ko/reference/voice/composite-voice)를 참조하세요.

## 실시간 음성 Provider

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

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

```typescript
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는 텍스트가 전사되는 대로 반환하는 스트리밍 전사를 지원합니다.
- 최상의 성능을 위해 사용을 마치면 오디오 스트림을 닫거나 종료하는 것이 좋습니다.

## 관련 방법

- [음성.말하기()](https://mastra.zisheng.pro/ko/reference/voice/voice.speak): 텍스트를 음성으로 변환합니다.
- [음성.전송()](https://mastra.zisheng.pro/ko/reference/voice/voice.send): 실시간으로 음성 제공자에게 오디오 데이터를 전송합니다.
- [음성.온()](https://mastra.zisheng.pro/ko/reference/voice/voice.on): 음성 이벤트에 대한 이벤트 리스너를 등록합니다.