mp4hls¶

/usr/local/m2/setting.json 다음 영역에 대해 기술한다.

{
  "functions": {
    "network": {
      "mp4hls": {
        ...
      }
    }
  }
}

How to use¶

명령어 리스트¶

용량제한 없는 HLS를 제공한다.

# 인덱스 파일을 제공한다.
https://foo.com/video.mp4/mp4hls/index.m3u8
https://foo.com/video.mp4/mp4hls/playlist.m3u8

# 분할된 미디어 파일을 mpeg2-ts로 전송한다.
https://foo.com/video.mp4/mp4hls/0.ts
https://foo.com/video.mp4/mp4hls/1.ts

# 라이브 방송을 제공한다.
https://foo.com/video.mp4/mp4hls/live/start=20250729100000/index.m3u8
https://foo.com/video.mp4/mp4hls/live/start=20250730143050;buffer=60/index.m3u8

에러 메시지¶

응답코드	`x-sc-chain-error` 필드	설명
원본응답	`not200`	원본에서 `200 OK` 를 응답받지 못함
원본응답	`ftpy`	MP4헤더 값이 `ftyp` 가 아님
원본응답	`invalidseq`	잘못된 HLS 인덱스 번호
원본응답	`toosmall`	원본이 최소구성크기(8bytes) 미만
원본응답	`failcache`	원본콘텐츠 캐시로딩 실패
원본응답	`failtrim`	MP4 분할실패
`415`	`noav`	오디오/비디오 트랙 모두 없음
`415`	`failparse`	MP4 분석실패
`415`	`failseek`	MP4 탐색실패
`415`	`failbuf`	MP4 소스버퍼 할당실패
`415`	`failinits`	MPEG2-TS 초기화 실패
`415`	`failgents`	MPEG2-TS 생성 실패

meta¶

"meta" : {
  "enable": false,
  "keyword": "mp4hls"
}

enable (기본: false): MP4편집 활성화
keyword (기본: mp4hls): MP4편집 키워드

hls¶

"hls" : {
  "duration": 10,
  "indexName": "index.m3u8"
  "playlist": {
    "version": 3,
    "alternates": false,
    "alternatesName": "playlist.m3u8",
    "sequence": 0
  }
}

duration (기본: 10초)

MP4를 HLS로 분할하는 기준 시간(초). 분할의 기준은 Video/Audio의 KeyFrame이다. KeyFrame은 들쭉날쭉할 수 있으므로 정확히 분할되지 않는다. 만약 10초로 분할하려는데 KeyFrame이 9초와 12초에 있다면 가까운 값(9초)을 선택한다.

indexName (기본: "index.m3u8)

HLS 인덱스(.m3u8) 파일명

playlist

인덱스 파일 구성

version (기본: 3): 인덱스 파일 버전
alternates (기본: false): Stream Alternates 사용여부.
alternatesName (기본: "playlist.m3u8): Stream Alternates 파일명.
sequence (기본: 0): .ts 파일의 시작 번호. 이 수를 기준으로 순차적으로 증가한다.

live¶

원본파일을 라이브 스트리밍으로 제공한다. 라이브 스트리밍은 URL에 명시된 start 시간부터 재생시간 동안만 유효하다.

"live" : {
  "buffer": 30,
  "denialCode": 403
}

buffer (기본: 30초): 버퍼링 시간
denialCode (기본: 403): 라이브 시간이 아닐 경우의 응답코드

Warning

HLS 라이브 방송은 반드시 플레이어와 호환성을 검증해야 한다.

라이브 방송의 특성상 일부 헤더 설정이 필요하다.

m3u8 파일이 캐싱되지 않도록 bypass 설정으로 instant2 를 설정한다.
```
# functions.network.http.frontEnd.bypass

 "matchingList": [
   {
     "pattern": "$URL[/*/mp4hls/live/*/*.m3u8]",
     "action": "instant2"
   }
 ]
```
instant 모드로 설정할 경우 원본 비디오까지 instant 모드로 동작하기 떄문에 매 요청마다 원본 비디오를 다운로드 받게 된다.
인덱스 파일이 갱신 메커니즘( 304 Not Modified )을 수행하지 않도록 modify 설정으로 클라이언트 응답헤더를 제거한다.
```
# functions.network.http.frontEnd.headers.modify

 "matchingList": [
   {
     "pattern": "$URL[/*/mp4hls/live/*/*.m3u8]",
     "header": "$RES[Last-Modified]",
     "mode": "unset"
   },
   {
     "pattern": "$URL[/*/mp4hls/live/*/*.m3u8]",
     "header": "$RES[ETag]",
     "mode": "unset"
   },
   {
     "pattern": "$URL[/*/mp4hls/live/*/*.m3u8]",
     "header": "$RES[Cache-Control: no-cache, no-store, must-revalidate]",
     "mode": "set"
   }
]
```
Note
엔터프라이즈 서비스에서 CDN 사용시 주의사항
- CDN TTL 정책
  - /*/mp4hls/live/*/*.m3u8 은 1~5초를 설정하여 매번 갱신되도록 한다.
  - /*/mp4hls/live/*/*.ts 는 1~5분으로 설정하여, 적당한 유효재생시간 동안 캐싱되도록 한다.
- CDN 응답시 Last-Modified 나 ETag 헤더를 제거하기에 304 Not Modified 는 발생하지 않는다.
- CDN (또는 브라우저)에게 좀 더 명시적인 동작을 강제하기 위해 Cache-Control: no-cache, no-store, must-revalidate 헤더를 추가한다.
원본 다운로드를 최소화하거나 트래픽 시점은 분산시키고 싶다면 limitMaxRange 를 설정한다.
```
# functions.network.http.backEnd.headers

 "limitMaxRange": {
   "enable": true,
   "size": 4
 }
```
비디오 해상도에 따라 4MB 면 아래와 같이 추정할 수 있다.

해상도

재생시간

비트레이트

1080p

약 5~8초

4~6 Mbps

720p

약 10~16초

2~3 Mbps

480p

약 21~32초

1~1.5 Mbps

360p

약 32~46초

0.7~1 Mbps

해상도	재생시간	비트레이트
1080p	약 5~8초	4~6 Mbps
720p	약 10~16초	2~3 Mbps
480p	약 21~32초	1~1.5 Mbps
360p	약 32~46초	0.7~1 Mbps

encrypt¶

EXT-X-KEY 암호화를 지원한다.

"encrypt": {
  "enable": false,
  "keyword": "segment.key",
  "token": "",
  "tokenType": null
}

enable (기본: false)

암호화 활성화

keyword (기본: "segment.key)

인덱스 파일에 표기될 암호화 키워드

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:10
#EXT-X-MEDIA-SEQUENCE:0
#EXT-X-KEY:METHOD=AES-128,URI="/sample.mp4/mp4hls/segment.key"
#EXTINF:10.677,
...

token

암호화 토큰

tokenType (기본: null)

암호화 토큰 타입

null 설정된 token 이 암호화 키로 사용한다.
enc 설정된 token 이 encryptpassword 로 암호화되어 있다. 사용시 복호화하여 사용한다.