videofly `alpha`¶

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

{
  "functions": {
    "services": {
      "videofly": {
        ...
      }
    }
  }
}

How to use¶

명령어 리스트¶

# _default 프로파일로 재생
https://example.com/video.mp4/vfly/v1/profile/_default

# review 프로파일로 재생
https://example.com/video.mp4/vfly/v1/profile/review

# review 프로파일로 재생 후 세부옵션 조정
https://example.com/video.mp4/vfly/v1/profile/review/options/duration=10

# 30초 구간 추출 후 재생
https://example.com/video.mp4/vfly/v1/trim/0-30/profile/_default

# mpeg2-ts포맷 (h264 코덱)의 720p 스트림만 제공한다.
https://example.com/sample.mp4/vfly/v1/profile/_default.m2ts.720p/playlist.m3u8

# fmp4포맷 (av1 코덱)의 360p 스트림만 제공한다.
https://example.com/sample.mp4/vfly/v1/profile/_default.fmp4.360p/playlist.m3u8

# 원본미디어 파일로부터 HLS 라이브 재생을 제공한다.
https://example.com/video.mp4/vfly/v1/profile/_default/live/start=20250729100000/master.m3u8
https://example.com/video.mp4/vfly/v1/profile/_default/live/start=20250730143050;buffer=60/master.m3u8
https://example.com/sample.mp4/vfly/v1/profile/_default.fmp4.360p/live/start=20250729100000;end=20250729110000/playlist.m3u8

싱글/멀티비트레이트¶

기본 _default 프로파일의 master.m3u8 는 다음과 같이 멀티 비트레이트 스트림을 모두 제공한다.

../../../../_images/vfly01.png — 클라이언트 네트워크 상태에 맞추어 최적의 스트림을 선택하여 재생한다.¶

Note

HLS 스펙에서 코덱과 포맷은 다소 모호하게 정의되어 있기 때문에 아래와 같이 쌍으로 제공하도록 기본 구성된다.

fMP4 는 av1 코덱만 지원
MPEG2-TS 는 h264 코덱만 지원

#EXTM3U
#EXT-X-VERSION:7

#EXT-X-STREAM-INF:BANDWIDTH=12000000,RESOLUTION=1920x1080,CODECS="av01.0.08M.08,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.fmp4.1080p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=6000000,RESOLUTION=1280x720,CODECS="av01.0.05M.08,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.fmp4.720p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=3000000,RESOLUTION=854x480,CODECS="av01.0.04M.08,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.fmp4.480p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1600000,RESOLUTION=640x360,CODECS="av01.0.04M.08,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.fmp4.360p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=800000,RESOLUTION=426x240,CODECS="av01.0.00M.08,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.fmp4.240p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=250000,RESOLUTION=256x144,CODECS="av01.0.00M.08,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.fmp4.144p/playlist.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=16000000,RESOLUTION=1920x1080,CODECS="avc1.640028,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.m2ts.1080p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=8000000,RESOLUTION=1280x720,CODECS="avc1.4D001F,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.m2ts.720p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=4000000,RESOLUTION=854x480,CODECS="avc1.4D001E,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.m2ts.480p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2200000,RESOLUTION=640x360,CODECS="avc1.42001E,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.m2ts.360p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=426x240,CODECS="avc1.420014,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.m2ts.240p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=400000,RESOLUTION=256x144,CODECS="avc1.420014,mp4a.40.2"
/sample.mp4/vfly/v1/profile/_default.m2ts.144p/playlist.m3u8

특정 스트림을 선택하는 문법은 다음과 같다.

# 프로파일의 마스터
.../vfly/v1/profile/{프로파일명}/master.m3u8

# 프로파일의 개별스트림
.../vfly/v1/profile/{프로파일명}.{포맷}.{해상도 or 프리셋}/playlist.m3u8

{프로파일명}: profiles 에 정의된 프로파일 이름. _default 프리셋이 지원된다.
{포맷}: 미디어 세그먼트 포맷. fmp4 , m2ts 중 택1
{해상도 or 프리셋}: profiles 의 resolution 에 정의된 해상도 또는 presets 에 정의된 프리셋 이름

싱글 스트림만 제공하고 싶은 경우에는 2가지 방법이 가능하지만, 특별한 경우가 아니라면 1안을 권장한다.

master.m3u8 는 멀티로 제공하고 노출영역에 맞추어 특정 스트림만 제공한다.

# mpeg2-ts포맷 (h264 코덱)의 720p 스트림만 제공한다.
https://example.com/sample.mp4/vfly/v1/profile/_default.m2ts.720p/playlist.m3u8

# fmp4포맷 (av1 코덱)의 360p 스트림만 제공한다.
https://example.com/sample.mp4/vfly/v1/profile/_default.fmp4.360p/playlist.m3u8

단일 스트림만 제공하도록 profiles 를 구성한다.

meta¶

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

enable (기본: false): 활성화
keyword (기본: vfly): 키워드

profiles¶

HLS 상세한 구성은 프로파일로 정의한다. 다음은 빌트인 프로파일이다.

name	playlist	비디오 코덱	해상도
`_default`	`fmp4` , `m2ts`	`av1` , `m2ts`	1080p, 720p, 480p, 360p, 144p
`_fmp4`	`fmp4`	`av1`	1080p, 720p, 480p, 360p, 144p
`_m2ts`	`m2ts`	`m2ts`	1080p, 720p, 480p, 360p, 144p

"profiles" : [
  {
    "enable": true,
    "name": "review",
    "ver": 7,
    "path": "abs",
    "duration": 3,
    "transcode": { ... },
    "playlist:" { ... },
    "event": { ... },
    "live": { ... },
    "encrypt": { ... }
  },
  {
    "name": "ads"
  }
]

enable (기본: true)

프로파일 활성화

name

프로파일 이름

ver (기본: 7)

HLS 버전

path (기본: "abs")

경로구성 정책

abs (기본) 절대경로 (항상 / 로 시작)
rel 상대경로

duration (기본: 3)

비디오 분할 시간. 길수록 반응성이 저하된다.

transcode

transcode 참조

playlist

playlist 참조

event

event 이벤트를 발동시킨다.

transcode¶

트랜스코딩 정책과 해상도를 구성한다.

"transcode": {
  "enable": true,
  "policy": "IF_SPEC_MISMATCH",
  "resolution": [ "1080p", "720p", "480p", "360p", "144p" ],
  "upscale": false
}

enable (기본: true)

트랜스코딩 활성화.

Note

[원본 해상도] 무변환 경우에만 비활성화한다.

policy (기본: IF_SPEC_MISMATCH)

개별 스트림 제공시 트랜스코딩 정책. 조건이 모두 만족할 경우에는 트랜스코딩하지 않는다.

정책명	Codec	Resolution	Bitrate
`IF_BITRATE_EXCEEDS`	일치	일치	같거나 낮음
`IF_SPEC_MISMATCH`	일치	일치
`IF_CODEC_MISMATCH`	일치
`ALWAYS`

resolution (기본: null)

스트림 해상도

가로로 촬영된 비디오는 세로 기준, 세로로 촬영된 비디오는 가로 기준으로 해상도 결정
4:3 비율의 원본 비디오가 입력될 경우, 높이에 맞춰 가로 해상도 결정

이름	해상도
`2160p`	3840 x 2160
`1440p`	2560 x 1440
`1080p`	1920 x 1080
`720p`	1280 x 720
`480p`	854 x 480
`360p`	640 x 360
`240p`	426 x 240
`144p`	256 x 144

Note

해상도는 playlist 공통으로, 만약 개별 스트림 단위로 다른 해상도를 제공하고 싶은 경우.

resolution 에서 공통이 아닌 해상도 제거
playlist 하위 개발 스트림에 맞추어 presets 지정

upscale (기본: true)

원본 비디오의 해상도가 출력 해상도보다 낮을 경우 업스케일링 여부. false 인 경우 원본 해상도보다 높은 스트림은 생성하지 않는다.

playlist¶

플레이리스트를 구성한다.

멀티비트레이트 스트림을 지원한다.
fMP4 와 MPEG2-TS 멀티 미디어 세그먼트를 지원한다.

Note

클라이언트 호환성을 100% 담보할 수 없는 경우

fMP4 와 MPEG2-TS 를 같이 구성
fMP4 는 av1 코덱만 지원
MPEG2-TS 는 h264 코덱만 지원
플레이어가 코덱을 통해 재생할 미디어 세그먼트를 선택

fmp4¶

fMP4(Fragmented MP4) 세그먼트를 구성한다.

"fmp4": {
  "enable": true,
  "vcodec": "av1",
  "acodec": "aac",
  "presets": null
}

enable (기본: false): 활성화
vcodec (기본: av1): 비디오 코덱 ( av1 , h264 중 택1)
acodec (기본: aac): 오디오 코덱 ( aac 는 AAC-LC를 의미한다.)
presets (기본: null: resolution 외에 추가될 제공할 트랜스코딩 presets 리스트

m2ts¶

MPEG2-TS(Transport Stream) 세그먼트를 구성한다.

"m2ts": {
  "enable": true,
  "vcodec": "h264",
  "acodec": "aac",
  "presets": null
}

enable (기본: false): 활성화
vcodec (기본: h264): 비디오 코덱 ( h264 단일지원)
acodec (기본: aac): 오디오 코덱 ( aac 는 AAC-LC를 의미한다.)
presets (기본: null: resolution 외에 추가될 제공할 트랜스코딩 presets 리스트

live¶

원본파일을 라이브 스트리밍으로 제공한다.

명령어	필수	예제	설명
`start`	O	start=20250729100000	라이브 시작시간 (형식: YYYYMMDDhhmmss)
`end`	X	end=20250729110000	라이브 종료시간 (형식: YYYYMMDDhhmmss)
`buffer`	X	buffer=30	버퍼링 시간 (초)

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

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

Note

멀티 포맷/멀티 해상도 스트림이 아닌 원본 그대로의 라이브 구성이 필요하다면 [원본 해상도] 무변환 를 참고한다.

설정 변경¶

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

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,
  "keyFileName": "enc.key",
  "token": "",
  "tokenType": null,
  "iv": null
}

enable (기본: false)

암호화 활성화

keyFileName (기본: "enc.key)

인덱스 파일에 표기될 키 파일명

#EXTM3U
...
#EXT-X-KEY:METHOD=AES-128,URI="/sample.mp4/vfly/v1/profile/_default.m2ts.720p/enc.key"
#EXTINF:10.677,
...

token

암호화 토큰

tokenType (기본: null)

암호화 토큰 타입

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

iv (기본: null)

Initial Vector. 0x 로 시작하는 16진수로 설정한다.

#EXTM3U
...
#EXT-X-KEY:METHOD=AES-128,URI="/sample.mp4/vfly/v1/profile/_default.m2ts.720p/enc.key",IV=0x0123456789abcdef0123456789abcdef
#EXTINF:10.677,
...

event¶

원본비디오가 서비스될 때 발생시킬 이벤트를 정의한다.

"event": {
  "normalize": "to_h264_aac"
}

normalize

비디오 포맷 표준화를 위헤해 스케쥴링한다.

Note

storgate beta 의 스케쥴링과 연동
2차 고도화시 스펙정의

설정 예제¶

다음은 멀티 스트림을 지원하는 최소 구성이다.

"profiles" : [
  {
    "name": "example",
    "transcode": {
      "policy": "IF_SPEC_MISMATCH",
      "resolution": [ "1080p", "720p", "480p", "360p", "144p" ]
    }
  }
]

Note

m2ts , fmp4 포맷은 활성화가 기본이다. 따라서 해상도별 멀티포맷 스트림이 제공된다.

그 밖의 예외적인 설정예제를 제공한다.

[원본 해상도] 무변환¶

트랜스코딩 없이 원본 해상도 그대로 HLS로 전송하는 구성이다.

"profiles" : [
  {
    "name": "example",
    "transcode": {
      "enable": false
    }
  }
]

transcode.enable 을 false 로 설정하여 트랜스코딩하지 않는다.
멀티 playlist 는 제공되지 않는다. m2ts 가 기본이며, 원본코덱이 m2ts 에서 지원되지 않는 경우에만 fmp4 로 제공된다.

[원본 해상도] 코덱호환성 보장¶

[원본 해상도] 무변환 상황과 같으나, 코덱 옵션이 다를 경우에만 트랜스코딩을 수행한다.

"profiles" : [
  {
    "name": "example",
    "transcode": {
      "enable": true,
      "policy": "IF_CODEC_MISMATCH"
    }
  }
]

transcode 를 활성화하고, policy 을 IF_CODEC_MISMATCH 로 설정하여 코덱이 불일치할 때만 트랜스코딩하도록 설정한다.
트랜스코딩이 가능하기 때문에 m2ts 포맷이 보장된다.
fmp4 포맷 스트림은 제공하지 않는다.

[원본 해상도] `h264` 기반 `fmp4`¶

[원본 해상도] 코덱호환성 보장 상황과 유사하나 h264 코덱으로 fmp4 포맷만 제공하는 구성이다.

{
  "name": "example",
  "transcode": {
    "enable": true,
    "policy": "IF_CODEC_MISMATCH"
  },
  "playlist": {
    "fmp4": {
      "vcodec": "h264"
    },
    "m2ts": {
      "enable": false
    }
  }
}

m2ts 를 비활성화한다.
fmp4 포맷의 비디오코덱을 h264 로 변경한다.

videofly alpha¶

How to use¶

명령어 리스트¶

싱글/멀티비트레이트¶

meta¶

profiles¶

transcode¶

playlist¶

fmp4¶

m2ts¶

live¶

설정 변경¶

encrypt¶

event¶

설정 예제¶

[원본 해상도] 무변환¶

[원본 해상도] 코덱호환성 보장¶

[원본 해상도] h264 기반 fmp4¶

videofly `alpha`¶

[원본 해상도] `h264` 기반 `fmp4`¶