아키텍처¶

Gateway는 WebRTC와 /sohri WSS 사이의 세션 단위 어댑터입니다. HTTP 시그널링은 연결을 만들기 위한 제어면이고, 연결 후 오디오와 데이터채널은 같은 PeerConnection의 데이터면을 사용합니다.

flowchart LR
    C["WebRTC 클라이언트"]
    H["HTTPS 시그널링<br/>/v1/realtime/calls"]
    P["Pion PeerConnection<br/>Opus + oai-events"]
    S["세션 객체"]
    B["세션 전용 /sohri WSS"]
    SB["sohri-socket-backend"]
    EPD["EPD · STT · DM · TTS"]
    OAI["OpenAI Realtime<br/>(선택 엔진)"]
    TURN["외부 coturn<br/>(선택 릴레이)"]

    C -->|offer SDP + Bearer| H
    H -->|answer SDP| C
    C <-->|SRTP / SCTP| P
    P <--> S
    S <-->|PCM16 + JSON| B
    B <--> SB
    SB <--> EPD
    SB -. 통합 브랜치에서 공급자 연결 소유 .-> OAI
    C -. relay 후보 사용 시 .-> TURN
    TURN -. UDP relay .-> P

구성 요소¶

계층	책임
HTTP	`/healthz`, `/metrics`, SDP POST와 선택적 CORS preflight
WebRTC	Pion 코덱 등록, ICE, 단일 인바운드 오디오 트랙, 아웃바운드 Opus 트랙, `oai-events`
세션	응답 lifecycle, 재생 세대, 바지인·입력 게이트, 페이싱, 이벤트 상관관계
오디오	Opus 48 kHz 디코드, 48→16 kHz 데시메이션, 16/24→48 kHz 보간, Opus 인코드
브리지	세션별 WSS, Bearer 전달, PCM 바이너리와 JSON 제어 프레임의 순서 보존
이벤트	`/sohri`의 A/A′/B 봉투 정규화와 OpenAI Realtime 형태 변환
관측	Prometheus 메트릭과 `gwSessionId`/`sessionId` 구조화 로그

세션 격리¶

WebRTC 세션 하나는 다음 상태를 독점합니다.

PeerConnection 하나와 아웃바운드 오디오 트랙 하나
/sohri WSS 하나
Opus decoder/encoder와 상태형 FIR resampler
데이터채널 대기열, 응답 ID, playout generation, 타이머

WSS나 resampler를 세션 사이에 공유하지 않습니다. 따라서 한 세션의 프레임 순서, FIR 히스토리, 재생 취소 세대가 다른 세션에 섞이지 않습니다.

신뢰 경계¶

Gateway는 Bearer 값의 접두·JWT 모양만 검사합니다. 서명, 만료, workspace, 권한은 socket-backend의 /sohri 핸드셰이크가 판정합니다. 이 인증이 성공하기 전에는 PeerConnection을 만들지 않습니다. 자세한 흐름은 인증·CORS를 참고하세요.

Gateway는 OpenAI API key를 보관하거나 OpenAI에 직접 다이얼하지 않습니다. 통합 브랜치의 openai_realtime 모드는 다음과 같이 동작합니다.

Gateway가 conversation_session_update를 세션 WSS로 보냅니다.
socket-backend가 공급자 세션을 만들고 conversation_session_updated ACK를 보냅니다.
Gateway는 ACK 이후에만 OpenAI 모드를 활성화합니다.
백엔드가 realtime_event와 raw PCM을 같은 WSS로 중계합니다.

현재 통합 브랜치 기능¶

conversationEngine=sohri|openai_realtime; 미지정은 sohri
초기 엔진 설정 ACK 전 response.create 1슬롯 보류 및 설정 update 병합
OpenAI provider 이벤트 원형 전달과 raw PCM 16/24/48 kHz playout
SOHRI TTS 레거시 WAV와 ttsStream=v1 raw PCM 청크
duck, 선택적 pause A/B, half-duplex 입력 게이트, 재생 자막 이벤트
RTCP 손실 보고 기반 Opus FEC 손실률 조정

표준 배포 가정¶

표준 배포는 host networking 또는 동등한 UDP 도달성, 고정 외부 IP 후보, 제한된 UDP 포트 범위를 사용하는 미디어 노드를 가정합니다. STUN 기반 직접 UDP가 기본이며 coturn은 네트워크 정책상 직접 경로가 불가능한 클라이언트를 위한 외부 선택 구성입니다. 실제 인프라 값은 Gateway 코드의 기능이 아니므로 환경별 설정과 방화벽을 함께 확인해야 합니다.

다음으로 시그널링·ICE·TURN과 미디어 파이프라인을 읽으세요.