> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 음성 상호작용

> 음성 입력 및 출력으로 상담원과 대화하세요.

# 음성 상호작용

지원되는 채널에서 음성을 사용하여 상담원과 소통하세요.

## 지원되는 엔진

### 텍스트 음성 변환(TTS)

상담원 음성 출력에 5개의 TTS 엔진을 사용할 수 있습니다.

**두 개의 TTS 경로(설계상):**

* **설정 > 음성** — 채널 응답, WebRTC 및 IM 음성 풍선(5개 공급자 + 무료 Edge 대체, 스트리밍, 스마트 요약)
* **에이전트 구성 TTS** — 채팅 명령 "소리내어 읽기"는 `tts_generate` 도구(OpenAI/ElevenLabs + 게이트웨이 청구)를 통해 **오디오 아티팩트**를 생성합니다.

두 경로 모두 프로덕션 테스트를 거쳤습니다. 632개 이상의 채널 음성 테스트 + 23개의 하네스 `llms/tts` 단위 테스트(98% 적용 범위).

### 음성 텍스트 변환(STT)

음성 입력 인식을 위한 5가지 STT 엔진: Local Whisper(무료, 개인 정보 보호 우선), OpenAI Whisper, Groq, Deepgram 및 xAI Grok STT. 사용자 정의 OpenAI 호환 엔드포인트도 기본 URL 설정을 통해 지원됩니다.

### 비디오 오디오 전사

비디오 메시지(텔레그램 원형 비디오 메모 포함)는 동일한 STT 파이프라인을 사용하여 자동으로 전사됩니다. 상담원은 별도의 구성 없이 영상 메시지의 내용을 이해합니다.

### 오디오 파일 업로드

WebUI 채팅 입력에 직접 오디오 파일을 업로드하세요. **8가지 형식** 지원: mp3, wav, ogg, flac, m4a, aac, wma, opus.

세 가지 업로드 방법:

* **첨부** 버튼을 클릭하여 파일을 선택하세요.
* **오디오 파일을 채팅 영역으로 드래그 앤 드롭**
* **붙여넣기**(일부 형식)

오디오 파일 크기 제한은 **25MB**입니다. 업로드된 파일은 STT 파이프라인을 통해 자동으로 기록되고 에이전트에 대한 컨텍스트로 삽입됩니다.

Tauri 데스크톱 클라이언트는 30개 이상의 파일 형식을 포괄하는 기본 파일 대화 상자를 통해 오디오 업로드도 지원합니다.

## 음성 모드

Myrm 에이전트는 설정 > 음성에서 선택할 수 있는 **4가지 음성 상호작용 모드**를 지원합니다.

| Mode            | Latency | Tool Calling            | Description                                                                  |
| --------------- | ------- | ----------------------- | ---------------------------------------------------------------------------- |
| Audio Only      | \~1-2s  | Via Agent Bridge        | Standard STT → Agent → TTS pipeline                                          |
| Agent Bridge    | \~1-2s  | Full Agent tools        | Server-side Agent handles the conversation with all capabilities             |
| OpenAI Realtime | \~200ms | Native Function Calling | WebRTC direct connection to OpenAI with tool declarations from Agent Profile |
| Gemini Live     | \~200ms | Native Function Calling | WebSocket to Google Gemini with video multimodal + tool declarations         |

### 기본 함수 호출(실시간 및 Gemini Live)

실시간 및 Gemini Live 모드에서는 선택한 에이전트 프로필에서 도구 선언이 동적으로 삽입됩니다. AI는 서버 측 에이전트 릴레이 없이 음성 대화 중에 직접 도구(웹 검색, 메모리, 파일 작업, 코드 실행, 브라우저, 칸반, 백그라운드 작업)를 호출할 수 있습니다. 이를 통해 300ms 미만의 도구 증강 음성 상호 작용이 가능해집니다.

### 음성 배경 작업

음성 대화 중에 "XXX를 검색해 주세요"와 같은 말을 하면 AI가 자동으로 이를 백그라운드 작업으로 전달합니다.

* **즉시 파견**: 단일 음성 명령으로 대화를 중단하지 않고 백그라운드 조사 작업을 생성합니다.
* **패널 가시성**: 발송된 작업은 원클릭 취소 또는 조정을 통해 활동 패널에 실시간으로 표시됩니다.
* **지속성**: 재시작 복구 및 좀비 감지 기능을 갖춘 Kanban 시스템을 통해 작업이 지속됩니다.
* **완료 알림**: 작업이 완료되면 원래 채팅에 결과가 자동으로 푸시됩니다.

### 백그라운드 작업 완료 통보

음성으로 파견한 백그라운드 작업이 완료되면 에이전트가 다음 음성 세션에서 **능동적으로 결과를 말해줍니다** — 네 가지 음성 모드(Audio Only / Agent Bridge / OpenAI Realtime / Gemini Live)가 완전히 대칭입니다.

* **말하고 떠나라, 돌아와서 결론을 들으세요**: 긴 작업을 음성으로 파견한 뒤 화면을 닫고 다른 일을 하다가 음성 세션에 돌아오면 에이전트가 결과 요약을 먼저 알려줍니다. 패널을 쳐다보거나 "다 됐어?"라고 물어볼 필요가 없습니다.
* **현재 발화를 절대 방해하지 않음**: 작업이 완료된 시점에 에이전트가 말하는 중이면, 완료 통보는 TTS 큐에서 안전하게 대기했다가 현재 발화가 끝나는 즉시 재생됩니다 — 큐 안전 삽입, 어색한 끊김 없음
* **통보는 대화의 일부**: 완료 통보는 채팅의 자연스러운 연속으로 음성 출력되며, 채팅 타임라인이 실시간으로 갱신되어 바로 세부 내용을 음성으로 물어볼 수 있고 에이전트가 전체 맥락으로 답합니다.
* **여러 창에서 중복 통보 없음**: 여러 창이나 기기를 동시에 열어도 활성 음성 세션에서만 정확히 한 번 통보됩니다 — 세션 범위 중복 제거.

## 전이중 및 바지인 인식

Myrm 에이전트는 **전이중 음성 대화**를 지원합니다. 에이전트가 말하는 동안 언제든지 에이전트를 중단할 수 있습니다(참여). 그렇게 할 때:

1. **TTS 재생이 즉시 중지됩니다**
2. **AI 모델은 이전 응답이 중단되었음을 자동으로 알립니다**. 이미 말한 내용을 반복하지 않고 자연스럽게 새로운 입력을 처리합니다.

이렇게 하면 음성 대화가 실제 사람과 대화하는 것처럼 느껴집니다. 방해로 인해 에이전트가 추적을 잃거나 반복하는 일이 발생하지 않습니다.

## 설정

1. **설정 > 음성**으로 이동하세요.
2. 선호하는 TTS 및 STT 엔진을 선택하세요.
3. 언어 및 음성 기본 설정 구성
4. 사용자 정의 STT 엔드포인트의 경우 기본 URL 필드를 설정합니다(OpenAI 및 xAI 공급자에 사용 가능).
5. 실시간 모드의 경우 설정 > 공급자에서 OpenAI API 키를 구성합니다.
6. Gemini 라이브 모드의 경우 설정 > 공급자에서 Google API 키를 구성하세요.

## 보안

모든 음성 데이터는 E2EE(End-to-End 암호화)로 처리됩니다. 명시적으로 구성하지 않는 한 오디오는 저장되지 않습니다.