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