Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_hls_module.xml @ 2313:35b02ed44e4a
Removed example from JSON.stringify in njs reference.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 25 Dec 2018 16:42:05 +0300 |
parents | 5cacd6fffade |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_http_hls_module" link="/en/docs/http/ngx_http_hls_module.html" lang="en" rev="7"> <section id="summary"> <para> The <literal>ngx_http_hls_module</literal> module provides HTTP Live Streaming (HLS) server-side support for MP4 and MOV media files. Such files typically have the <path>.mp4</path>, <path>.m4v</path>, <path>.m4a</path>, <path>.mov</path>, or <path>.qt</path> filename extensions. The module supports H.264 video codec, AAC and MP3 audio codecs. </para> <para> For each media file, two URIs are supported: <list type="bullet"> <listitem> A playlist URI with the “<literal>.m3u8</literal>” filename extension. The URI can accept optional arguments: <list type="bullet"> <listitem> “<literal>start</literal>” and “<literal>end</literal>” define playlist boundaries in seconds (1.9.0). </listitem> <listitem> “<literal>offset</literal>” shifts an initial playback position to the time offset in seconds (1.9.0). A positive value sets a time offset from the beginning of the playlist. A negative value sets a time offset from the end of the last fragment in the playlist. </listitem> <listitem> “<literal>len</literal>” defines the fragment length in seconds. </listitem> </list> </listitem> <listitem> A fragment URI with the “<literal>.ts</literal>” filename extension. The URI can accept optional arguments: <list type="bullet"> <listitem> “<literal>start</literal>” and “<literal>end</literal>” define fragment boundaries in seconds. </listitem> </list> </listitem> </list> </para> <para> <note> This module is available as part of our <commercial_version>commercial subscription</commercial_version>. </note> </para> </section> <section id="example" name="Example Configuration"> <para> <example> location / { hls; hls_fragment 5s; hls_buffers 10 10m; hls_mp4_buffer_size 1m; hls_mp4_max_buffer_size 5m; root /var/video/; } </example> With this configuration, the following URIs are supported for the “<path>/var/video/test.mp4</path>” file: <example> 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 </example> </para> </section> <section id="directives" name="Directives"> <directive name="hls"> <syntax/> <default/> <context>location</context> <para> Turns on HLS streaming in the surrounding location. </para> </directive> <directive name="hls_buffers"> <syntax><value>number</value> <value>size</value></syntax> <default>8 2m</default> <context>http</context> <context>server</context> <context>location</context> <para> Sets the maximum <value>number</value> and <value>size</value> of buffers that are used for reading and writing data frames. </para> </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.12</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">ngx_http_secure_link_module</link> 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, <var>$uri</var> 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 <var>$uri</var> (<var>$hls_uri</var> 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> <context>http</context> <context>server</context> <context>location</context> <para> Defines the default fragment length for playlist URIs requested without the “<literal>len</literal>” argument. </para> </directive> <directive name="hls_mp4_buffer_size"> <syntax><value>size</value></syntax> <default>512k</default> <context>http</context> <context>server</context> <context>location</context> <para> Sets the initial <value>size</value> of the buffer used for processing MP4 and MOV files. </para> </directive> <directive name="hls_mp4_max_buffer_size"> <syntax><value>size</value></syntax> <default>10m</default> <context>http</context> <context>server</context> <context>location</context> <para> During metadata processing, a larger buffer may become necessary. Its size cannot exceed the specified <value>size</value>, or else nginx will return the server error <http-status code="500" text="Internal Server Error"/>, and log the following message: <example> "/some/movie/file.mp4" mp4 moov atom is too large: 12583268, you may want to increase hls_mp4_max_buffer_size </example> </para> </directive> </section> </module>