음성, TTS, 전사

음성 통화 채널, 웨이크워드 캡처, ClawdTalk SIP, 그리고 공유 TTS/전사/미디어/링크 보강 서브시스템.

Revka는 텍스트 입력뿐만 아니라 말하고 들을 수 있습니다. 이 페이지에서는 세 가지 음성 채널 — 멀티 프로바이더 Voice Call 채널(Twilio / Telnyx / Plivo), 로컬 마이크 기반 Voice Wake 웨이크워드 감지기, ClawdTalk(Telnyx SIP) — 과 음성 및 텍스트 채널이 함께 사용하는 네 가지 공유 서브시스템: TTS(텍스트 음성 변환), Transcription(음성 텍스트 변환), 미디어 파이프라인, 링크 보강기를 설명합니다.

TTS, 전사, 미디어 파이프라인, 링크 보강기는 ~/.revka/config.toml의 최상위 레벨에서 한 번 설정하면 필요한 채널에서 모두 사용합니다. 음성 채널은 다른 채널과 동일하게 [channels_config] 아래에 위치합니다. 채널을 처음 연결하는 경우라면 채널 개요에서 공유 트레이트 모델, 허용 목록 동작 방식, 폴링과 웹훅의 차이에 대해 먼저 읽어보시기 바랍니다.

Voice Call

Voice Call 채널은 Twilio, Telnyx, Plivo 중 하나의 통신 프로바이더를 통해 실시간 인바운드 및 아웃바운드 전화 통화를 처리하며, provider 키 하나로 프로바이더를 선택합니다. 통화 중 음성-텍스트 변환과 텍스트-음성 변환을 스트리밍하고, 선택적으로 전체 통화 기록을 워크스페이스에 저장하며, 아웃바운드 통화는 승인 워크플로우를 통해 제어합니다. 통신 프로바이더는 통화 이벤트를 Revka의 웹훅으로 POST 요청 형태로 전송하며, Revka는 이를 에이전트 루프용 채널 메시지로 변환합니다.

[channels_config.voice_call]
provider = "twilio"               # twilio | telnyx | plivo
account_id = "ACxxxxxxxxxxxxxxxx" # Twilio Account SID / Telnyx API Key / Plivo Auth ID
auth_token = "your-auth-token"    # Twilio auth token / Telnyx API secret / Plivo auth token
from_number = "+15551234567"      # E.164 caller ID for outbound calls
webhook_port = 8090
require_outbound_approval = true
transcription_logging = true
# tts_voice = "Polly.Joanna"      # provider-specific voice name
max_call_duration_secs = 3600
# webhook_base_url = "https://your-tunnel.example.com"

필드	타입 / 값	기본값	설명
`provider`	`"twilio"` \| `"telnyx"` \| `"plivo"`	`"twilio"`	통신 프로바이더.
`account_id`	string (필수)	—	Twilio Account SID, Telnyx API Key, 또는 Plivo Auth ID.
`auth_token`	string (필수)	—	Twilio auth token, Telnyx API secret, 또는 Plivo auth token.
`from_number`	string (필수)	—	아웃바운드 통화에 사용할 E.164 발신자 ID.
`webhook_port`	integer	`8090`	통신 프로바이더 웹훅을 수신할 포트.
`require_outbound_approval`	bool	`true`	아웃바운드 통화 전 사람의 승인을 요구합니다.
`transcription_logging`	bool	`true`	전체 통화 기록을 워크스페이스 디렉터리에 저장합니다.
`tts_voice`	string (선택)	—	통화 음성에 사용할 프로바이더별 음성 이름(예: `Polly.Joanna`).
`max_call_duration_secs`	integer	`3600`	통화 최대 길이 제한(초 단위).
`webhook_base_url`	string (선택)	자동 감지	웹훅 콜백에 사용할 공개 URL 재정의(예: ngrok / Tailscale 터널).

통신 프로바이더는 통화 이벤트를 웹훅(푸시) 방식으로 전달하므로 Voice Call에는 외부에서 접근 가능한 HTTPS 콜백 URL이 필요합니다. webhook_base_url에 공개 주소를 설정하거나, 터널을 통해 게이트웨이를 외부에 노출하세요 — 터널로 게이트웨이 노출하기를 참고하시기 바랍니다.

Voice Wake

Voice Wake는 호스트 머신의 마이크를 항상 대기 중인 웨이크워드 트리거로 활용합니다. cpal을 통해 기본 오디오 입력을 지속적으로 수신하고, 에너지 기반 음성 활동 감지(VAD)를 사용해 음성을 감지하며, 짧은 구간을 전사해 설정된 웨이크워드가 포함되어 있는지 확인합니다. 웨이크워드가 감지되면 전체 발화를 캡처해 에이전트로 전송합니다. 내부적으로 Listening → Triggered → Capturing → Processing의 네 가지 상태 머신으로 동작합니다.

[channels_config.voice_wake]
wake_word = "hey revka"
silence_timeout_ms = 2000
energy_threshold = 0.01
max_capture_secs = 30

필드	타입	기본값	설명
`wake_word`	string	`"hey revka"`	트리거 구간에서 대소문자 구분 없이 일치하는 부분 문자열.
`silence_timeout_ms`	integer	`2000`	마지막 에너지 스파이크 이후 캡처를 완료하기까지의 무음 시간(ms).
`energy_threshold`	float	`0.01`	VAD의 RMS 임계값; 이 값 이하의 샘플은 무음으로 처리됩니다.
`max_capture_secs`	integer	`30`	전사가 강제 실행되기 전까지의 최대 캡처 길이.

Voice Wake는 최상위 [transcription] 섹션도 반드시 필요합니다 — 자체 STT 엔진이 없으며, 캡처된 오디오를 텍스트로 변환하기 위해 공유 전사 서브시스템을 사용합니다. 활성화 전에 전사 설정을 먼저 완료하세요.

피처를 활성화해 빌드하려면:

cargo build --release --locked --features voice-wake

[channels_config.voice_wake]가 설정되어 있지만 해당 플래그 없이 빌드된 바이너리라면, Revka는 오류 없이 해당 채널을 건너뜁니다 — revka channel list와 revka channel doctor에서 이 빌드에서는 건너뜀으로 표시됩니다.

ClawdTalk

ClawdTalk는 Telnyx 글로벌 SIP 네트워크 위에 구축된 전용 AI 음성 채널로, 통화 관리에 Telnyx API v2(https://api.telnyx.com/v2)를 사용합니다. 멀티 프로바이더 Voice Call 채널과는 구별됩니다. Voice Call이 세 가지 통신 벤더를 추상화하는 반면, ClawdTalk는 Telnyx SIP에 특화되어 저지연 대화형 통화에 최적화되어 있습니다. 인바운드 통화 이벤트는 선택적 서명 검증을 통해 웹훅으로 수신됩니다.

[channels_config.clawdtalk]
api_key = "KEY01xxxxxxxxxxxxxxxx"     # Telnyx API key (required)
connection_id = "telnyx-connection-id" # Telnyx SIP connection (required)
from_number = "+15551234567"           # E.164 caller ID (required)
allowed_destinations = []              # empty = allow all destinations
# webhook_secret = "telnyx-webhook-secret"

필드	타입	기본값	설명
`api_key`	string (필수)	—	Telnyx API 키.
`connection_id`	string (필수)	—	Telnyx SIP 연결 ID.
`from_number`	string (필수)	—	아웃바운드 통화에 사용할 E.164 발신자 ID.
`allowed_destinations`	list	`[]` → 모두 허용	목적지 번호 접두사/패턴 또는 `"*"`. 빈 목록은 모든 목적지를 허용합니다.
`webhook_secret`	string (선택)	—	인바운드 이벤트 검증을 위한 Telnyx 웹훅 서명 시크릿.

TTS (텍스트 음성 변환)

[tts] 섹션은 음성 채널(및 WhatsApp Web)에서 사용하는 공유 멀티 프로바이더 음성 합성 서브시스템입니다. 직접 호출하는 것이 아니라 채널에서 에이전트의 텍스트를 오디오로 변환해야 할 때 자동으로 호출됩니다. 지원 프로바이더: OpenAI, ElevenLabs, Google Cloud TTS, Edge TTS(무료 서브프로세스 기반 백엔드), Piper(로컬 OpenAI 호환 엔드포인트).

[tts]
enabled = true
default_provider = "openai"       # openai | elevenlabs | google | edge | piper
default_voice = "alloy"
default_format = "mp3"            # mp3 | opus | wav
max_text_length = 4096

[tts.openai]
# api_key = "..."                 # falls back to OPENAI_API_KEY
model = "tts-1"
speed = 1.0

[tts.elevenlabs]
# api_key = "..."                 # falls back to ELEVENLABS_API_KEY
model_id = "eleven_monolingual_v1"
stability = 0.5
similarity_boost = 0.5

[tts.google]
# api_key = "..."                 # falls back to GOOGLE_TTS_API_KEY
language_code = "en-US"

[tts.edge]
binary_path = "edge-tts"

[tts.piper]
api_url = "http://127.0.0.1:5000/v1/audio/speech"

최상위 [tts] 키:

키	타입	기본값	설명
`enabled`	bool	`false`	TTS 합성 마스터 토글.
`default_provider`	string	`"openai"`	`openai`, `elevenlabs`, `google`, `edge`, 또는 `piper`.
`default_voice`	string	`"alloy"`	선택한 프로바이더에 전달할 음성 ID.
`default_format`	string	`"mp3"`	출력 오디오 포맷: `mp3`, `opus`, 또는 `wav`.
`max_text_length`	integer	`4096`	최대 입력 텍스트 길이(문자 단위).

프로바이더별 서브 테이블:

서브 테이블	키 (기본값)
`[tts.openai]`	`api_key`, `model` (`tts-1`), `speed` (`1.0`)
`[tts.elevenlabs]`	`api_key`, `model_id` (`eleven_monolingual_v1`), `stability` (`0.5`), `similarity_boost` (`0.5`)
`[tts.google]`	`api_key`, `language_code` (`en-US`)
`[tts.edge]`	`binary_path` (`edge-tts`)
`[tts.piper]`	`api_url` (`http://127.0.0.1:5000/v1/audio/speech`)

OpenAI의 기본 제공 음성은 alloy, echo, fable, onyx, nova, shimmer입니다. Edge TTS는 Microsoft Neural 음성을 사용하며 무료이지만 PATH에 edge-tts 바이너리가 있어야 합니다. Piper는 OpenAI 호환 HTTP 엔드포인트를 통해 로컬에서 실행되며, 완전히 오프라인이거나 GPU 가속 합성이 필요한 경우에 유용합니다.

Transcription (음성 텍스트 변환)

[transcription] 섹션은 공유 STT 서브시스템입니다. Voice Wake, 미디어 파이프라인의 오디오 구간, 그리고 음성 메모를 지원하는 모든 채널(Telegram, Discord, Slack, Mattermost, Matrix, WhatsApp Web, WATI 등)의 오디오 첨부 파일 처리를 담당합니다. 기본 프로바이더는 Groq(Whisper 호환)이며, OpenAI, Deepgram, AssemblyAI, Google Cloud Speech-to-Text, 또는 자체 호스팅 Whisper 엔드포인트도 사용할 수 있습니다.

[transcription]
enabled = true
default_provider = "groq"         # groq | openai | deepgram | assemblyai | google | local_whisper
# api_key = "..."                 # Groq provider; falls back to GROQ_API_KEY
api_url = "https://api.groq.com/openai/v1/audio/transcriptions"
model = "whisper-large-v3-turbo"
# language = "en"                 # optional ISO-639-1 hint
# initial_prompt = "Revka, Kumiho"  # bias toward expected vocabulary
max_duration_secs = 120
transcribe_non_ptt_audio = false

# Optional per-provider sub-tables:
[transcription.openai]
# api_key = "..."
model = "whisper-1"

[transcription.local_whisper]
url = "http://10.10.0.1:8001/v1/transcribe"
# bearer_token = "..."
# max_audio_bytes = 26214400      # 25 MB
timeout_secs = 300

키	타입	기본값	설명
`enabled`	bool	`false`	전사 마스터 토글.
`default_provider`	string	`"groq"`	`groq`, `openai`, `deepgram`, `assemblyai`, `google`, 또는 `local_whisper`.
`api_key`	string (선택)	—	Groq 프로바이더 키; `GROQ_API_KEY`로 폴백합니다.
`api_url`	string	`https://api.groq.com/openai/v1/audio/transcriptions`	Whisper 호환 엔드포인트(Groq 프로바이더).
`model`	string	`"whisper-large-v3-turbo"`	Whisper 모델 이름(Groq 프로바이더).
`language`	string (선택)	—	ISO-639-1 언어 힌트(예: `en`, `ru`).
`initial_prompt`	string (선택)	—	예상 고유명사/용어로 전사를 유도하는 프롬프트.
`max_duration_secs`	integer	`120`	이 시간(초)보다 긴 오디오는 건너뜁니다.
`transcribe_non_ptt_audio`	bool	`false`	WhatsApp에서 음성 메모가 아닌(전달됨/일반) 오디오도 전사합니다.

프로바이더별 서브 테이블: [transcription.openai] (api_key, model = whisper-1), [transcription.deepgram] (api_key, model = nova-2), [transcription.assemblyai] (api_key), [transcription.google] (api_key, language_code = en-US), [transcription.local_whisper].

local_whisper 서브 테이블은 접근 가능한 Whisper 호환 엔드포인트를 가리킵니다:

키	타입	기본값	설명
`url`	string (필수)	—	HTTP(S) 엔드포인트 URL.
`bearer_token`	string (선택)	—	인증 토큰; 인증 없는 로컬 엔드포인트는 생략합니다.
`max_audio_bytes`	integer	`26214400` (25 MB)	허용되는 최대 오디오 크기; 요청당 최대 메모리는 이 값의 약 2배입니다.
`timeout_secs`	integer	`300`	요청 타임아웃(로컬 GPU에서 대용량 파일 처리 시).

미디어 파이프라인

미디어 파이프라인은 채널 간 공유 인바운드 미디어 이해 단계입니다. 활성화하면 에이전트가 첨부 파일을 받기 전에 미리 처리하여 원본 파일을 텍스트 주석으로 대체합니다. 오디오는 전사되고, 이미지는 설명되며, 동영상은 요약됩니다. 이를 통해 텍스트 모델 기반의 에이전트도 별도의 도구 호출 없이 음성 메모나 사진을 이해할 수 있습니다.

[media_pipeline]
enabled = true
transcribe_audio = true
describe_images = true
summarize_video = true

키	타입	기본값	설명
`enabled`	bool	`false`	파이프라인 마스터 토글.
`transcribe_audio`	bool	`true`	`[transcription]` 프로바이더를 통해 오디오 첨부 파일을 전사합니다.
`describe_images`	bool	`true`	비전 지원 모델이 활성화된 경우 이미지를 설명합니다.
`summarize_video`	bool	`true`	동영상 첨부 파일을 요약합니다(외부 API 필요).

오디오 처리는 [transcription] 설정을 재사용하며, 이미지 설명은 활성 프로바이더의 비전 기능을 활용합니다. 프로바이더가 비전을 지원하지 않는 경우, 오류 없이 간단한 [Image: attached] 주석으로 우아하게 폴백합니다.

링크 보강기

링크 보강기는 인바운드 메시지의 URL 뒤에 있는 콘텐츠를 가져와 짧은 요약을 앞에 추가함으로써, 에이전트가 명시적인 웹 조회 도구 호출 없이도 링크 맥락을 파악할 수 있게 합니다. 기본적으로 비활성화되어 있으며 SSRF 보호가 적용됩니다.

[link_enricher]
enabled = false
max_links = 3
timeout_secs = 10

키	타입	기본값	설명
`enabled`	bool	`false`	보강기 마스터 토글.
`max_links`	integer	`3`	메시지당 가져올 최대 고유 URL 수.
`timeout_secs`	integer	`10`	URL당 가져오기 타임아웃(초 단위).

구성 요소 간의 관계

음성 채널은 오디오 입출력 인터페이스이며, 네 가지 서브시스템은 음성 채널과 텍스트 채널 모두가 사용하는 공유 엔진입니다:

구성 요소	설정 위치	역할	피처 플래그
Voice Call	`[channels_config.voice_call]`	Twilio / Telnyx / Plivo를 통한 전화 통화(웹훅)	—
Voice Wake	`[channels_config.voice_wake]`	로컬 마이크 웨이크워드 캡처(입력 전용)	`voice-wake`
ClawdTalk	`[channels_config.clawdtalk]`	Telnyx SIP 음성 통화(웹훅)	—
TTS	`[tts]`	텍스트 → 음성 (음성 응답용)	—
Transcription	`[transcription]`	음성 → 텍스트 (음성 입력용)	—
미디어 파이프라인	`[media_pipeline]`	인바운드 오디오/이미지/동영상 주석 처리	—
링크 보강기	`[link_enricher]`	메시지의 URL 가져오기 & 요약	—

일반적인 엔드투엔드 음성 설정은 여러 구성 요소를 조합합니다. 음성 입력을 텍스트로 변환하려면 [transcription]을 활성화하고, 응답을 오디오로 출력하려면 [tts]를 활성화한 후, 음성 채널을 추가합니다(전화 통화는 [channels_config.voice_call], 로컬 마이크는 [channels_config.voice_wake]). Voice Call은 transcription_logging = true일 때 통화 기록도 저장합니다.

음성, TTS, 전사

Voice Call

Voice Wake

ClawdTalk

TTS (텍스트 음성 변환)

Transcription (음성 텍스트 변환)

미디어 파이프라인

링크 보강기

구성 요소 간의 관계

관련 페이지

시작하기

핵심 개념

가이드

CLI 참조

게이트웨이 API

대시보드

채널

프로바이더 및 모델

도구

메모리

워크플로우 및 SOP

크론 및 스케줄링

보안 및 감사

배포 및 운영

하드웨어

MCP 및 확장성

에코시스템

참조