dvgateway

DVGateway Python SDK — AI 음성 서비스를 실시간 전화 통화에 연결합니다.

설치

# 기본 SDK
pip install dvgateway

# AI 어댑터 포함 (Anthropic, OpenAI)
pip install dvgateway[adapters]

빠른 시작

import asyncio
import os
from dvgateway import DVGatewayClient
from dvgateway.adapters.stt import DeepgramAdapter
from dvgateway.adapters.llm import AnthropicAdapter
from dvgateway.adapters.tts import ElevenLabsAdapter

async def main():
    gw = DVGatewayClient(
        base_url="http://localhost:8080",
        auth={"type": "apiKey", "api_key": os.environ["DV_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())

Comfort Noise — AI 처리 중 Dead Air 방지

게이트웨이에서 GW_COMFORT_NOISE_ENABLED=true를 설정하면, AI 처리 중 무음 구간에 배경 소음이 자동으로 주입됩니다.

파이프라인 빌더 사용 시 자동 동작 (별도 코드 불필요):

# thinking:start/stop 시그널이 자동 전송됩니다
await (
    gw.pipeline()
    .stt(DeepgramAdapter(api_key="...", language="ko"))
    .llm(AnthropicAdapter(api_key="...", model="claude-sonnet-4-6"))
    .tts(ElevenLabsAdapter(api_key="..."))
    .start()
)

수동 제어:

# WebSocket 시그널 (저레이턴시)
audio_stream = gw.stream_audio(linked_id)
await audio_stream.send_thinking_start()  # 배경 소음 시작
# ... AI 처리 ...
await audio_stream.send_thinking_stop()   # 배경 소음 중단

# REST API
await gw.start_thinking(linked_id)
await gw.stop_thinking(linked_id)

TTS 재생 완료 이벤트 — `on_tts_complete` (v1.4+)

gw.inject_tts() 는 오디오 iterator 소진 시점에 리턴하지만, 게이트웨이가 실제로 DVGateway에 프레임을 다 넣은 시점이 아닙니다. tts:complete 이벤트가 authoritative 완료 신호입니다.

주요 활용:

순차 TTS 재생 (인사말 → 메뉴 체이닝)
AI 응답 종료 시점 정확히 포착 (S2S 모드)
고객 VAD 리오픈 타이밍 제어

import asyncio
from dvgateway import DVGatewayClient, TTSCompleteEvent

# 인사말 재생
await gw.inject_tts(linked_id, welcome_tts.synthesize("안녕하세요"))

# 인사말 끝나면 메뉴 안내로 전환
def on_done(ev: TTSCompleteEvent) -> None:
    if ev.linked_id != linked_id:
        return
    asyncio.ensure_future(
        gw.inject_tts(linked_id, menu_tts.synthesize("1번을 눌러주세요"))
    )

unsub = gw.on_tts_complete(on_done)
# 필요시 unsub() 호출로 구독 해지

발생 시점: Player.Play() 세션 정상 EOF / 명시적 Stop / 동시 호출 선점. Stale 세션은 중복 발행 안 함.

전체 이벤트 카탈로그:

이벤트	발생 시점	페이로드
`call:new`	새 통화 시작	`session` (CallSession)
`call:ended`	통화 종료	`linked_id`, `duration_sec`
`conf:join` / `conf:leave` / `conf:ended`	회의 이벤트	`linked_id`, `conf_id`
`tts:complete`	TTS 재생 완료	`linked_id`, `tenant_id`, `server_id`, `timestamp`

자세한 가이드: docs/sdk-guide/05-events-fallback.md

고급 통화 제어

메서드	설명
`await gw.collect_dtmf(linked_id, ...)`	DTMF 키 수집 (타임아웃, 종료 키, STT 자동 뮤트 포함)
`await gw.mute_stt(linked_id)`	STT 입력 뮤트 (DTMF 입력 중 음성 인식 차단)
`await gw.unmute_stt(linked_id)`	STT 뮤트 해제
`await gw.play_audio(linked_id, audio_url=..., ...)`	통화 채널에 오디오 파일 재생
`await gw.stop_audio(linked_id)`	재생 중인 오디오 중단
`await gw.warm_transfer(linked_id, ...)`	상담원 이관 — 내선 또는 외부 PSTN 번호 (`outbound=True`, `cid_number`, `cid_name`, `account_code` 지원). whisper 안내는 이관 대상에게만 들림 (활성 클라우드 TTS 프로바이더 필요)

자세한 시그니처 및 예제는 docs/sdk-guide/13-voice-flow-controls.md 참조.

요구사항

Python 3.10+
aiohttp >= 3.9.0
websockets >= 12.0

라이선스

MIT

Metadata

Release files for dvgateway 1.9.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dvgateway 1.9.4
File	Size	Uploaded
dvgateway-1.9.4.tar.gz	141.8 kB	Sep 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dvgateway 1.9.4
File	Interpreter	ABI	Platform	Reset
dvgateway-1.9.4-py3-none-any.whl 146.3 kB Sep 29, 2026	Python 3	none	any	Details

Total release size: 288.1 kB

Release files / dvgateway-1.9.4.tar.gz

Download URL	dvgateway-1.9.4.tar.gz
Size	141.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`91ebd2ad91df5524723c1aa0241b826403e8230abb3f896450b23399d3e136e5`
BLAKE2b-256 checksum How to use checksums	`d546b6d364868844a3f245cafc327e38dde8439b37ed7e2fc088e77d52ae10dc`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

Release files / dvgateway-1.9.4-py3-none-any.whl

Download URL	dvgateway-1.9.4-py3-none-any.whl
Size	146.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b2cbe17ecce92df7db700ce93fb8a0c275dd434135845e303b2895bbe3d28e78`
BLAKE2b-256 checksum How to use checksums	`164e0bc94c847eb88d1a7a46b9fb096b2e385c7f25c8439dfeb1626f076a923c`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`