ngx_http_hls_module 모듈

• Nginx http hls 모듈 : Module ngx_http_hls_module (nginx.org)

Module ngx_http_hls_module

 

• ngx_http_hls_module 모듈은 MP4 및 MOV 미디어 파일에 대한 HTTP 라이브 스트리밍(HLS) 서버 측 지원을 제공
• 파일의 파일 확장자는 일반적으로 .mp4, .m4v, .m4a, .mov, .qt
• ngx_http_hls_module 모듈은 H.264 비디오 코덱, AAC 및 MP3 오디오 코덱을 지원
  
  
• 각 미디어 파일에 대해 두 개의 URI가 지원
  1. 파일 이름 확장자가 .m3u8인 재생 목록 URI (URI는 아래 선택적 인수를 사용 가능)
     • start 및 end는 재생 목록 경계(playlist boundaries)를 초 단위로 정의
     • offset은 초기 재생 위치를 초 단위의 시간 오프셋(time offset)으로 이동
     • 양수 값은 재생 목록의 시작부터 시간 오프셋(offset)을 설정
     • 음수 값은 재생 목록의 마지막 조각 끝에서 시간 오프셋(offset)을 설정
     • len은 조각 길이를 초 단위로 정의
  2. 파일 이름 확장자가 ".ts"인 조각 URI (URI는 아래 선택적 인수를 사용 가능)
     • start 및 end는 조각 경계(fragment boundaries)를 초 단위로 정의
       
       
• 구성 예시

  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

 

hls 지시자

• HLS 스트리밍 설정
  
  
• 문맥 : location
• 사용 문법

  ## 문법
  hls;

 

hls_buffers 지시자

• 데이터 프레임 읽기 및 쓰기에 사용되는 버퍼의 최대 수와 크기를 설정
  
  
• 문맥 : http, server, location
• 사용 문법

  ## 문법
  hls_buffers number size;

• 사용 예시

  ## 사용 예시(기본 설정)
  hls_buffers 8 2m;

 

hls_forward_args 지시자

• 재생 목록 요청(playlist request)의 인수(arguments)를 URI의 조각(fragments)에 추가
• 조각(fragments)을 요청하는 순간에 클라이언트 인증을 수행하거나 ngx_http_secure_link_module 모듈로 HLS 스트림을 보호할 때 유용하게 사용 가능
• 예시) 클라이언트가 http://example.com/hls/test.mp4.m3u8?a=1&b=2 재생 목록을 요청하는 경우, 인수가 시작되고 끝나는 부분 뒤에 인자 a=1 및 b=2가 조각의 URI에 추가

  #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 모듈로 보호되는 경우, 조각을 요청할 때 오류가 발생할 수 있으므로 secure_link_md5 표현식에 $uri를 사용해서는 안 됨
• $uri 대신 Base URI를 사용해야 함(예시에서는 $hls_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;
              }
          }
      }
  }

 

• 문맥 : http, server, location
• 사용 문법

  ## 문법
  hls_forward_args on | off;

• 사용 예시

  ## 사용 예시(기본 설정)
  hls_forward_args off;

 

hls_fragment 지시자

• len 인수 없이 요청된 재생 목록 URI의 기본 조각 길이를 정의
  
  
• 문맥 : http, server, location
• 사용 문법

  ## 문법
  hls_fragment time;

• 사용 예시

  ## 사용 예시(기본 설정)
  hls_fragment 5s;

 

hls_mp4_buffer_size 지시자

• MP4 및 MOV 파일 처리에 사용되는 버퍼의 초기 크기를 설정
  
  
• 문맥 : http, server, location
• 사용 문법

  ## 문법
  hls_mp4_buffer_size size;

• 사용 예시

  ## 사용 예시(기본 설정)
  hls_mp4_buffer_size 512k

 

hls_mp4_max_buffer_size 지시자

• 메타데이터(metadata)를 처리하는 동안 더 큰 버퍼가 필요할 수 있음
• 버퍼의 크기가 지정된 크기를 초과할 수 없으며, 그렇지 않으면 nginx에서 서버 오류 500(내부 서버 오류)을 반환
  
  
• 발생 에러

  "/some/movie/file.mp4" mp4 moov atom is too large:
  12583268, you may want to increase hls_mp4_max_buffer_size

   
• 문맥 : http, server, location
• 사용 문법

  ## 문법
  hls_mp4_max_buffer_size size;

• 사용 예시

  ## 사용 예시(기본 설정)
  hls_mp4_max_buffer_size 10m;