AI 음성 재생 경로 — 패킷 → 지터 버퍼 → 디코더 → 샘플 → 출력 쉬운설명

마지막 업데이트 2026-10-16

2026-10-16apps/web · LiveKit 게스트 AI 출력관련: PPI-1377, PPI-1290

요약: 아동 단말에 도착한 AI 음성 패킷은 지터 버퍼에 인코딩된 채로 대기하다가, <audio> 렌더러가 10ms마다 "줘" 하고 꺼내 갈 때 비로소 디코딩되어 샘플이 됩니다(pull 구조). 그래서 Chrome에서는 꺼내 가는 쪽이 멈추면 packetsReceived는 계속 늘어도 totalSamplesReceived는 멈춥니다. 이것이 PPI-1377의 playout stall입니다.

1. 코드 경로

파일책임
apps/web/lib/voice-agent/livekit-client-session.tsRoomEvent.TrackSubscribed(3376행)에서 AI 트랙을 <audio>에 attach, autoplay·setSinkId·play()
apps/web/lib/voice-agent/livekit-playout-drift-monitor.ts1초마다 getStats() inbound-rtp를 읽어 재생 지연(drift) 판정, stall guard에 같은 통계 전달
apps/web/lib/voice-agent/livekit-playout-stall.ts패킷 도착·샘플 정지 판정(2회 연속) → 재부착 → 요소 교체 복구

2. 전체 흐름

LiveKit Agent(TTS) → LiveKit 서버 → 아동 단말

① RTP 패킷 수신        Opus, 20ms 단위            packetsReceived ↑
        │
② NetEQ 패킷 버퍼       인코딩된 채로 대기·순서 보정   (지터 버퍼, 변환 없음)
        │   ▲
        │   └──── 10ms마다 "줘" (pull) ────┐
        ▼                                     │
③ NetEQ 디코더 + DSP    패킷 1개 → 샘플 960개(48kHz)  totalSamplesReceived ↑
        │                 비면 은닉 샘플로 채움        concealedSamples ↑
        ▼                                     │
④ <audio> 렌더러        오디오 장치 콜백이 요청 주체 ─┘  currentTime ↑
        │
⑤ OS 오디오 · 스피커    실제 소리                   (관측 불가)

샘플은 소리 파형을 일정 간격으로 잰 진폭값 하나(PCM 숫자 1개)입니다. 48kHz면 1초에 48,000개이고, 20ms Opus 패킷 하나가 디코딩되면 960개가 나옵니다.

3. 시나리오 시뮬레이터

시나리오를 바꾸면 각 단계의 값과 1초 폴링 stall 판정이 어떻게 달라지는지 보여 줍니다. 숫자는 개념 시뮬레이션이며 실측값이 아닙니다.

① 네트워크RTP 패킷 수신20ms마다 1개
packetsReceived0
② 패킷 버퍼지터 버퍼
대기0
③ 디코더Opus → PCM꺼내 갈 때만 실행
samples0
concealed0
④ 재생 요소<audio> 렌더러10ms마다 요청
pausedfalse
currentTime0.00s
⑤ 단말스피커통계 없음
소리나옴
← ④가 10ms마다 "줘" → ②에서 꺼내 ③에서 디코딩
Δ packets / 1s–
Δ samples / 1s–
연속 횟수0 / 2
판정정상

4. 단계별 세부

② 지터 버퍼는 변환하지 않는다

지터 버퍼(NetEQ의 패킷 버퍼)는 인코딩된 패킷을 그대로 담아 두고 도착 순서·간격만 맞춥니다. packet → sample 변환은 ③ 디코더가 합니다. 둘이 NetEQ라는 한 모듈에 묶여 있어 흔히 "NetEQ가 변환한다"고 뭉뚱그려 말합니다.

③ 패킷 수와 샘플 수는 정확히 비례하지 않는다

④ pull 구조 — 꺼내 가지 않으면 샘플도 없다

오디오 장치 콜백 → <audio> 렌더러 → NetEQ "10ms 줘" → 패킷 꺼냄 → 디코딩 → 샘플 +480. 디코딩과 샘플 카운트가 모두 이 요청 안에서 일어나므로, 요청이 끊기면 패킷만 버퍼에 쌓입니다.

단계별 관측 지표

단계지표쓰는 곳
①packetsReceived, bytesReceivedstall 판정(패킷 도착 여부)
②jitterBufferDelay ÷ jitterBufferEmittedCountdrift 판정(NetEQ 평균 지연)
③totalSamplesReceived, concealedSamplesstall 판정, 은닉 비율
④audio.currentTime, pauseddrift 판정(렌더 결손), stall 제외 조건
⑤없음출력단만 멈추거나 밀리면 감시로 못 잡음

5. 비슷해 보이는 세 경우 구분

경우pausedpacketssamplesstall 판정
정상false↑↑정상
Playout stall (Chrome 내부 렌더러 정지)false↑02회 연속이면 감지 → 재부착 → 요소 교체 (세션당 단계별 1회)
Autoplay 차단 (play() NotAllowedError)true↑0 (구조상 추론)제외 — isPlaybackExpected()=false (livekit-playout-stall.ts:416)

AudioContext 락업은 이 경로와 별개입니다. AI 원격 오디오는 AudioContext가 아니라 <audio> 요소로 재생합니다(livekit-playout-drift-monitor.ts:380 주석). LiveKit에 공유 AudioContext를 주입하는 PPI-1290 webAudioMix는 현재 web 코드에 없습니다. AudioContext가 멈추면 영향은 마이크 입력 처리 쪽입니다. 단말 오디오 출력 자체가 멈추는 경우는 AudioContext currentTime 고정이 같이 나오는 다른 증상입니다.

6. 주의사항 · 이슈 히스토리