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

# 음성-텍스트(STT)

Mastra의 STT(Speech-to-Text)는 여러 서비스 Provider를 통해 오디오 입력을 텍스트로 변환할 수 있는 표준화된 인터페이스를 제공합니다. STT를 사용하면 음성 지원 애플리케이션이 사람의 음성에 응답할 수 있습니다. 핸즈프리 상호 작용을 지원하고 장애가 있는 사용자의 접근성을 높이며, 더욱 자연스러운 인터페이스를 제공합니다.

## 구성

Mastra에서 STT를 사용하려면 음성 Provider를 초기화할 때 `listeningModel`을 구성하세요. 여기에는 다음과 같은 매개변수가 포함됩니다.

- **`name`**: 사용할 특정 STT Model입니다.
- **`apiKey`**: 인증을 위한 API 키입니다.
- **공급자별 옵션**: 특정 음성 Provider에서 요구하거나 지원할 수 있는 추가 옵션입니다.

**행동**: 이 매개변수는 모두 선택사항입니다. 사용 중인 특정 공급자에 따라 달라지는 음성 공급자가 제공하는 기본 설정을 사용할 수 있습니다.

```typescript
const voice = new OpenAIVoice({
  listeningModel: {
    name: 'whisper-1',
    apiKey: process.env.OPENAI_API_KEY,
  },
})

// If using default settings the configuration can be simplified to:
const voice = new OpenAIVoice()
```

## 이용 가능한 Provider

Mastra는 각각 고유한 기능과 장점을 갖춘 여러 Speech-to-Text Provider를 지원합니다.

- [**OpenAI**](https://mastra.zisheng.pro/ko/reference/voice/openai): Whisper Model을 사용한 고정밀 음성 기록
- [**Azure**](https://mastra.zisheng.pro/ko/reference/voice/azure): 엔터프라이즈급 안정성을 갖춘 Microsoft의 음성 인식
- [**ElevenLabs**](https://mastra.zisheng.pro/ko/reference/voice/elevenlabs): 다국어를 지원하는 고급 음성 인식
- [**Google**](https://mastra.zisheng.pro/ko/reference/voice/google): 폭넓은 언어를 지원하는 Google의 음성 인식
- [**Cloudflare**](https://mastra.zisheng.pro/ko/reference/voice/cloudflare): 지연 시간이 짧은 애플리케이션을 위한 엣지 최적화 음성 인식
- [**Deepgram**](https://mastra.zisheng.pro/ko/reference/voice/deepgram): 다양한 억양을 정확하게 인식하는 AI 기반 음성 인식
- [**Sarvam**](https://mastra.zisheng.pro/ko/reference/voice/sarvam): 인도 언어 및 억양에 특화 각 공급자는 필요에 따라 설치할 수 있는 별도의 패키지로 구현됩니다.

```bash
pnpm add @mastra/voice-openai@latest  # Example for OpenAI
```

## 듣기 방법 사용

STT의 기본 메서드는 음성 오디오를 텍스트로 변환하는 `listen()`입니다. 사용 방법은 다음과 같습니다.

```typescript
import { Agent } from '@mastra/core/agent'
import { OpenAIVoice } from '@mastra/voice-openai'
import { getMicrophoneStream } from '@mastra/node-audio'

const voice = new OpenAIVoice()

const agent = new Agent({
  id: 'voice-agent',
  name: 'Voice Agent',
  instructions: 'You are a voice assistant that provides recommendations based on user input.',
  model: 'openai/gpt-5.6-sol',
  voice,
})

const audioStream = getMicrophoneStream() // Assume this function gets audio input

const transcript = await agent.voice.listen(audioStream, {
  filetype: 'm4a', // Optional: specify the audio file type
})

console.log(`User said: ${transcript}`)

const { text } = await agent.generate(
  `Based on what the user said, provide them a recommendation: ${transcript}`,
)

console.log(`Recommendation: ${text}`)
```

## 오디오 파일 녹음

`listen()` 메서드는 마이크 또는 파일의 오디오 데이터 스트림을 받습니다. 오디오 파일을 전사하려면 `createReadStream()`을 사용하세요.

```typescript
import { createReadStream } from 'fs'
import path from 'path'

const audioFilePath = path.join(process.cwd(), 'agent.m4a')
const audioStream = createReadStream(audioFilePath)

const transcription = await agent.voice.listen(audioStream, {
  filetype: 'm4a',
})

console.log(`Transcription: ${transcription}`)
```

Agent의 음성 Provider에 관한 전반적인 개요는 [Mastra의 음성 기능](https://mastra.zisheng.pro/ko/guides/voice/overview)을 참조하세요.