dvgateway-sdk 1.0.0

package/README.md

@@ -0,0 +1,615 @@
+# DVGateway SDK
+
+DVGateway를 통해 AI 플랫폼과 실시간 음성 서비스를 **5줄의 코드**로 연동합니다.
+**Node.js(TypeScript)** 와 **Python** 두 언어를 모두 지원합니다.
+
+---
+
+## Node.js SDK
+
+### 설치
+
+```bash
+npm install dvgateway-sdk dvgateway-adapters
+```
+
+### 30초 시작 가이드
+
+```typescript
+import { DVGatewayClient } from 'dvgateway-sdk';
+import { DeepgramAdapter } from 'dvgateway-adapters/stt';
+import { AnthropicAdapter } from 'dvgateway-adapters/llm';
+import { ElevenLabsAdapter } from 'dvgateway-adapters/tts';
+
+const gw = new DVGatewayClient({
+  baseUrl: 'http://localhost:8080',           // DVGateway API 서버 (:8080)
+  auth: { type: 'apiKey', apiKey: 'your_key' },
+});
+
+await gw.pipeline()
+  .stt(new DeepgramAdapter({ apiKey: '...', language: 'ko' }))
+  .llm(new AnthropicAdapter({ apiKey: '...', model: 'claude-sonnet-4-6' }))
+  .tts(new ElevenLabsAdapter({ apiKey: '...' }))
+  .start();
+```
+
+---
+
+## Python SDK
+
+### 설치
+
+```bash
+pip install dvgateway dvgateway-adapters python-dotenv
+```
+
+### 30초 시작 가이드
+
+```python
+import asyncio
+import os
+from dotenv import load_dotenv
+
+from dvgateway import DVGatewayClient
+from dvgateway.adapters.stt import DeepgramAdapter
+from dvgateway.adapters.llm import AnthropicAdapter
+from dvgateway.adapters.tts import ElevenLabsAdapter
+
+load_dotenv()
+
+async def main():
+    gw = DVGatewayClient(
+        base_url="http://localhost:8080",
+        auth={"type": "apiKey", "api_key": os.environ["GATEWAY_API_KEY"]},
+    )
+
+    await (
+        gw.pipeline()
+        .stt(DeepgramAdapter(api_key=os.environ["DEEPGRAM_API_KEY"], language="ko"))
+        .llm(AnthropicAdapter(api_key=os.environ["ANTHROPIC_API_KEY"], model="claude-sonnet-4-6"))
+        .tts(ElevenLabsAdapter(api_key=os.environ["ELEVENLABS_API_KEY"]))
+        .start()
+    )
+
+asyncio.run(main())
+```
+
+### Python — 로컬 어댑터 (오프라인)
+
+Python SDK는 로컬 STT/LLM 어댑터를 추가로 지원합니다. 인터넷 없이 완전 오프라인 운영이 가능합니다.
+
+```bash
+# 로컬 어댑터 추가 패키지
+pip install faster-whisper        # Faster-Whisper STT
+pip install openai-whisper        # OpenAI Whisper STT (공식)
+# Ollama는 별도 설치: https://ollama.com/install.sh
+```
+
+```python
+# 완전 오프라인 파이프라인
+from dvgateway.adapters.stt import FasterWhisperAdapter
+from dvgateway.adapters.llm import OllamaAdapter
+
+await (
+    gw.pipeline()
+    # Faster-Whisper: 로컬 고속 STT
+    .stt(FasterWhisperAdapter(
+        model="large-v3",
+        device="cpu",           # GPU: "cuda"
+        compute_type="int8",    # GPU: "float16"
+        language="ko",
+        vad_enabled=True,
+    ))
+    # Qwen via Ollama: 로컬 LLM
+    .llm(OllamaAdapter(
+        base_url="http://localhost:11434",
+        model="qwen3.5:9b",
+        system_prompt="친절한 한국어 AI 상담원입니다.",
+        options={"think": False},
+    ))
+    .tts(ElevenLabsAdapter(api_key="..."))  # TTS는 ElevenLabs 권장
+    .start()
+)
+```
+
+### Node.js — OpenAI Realtime (Speech-to-Speech)
+
+For sub-300ms end-to-end latency, use the Realtime adapter to bypass the STT→LLM→TTS chain entirely:
+
+```typescript
+import { DVGatewayClient } from 'dvgateway-sdk';
+import { OpenAIRealtimeAdapter } from 'dvgateway-adapters/realtime';
+
+const gw = new DVGatewayClient({
+  baseUrl: 'http://localhost:8080',
+  auth: { type: 'apiKey', apiKey: 'your_key' },
+});
+
+const realtime = new OpenAIRealtimeAdapter({
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-4o-mini-realtime-preview',  // cost-efficient; use gpt-4o-realtime-preview for best quality
+  voice: 'alloy',                          // alloy | echo | nova | shimmer | ash | coral | sage | verse
+  instructions: 'You are a helpful voice assistant. Keep answers short and conversational.',
+  turnDetection: { mode: 'server_vad', silenceDurationMs: 500 },
+  inputTranscription: true,
+});
+
+realtime.onAudioOutput((chunk, linkedId) => gw.injectAudio(linkedId, chunk));
+realtime.onTranscript((result) => console.log(`[${result.speaker}] ${result.text}`));
+
+gw.onCallEvent(async (event) => {
+  if (event.type === 'call:new') {
+    const audioStream = gw.streamAudio(event.session.linkedId, { dir: 'in' });
+    await realtime.startSession(event.session.linkedId, audioStream);
+  }
+  if (event.type === 'call:ended') {
+    await realtime.stop(event.linkedId);
+  }
+});
+
+await gw.connect();
+```
+
+**Realtime vs cascaded pipeline:**
+
+| | Cascaded (STT→LLM→TTS) | Realtime (Speech-to-Speech) |
+|--|---|---|
+| Latency | ~500ms | ~300ms |
+| Cost | per-service billing | single API call |
+| Control | full per-step control | unified session |
+| Best for | complex agents, custom logic | low-latency voice bots |
+
+---
+
+---
+
+### 사람다운 음성 최적화 (Human Voice Options)
+
+TTS 어댑터에 **사람다운 음성** 옵션이 내장되어 있습니다. 기본값은 **한국어 대화**에 최적화되어 있으며, 자연스러운 쉼, 숨소리, 필러 단어, 감탄사, 감정 표현을 제어할 수 있습니다.
+
+```typescript
+import { ElevenLabsAdapter } from 'dvgateway-adapters/tts';
+import { OpenAITtsAdapter } from 'dvgateway-adapters/tts';
+
+// ✅ 기본값: 한국어 최적화 (humanVoice 자동 활성화)
+const tts = new ElevenLabsAdapter({ apiKey: '...' });
+// → stability: 0.3, style: 0.6, model: eleven_multilingual_v2
+
+// ✅ OpenAI: gpt-4o-mini-tts 자동 선택 + 음성 지시 자동 생성
+const openaiTts = new OpenAITtsAdapter({ apiKey: '...' });
+// → model: gpt-4o-mini-tts, voiceInstructions 자동 생성
+
+// ✅ 커스텀 설정
+const customTts = new ElevenLabsAdapter({
+  apiKey: '...',
+  humanVoice: {
+    naturalPauses: true,      // 문장 사이 자연스러운 쉼
+    breathingSounds: true,    // 숨소리 포함
+    fillerWords: false,       // 필러 단어 비활성화 (음, 어, 그...)
+    exclamations: true,       // 감탄사 (아, 네, 맞아요...)
+    emotionalRange: 0.8,      // 감정 표현 범위 (0.0–1.0)
+    speechVariation: 0.7,     // 음성 변화도 (0.0–1.0)
+  },
+});
+
+// ❌ 비활성화: 기존 방식 사용
+const flatTts = new ElevenLabsAdapter({
+  apiKey: '...',
+  humanVoice: false,
+  // → stability: 0.5, style: 0.0, model: eleven_flash_v2_5 (기존 기본값)
+});
+```
+
+#### HumanVoiceOptions 인터페이스
+
+| 옵션 | 타입 | 기본값 (KO) | 설명 |
+|------|------|-------------|------|
+| `naturalPauses` | `boolean` | `true` | 문장·절 사이 자연스러운 쉼 |
+| `breathingSounds` | `boolean` | `true` | 긴 문장 사이 숨소리 |
+| `fillerWords` | `boolean` | `true` | 필러 단어 (음, 어, 그, 저) |
+| `exclamations` | `boolean` | `true` | 감탄사 (아, 네, 맞아요) |
+| `emotionalRange` | `number` | `0.6` | 감정 표현 범위 (0.0–1.0) |
+| `speechVariation` | `number` | `0.7` | 음성 변화도 (0.0–1.0) |
+
+#### 프로바이더별 매핑
+
+| HumanVoiceOptions | ElevenLabs | OpenAI (gpt-4o-mini-tts) |
+|---|---|---|
+| `emotionalRange` | → `style` 파라미터 | → voiceInstructions 감정 지시 |
+| `speechVariation` | → `stability` (역비례: 1.0 - variation) | → voiceInstructions 톤 변화 지시 |
+| `naturalPauses` | 모델 내장 (multilingual v2) | → voiceInstructions 쉼 지시 |
+| `breathingSounds` | 모델 내장 (multilingual v2) | → voiceInstructions 숨소리 지시 |
+| `fillerWords` | 모델 내장 | → voiceInstructions 필러 단어 지시 |
+| `exclamations` | 모델 내장 | → voiceInstructions 감탄사 지시 |
+
+#### 프리셋
+
+```typescript
+import { HUMAN_VOICE_DEFAULTS_KO, HUMAN_VOICE_DEFAULTS_EN } from 'dvgateway-sdk';
+
+// 한국어 기본값 (기본 적용)
+HUMAN_VOICE_DEFAULTS_KO  // { naturalPauses: true, breathingSounds: true, fillerWords: true, ... }
+
+// 영어 기본값
+HUMAN_VOICE_DEFAULTS_EN  // { naturalPauses: true, breathingSounds: true, fillerWords: false, ... }
+```
+
+---
+
+### ElevenLabs 한국어 네이티브 보이스
+
+ElevenLabs Voice Library에서 선별한 **9개 한국어 네이티브 음성**이 내장되어 있습니다:
+
+```typescript
+import { ELEVENLABS_KOREAN_VOICES } from 'dvgateway-adapters';
+
+// 내장 한국어 음성 목록
+for (const voice of ELEVENLABS_KOREAN_VOICES) {
+  console.log(`${voice.id} — ${voice.label}`);
+}
+// pjJMvFj0JGWi3mogOkHH — Hyun Bin (남성, 한국어)
+// t0jbNlBVZ17f02VDIeMI — 지영 / JiYoung (여성, 한국어)
+// zrHiDhphv9ZnVXBqCLjz — Jennie (여성, 한국어)
+// ZJCNdOEhQGMOIbMuhBME — Han Aim (남성, 한국어)
+// ova4yY2jqnnUdGOmTGbx — KKC HQ (남성, 한국어)
+// Xb7hH8MSUJpSbSDYk0k2 — Anna Kim (여성, 한국어)
+// XrExE9yKIg1WjnnlVkGX — Yuna (여성, 한국어)
+// ThT5KcBeYPX3keUQqHPh — Jina (여성, 한국어)
+// Sita5M0jWFxPiECPABjR — jjeong (여성, 한국어)
+
+// 한국어 음성으로 TTS 생성
+const tts = new ElevenLabsAdapter({
+  apiKey: '...',
+  voiceId: ELEVENLABS_KOREAN_VOICES[0].id,  // Hyun Bin
+});
+```
+
+```python
+# Python
+from dvgateway.adapters.tts import ElevenLabsAdapter, KOREAN_VOICES
+
+for voice in KOREAN_VOICES:
+    print(f"{voice.id} — {voice.label}")
+
+tts = ElevenLabsAdapter(api_key="...", voice_id=KOREAN_VOICES[0].id)
+```
+
+---
+
+### ElevenLabs Voice Fetch (동적 음성 목록 조회)
+
+ElevenLabs 계정에 등록된 **모든 음성**(기본, 클론, 라이브러리)을 동적으로 조회합니다:
+
+```typescript
+import { ElevenLabsAdapter } from 'dvgateway-adapters/tts';
+
+// API에서 사용 가능한 모든 음성 조회
+const voices = await ElevenLabsAdapter.fetchVoices('your-elevenlabs-api-key');
+for (const v of voices) {
+  console.log(`${v.id} — ${v.label}`);
+  // 클론된 음성: "My Voice (클론) [ko]"
+  // 생성된 음성: "Custom Voice (생성됨)"
+}
+```
+
+```python
+# Python
+voices = await ElevenLabsAdapter.fetch_voices("your-elevenlabs-api-key")
+for v in voices:
+    print(f"{v.id} — {v.label}")
+```
+
+**DVGateway REST API:**
+```
+GET /api/v1/config/apikeys/voices/elevenlabs/fetch
+```
+
+---
+
+### ElevenLabs Voice Cloning (음성 복제)
+
+오디오 파일을 업로드하여 **커스텀 음성을 생성**합니다:
+
+```typescript
+import { ElevenLabsAdapter } from 'dvgateway-adapters/tts';
+import { readFileSync } from 'fs';
+
+// 오디오 파일에서 음성 복제
+const audioData = readFileSync('./my-voice-sample.wav');
+const newVoice = await ElevenLabsAdapter.cloneVoice(
+  'your-elevenlabs-api-key',
+  '내 목소리',           // 음성 이름
+  audioData,             // 오디오 데이터 (WAV, MP3, OGG)
+  'my-voice-sample.wav', // 파일명
+  '한국어 남성 음성',     // 설명 (선택)
+);
+
+console.log(`클론된 음성 ID: ${newVoice.id}`);  // → 새로운 voice_id
+
+// 클론된 음성으로 TTS 생성
+const tts = new ElevenLabsAdapter({
+  apiKey: '...',
+  voiceId: newVoice.id,
+});
+```
+
+```python
+# Python
+audio_data = open("./my-voice-sample.wav", "rb").read()
+new_voice = await ElevenLabsAdapter.clone_voice(
+    api_key="your-elevenlabs-api-key",
+    name="내 목소리",
+    audio_data=audio_data,
+    file_name="my-voice-sample.wav",
+    description="한국어 남성 음성",
+)
+print(f"클론된 음성 ID: {new_voice.id}")
+```
+
+**DVGateway REST API:**
+```
+POST /api/v1/config/apikeys/voices/elevenlabs/clone
+Content-Type: multipart/form-data
+Fields: name, description (optional), file (audio)
+```
+
+---
+
+### TTS 캐싱 (CachedTtsAdapter)
+
+디스크 기반 TTS 오디오 캐싱으로 **비용 절감**과 **응답 속도 향상**을 동시에 달성합니다:
+
+```typescript
+import { CachedTtsAdapter, ElevenLabsAdapter } from 'dvgateway-adapters';
+
+const inner = new ElevenLabsAdapter({ apiKey: '...' });
+const tts = new CachedTtsAdapter(inner, {
+  provider: 'elevenlabs',
+  cacheDir: './tts-cache',
+  ttlMs: 7 * 24 * 60 * 60 * 1000,  // 7일
+  maxEntries: 1000,                 // LRU 제한
+});
+
+// 자주 사용하는 안내 멘트 사전 캐싱
+await tts.warmup([
+  { text: '안녕하세요, 무엇을 도와드릴까요?' },
+  { text: '잠시만 기다려 주세요.' },
+  { text: '감사합니다. 좋은 하루 되세요.' },
+]);
+
+// 캐시 히트 시 즉시 응답 (API 호출 없음)
+const stats = tts.getStats();
+console.log(`캐시 히트: ${stats.hits}, 미스: ${stats.misses}`);
+```
+
+```python
+# Python
+from dvgateway.adapters.tts import CachedTtsAdapter, ElevenLabsAdapter
+
+inner = ElevenLabsAdapter(api_key="...")
+tts = CachedTtsAdapter(inner, provider="elevenlabs", cache_dir="./tts-cache")
+
+await tts.warmup([
+    {"text": "안녕하세요, 무엇을 도와드릴까요?"},
+    {"text": "잠시만 기다려 주세요."},
+])
+```
+
+---
+
+### STT 옵션 (SttOptions)
+
+STT 어댑터에 전달 가능한 프로바이더 독립적 옵션입니다.
+
+```typescript
+import type { SttOptions } from 'dvgateway-sdk';
+
+const sttOptions: SttOptions = {
+  language: 'ko',              // 언어 코드
+  diarize: true,               // 화자 분리
+  vadSensitivity: 'medium',    // VAD 감도 (low/medium/high)
+  endpointingMs: 300,          // 발화 종료 감지 (ms)
+  utteranceEndMs: 800,         // 발화 최종 확정 (ms, 한국어 최적화)
+  interimResults: true,        // 중간 결과 수신
+  smartFormat: true,           // 스마트 포맷팅 (숫자, 날짜, 구두점)
+  keywords: ['DVGateway', 'AI'], // 도메인 키워드 부스트
+  punctuate: true,             // 구두점 자동 추가
+  profanityFilter: false,      // 비속어 필터
+  sentiment: true,             // 감정 분석 (Deepgram Nova-3)
+};
+```
+
+---
+
+### 감정 분석 (Sentiment Analysis)
+
+Deepgram Nova-3 모델에서 **실시간 감정 분석**을 지원합니다. 각 발화(transcript segment)를 `positive` / `neutral` / `negative`로 분류하고 신뢰도 점수를 반환합니다.
+
+```typescript
+import { DeepgramAdapter } from 'dvgateway-adapters/stt';
+
+// sentiment: true 로 감정 분석 활성화
+const stt = new DeepgramAdapter({
+  apiKey: '...',
+  language: 'ko',
+  sentiment: true,  // 감정 분석 활성화
+});
+
+gw.pipeline()
+  .stt(stt)
+  .onTranscript((result, session) => {
+    console.log(`[${result.speaker}] ${result.text}`);
+    if (result.sentiment) {
+      console.log(`  감정: ${result.sentiment.sentiment} (${result.sentiment.sentimentScore})`);
+      // → 감정: positive (0.87)
+    }
+  })
+  .start();
+```
+
+```python
+# Python
+from dvgateway.adapters.stt import DeepgramAdapter
+
+stt = DeepgramAdapter(api_key="...", language="ko", sentiment=True)
+
+# result.sentiment.sentiment → "positive" | "neutral" | "negative"
+# result.sentiment.sentiment_score → 0.0–1.0
+```
+
+#### SentimentResult 인터페이스
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `sentiment` | `'positive' \| 'neutral' \| 'negative'` | 세그먼트 감정 분류 |
+| `sentimentScore` | `number` | 감정 신뢰도 점수 (0.0–1.0) |
+
+> 대시보드에서도 Deepgram STT 프로바이더 설정에서 "감정 분석" 체크박스로 활성화할 수 있습니다.
+
+---
+
+### Node.js vs Python SDK 비교
+
+| 항목 | Node.js | Python |
+|------|---------|--------|
+| 패키지 | `dvgateway-sdk` | `dvgateway` |
+| 어댑터 | `dvgateway-adapters` | `dvgateway-adapters` |
+| 이벤트 핸들러 | `.onNewCall(cb)` | `.on_new_call(cb)` |
+| 비동기 | `async/await` | `asyncio` |
+| Realtime (S2S) | ✅ `OpenAIRealtimeAdapter` | ✅ `OpenAIRealtimeAdapter` |
+| 로컬 STT 지원 | whisper.cpp (외부 서버) | ✅ whisper.cpp, Faster-Whisper, OpenAI Whisper (인프로세스) |
+| 로컬 LLM 지원 | Ollama (외부 서버) | ✅ Ollama, vLLM (OpenAI 호환) |
+
+## DVGateway 포트 구조
+
+| 포트 | 용도 |
+|------|------|
+| `:8080` | API 서버 — AI SDK가 연결하는 포트 |
+| `:8081` | 대시보드 UI |
+| `:8092` | 미디어 서버 — Asterisk ExternalMedia WebSocket (`GW_MEDIA_ADDR` 기본값) |
+| `:8088` | Asterisk ARI HTTP — DVGateway가 Asterisk에 연결할 때 사용 |
+
+> ⚠️ SDK는 항상 **:8080 API 서버**에 연결합니다. `:8092`는 Asterisk가 DVGateway에 연결하는 포트입니다.
+
+## 아키텍처
+
+```
+Asterisk PBX
+    │ ExternalMedia WebSocket (slin16, 16kHz)
+    ↓
+DVGateway (:8092 미디어 서버)
+    │
+    ↓
+DVGateway API (:8080)
+    │  ├── /api/v1/ws/callinfo    콜 이벤트
+    │  ├── /api/v1/ws/stream      오디오 스트림 (AI → 구독)
+    │  └── /api/v1/ws/tts/{id}    TTS 주입 (AI → Asterisk)
+    │
+    ↓
+dvgateway-sdk (이 패키지)
+    │
+    ├── SttAdapter      (Deepgram, whisper.cpp, Faster-Whisper, ...)
+    ├── LlmAdapter      (Anthropic Claude, OpenAI GPT, Ollama/Qwen, ...)
+    ├── TtsAdapter      (ElevenLabs, OpenAI TTS, ...)
+    └── RealtimeAdapter (OpenAI Realtime — speech-to-speech, bypasses STT/LLM/TTS)
+```
+
+## 오디오 포맷
+
+DVGateway는 **slin16** 포맷으로 오디오를 전송합니다:
+- 샘플레이트: 16,000 Hz
+- 비트깊이: 16-bit signed integer
+- 채널: Mono (1채널)
+- 엔디안: Little-endian
+- 프레임 크기: 640 bytes = 320 samples = **20ms**
+
+SDK는 자동으로 `slin16 → Float32Array [-1.0, 1.0]`으로 변환합니다.
+
+## API 참조
+
+### 고수준 API (파이프라인 빌더)
+
+```typescript
+gw.pipeline()
+  .stt(adapter)                    // STT 어댑터 설정
+  .llm(adapter)                    // LLM 어댑터 설정 (선택)
+  .tts(adapter)                    // TTS 어댑터 설정 (선택)
+  .audioFilter({ dir: 'in' })      // 오디오 방향 필터 (both/in/out)
+  .onNewCall(handler)              // 새 콜 이벤트
+  .onCallEnded(handler)            // 콜 종료 이벤트
+  .onTranscript(handler)           // 전사 결과 이벤트
+  .onError(handler)                // 오류 이벤트
+  .start()                         // 시작 (Promise — 중단할 때까지 실행)
+```
+
+### 중간수준 API
+
+```typescript
+// 오디오 스트림 구독
+const stream = gw.streamAudio(linkedId, { dir: 'both' });
+for await (const chunk of stream) {
+  // chunk.samples: Float32Array
+}
+
+// TTS 주입
+await gw.injectTts(linkedId, tts.synthesize('안녕하세요'));
+
+// 컨퍼런스 TTS 브로드캐스트
+await gw.broadcastTts(confId, tts.synthesize('안내말씀'));
+
+// 콜 이벤트 구독
+const unsub = gw.onCallEvent((event) => { /* ... */ });
+
+// 세션 관리
+const sessions = await gw.listSessions();
+await gw.updateSessionMeta(linkedId, { customerId: 'C001' });
+
+// 회의록
+await gw.submitTranscript(confId, result);
+const minutes = await gw.downloadMinutes(confId, 'txt');
+```
+
+## 보안
+
+- **API Key → JWT 자동 교환**: SDK가 내부적으로 처리, 사용자 코드에서 토큰 관리 불필요
+- **PII 자동 마스킹**: 로그에서 전화번호 등 개인정보 자동 제거 (기본 활성화)
+- **TLS 강제**: `http://`를 `https://`로 자동 업그레이드 (프로덕션)
+- **mTLS 지원**: 기업 환경의 클라이언트 인증서 지원
+
+## 서비스 지속성
+
+- **자동 재연결**: WebSocket 끊김 시 지수 백오프(Exponential backoff)로 자동 재연결
+- **활성 콜 보호**: 재연결 후 진행 중인 콜 자동 재구독
+- **재연결 설정**:
+  ```typescript
+  new DVGatewayClient({
+    reconnect: {
+      maxAttempts: 10,        // 최대 재시도 횟수
+      initialDelayMs: 2000,   // 첫 재시도 대기 (2초)
+      maxDelayMs: 30_000,     // 최대 대기 (30초)
+      backoffMultiplier: 2.0, // 대기 시간 배수
+    },
+  });
+  ```
+
+## 메트릭
+
+```typescript
+// 레이턴시 통계
+gw.metrics.logSummary();
+
+// Prometheus 형식으로 내보내기
+const promText = gw.metrics.toPrometheus();
+```
+
+수집 메트릭:
+- `dvgw_stt_latency_ms` — STT 응답 시간
+- `dvgw_llm_ttft_ms` — LLM 첫 토큰까지 시간
+- `dvgw_tts_latency_ms` — TTS 첫 오디오까지 시간
+- `dvgw_e2e_latency_ms` — 전체 E2E 레이턴시
+- `dvgw_transcripts_total` — 처리된 발화 수
+- `dvgw_errors_total` — 오류 수
+
+## 라이선스
+
+MIT

package/dist/audio/codec.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Audio Codec Utilities
+ *
+ * Converts between DVGateway's native slin16 format and Float32 PCM
+ * used by most AI STT/TTS APIs.
+ *
+ * DVGateway audio format:
+ *   - Sample rate: 16000 Hz
+ *   - Bit depth: 16-bit signed integer
+ *   - Endianness: little-endian
+ *   - Frame size: 640 bytes = 320 samples = 20ms
+ *   - Channels: 1 (mono)
+ */
+/** Convert slin16 Buffer → normalized Float32Array [-1.0, 1.0] */
+export declare function slin16ToFloat32(buf: Buffer): Float32Array;
+/** Convert normalized Float32Array [-1.0, 1.0] → slin16 Buffer */
+export declare function float32ToSlin16(samples: Float32Array): Buffer;
+/** Convert μ-law (ulaw) Buffer → slin16 Buffer */
+export declare function ulawToSlin16(ulaw: Buffer): Buffer;
+/** Convert slin16 Buffer → μ-law (ulaw) Buffer */
+export declare function slin16ToUlaw(slin16: Buffer): Buffer;
+/**
+ * Resample Float32Array from one sample rate to another.
+ * Uses linear interpolation — suitable for real-time processing.
+ *
+ * @param samples - Input samples
+ * @param fromRate - Source sample rate (e.g. 16000)
+ * @param toRate   - Target sample rate (e.g. 24000 for ElevenLabs)
+ */
+export declare function resample(samples: Float32Array, fromRate: number, toRate: number): Float32Array;
+/**
+ * Calculate RMS (Root Mean Square) amplitude of audio samples.
+ * Returns a value in [0.0, 1.0].
+ */
+export declare function calculateRms(samples: Float32Array): number;
+/**
+ * Simple Voice Activity Detection based on RMS threshold.
+ * Returns true if the frame likely contains speech.
+ *
+ * @param samples - Float32 samples
+ * @param threshold - RMS threshold (default: 0.01, i.e. -40 dBFS)
+ */
+export declare function detectVoiceActivity(samples: Float32Array, threshold?: number): boolean;
+//# sourceMappingURL=codec.d.ts.map

package/dist/audio/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/audio/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAYzD;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAW7D;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASjD;AAED,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAUnD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,YAAY,CAkBd;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAS1D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,YAAY,EAAE,SAAS,SAAO,GAAG,OAAO,CAEpF"}