마지막 업데이트 2026-10-22
증상: 아동 화면에서 활동 첫 영상 movie_04(주원퇴장영상)와 movie_05(복도브릿지영상)가 재생되지 않았다. loadedmetadata 직후 5~7ms 만에 Video error event fired가 발생했다(readyState 1, currentTime 0). 진행자가 다음 스텝으로 넘길 때까지 화면이 각각 44초, 28초 멈췄다.
배제: 콘텐츠 문제는 아니다. 원본은 H.264 Baseline·faststart이고 전체 디코드에서도 오류가 없었으며, 진행자 데스크톱에서는 정상 재생됐다. 캐시·blob 경로도 원인이 아니다. 정상 재생된 03·08도 똑같이 진입 직전에 새로 다운로드한 blob이었다. LiveKit 쪽 이상도 없다. 실패 건과 정상 건의 연결 지표가 같다.
유일한 차이(가설): 활동 첫 영상 동안 다음 AI 세션을 미리 여는 기능(PPI-1351)의 LiveKit 연결 완료와 오디오 그래프 생성이 영상 loadstart보다 먼저 끝난 경우에만 영상이 실패했다. 영상이 먼저 로드를 시작한 03은 정상이었다. 실패 2건과 정상 1건만 비교한 것이라 확정이 아니다.
확정 걸림돌: 영상 에러 로그에 video.error.code와 message가 없다. Chrome은 이 message에 PIPELINE_ERROR_DECODE 같은 상세 원인을 넣어 주므로, 이 값만 있으면 원인을 바로 가를 수 있다.
적용(로컬): 에러 로그에 mediaErrorCode·mediaErrorMessage를 남기고, 첫 에러 뒤 500ms에 같은 blob으로 load()를 1회 재시도한다. 사전 준비 순서 조정(제안 3)은 재로드 결과를 본 뒤 결정한다(5절).
| 단계 | 파일:줄 | 역할 |
|---|---|---|
| 활동 전환 | entities/guest-page-session/model/use-step-transition.ts:109-117 | 새 활동 진입 시 기존 AI 세션 종료 |
| AI 사전 준비 | use-step-transition.ts:139-166 | 비AI 첫 스텝이면 first_video_prepare_requested 로그 후 prepareSession()을 await 없이 시작 |
| 사전 준비 조건 | entities/guest-page-session/lib/first-video-ai-prepare.ts:15-55 | 새 활동의 full:video이고 뒤쪽에 AI 스텝이 있을 때. 기본 on, ?aiPrepare=off 또는 localStorage로 끔 |
| 오디오 그래프 | lib/voice-agent/livekit-audio-chain-processor.ts:402 | Audio chain graph built 로그 |
| 영상 에러 | shared/ui/meet-video.tsx:778-808 | 분석 시점에는 getPlaybackSnapshot(:317)만 기록하고 재시도가 없었다. 적용 후 MediaError code·message를 기록하고 1회 재로드한다(5절). |
| 리소스 캐시 | hooks/use-resource-cache.ts:426-470 | 디스크 캐시 적중 시 로그 없이 blob 반환, 미적중이면 S3 다운로드 후 Successfully cached |
-750 자동전환 매칭 "됐어!안들을래!" → activity 8 / step 0 (full:video) -625 이전 LiveKit 방(jwv2) disconnected -621 first_video_prepare_requested → 다음 AI 세션 사전 준비 시작 (await 없음) -463/-375 다음 아바타 sav3 idle·talking 새로 다운로드 -436 LiveKit connecting (sav3 방) -214 LiveKit connected -73 Audio chain graph built → -70 livekit_connect_end -41 movie_04 S3 새로 다운로드 완료 → blob URL -13 loadstart → -7 loadedmetadata (1280x720, 24.768s) -1 RESOURCE_ERROR blob:… 0 Video error event fired readyState 1 · networkState 1 · currentTime 0 +379 session_prepared (AI 세션 정상 준비 완료) +44.3s 진행자 전환으로 step 1 진입 (영상은 끝내 재생 안 됨)
| 직전 상황 | 04 실패 | 05 실패 | 03 정상 | 08 정상 |
|---|---|---|---|---|
| 영상 새로 다운로드 (캐시 미적중) | O | O | O | O |
| 다음 아바타 영상 새로 다운로드 | O (sav3) | O (jwv3) | O (jwv2) | X |
| AI 사전 준비 | O | O | O | X (마지막 활동) |
| LiveKit connected 시점 | loadstart 전 (-201) | loadstart 전 (-259) | loadstart 후 (+27) | — |
| graph built 시점 | loadstart 전 (-60) | loadstart 전 (-80) | canplay 후 (+49) | — |
| 결과 | error | error | canplay·재생 | canplay·ended |
| 항목 | 03 정상 | 04 실패 | 05 실패 |
|---|---|---|---|
| connect 소요 | 441ms | 368ms | 560ms |
| agent_ready 소요 | 481ms | 449ms | 583ms |
| 이후 60초 Audio chain health | 11/11 정상 | 12/12 정상 | 12/12 정상 |
| warn/error | 셋 다 DataChannel closed, Failed to flush pending LiveKit ASR continuation window만 있음 (활동 전환마다 나오는 고정 로그) | ||
| 가설 | 판정 | 근거 |
|---|---|---|
| 콘텐츠(인코딩) 손상 | 기각 | movie_04 원본 ffprobe·ffmpeg -xerror 전체 디코드 무오류, 진행자 데스크톱 정상 |
| 대기실 프리페치 누락 → 새 다운로드 blob 문제 | 기각 (단독 원인 아님) | 정상 03·08도 새 다운로드. intro·01·02만 캐시 적중, 활동 7 이후 전부 미적중(프리페치 중단 추정, LogRocket Guest:WaitingPrefetchFinished로 확인 필요) |
| 아바타 blob 로드 부하 | 기각 (단독 원인 아님) | 정상 03도 직전 jwv2 로드 |
| 저사양 디코드 과부하 (DECODE_OVERLOAD) | 해당 없음 | 8코어/8GB, 저사양 false. 실패는 재생 중이 아니라 첫 프레임 전 |
| LiveKit 오디오 경로 활성화 직후 영상 파이프라인 초기화 실패 | 유력 (미확정) | 실패 2건만 connected·graph built가 loadstart 앞. Android Chrome에서 WebRTC 오디오 출력이 막 활성화된 순간 영상의 디코더나 오디오 렌더러 확보가 실패한 것으로 추정. 경로별 검토는 4-1절 |
이 절의 내용은 코드와 구조에서 추론한 것이고 확정이 아니다.
loadstart → loadedmetadata (성공: 1280x720, 24.768s, moov 파싱)
→ [디코더·렌더러 준비 → 첫 프레임 디코드 → readyState 2] ✗ 도달 못 함
→ 5~7ms 뒤 error (readyState 1, currentTime 0)
DECODE_OVERLOAD와는 다르다. 그 경우는 readyState가 2 이상이고, 브라우저 error 이벤트 없이 watchdog이 감지한다. 이번 건은 브라우저가 error를 직접 냈다.error 로그에 프레임 수(getDecodeInfo)가 없어서 totalVideoFrames=0도 readyState 1에서 추론한 값이다.lib/voice-agent/livekit-client-session.ts):4120), 그 트랙을 처리하는 WebAudio 그래프(EQ·compressor·limiter)를 공유 AudioContext 위에 만든다. 이때 Audio chain graph built 로그가 남는다.| 경로 | 가능성 | 이유 |
|---|---|---|
| 영상 디코더(하드웨어 MediaCodec) 직접 경합 | 낮음 | LiveKit은 오디오만 다루고 Opus를 소프트웨어로 디코드하므로 영상 하드웨어 디코더를 쓰지 않는다. |
| 오디오 출력·렌더러 경합 | 상대적으로 유력 | 새 AI 오디오 출력이 열리는 순간 영상의 오디오 렌더러가 초기화된다. 렌더러 초기화가 실패하면 Chrome은 영상까지 포함한 파이프라인 전체를 error로 처리한다. |
| 앱 WebAudio 그래프(공유 AudioContext) 경합 | Android 해당 없음 | 영상 오디오를 공유 ctx로 보내는 loopback은 iOS 게스트에서만 켜진다(shared/ui/guest-layout-content.tsx:98-103). Android에서는 영상 오디오가 <video> 기본 출력으로 바로 나가므로 LiveKit 그래프와 앱 안에서 공유하는 노드가 없다. |
| Android 통화 모드 전환 | 낮음 | WebRTC가 오디오를 쓰면 Android가 통화 모드로 바뀌지만, 아동 마이크는 mediasoup으로 이미 송출 중이라 이 시점에 처음 바뀌는 게 아니다. |
| CPU 순간 부하 | 낮음 | 부하라면 지연이나 정체로 나타나야 하는데, 5~7ms 만에 바로 error가 났다. |
| 같은 시점 아바타 영상(blob) 로드 | 별개 변수 | 하드웨어 디코더를 실제로 쓰지만, 정상 재생된 03에도 같은 로드(jwv2)가 있었다. |
영상 <video> 오디오 ─┐
├→ Chrome 오디오 서비스 → Android 오디오 출력
LiveKit AI 오디오 ─────┘ (WebRTC 재생)
앱 코드에서는 겹치는 곳이 없고, 브라우저와 OS의 출력 계층에서만 만난다. 실패 2건은 LiveKit 연결과 graph built가 영상 loadstart보다 먼저 끝났고, 정상 1건(03)은 순서가 반대였다(3절). 이 순서 차이와 위 설명이 맞아떨어진다.
NetEQ는 WebRTC의 수신 오디오 처리 엔진이다. 네트워크로 들어온 오디오 패킷을 끊김 없는 PCM으로 바꿔 렌더러에 넘기는 일까지 맡는다.
네트워크 RTP 패킷 → [NetEQ] → 10ms 단위 PCM → 오디오 렌더러(<audio>·출력 싱크) → 스피커
| 하는 일 | 설명 |
|---|---|
| 지터 버퍼 | 불규칙하게 도착한 패킷을 잠시 모았다가 일정 간격으로 꺼낸다. 버퍼 깊이는 네트워크 상태를 보고 스스로 조절한다. |
| 디코드 | Opus 같은 코덱 패킷을 PCM으로 푼다. Opus 디코드는 NetEQ 안에서 소프트웨어로 처리한다. |
| 패킷 손실 은닉(PLC) | 빠진 패킷 자리를 앞뒤 소리로 만든 그럴듯한 소리로 메운다. |
| 시간 늘이기·줄이기 | 버퍼가 비어 가면 소리를 살짝 늘리고(감속), 쌓이면 줄여서(가속) 지연을 맞춘다. 음높이는 유지한다. |
| 순서 정렬·중복 제거 | 늦게 오거나 순서가 바뀐 패킷을 재정렬하고 중복은 버린다. |
| 무음·컴포트 노이즈 | 상대가 말하지 않아 패킷이 줄어든 구간(DTX)에 자연스러운 배경음을 채운다. |
LiveKit 재생 정체(Playout stall detected, 패킷은 수신·samples 0)를 복구하면 그동안 쌓인 패킷이 가속으로 소진되며 빨리감기가 난다(윤건이 10/20 사례, 추정). NetEQ 버퍼만 비우는 웹 API는 없다.
재생 정체 (요소가 PCM을 가져가지 않음) → RTP 패킷은 계속 도착 → NetEQ 버퍼에 쌓임 → reattach/replace 복구 (livekit-client-session.ts:3447)는 <audio> 요소만 교체 → RTCRtpReceiver·NetEQ는 그대로 → 쌓인 버퍼 유지 → 재생 재개 → 버퍼가 목표치를 크게 넘음 → 가속 → 빨리감기
| 방법 | 버퍼 초기화 | 비용·위험 |
|---|---|---|
트랙 재구독 setSubscribed(false→true) | 됨(추정). 수신기가 새로 생기며 NetEQ도 새로 만들어짐 | 재협상 수백 ms, 밀린 발화 구간 손실. transceiver 재사용 시에도 새로 생기는지 실측 필요 |
| 가속 구간 음소거 | 안 됨. 빨리감기 소리만 가림 | getStats removedSamplesForAcceleration 증가가 멈출 때까지 muted. 구현은 쉽지만 내용 손실은 같음 |
jitterBufferTarget 조정 | 안 됨 | 목표 지연만 바꿈. 낮추면 가속이 더 세짐 |
setEnabled(false/true) | 안 됨 | 서버 전송만 멈춤. 클라이언트에 쌓인 패킷은 남음 |
| Agent 발화 취소·재생성 | 의미상 초기화 | 재구독과 함께 써야 소리도 깔끔하게 끊김 |
일반적인 웹 서비스는 버퍼를 직접 비우지 않는다. 세 층 중 하나에 맡긴다.
| 계열 | 대응 | 특징 |
|---|---|---|
| 화상회의 (Meet, Zoom 웹, Discord) | NetEQ에 맡김. 짧은 정체는 가속으로 따라잡고, 버퍼가 넘치면 NetEQ가 스스로 비운다 | 사람 간 통화에서 1~2초 빨라짐은 순간 끊김으로 받아들여진다 |
| 긴 정체·미디어 경로 이상 | ICE restart나 PeerConnection 재생성(LiveKit SDK의 resume·full reconnect) | 수신기가 새로 생겨 버퍼도 사라진다. 재구독과 같은 효과지만 목적은 연결 복구다 |
| 음성 AI (OpenAI Realtime, LiveKit Agents, Pipecat) | "사용자가 실제로 어디까지 들었나"를 서버와 맞춘다. OpenAI는 conversation.item.truncate(audio_end_ms), LiveKit Agents는 끼어들기 때 재생된 위치까지만 기록한다 | 밀린 발화를 따라잡지 않고 취소·재생성한다. 듣지 못한 말을 AI가 "말했다"고 기억하는 문제가 더 크다 |
removedSamplesForAcceleration가 크게 늘고 jitterBufferDelay / jitterBufferEmittedCount가 높으면 NetEQ로 확정한다. 이 값들이 평범하면 백로그는 SFU나 TURN/TCP 쪽에 있고, 클라이언트 초기화는 소용없다.AI 사전 준비 → WebRTC 연결 → NetEQ → AI <audio> 출력 싱크 열림
✕ 동시에
MP4 <video> → 오디오 렌더러 → 출력 싱크 열기 실패 → 파이프라인 error → 멈춤
| 고리 | 판단 | 근거 |
|---|---|---|
| NetEQ | 무관 | 패킷을 버퍼링·디코드하는 단계일 뿐 출력 장치를 열지 않는다(위 참고). |
| AI 오디오 싱크가 열리는 시점 | 확인 필요 | AI 트랙을 구독하면 <audio>에 붙일 때(livekit-client-session.ts:3426) 싱크가 열린다. movie_04는 agent_ready가 error보다 약 45ms 뒤(connecting −436 + 481ms)라 error 시점에 AI 싱크가 아직 없었을 수 있다. movie_05는 약 190ms 앞이라 두 건이 엇갈린다. |
| MP4 싱크 실패 → error | 약함 | 알려진 Chrome 동작상 영상의 오디오 출력 장치에 오류가 나면 null sink로 바꿔 재생을 계속한다(확인 필요). 이 경우 결과는 error가 아니라 무음 재생이다. |
setSinkId 실패 | 해당 없음 | 실패하면 video setSinkId failed warn만 남고 error 이벤트로 이어지지 않는다. 이번 세션에는 이 warn도 없었다. |
싱크 실패가 원인이라면 증상은 멈춤이 아니라 무음 재생이어야 맞다. readyState 1에서 error가 난 이번 패턴에는 디코더(MediaCodec) 할당 실패가 더 잘 맞는다(추정).
LiveKit remote audio track subscribed 시각을 영상 error와 비교한다. 실패 2건 모두 error보다 뒤라면 AI 오디오 싱크 경합은 기각된다.mediaErrorMessage를 본다. 렌더러 계열(예: PIPELINE_ERROR_COULD_NOT_RENDER)이면 이 가설이 확인되고, 디코드 계열(PIPELINE_ERROR_DECODE, DECODER_ERROR_NOT_SUPPORTED)이면 디코더 쪽으로 다시 본다. 정확한 문자열은 Chrome 버전에 따라 다르다.?aiPrepare=off로 A/B 비교한다.| 제안 | 상태 | 내용 |
|---|---|---|
| 1. MediaError 기록 | 적용(로컬) | Video error event fired 로그에 mediaErrorCode, mediaErrorMessage, reloadAttempted를 추가했다. 다음 재발 때 디코드 실패(PIPELINE_ERROR_DECODE)인지 렌더러 초기화 실패인지 갈린다. 공용 getPlaybackSnapshot은 바꾸지 않아 다른 로그는 그대로다. |
| 2. 에러 후 1회 재로드 | 적용(로컬) | 같은 영상 URL에서 첫 error가 나면 ERROR_RELOAD_DELAY_MS(500ms) 뒤 같은 blob으로 load()를 한 번 다시 시도하고 Video error reload attempt 로그를 남긴다. 재생 재개는 기존 경로를 쓴다(모바일은 autoPlay, 데스크톱은 canplay 핸들러). 복구되면 기존 onMediaVideoRecovered가 진행자에게 "복구"를 보낸다. |
| 3. 사전 준비를 canplay 이후로 | 보류 | 재로드 결과를 보고 결정한다(아래). |
4. ?aiPrepare=off A/B | 배포 불필요 | 이미 있는 런타임 오버라이드다. |
apps/web/shared/ui/meet-video.tsx)errorReloadAttemptedRef는 영상 URL이 바뀔 때만(:411) 초기화한다. 재로드가 일으키는 loadstart에서는 초기화하지 않으므로 무한 재시도가 생기지 않는다. 두 번째 error부터는 기존처럼 멈춘 상태로 둔다.onMediaVideoError)은 기존처럼 첫 error 때 바로 보낸다.meet-video.test.tsx): code·message 기록, error가 없을 때 null 기록, 1회만 재로드, 언마운트 시 취소, URL 변경 후 재시도 기회 재생성. 11개 모두 통과했다.currentTime을 0으로 되돌린다. 이번 사례처럼 첫 프레임 전 실패에는 문제가 없지만, 재생 도중 error가 나면 영상이 처음부터 다시 나온다. 모니터 seek 모드에서도 재로드 뒤 위치를 다시 맞추지 않는다.agent_ready까지는 0.5초 안팎이다(3절). canplay까지 수백 ms 늦춰도 AI 스텝 전에 준비가 끝나므로, 첫 응답 지연이 다시 늘어나는 것은 영상이 아주 짧을 때뿐이다.use-step-transition에 있고 canplay 신호는 공용 UI인 MeetVideo에 있어서, 둘을 잇는 신호를 새로 연결해야 한다. canplay가 끝내 오지 않거나 error가 나도 준비를 시작하도록 대체 타이머(예: 3초)가 반드시 필요하다.mediaErrorMessage와 Video error reload attempt 뒤의 canplay(또는 두 번째 error, 이때 reloadAttempted: true)를 확인 → 제안 3 여부를 결정한다.c7293248, 2026-10-02, release 3.4.6부터)이 활동 첫 영상 동안 AI 세션을 미리 연결하기 시작했다. 같은 시그니처(loadedmetadata 직후 error, readyState 1)의 Android 사례가 이 릴리스 전에도 있었는지 대조하면 가설을 검증할 수 있다.Successfully cached 로그는 캐시 미적중(새 다운로드)일 때만 남는다. 이 로그가 없으면 디스크 캐시 적중이다.