HLS(HTTP Live Streaming) 완벽 가이드: 음악 스트리밍 서비스의 핵심 기술

#EXTM3U
#EXT-X-VERSION:4

#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=640x360,CODECS="avc1.4d401f,mp4a.40.2"
quality_360p/playlist.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=1400000,RESOLUTION=1280x720,CODECS="avc1.4d401f,mp4a.40.2"
quality_720p/playlist.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=2800000,RESOLUTION=1920x1080,CODECS="avc1.640028,mp4a.40.2"
quality_1080p/playlist.m3u8

#EXTM3U
#EXT-X-VERSION:4
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-KEY:METHOD=AES-128,URI="https://key-server.example.com/key?track=audio",IV=0x1234567890ABCDEF

#EXTINF:10.0,
segment_001.ts
#EXTINF:10.0,
segment_002.ts
#EXTINF:10.0,
segment_003.ts
#EXTINF:8.5,
segment_004.ts

#EXT-X-ENDLIST

Master Playlist (index.m3u8)
├── 360p Media Playlist (quality_360p/playlist.m3u8)
│   ├── segment_001.ts
│   ├── segment_002.ts
│   └── ...
├── 720p Media Playlist (quality_720p/playlist.m3u8)
│   ├── segment_001.ts
│   ├── segment_002.ts
│   └── ...
└── 1080p Media Playlist (quality_1080p/playlist.m3u8)
    ├── segment_001.ts
    ├── segment_002.ts
    └── ...

원본 파일 (3분 곡)
    ↓ 분할
18개의 ts 세그먼트 (각 10초)

#EXT-X-KEY:METHOD=AES-128,URI="https://keyserver.example.com/getKey?token=eyJhbGc...",IV=0x1234567890ABCDEF

// 전통적 다운로드
downloadFile('song.mp3') // 전체 파일 획득 가능

// HLS 스트리밍
// segment_001.ts, segment_002.ts, ... 수십 개 파일
// + 암호화되어 있음
// + 키가 없으면 무용지물

// 키서버 요청 예시
const keyResponse = await fetch('https://keyserver.example.com/getKey', {
  headers: {
    Authorization: `Bearer ${userToken}`,
    'X-Device-ID': deviceId,
    'X-Session-ID': sessionId,
  },
})

// URL에 시간 기반 토큰 추가
const signedUrl = `https://cdn.example.com/segment.ts?token=${generateToken(userId, expiresAt)}`

보안 수준 ↑                    지연시간 ↓
──────────────────────────────────────────
Strong DRM (Widevine, FairPlay)    ← 가장 안전, 구현 복잡
HLS + AES-128 + Token Auth         ← 실무에서 많이 사용
HLS + AES-128                      ← 기본적 보호
Plain HLS                          ← 보안 없음

npm install hls.js

import Hls from 'hls.js'

function initHlsPlayer(videoElement: HTMLVideoElement, streamUrl: string) {
  // 1. iOS Safari 등 네이티브 지원 브라우저 처리
  // 중요: iOS Safari는 MSE를 통한 HLS를 지원하지 않으므로 hls.js 사용 불가
  if (videoElement.canPlayType('application/vnd.apple.mpegurl')) {
    videoElement.src = streamUrl
    videoElement.play()
    return
  }

  // hls.js 지원 여부 확인
  if (!Hls.isSupported()) {
    console.error('HLS is not supported in this browser')
    return
  }

  const hls = new Hls({
    debug: false,
    enableWorker: true,
    lowLatencyMode: true,
  })

  hls.loadSource(streamUrl)
  hls.attachMedia(videoElement)

  hls.on(Hls.Events.MANIFEST_PARSED, () => {
    console.log('Manifest loaded, starting playback')
    videoElement.play()
  })

  hls.on(Hls.Events.ERROR, (event, data) => {
    if (data.fatal) {
      switch (data.type) {
        case Hls.ErrorTypes.NETWORK_ERROR:
          console.error('Network error, trying to recover...')
          hls.startLoad()
          break
        case Hls.ErrorTypes.MEDIA_ERROR:
          console.error('Media error, trying to recover...')
          hls.recoverMediaError()
          break
        default:
          console.error('Fatal error, cannot recover')
          hls.destroy()
          break
      }
    }
  })

  return hls
}

import Hls from 'hls.js'

const hls = new Hls({
  // 커스텀 XHR 설정
  xhrSetup: (xhr: XMLHttpRequest, url: string) => {
    // 키서버 요청에 인증 헤더 추가
    if (url.includes('keyserver')) {
      xhr.setRequestHeader('Authorization', `Bearer ${getAccessToken()}`)
      xhr.setRequestHeader('X-Device-ID', getDeviceId())
    }
  },

  // 또는 fetch 기반 로더 사용
  loader: class CustomLoader extends Hls.DefaultConfig.loader {
    load(context: any, config: any, callbacks: any) {
      const { url, type } = context

      if (type === 'key') {
        // 키 요청 커스터마이징
        fetch(url, {
          headers: {
            Authorization: `Bearer ${getAccessToken()}`,
          },
        })
          .then((response) => response.arrayBuffer())
          .then((data) => {
            callbacks.onSuccess({ data }, { url }, context)
          })
          .catch((error) => {
            callbacks.onError({ code: 0, text: error.message }, context, null)
          })
      } else {
        // 일반 요청은 기본 로더 사용
        super.load(context, config, callbacks)
      }
    }
  },
})

const hls = new Hls({
  // ABR(Adaptive Bitrate) 설정
  abrController: Hls.DefaultConfig.abrController,
  abrEwmaDefaultEstimate: 500000, // 초기 대역폭 추정 (500 kbps)
  abrBandWidthFactor: 0.95, // 대역폭 사용률
  abrBandWidthUpFactor: 0.7, // 품질 상향 시 대역폭 요구량

  // 버퍼 설정
  maxBufferLength: 30, // 최대 버퍼 길이 (초)
  maxBufferSize: 60 * 1000 * 1000, // 최대 버퍼 크기 (60MB)
  maxBufferHole: 0.5, // 버퍼 홀 허용치 (초)
})

// 이벤트를 통한 품질 모니터링
hls.on(Hls.Events.LEVEL_SWITCHED, (event, data) => {
  console.log(`품질 변경: Level ${data.level}`)
  const level = hls.levels[data.level]
  console.log(`해상도: ${level.width}x${level.height}`)
  console.log(`비트레이트: ${(level.bitrate / 1000).toFixed(0)} kbps`)
})

// 수동 품질 선택 (자동 ABR 비활성화)
function setQuality(levelIndex: number) {
  hls.currentLevel = levelIndex // -1이면 자동
}

import { useEffect, useRef, useState } from 'react'
import Hls from 'hls.js'

interface HlsPlayerProps {
  src: string
  autoPlay?: boolean
  onReady?: () => void
  onError?: (error: string) => void
}

export function HlsPlayer({ src, autoPlay = false, onReady, onError }: HlsPlayerProps) {
  const videoRef = useRef<HTMLVideoElement>(null)
  const hlsRef = useRef<Hls | null>(null)
  const [currentQuality, setCurrentQuality] = useState<string>('Auto')

  useEffect(() => {
    const video = videoRef.current
    if (!video) return

    // Safari는 네이티브 HLS 지원
    if (video.canPlayType('application/vnd.apple.mpegurl')) {
      video.src = src
      onReady?.()
      return
    }

    if (!Hls.isSupported()) {
      onError?.('HLS is not supported')
      return
    }

    const hls = new Hls({
      enableWorker: true,
      lowLatencyMode: true,
    })

    hlsRef.current = hls

    hls.loadSource(src)
    hls.attachMedia(video)

    hls.on(Hls.Events.MANIFEST_PARSED, () => {
      onReady?.()
      if (autoPlay) {
        video.play().catch(console.error)
      }
    })

    hls.on(Hls.Events.LEVEL_SWITCHED, (_, data) => {
      const level = hls.levels[data.level]
      setCurrentQuality(`${level.height}p`)
    })

    hls.on(Hls.Events.ERROR, (_, data) => {
      if (data.fatal) {
        onError?.(data.type)
      }
    })

    return () => {
      hls.destroy()
    }
  }, [src, autoPlay, onReady, onError])

  return (
    <div className="relative">
      <video ref={videoRef} controls className="w-full rounded-lg" playsInline />
      <div className="absolute right-4 bottom-16 rounded bg-black/70 px-2 py-1 text-sm text-white">
        {currentQuality}
      </div>
    </div>
  )
}

hls.on(Hls.Events.ERROR, (event, data) => {
  if (data.fatal) {
    switch (data.type) {
      case Hls.ErrorTypes.NETWORK_ERROR:
        // 인터넷 연결 문제 등 -> 재시도 로직
        console.log('네트워크 에러, 스트림 로드 재시도...')
        hls.startLoad()
        break
      case Hls.ErrorTypes.MEDIA_ERROR:
        // 깨진 세그먼트 등 -> 해당 구간 건너뛰기 시도
        console.log('미디어 에러, 자동 복구 시도...')
        hls.recoverMediaError()
        break
      default:
        // 복구 불가능한 에러 -> 플레이어 파괴 및 사용자 알림
        console.error('복구 불가능한 치명적 에러')
        hls.destroy()
        // 사용자에게 "재생할 수 없습니다" UI 표시
        break
    }
  } else {
    // Non-fatal 에러 (일시적 버퍼 부족 등) -> 로그만 남김
    console.warn('Non-fatal error:', data.details)
  }
})

// 클라이언트 측 캐시 방지 설정 예시
const hls = new Hls({
  xhrSetup: (xhr, url) => {
    if (url.includes('keyserver')) {
      xhr.setRequestHeader('Cache-Control', 'no-cache')
    }
  },
})

const hls = new Hls({
  // 초기 버퍼링 최소화 (빠른 시작)
  maxBufferLength: 10,
  maxMaxBufferLength: 30,

  // Low Latency 모드
  lowLatencyMode: true,
  liveSyncDuration: 3,
  liveMaxLatencyDuration: 10,

  // 세그먼트 prefetch
  maxBufferHole: 0.5,
})

사용자 요청
    ↓
엣지 서버 (가까운 위치)
    ↓ (캐시 miss 시)
오리진 서버