Mercurial > hg > nginx-site
changeset 1142:8cb0c634ff97
HLS: documented the "hls_forward_args" directive.
| author | Yaroslav Zhuravlev <yar@nginx.com> |
|---|---|
| date | Wed, 26 Mar 2014 13:51:42 +0400 |
| parents | 15f78372b132 |
| children | b93422ca9fe7 |
| files | xml/en/docs/http/ngx_http_hls_module.xml xml/ru/docs/http/ngx_http_hls_module.xml |
| diffstat | 2 files changed, 184 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_hls_module.xml +++ b/xml/en/docs/http/ngx_http_hls_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_http_hls_module" link="/en/docs/http/ngx_http_hls_module.html" lang="en" - rev="2"> + rev="3"> <section id="summary"> @@ -102,6 +102,97 @@ that are used for reading and writing da </directive> +<directive name="hls_forward_args"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.5.13</appeared-in> + +<para> +Adds arguments from a playlist request to URIs of fragments. +This may be useful for performing client authorization at the moment of +requesting a fragment, or when protecting an HLS stream with the +<link doc="ngx_http_secure_link_module.xml"/> module. +</para> + +<para> +For example, if a client requests a playlist +<literal>http://example.com/hls/test.mp4.m3u8?a=1&b=2</literal>, +the arguments <literal>a=1</literal> and <literal>b=2</literal> +will be added to URIs of fragments after the arguments +<literal>start</literal> and <literal>end</literal>: +<example> +#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 +</example> +</para> + +<para> +If an HLS stream is protected with the +<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link> +module, <literal>$uri</literal> should not be used in the +<link doc="ngx_http_secure_link_module.xml" id="secure_link_md5"/> +expression because this will cause errors when requesting the fragments. +<link doc="ngx_http_map_module.xml" id="map">Base URI</link> should be used +instead of <literal>$uri</literal> +(<literal>$hls_uri</literal> in the example): +<example> +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; + } + } + } +} +</example> +</para> + +</directive> + + <directive name="hls_fragment"> <syntax><value>time</value></syntax> <default>5s</default>
--- a/xml/ru/docs/http/ngx_http_hls_module.xml +++ b/xml/ru/docs/http/ngx_http_hls_module.xml @@ -9,7 +9,7 @@ <module name="Module ngx_http_hls_module" link="/ru/docs/http/ngx_http_hls_module.html" lang="ru" - rev="2"> + rev="3"> <section id="summary"> @@ -102,6 +102,97 @@ http://hls.example.com/video/test.mp4.ts </directive> +<directive name="hls_forward_args"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.5.13</appeared-in> + +<para> +Добавляет аргументы из запроса плейлиста в URI фрагментов. +Это может быть необходимо для авторизации клиента +во время запроса фрагментов, а также для защиты HLS-потока с помощью +модуля <link doc="ngx_http_secure_link_module.xml"/>. +</para> + +<para> +Например, если клиент запрашивает плейлист +<literal>http://example.com/hls/test.mp4.m3u8?a=1&b=2</literal>, +то аргументы <literal>a=1</literal> и <literal>b=2</literal> +будут добавлены в URI фрагментов после аргументов +<literal>start</literal> и <literal>end</literal>: +<example> +#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 +</example> +</para> + +<para> +Если HLS-поток защищён с помощью модуля +<link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link>, +переменную <literal>$uri</literal> не следует использовать в выражении +<link doc="ngx_http_secure_link_module.xml" id="secure_link_md5"/>, +так как это приведёт к ошибкам при запросах к фрагментам. +Вместо <literal>$uri</literal> следует использовать +<link doc="ngx_http_map_module.xml" id="map">базовую часть URI</link> +(<literal>$hls_uri</literal> в примере): +<example> +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; + } + } + } +} +</example> +</para> + +</directive> + + <directive name="hls_fragment"> <syntax><value>время</value></syntax> <default>5s</default>