설정 참조¶

Gateway는 환경변수를 기본값으로 읽고 같은 이름의 CLI flag가 있으면 flag가 최종 값을 덮어씁니다. Go duration은 250ms, 2s, 1m처럼 단위를 포함해야 합니다. 주요 운영 노브는 파싱 오류를 조용히 기본값으로 바꾸지 않고 프로세스 기동을 실패시킵니다.

코드 기본값과 배포값

아래 기본값은 현재 통합 브랜치 config.Load의 값입니다. Helm values-stg.yaml, values-prd.yaml은 환경별로 이를 덮어쓸 수 있습니다. 기능 지원 여부와 특정 환경의 활성화 여부를 혼동하지 마세요.

서버·브리지¶

환경변수	코드 기본값	설명
`GATEWAY_ADDR`	`:8090`	HTTP listen 주소
`SOHRI_WS_URL`	`ws://localhost:8080/sohri`	세션별 backend WSS URL
`STUN_URL`	`stun:stun.l.google.com:19302`	Pion ICE server URL; 빈 값이면 미설정
`CORS_ALLOWED_ORIGINS`	빈 값	쉼표 구분 exact Origin; 빈 값이면 CORS 비활성
`PEER_DISCONNECTED_GRACE`	`10s`	`Disconnected` 복구 유예

--bridge-dial-timeout은 현재 기본 10s인 flag-only 설정입니다.

SOHRI_API_KEY, SOHRI_API_KEY_SECRET, SECRET_CACHE_TTL(30s) 설정과 secret resolver 구현도 저장소에 존재합니다. 그러나 현재 SDP 세션 경로는 클라이언트가 보낸 Bearer credential을 startSession에 직접 전달하며 이 값을 대체하지 않습니다. 따라서 이를 브라우저 credential fallback으로 가정하면 안 됩니다. client-secret은 app-backend가 발급하고 backend가 검증합니다.

EPD·바지인¶

환경변수	코드 기본값	범위·동작
`MIN_SPEECH`	`0.3`	0.1..1800초
`END_SILENCE`	`1.2`	0.1..5초
`EPD_TIMEOUT`	`7.0`	0.1..1800초, `MIN_SPEECH` 이상
`INITIAL_PLAYBACK_GRACE`	`2s`	첫 TTS 직후 candidate 억제; 0 이상
`BARGE_IN_ENABLED`	`true`	false면 TTS 동안 mic input gate
`MIC_PREROLL_MS`	`0`	0..5000, 100 ms 단위; barge-in=false에서만
`TTS_DUCK_CANDIDATE_GAIN`	`0.35`	0 초과 1 이하
`TTS_DUCK_MIN_HOLD`	`250ms`	0 이상
`TTS_PAUSE_WINDOW`	`0s`	0이면 pause 비활성; 가청 누계 기준
`TTS_PAUSE_MAX`	`8s`	pause 상한; 활성 시 window 이상
`TTS_PAUSE_AB_PERCENT`	`100`	0..100; session hash 기반 B군 비율

pause window가 0이면 A/B 비율과 무관하게 모든 세션이 대조군으로 기록됩니다. 설정 변경은 hot reload가 아니며 Pod rollout과 진행 중 세션 종료를 수반합니다.

TTS wire¶

환경변수	코드 기본값	설명
`TTS_SAMPLE_RATE`	`16000`	`16000`, `24000`, `48000`만 허용
`TTS_STREAM_WIRE`	`off`	`off` 또는 `v1`
`TTS_DEBUG_CAPTURE`	`false`	기간 한정 GCS debug capture
`TTS_DEBUG_CAPTURE_BUCKET`	빈 값	비어 있으면 capture 비활성
`TTS_DEBUG_CAPTURE_MAX_SECONDS`	`30`	턴당 1..120초

TTS_SAMPLE_RATE는 “받을 수 있는 최대 목표”입니다. 실제 rate는 backend가 provider 능력과 교차해 낮출 수 있고 Gateway는 WAV/start format의 실제 16/24/48 kHz 값을 따릅니다.

TTS_STREAM_WIRE=v1은 Gateway 요청만으로 활성화되지 않습니다. socket-backend의 streaming feature flag도 켜져 있어야 하며, 협상 결과는 connection_established의 echo와 negotiation 메트릭에서 확인합니다.

ICE·UDP¶

환경변수	코드 기본값	설명
`NAT_1TO1_IP`	빈 값	Pion host 후보로 광고할 외부 IP
`UDP_PORT_MIN`	`0`	미디어 UDP 범위 하한
`UDP_PORT_MAX`	`0`	미디어 UDP 범위 상한

UDP 범위는 두 값이 모두 양수일 때 적용됩니다. 한쪽만 설정하거나 min > max인 구성은 허용되지 않습니다. 범위는 LB와 node firewall 설정에 정확히 일치해야 합니다. STUN_URL 설정에는 TURN username/credential 필드가 없습니다.

Opus encoder¶

환경변수	코드 기본값	범위·동작
`OPUS_BITRATE`	`32000`	0=libopus auto, 그 외 6000..510000 bps
`OPUS_COMPLEXITY`	`9`	0..10
`OPUS_INBAND_FEC`	`true`	Opus LBRR 활성
`OPUS_LOSS_FLOOR_PERC`	`5`	RTCP 추정 손실률 하한 0..20

FEC가 켜져 있으면 bitrate와 complexity 조합이 실제 LBRR을 만들 수 있는 하한을 만족해야 하며, 그렇지 않으면 기동을 거부합니다. 32 kbps는 complexity 9 이상에서만 유효합니다. loss floor가 0이면 FEC flag가 true여도 초기 LBRR이 실리지 않습니다.

실제 encoder는 opusenc build tag와 libopus/cgo가 있는 production build에서만 동작합니다. 기본 tag의 stub은 인코딩을 제공하지 않습니다.

GCP 자격증명¶

환경변수	코드 기본값	설명
`GCP_WORKLOAD_IDENTITY_POOL`	빈 값	workload identity pool
`GCP_IDENTITY_PROVIDER`	빈 값	STS audience용 cluster URL
`GCP_SERVICE_ACCOUNT_EMAIL`	빈 값	impersonate할 GSA
`GCP_TOKEN_FILE`	`/var/run/secrets/tokens/token`	projected KSA token

hostNetwork 표준 배포에서는 metadata server를 우회할 수 있어 projected token 기반 WIF를 사용합니다. pool/provider/service account는 모두 설정하거나 모두 비워야 합니다. 일부만 설정된 구성은 기동을 거부합니다. 이 자격증명은 Secret Manager와 debug GCS capture용이며 WebRTC 클라이언트 인증과 별개입니다.

세션별 query·데이터채널 설정¶

프로세스 환경변수 외에 각 SDP 요청의 query가 EPD·engine·DM·TTS 선택을 초기화할 수 있습니다. 이후 session.update가 지정된 필드만 병합합니다.

query 정본: camelCase, snake_case 별칭 허용
instructions, scenarioGraph: DataChannel 전용
conversationEngine: sohri 또는 openai_realtime
sessionCreateMode: registered 또는 json_graph
externalUser.latitude: −90..90, longitude: −180..180
OpenAI 엔진의 좌표는 두 값을 함께 제공
instructions: OpenAI 엔진에서만, 최대 12,000 UTF-16 code unit

형식과 예시는 엔드포인트·이벤트 참조를 참고하세요.