ngx_http_hls_module
ngx_http_hls_module 모듈은 MP4와 MOV 미디어 파일에 HTTP Live Streaming(HLS) 서버 측 지원을 제공합니다. 일반적으로 이런 파일은 확장자가 .mp4, .m4v, .m4a, .mov, .qt입니다. 이 모듈은 H.264 영상 코덱, AAC 및 MP3 오디오 코덱을 지원합니다.
각 미디어 파일에 URI 2개가 지원됩니다.
- 하나는 파일 이름 확장자가 “.m3u8″인 재생 목록 URI가 있습니다. 이 URI는 선택적 인수를 받습니다.
- “start”와 “end”는 재생 목록 경계(초)를 정의합니다(1.9.0).
- “offset”은 최초 재생 위치를 시간 오프셋(초)으로 이동합니다(1.9.0). 양수 값은 재생 목록 처음부터 시간 오프셋을 설정합니다. 음수 값은 재생 목록 마지막 프래그먼트 끝에서 시간 오프셋을 설정합니다.
- “len”은 프래그먼트 길이(초)를 정의합니다.
- 다른 하나는 파일 이름 확장자가 “.ts”인 프래그먼트 URI가 있습니다. 이 URI는 선택적 인수를 받습니다.
- “start” 및 “end”는 프래그먼트 경계(초)를 정의합니다.
이 모듈은 상업용 구독에서 제공합니다.
예제 구성
location / {
hls;
hls_fragment 5s;
hls_buffers 10 10m;
hls_mp4_buffer_size 1m;
hls_mp4_max_buffer_size 5m;
root /var/video/;
}
이 구성에서는 “/var/video/test.mp4” 파일에 다음의 URI를 지원합니다.
http://hls.example.com/test.mp4.m3u8?offset=1.000&start=1.000&end=2.200
http://hls.example.com/test.mp4.m3u8?len=8.000
http://hls.example.com/test.mp4.ts?start=1.000&end=2.200
Directives
Syntax: hls;
Default: —
Context: location
주변 위치에서 HLS 스트리밍을 활성화합니다.
Syntax: hls_buffers number size;
Default: hls_buffers 8 2m;
Context: http, server, location
데이터 프레임을 읽고 쓰는 데 사용하는 버퍼의 최대 number와 size를 설정합니다.
Syntax: hls_forward_args on | off;
Default: hls_forward_args off;
Context: http, server, location
This directive appeared in version 1.5.12.
재생 목록 요청의 인수를 프래그먼트 URI에 추가합니다. 프래그먼트를 요청하는 시점이나 ngx_http_secure_link_module 모듈로 HLS 스트림을 보호할 때 클라이언트 인증을 수행하는 데 유용합니다.
예를 들어 클라이언트가 재생 목록 http://example.com/hls/test.mp4.m3u8?a=1&b=2을 요청하면 프래그먼트 URI에서 인수 a=1과 b=2를 인수 start와 end 뒤에 추가합니다.
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:15
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:9.333,
test.mp4.ts?start=0.000&end=9.333&a=1&b=2
#EXTINF:7.167,
test.mp4.ts?start=9.333&end=16.500&a=1&b=2
#EXTINF:5.416,
test.mp4.ts?start=16.500&end=21.916&a=1&b=2
#EXTINF:5.500,
test.mp4.ts?start=21.916&end=27.416&a=1&b=2
#EXTINF:15.167,
test.mp4.ts?start=27.416&end=42.583&a=1&b=2
#EXTINF:9.626,
test.mp4.ts?start=42.583&end=52.209&a=1&b=2
#EXT-X-ENDLIST
HLS 스트림을 ngx_http_secure_link_module 모듈로 보호할 경우, $uri는 프래그먼트를 요청할 때 오류를 발생시키므로 secure_link_md5 식에서 사용해서는 안 됩니다. $uri(예시에서는 $hls_uri) 대신 기본 URI를 사용해야 합니다.
http {
...
map $uri $hls_uri {
~^(?<base_uri>.*).m3u8$ $base_uri;
~^(?<base_uri>.*).ts$ $base_uri;
default $uri;
}
server {
...
location /hls/ {
hls;
hls_forward_args on;
alias /var/videos/;
secure_link $arg_md5,$arg_expires;
secure_link_md5 "$secure_link_expires$hls_uri$remote_addr secret";
if ($secure_link = "") {
return 403;
}
if ($secure_link = "0") {
return 410;
}
}
}
}
Syntax: hls_fragment time;
Default: hls_fragment 5s;
Context: http, server, location
“len” 인수 없이 요청된 재생 목록 URI의 기본 프래그먼트 길이를 정의합니다.
Syntax: hls_mp4_buffer_size size;
Default: hls_mp4_buffer_size 512k;
Context: http, server, location
MP4 및 MOV 파일을 처리하는 데 사용하는 버퍼의 최초 size를 설정합니다.
Syntax: hls_mp4_max_buffer_size size;
Default: hls_mp4_max_buffer_size 10m;
Context: http, server, location
메타데이터를 처리하는 동안 큰 버퍼가 필요할 수 있습니다. 용량은 지정된 size를 초과할 수 없습니다. 초과할 경우, nginx가 500(내부 서버 오류) 서버 오류를 반환하고 다음의 메시지를 로깅합니다.
"/some/movie/file.mp4" mp4 moov atom is too large:
12583268, you may want to increase hls_mp4_max_buffer_size