WebRTC Gateway

WebRTC Gateway는 브라우저·네이티브 클라이언트의 WebRTC 연결을 종단하고, 세션마다 sohri-socket-backend의 /sohri WebSocket에 연결하는 Go/Pion 미디어 게이트웨이입니다. 클라이언트에는 OpenAI Realtime과 유사한 SDP 엔드포인트와 oai-events 데이터채널을 제공하지만, SOHRI 백엔드와의 오디오·이벤트 계약을 변환하는 것이 핵심 역할입니다.

한눈에 보기

• 시그널링: POST /v1/realtime/calls, SDP offer/answer, 비-트리클 ICE
• 인증: 클라이언트 Bearer credential을 백엔드로 그대로 전달하고, 백엔드 인증 성공 후 PeerConnection 생성
• 인바운드: Opus 48 kHz → PCM 16 kHz mono s16le → 3,200 B/100 ms 단위 WSS 전송
• 아웃바운드: PCM/WAV 16·24·48 kHz → 48 kHz → 20 ms Opus 프레임
• 제어: OpenAI Realtime 호환 이벤트와 SOHRI 이벤트·재생 ACK 사이의 변환
• 격리: WebRTC 세션마다 /sohri WSS 연결 하나를 소유하며 다른 세션과 공유하지 않음

통합 브랜치와 표준 배포를 구분하세요

현재 통합 브랜치는 conversationEngine=sohri|openai_realtime 선택과 OpenAI Realtime 이벤트 패스스루를 구현합니다. 그러나 Gateway가 OpenAI에 직접 접속하지는 않습니다. 두 엔진 모두 세션별 /sohri WSS를 통과하며, openai_realtime의 공급자 연결과 자격증명은 socket-backend가 소유합니다.

표준 배포의 기본 엔진은 sohri입니다. 기본 네트워크 경로는 STUN으로 공인 후보를 수집한 뒤 게이트웨이 UDP 포트로 직접 연결하는 방식입니다. coturn은 게이트웨이 바깥의 선택적 릴레이 인프라이지, 이 프로세스에 내장된 TURN 서버가 아닙니다.

요청 흐름

1. 클라이언트가 로컬 ICE 수집을 완료한 offer SDP와 Bearer credential을 보냅니다.
2. Gateway가 credential 형식을 검사하고 /sohri WSS 핸드셰이크에 그대로 전달합니다.
3. 백엔드가 인증을 승인한 뒤에만 PeerConnection, 트랙, ICE agent를 만듭니다.
4. Gateway가 원격 offer를 적용하고 로컬 ICE 수집 완료를 기다린 뒤 완성된 answer SDP를 201로 반환합니다.
5. 미디어는 WebRTC, 제어 이벤트는 oai-events, 백엔드 연결은 세션 전용 WSS로 흐릅니다.

문서 안내

• 브라우저·클라이언트 연동 가이드
• 아키텍처: 구성 요소, 신뢰 경계, 통합 브랜치 기능
• 시그널링·ICE·TURN: 비-트리클 SDP와 UDP 배포
• 인증·CORS: credential 패스스루와 브라우저 호출
• 미디어 파이프라인: Opus↔PCM 변환과 페이싱
• 이벤트·세션 제어: 데이터채널과 /sohri 이벤트
• 바지인·재생: duck, pause, generation, half-duplex
• 수명주기: 연결 상태, 10초 유예, 종료 순서
• 운영·메트릭: 배포 전제와 관측 지표
• 테스트·문제 해결: 검증 계층과 증상별 진단
• 엔드포인트·이벤트 참조
• 설정 참조

지원 경계

Gateway는 SDP 교환용 HTTP 서버, WebRTC 미디어 종단, WSS 브리지, 이벤트 변환을 담당합니다. UDP Load Balancer·방화벽·coturn·백엔드 인증 정책·OpenAI 공급자 세션은 외부 시스템의 책임입니다. POST /v1/realtime/client_secrets는 제거되어 항상 404이며, 브라우저용 client-secret은 app-backend가 발급해야 합니다.