마지막 업데이트 2026-10-16
요약: 아동 단말에 도착한 AI 음성 패킷은 지터 버퍼에 인코딩된 채로 대기하다가, <audio> 렌더러가 10ms마다 "줘" 하고 꺼내 갈 때 비로소 디코딩되어 샘플이 됩니다(pull 구조). 그래서 Chrome에서는 꺼내 가는 쪽이 멈추면 packetsReceived는 계속 늘어도 totalSamplesReceived는 멈춥니다. 이것이 PPI-1377의 playout stall입니다.
| 파일 | 책임 |
|---|---|
apps/web/lib/voice-agent/livekit-client-session.ts | RoomEvent.TrackSubscribed(3376행)에서 AI 트랙을 <audio>에 attach, autoplay·setSinkId·play() |
apps/web/lib/voice-agent/livekit-playout-drift-monitor.ts | 1초마다 getStats() inbound-rtp를 읽어 재생 지연(drift) 판정, stall guard에 같은 통계 전달 |
apps/web/lib/voice-agent/livekit-playout-stall.ts | 패킷 도착·샘플 정지 판정(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개가 나옵니다.
시나리오를 바꾸면 각 단계의 값과 1초 폴링 stall 판정이 어떻게 달라지는지 보여 줍니다. 숫자는 개념 시뮬레이션이며 실측값이 아닙니다.
지터 버퍼(NetEQ의 패킷 버퍼)는 인코딩된 패킷을 그대로 담아 두고 도착 순서·간격만 맞춥니다. packet → sample 변환은 ③ 디코더가 합니다. 둘이 NetEQ라는 한 모듈에 묶여 있어 흔히 "NetEQ가 변환한다"고 뭉뚱그려 말합니다.
totalSamplesReceived에 포함되고 concealedSamples에도 따로 집계됩니다.오디오 장치 콜백 → <audio> 렌더러 → NetEQ "10ms 줘" → 패킷 꺼냄 → 디코딩 → 샘플 +480. 디코딩과 샘플 카운트가 모두 이 요청 안에서 일어나므로, 요청이 끊기면 패킷만 버퍼에 쌓입니다.
| 단계 | 지표 | 쓰는 곳 |
|---|---|---|
| ① | packetsReceived, bytesReceived | stall 판정(패킷 도착 여부) |
| ② | jitterBufferDelay ÷ jitterBufferEmittedCount | drift 판정(NetEQ 평균 지연) |
| ③ | totalSamplesReceived, concealedSamples | stall 판정, 은닉 비율 |
| ④ | audio.currentTime, paused | drift 판정(렌더 결손), stall 제외 조건 |
| ⑤ | 없음 | 출력단만 멈추거나 밀리면 감시로 못 잡음 |
| 경우 | paused | packets | samples | stall 판정 |
|---|---|---|---|---|
| 정상 | false | ↑ | ↑ | 정상 |
| Playout stall (Chrome 내부 렌더러 정지) | false | ↑ | 0 | 2회 연속이면 감지 → 재부착 → 요소 교체 (세션당 단계별 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 고정이 같이 나오는 다른 증상입니다.
?livekitStallRecovery=off|detect|on.livekit-playout-stall.ts:19)이 이 구조와 일치합니다.