hls.js의 Video Stall 처리 - GapController 따라가기#

#Shaka에 이어, hls.js는 어떻게 다를까

지난 글에서 Shaka Player가 stall을 어떻게 감지하고 복구하는지 따라가 봤습니다. 핵심은 벽시계 시간 기준 폴링과 두 가지 복구 전략(미세 시킹 / pause·play 토글)이었습니다.

같은 문제를 풀어야 하는 hls.js는 어떨까요? hls.js는 MSE 위에서 동작하는 HLS 전용 라이브러리지만, "버퍼는 있는데 currentTime이 안 움직인다"는 문제를 다뤄야 한다는 점은 동일합니다. 다만 접근 방식과 복구 전략의 폭이 Shaka와 흥미롭게 갈립니다.

이 글에서는 hls.js v1.x의 master 브랜치를 기준으로 src/controller/gap-controller.ts 한 파일을 따라가며 hls.js의 stall 처리를 정리하고, 마지막에 Shaka Player와의 차이를 비교합니다.

#hls.js에서 stall 처리는 어디에 있는가

hls.js의 stall 감지/복구 로직은 src/controller/gap-controller.ts 단일 파일에 모여 있습니다. Shaka가 gap_jumping_controller.js에 StallDetector와 GapJumpingController를 함께 두는 것과 구조적으로 비슷합니다.

진입은 GapController 클래스가 담당합니다.

1export default class GapController extends TaskLoop {
2  // ...
3  private onMediaAttached(event, data: MediaAttachedData) {
4    this.setInterval(TICK_INTERVAL);
5    this.mediaSource = data.mediaSource;
6    const media = (this.media = data.media);
7    addEventListener(media, 'playing', this.onMediaPlaying);
8    addEventListener(media, 'waiting', this.onMediaWaiting);
9    addEventListener(media, 'ended', this.onMediaEnded);
10  }
11}

TICK_INTERVAL = 100(ms) 간격으로 tick()이 호출되고, 미디어 엘리먼트의 playing / waiting / ended 이벤트도 함께 구독합니다. waiting이 들어오면 즉시 this.waiting = performance.now()를 저장한 뒤 tick()을 강제로 한 번 더 돌립니다.

1private onMediaWaiting = () => {
2  if (this.media?.seeking) {
3    return;
4  }
5  this.waiting = self.performance.now();
6  this.tick();
7};

tick()은 readyState와 buffered 유무를 확인한 뒤 poll(currentTime, lastCurrentTime)로 본격적인 판정에 들어갑니다.

#poll() — 분기 따라가기

poll()이 hls.js stall 처리의 본체입니다. 분기 순서를 정리하면 다음과 같습니다.

#1. playhead가 움직였는가

1if (currentTime !== lastCurrentTime) {
2  if (lastCurrentTime) {
3    this.ended = 0;
4  }
5  this.moved = true;
6  if (!seeking) {
7    this.skipRetry = this.nudgeRetry = 0;
8    if (
9      config.nudgeOnVideoHole &&
10      !pausedEndedOrHalted &&
11      currentTime > lastCurrentTime
12    ) {
13      this.nudgeOnVideoHole(currentTime, lastCurrentTime);
14    }
15  }
16  if (this.waiting === 0) {
17    this.stallResolved(currentTime);
18  }
19  return;
20}

currentTime이 직전 폴링과 다르면 재생이 정상 진행 중입니다. skipRetry/nudgeRetry 카운터를 0으로 리셋하고, 필요하다면 stallResolved()로 stall 해제 이벤트를 발행한 뒤 종료합니다. 이때 video buffered range 경계를 막 넘어간 상황이라면 nudgeOnVideoHole() 이라는 특수 처리가 끼어듭니다. 이건 뒤에서 다시 다룹니다.

#2. seeking 진입/완료

1if (beginSeek || seeked) {
2  if (seeked) {
3    this.stallResolved(currentTime);
4  }
5  return;
6}

시킹 자체가 일시적으로 currentTime 진행을 멈추기 때문에, 시킹 노이즈로 stall을 오판하지 않도록 빠져나갑니다.

#3. 정지 상태(pausedEndedOrHalted)

1if (pausedEndedOrHalted) {
2  this.skipRetry = this.nudgeRetry = 0;
3  this.stallResolved(currentTime);
4  if (!this.ended && media.ended && this.hls) {
5    this.ended = currentTime || 1;
6    this.hls.trigger(Events.MEDIA_ENDED, { stalled: false });
7  }
8  return;
9}

paused, ended, playbackRate === 0인 경우는 "원래 안 움직여야 정상"이므로 stall 아님으로 처리합니다.

#4. 시킹 중 + 충분한 버퍼 / 멀리 있는 홀

시킹 중이고 점프할 만한 적당한 거리의 홀이 없거나 in-flight fragment가 있다면 종료합니다. 시킹이 마무리되기를 기다리는 단계입니다.

#5. 시작 갭 점프

1if (!this.moved && this.stalled !== null && fragmentTracker) {
2  // ...
3  const startJump = Math.max(nextStart, bufferInfo.start || 0) - currentTime;
4  const isLive = !!levelDetails?.live;
5  const maxStartGapJump = isLive
6    ? levelDetails!.targetduration * 2
7    : MAX_START_GAP_JUMP;
8  const appended = appendedFragAtPosition(currentTime, fragmentTracker);
9  if (startJump > 0 && (startJump <= maxStartGapJump || appended)) {
10    if (!media.paused) {
11      this._trySkipBufferHole(appended);
12    }
13    return;
14  }
15}

아직 한 번도 움직인 적 없는데(!this.moved) stall이 잡혔다면, 영상이 시작 위치 직전의 작은 갭에 걸린 경우일 수 있습니다. 이때는 MAX_START_GAP_JUMP = 2.0초(라이브는 targetduration * 2) 이내라면 _trySkipBufferHole()로 점프합니다.

#6. stall 누적 시작

1const detectStallWithCurrentTimeMs = config.detectStallWithCurrentTimeMs;
2const tnow = self.performance.now();
3const tWaiting = this.waiting;
4let stalled = this.stalled;
5if (stalled === null) {
6  if (tWaiting > 0 && tnow - tWaiting < detectStallWithCurrentTimeMs) {
7    stalled = this.stalled = tWaiting;
8  } else {
9    this.stalled = tnow;
10    return;
11  }
12}

여기까지 도달했다는 건 "재생이 멈춰있고, 시킹/정지 상태도 아니다"라는 뜻입니다. stall 시작 시각을 this.stalled에 기록합니다. 만약 직전에 waiting 이벤트가 detectStallWithCurrentTimeMs(기본 1250ms) 내에 발생했다면 그 시점을, 아니면 현재 시각을 기준으로 잡습니다.

#7. stall 보고

stalledDuration이 임계치를 넘어서거나 이미 waiting 이벤트가 들어와 있고 한 번이라도 재생한 적이 있다면 _reportStall()로 BUFFER_STALLED_ERROR를 1회 발행합니다.

#8. 복구 시도

1const bufferedWithHoles = BufferHelper.bufferInfo(
2  media,
3  currentTime,
4  config.maxBufferHole,
5);
6this._tryFixBufferStall(bufferedWithHoles, stalledDuration, currentTime);

마지막으로 _tryFixBufferStall()을 호출해 실제 복구를 시도합니다.

#복구 전략 1 —_trySkipBufferHole()

_trySkipBufferHole()은 partial fragment로 인해 생긴 작은 홀을 점프해서 해소하는 전략입니다.

1private _trySkipBufferHole(appended: MediaFragment | Part | null): number {
2  // ...
3  const startTime =
4    currentTime < bufferInfo.start ? bufferInfo.start : bufferInfo.nextStart;
5  if (startTime && this.hls) {
6    const bufferStarved = bufferInfo.len <= config.maxBufferHole;
7    const waiting =
8      bufferInfo.len > 0 && bufferInfo.len < 1 && media.readyState < 3;
9    const gapLength = startTime - currentTime;
10    if (gapLength > 0 && (bufferStarved || waiting)) {
11      // ...
12      const targetTime =
13        Math.max(startTime, currentTime) + skipBufferHolePadding;
14      if (!fatal) {
15        media.currentTime = targetTime;
16      }
17      // ...
18    }
19  }
20}

핵심 동작:

• 홀이 maxBufferHole(기본 0.1초)보다 크다면 함부로 점프하지 않고, 그 구간 전체가 partial/appended fragment로 채워질 예정인지를 walk 하면서 확인합니다.
• in-flight fragment가 있으면 점프 보류 — 곧 도착할 데이터를 기다립니다.
• 점프 시 skipBufferHolePadding(기본 0.1초)만큼 여유를 더한 위치로 currentTime을 이동시키고, BUFFER_SEEK_OVER_HOLE 에러를 fatal: false로 발행합니다.
• skipRetry가 nudgeMaxRetry(기본 3)를 초과하면 fatal로 승격됩니다.

#복구 전략 2 —_tryNudgeBuffer()

_tryNudgeBuffer()는 같은 버퍼 안인데 재생이 안 되는 경우를 위한 미세 시킹입니다.

1private _tryNudgeBuffer(bufferInfo: BufferInfo) {
2  const { hls, media, nudgeRetry } = this;
3  const config = hls?.config;
4  // ...
5  this.nudgeRetry++;
6  if (nudgeRetry < config.nudgeMaxRetry) {
7    const targetTime = currentTime + (nudgeRetry + 1) * config.nudgeOffset;
8    media.currentTime = targetTime;
9    hls.trigger(Events.ERROR, {
10      type: ErrorTypes.MEDIA_ERROR,
11      details: ErrorDetails.BUFFER_NUDGE_ON_STALL,
12      // ...
13      fatal: false,
14    });
15  } else {
16    hls.trigger(Events.ERROR, {
17      type: ErrorTypes.MEDIA_ERROR,
18      details: ErrorDetails.BUFFER_STALLED_ERROR,
19      // ...
20      fatal: true,
21    });
22  }
23}

핵심 포인트:

• 재시도 횟수마다 점프 폭이 (nudgeRetry + 1) * nudgeOffset 으로 누진됩니다. 기본값은 nudgeOffset = 0.1이므로 0.1초 → 0.2초 → 0.3초 식으로 점점 크게 흔듭니다.
• nudgeMaxRetry(기본 3)를 초과하면 그제야 BUFFER_STALLED_ERROR를 fatal: true로 발행합니다. 즉 그 전까지는 모든 stall이 recoverable로 분류됩니다.

_tryFixBufferStall()은 partial fragment 홀이 있으면 _trySkipBufferHole()을 먼저 시도하고, 그게 통하지 않거나 해당 상황이 아니면 stalledDuration > highBufferWatchdogPeriod(기본 2초) 조건이 성립할 때 _tryNudgeBuffer()로 넘어갑니다.

#복구 전략 3 —nudgeOnVideoHole()의 0.000001 트릭

세 번째 전략은 hls.js만의 독특한 처방입니다. 이미 재생은 진행되고 있는데 video buffered range 경계를 막 넘는 순간, 디코더가 다음 range를 무시하고 멈춰버리는 Chrome 버그를 회피하기 위한 코드입니다.

1private nudgeOnVideoHole(currentTime: number, lastCurrentTime: number) {
2  // Chrome will play one second past a hole in video buffered time ranges
3  // without rendering any video from the subsequent range and then stall
4  // as long as audio is buffered:
5  // https://github.com/video-dev/hls.js/issues/5631
6  // ...
7  if (
8    (bufferedIndex === -1 || bufferedIndex > lastBufferedIndex) &&
9    holeEnd - holeStart < 1 &&
10    currentTime - holeStart < 2
11  ) {
12    // Magic number to flush the pipeline without interuption to audio playback:
13    this.media.currentTime += 0.000001;
14    // ...
15  }
16}

압권은 this.media.currentTime += 0.000001 한 줄입니다. 사람 눈에는 절대 보이지 않을 마이크로 시킹으로 비디오 디코더 파이프라인을 강제 flush합니다. 주석에는 "Magic number to flush the pipeline without interuption to audio playback"이라고 적혀 있습니다.

발동 조건도 굉장히 까다롭습니다.

• audio buffered range는 연속(playhead 주변에 1초 이상의 audio buffer가 있어야 함)
• video buffered range는 두 개 이상이고, 그 사이 홀이 1초 미만
• 직전 홀의 시작 이후 2초 이내

이런 좁은 조건에서만 미세 시킹을 트리거합니다. 무차별 nudge가 audio 끊김을 유발할 수 있기 때문에 굉장히 보수적으로 가드된 셈입니다.

#숨겨진 디테일들

본체 분기 외에도 코드 곳곳에 흥미로운 보조 로직이 숨어있습니다.

#MAX_START_GAP_JUMP와 라이브 보정

1const isLive = !!levelDetails?.live;
2const maxStartGapJump = isLive
3  ? levelDetails!.targetduration * 2
4  : MAX_START_GAP_JUMP;

상수 MAX_START_GAP_JUMP = 2.0은 VOD 환경의 시작 갭 점프 한도입니다. 라이브 스트림은 targetduration * 2 까지 허용되는데, 라이브 윈도우 슬라이딩으로 audio-stream-controller가 video보다 약간 뒤쪽 프래그먼트를 append하면서 발생하는 시작 갭을 흡수하기 위한 보정입니다.

#adjacentTraversal의sn 가드

1private adjacentTraversal(bufferInfo: BufferInfo, currentTime: number) {
2  const fragmentTracker = this.fragmentTracker;
3  const nextStart = bufferInfo.nextStart;
4  if (fragmentTracker && nextStart) {
5    const current = fragmentTracker.getFragAtPos(currentTime, PlaylistLevelType.MAIN);
6    const next = fragmentTracker.getFragAtPos(nextStart, PlaylistLevelType.MAIN);
7    if (current && next) {
8      return next.sn - current.sn < 2;
9    }
10  }
11  return false;
12}

nudge 시도 전, 현재 프래그먼트와 다음 프래그먼트의 시퀀스 번호(sn) 차이가 2 미만인 경우에만 nudge를 허용합니다. 멀리 떨어진 segment로 점프해버리지 않도록 가드하는 셈입니다.

#stallReported 단일 발행 +STALL_RESOLVED

1private _reportStall(bufferInfo: BufferInfo) {
2  const { hls, media, stallReported, stalled } = this;
3  if (!stallReported && stalled !== null && media && hls) {
4    this.stallReported = true;
5    // ...
6  }
7}
8
9private stallResolved(currentTime: number) {
10  const stalled = this.stalled;
11  if (stalled && this.hls) {
12    this.stalled = null;
13    if (this.stallReported) {
14      // ...
15      this.stallReported = false;
16      this.waiting = 0;
17      this.hls.trigger(Events.STALL_RESOLVED, {});
18    }
19  }
20}

stallReported 플래그로 한 stall 구간당 BUFFER_STALLED_ERROR는 한 번만 발행되고, 해소 시 STALL_RESOLVED가 정확히 한 번 짝맞춰 발행됩니다. 외부에서 카운트할 때는 "정지된 프레임 수"가 아니라 "stall 구간 수"라는 점을 기억해야 합니다.

#외부로 노출되는 이벤트/에러

hls.js는 stall 관련 신호를 모두 Events.ERROR와 Events.STALL_RESOLVED 두 가지 채널로 노출합니다.

특이한 건 fatal: false인 ERROR가 굉장히 자주 발행될 수 있다는 점입니다. nudge 한 번에 한 번씩 발행되므로, 외부에서 무조건 ERROR를 사용자에게 노출하면 안 됩니다. fatal 플래그를 반드시 확인해야 합니다.

#Shaka Player와의 비교

같은 문제를 두 라이브러리가 어떻게 다르게 푸는지를 정리하면 차이가 명확해집니다.

#1. 감지 기준

• Shaka: Date.now() 기반 벽시계 시간으로 정지 여부를 판단. "현재 진행되어야 마땅한가(shouldBeMakingProgress)"라는 별도 판단이 핵심.
• hls.js: performance.now() + waiting 이벤트 시점을 함께 사용. paused / ended / playbackRate === 0을 직접 확인해 진행 여부를 판단.

판정 임계치도 다릅니다. Shaka는 stallThreshold 기본 1초, hls.js는 detectStallWithCurrentTimeMs 기본 1250ms입니다.

#2. 복구 전략 수와 구조

Shaka는 "플랫폼별로 어울리는 단일 전략 하나를 고른다"는 접근입니다. 데스크톱은 시킹, WebOS/Chromecast 같은 임베디드는 pause/play 토글로 자동 갈립니다.

hls.js는 "상황별로 다른 전략을 순차 시도한다"는 접근입니다. partial fragment 홀이면 skip, 같은 버퍼 안이면 nudge, video range 경계 통과면 마이크로 시킹. 그리고 각각이 자체 retry 카운터를 갖습니다.

#3. 시작 갭 vs 일반 stall

• Shaka: GapJumpingController가 buffered ranges 사이의 진짜 gap을 별도로 점프. stall 처리와 gap jump가 같은 onPollGapJump_() 안에서 동작하지만 책임은 분리.
• hls.js: 시작 갭 점프도 _trySkipBufferHole() 한 메서드가 담당. MAX_START_GAP_JUMP와 라이브 targetduration * 2 보정으로 구간을 다르게 적용.

#4. 플랫폼 적응 vs 단일 정책

• Shaka: lib/device/webos.js, lib/device/chromecast.js의 adjustConfig()에서 디바이스별로 stallSkip = 0을 강제. 즉 디바이스 인지 기반 정책.
• hls.js: 디바이스별 분기 대신, 상황 인지 기반 분기. nudgeOnVideoHole은 사실상 Chrome 버그를 겨냥하지만, 코드는 디바이스가 아니라 buffered ranges 형태를 보고 판단합니다.

#5. 설계 철학

한 줄로 요약하면 다음과 같습니다.

Shaka는 "플랫폼별로 어울리는 단일 처방"을 선택한다. hls.js는 "상황별로 다른 처방을 누진 적용"한다.

Shaka가 디바이스 다양성을 우선시한다면, hls.js는 동일 디바이스 안에서도 매니페스트·세그먼트 구조에서 비롯되는 다양한 갭 패턴을 우선시합니다. 두 접근 모두 해당 라이브러리가 주로 사용되는 환경(Shaka는 OTT/CTV, hls.js는 브라우저)에 잘 맞춰져 있습니다.

#실전 가이드 — React 환경에서 이벤트 구독

자동 복구는 hls.js가 알아서 해주므로, 앱 레벨에서 할 일은 사용자 안내와 텔레메트리입니다. ERROR 이벤트에서 stall 관련 detail만 필터링하고, STALL_RESOLVED로 해제 시점을 잡는 훅을 예시로 작성해 봅니다.

1import { useEffect, useRef, useState } from 'react'
2import Hls from 'hls.js'
3
4interface StallState {
5  isStalled: boolean
6  stallCount: number
7  nudgeCount: number
8  lastStallAt: number | null
9}
10
11const STALL_DETAILS = new Set([
12  'bufferStalledError',
13  'bufferSeekOverHole',
14])
15
16export function useHlsStallMonitor(hls: Hls | null) {
17  const [state, setState] = useState<StallState>({
18    isStalled: false,
19    stallCount: 0,
20    nudgeCount: 0,
21    lastStallAt: null,
22  })
23
24  useEffect(() => {
25    if (!hls) return
26
27    const onError = (_evt: unknown, data: Hls.errorData) => {
28      if (data.details === 'bufferNudgeOnStall') {
29        setState((prev) => ({ ...prev, nudgeCount: prev.nudgeCount + 1 }))
30        return
31      }
32      if (STALL_DETAILS.has(data.details) && !data.fatal) {
33        setState((prev) => ({
34          ...prev,
35          isStalled: true,
36          stallCount: prev.stallCount + 1,
37          lastStallAt: Date.now(),
38        }))
39      }
40    }
41
42    const onResolved = () => {
43      setState((prev) => ({ ...prev, isStalled: false }))
44    }
45
46    hls.on(Hls.Events.ERROR, onError)
47    hls.on(Hls.Events.STALL_RESOLVED, onResolved)
48    return () => {
49      hls.off(Hls.Events.ERROR, onError)
50      hls.off(Hls.Events.STALL_RESOLVED, onResolved)
51    }
52  }, [hls])
53
54  return state
55}

이 훅은 hls.js의 복구 로직을 대체하지 않습니다. BUFFER_STALLED_ERROR와 BUFFER_SEEK_OVER_HOLE은 stall 보고/스킵 시점을, BUFFER_NUDGE_ON_STALL은 미세 시킹 횟수를, STALL_RESOLVED는 해제 시점을 알려줍니다. 사용자 UI 표시와 텔레메트리 전송에 그대로 활용할 수 있습니다.

#정리

hls.js의 stall 처리를 한 흐름으로 요약하면 다음과 같습니다.

1. MEDIA_ATTACHED → 100ms 폴링 + waiting 이벤트 트리거
2. poll(): playhead 이동, seeking, paused·ended, 시작 갭, stall 누적을 단계별로 분기
3. _tryFixBufferStall(): 상황에 따라 _trySkipBufferHole() → _tryNudgeBuffer() 순서로 시도
4. 별개로 nudgeOnVideoHole()이 Chrome video hole 버그를 마이크로 시킹으로 회피
5. ERROR(fatal: false 위주) + STALL_RESOLVED 이벤트로 외부에 신호

Shaka Player와 hls.js는 결국 다른 길로 같은 곳에 도착합니다. Shaka는 플랫폼별로 처방을 골라 적용하고, hls.js는 상황별로 처방을 누진 적용합니다. 만약 라이브러리 선택지가 둘 다 열려 있다면, 임베디드 디바이스 비중이 크고 디바이스별 정책 분기를 줄이고 싶다면 Shaka가, 브라우저 위주이고 partial fragment·라이브 윈도우 같은 매니페스트 변동성을 정밀하게 다뤄야 한다면 hls.js가 더 어울리는 선택이 될 수 있습니다.

다음에 영상이 멈춘다는 사용자 제보를 받고 라이브러리 소스로 내려가야 한다면, hls.js의 경우 가장 먼저 살펴볼 곳은 gap-controller.ts 한 파일이라는 점만 기억해두면 됩니다. 거기에 답이 거의 다 들어 있습니다.