Mercurial > hg > nginx-site

annotate xml/en/docs/http/ngx_http_hls_module.xml @ 2651:b4991bbd64ee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the js_header_filter directive.
author Yaroslav Zhuravlev <yar@nginx.com>
date Mon, 08 Feb 2021 12:30:01 +0000
parents 5cacd6fffade
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
3 <!--
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
4 Copyright (C) Nginx, Inc.
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
5 -->
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
6
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9 <module name="Module ngx_http_hls_module"
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 link="/en/docs/http/ngx_http_hls_module.html"
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 lang="en"
2206
5cacd6fffade Eliminated some examples of unsafe prefix locations.
Ruslan Ermilov <ru@nginx.com>
parents: 1497
diff changeset
12 rev="7">
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14 <section id="summary">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
17 The <literal>ngx_http_hls_module</literal> module provides HTTP Live Streaming
1476
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
18 (HLS) server-side support for MP4 and MOV media files.
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
19 Such files typically have the <path>.mp4</path>, <path>.m4v</path>,
1497
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
20 <path>.m4a</path>, <path>.mov</path>, or <path>.qt</path> filename extensions.
1476
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
21 The module supports H.264 video codec, AAC and MP3 audio codecs.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
22 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
23
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
24 <para>
1497
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
25 For each media file, two URIs are supported:
1476
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
26 <list type="bullet">
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
27
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
28 <listitem>
1497
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
29 A playlist URI with the “<literal>.m3u8</literal>” filename extension.
1476
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
30 The URI can accept optional arguments:
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
31 <list type="bullet">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
32
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
33 <listitem>
1476
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
34 “<literal>start</literal>” and “<literal>end</literal>”
1497
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
35 define playlist boundaries in seconds (1.9.0).
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
36 </listitem>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
37
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
38 <listitem>
1476
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
39 “<literal>offset</literal>” shifts an initial playback position
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
40 to the time offset in seconds (1.9.0).
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
41 A positive value sets a time offset from the beginning of the playlist.
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
42 A negative value sets a time offset
1497
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
43 from the end of the last fragment in the playlist.
1476
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
44 </listitem>
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
45
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
46 <listitem>
1497
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
47 “<literal>len</literal>” defines the fragment length in seconds.
1476
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
48 </listitem>
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
49 </list>
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
50
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
51 </listitem>
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
52
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
53 <listitem>
1497
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
54 A fragment URI with the “<literal>.ts</literal>” filename extension.
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
55 The URI can accept optional arguments:
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
56 <list type="bullet">
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
57
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
58 <listitem>
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
59 “<literal>start</literal>” and “<literal>end</literal>”
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60 define fragment boundaries in seconds.
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
61 </listitem>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
62
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
63 </list>
1497
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
64 </listitem>
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
65
6650933c46d4 Corrected language and formatting in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1477
diff changeset
66 </list>
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
67 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
68
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
69 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
70 <note>
1128
1594ed379f1f De-i18n'ed <commercial_version/>.
Ruslan Ermilov <ru@nginx.com>
parents: 1115
diff changeset
71 This module is available as part of our
1594ed379f1f De-i18n'ed <commercial_version/>.
Ruslan Ermilov <ru@nginx.com>
parents: 1115
diff changeset
72 <commercial_version>commercial subscription</commercial_version>.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73 </note>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
74 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76 </section>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
78
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
79 <section id="example" name="Example Configuration">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
82 <example>
1477
ad8a1fae0b72 Corrected example in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1476
diff changeset
83 location / {
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
84 hls;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85 hls_fragment 5s;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86 hls_buffers 10 10m;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87 hls_mp4_buffer_size 1m;
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88 hls_mp4_max_buffer_size 5m;
1477
ad8a1fae0b72 Corrected example in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1476
diff changeset
89 root /var/video/;
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
90 }
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
91 </example>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
92 With this configuration, the following URIs are supported for
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
93 the “<path>/var/video/test.mp4</path>” file:
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
94 <example>
1477
ad8a1fae0b72 Corrected example in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1476
diff changeset
95 http://hls.example.com/test.mp4.m3u8?offset=1.000&amp;start=1.000&amp;end=2.200
ad8a1fae0b72 Corrected example in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1476
diff changeset
96 http://hls.example.com/test.mp4.m3u8?len=8.000
ad8a1fae0b72 Corrected example in the hls module.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1476
diff changeset
97 http://hls.example.com/test.mp4.ts?start=1.000&amp;end=2.200
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
98 </example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
99 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
100
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
101 </section>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
102
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
103
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
104 <section id="directives" name="Directives">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
105
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
106 <directive name="hls">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
107 <syntax/>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
108 <default/>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
109 <context>location</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
110
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
111 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
112 Turns on HLS streaming in the surrounding location.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
113 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
114
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
115 </directive>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
116
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
117
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
118 <directive name="hls_buffers">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
119 <syntax><value>number</value> <value>size</value></syntax>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
120 <default>8 2m</default>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
121 <context>http</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
122 <context>server</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
123 <context>location</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
124
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
125 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
126 Sets the maximum <value>number</value> and <value>size</value> of buffers
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
127 that are used for reading and writing data frames.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
128 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
129
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
130 </directive>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132
1142
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
133 <directive name="hls_forward_args">
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
134 <syntax><literal>on</literal> | <literal>off</literal></syntax>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
135 <default>off</default>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
136 <context>http</context>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
137 <context>server</context>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
138 <context>location</context>
1228
0ffd5caf0766 HLS: corrected the "appeared-in" version for hls_forward_args.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1153
diff changeset
139 <appeared-in>1.5.12</appeared-in>
1142
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
140
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
141 <para>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
142 Adds arguments from a playlist request to URIs of fragments.
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
143 This may be useful for performing client authorization at the moment of
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
144 requesting a fragment, or when protecting an HLS stream with the
1147
ff7defe134d8 HLS: fixed fallouts in the previous edition.
Ruslan Ermilov <ru@nginx.com>
parents: 1142
diff changeset
145 <link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link>
ff7defe134d8 HLS: fixed fallouts in the previous edition.
Ruslan Ermilov <ru@nginx.com>
parents: 1142
diff changeset
146 module.
1142
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
147 </para>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
148
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
149 <para>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
150 For example, if a client requests a playlist
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
151 <literal>http://example.com/hls/test.mp4.m3u8?a=1&amp;b=2</literal>,
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
152 the arguments <literal>a=1</literal> and <literal>b=2</literal>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
153 will be added to URIs of fragments after the arguments
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
154 <literal>start</literal> and <literal>end</literal>:
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
155 <example>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
156 #EXTM3U
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
157 #EXT-X-VERSION:3
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
158 #EXT-X-TARGETDURATION:15
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
159 #EXT-X-PLAYLIST-TYPE:VOD
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
160
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
161 #EXTINF:9.333,
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
162 test.mp4.ts?start=0.000&amp;end=9.333&amp;a=1&amp;b=2
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
163 #EXTINF:7.167,
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
164 test.mp4.ts?start=9.333&amp;end=16.500&amp;a=1&amp;b=2
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
165 #EXTINF:5.416,
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
166 test.mp4.ts?start=16.500&amp;end=21.916&amp;a=1&amp;b=2
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
167 #EXTINF:5.500,
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
168 test.mp4.ts?start=21.916&amp;end=27.416&amp;a=1&amp;b=2
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
169 #EXTINF:15.167,
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
170 test.mp4.ts?start=27.416&amp;end=42.583&amp;a=1&amp;b=2
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
171 #EXTINF:9.626,
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
172 test.mp4.ts?start=42.583&amp;end=52.209&amp;a=1&amp;b=2
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
173
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
174 #EXT-X-ENDLIST
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
175 </example>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
176 </para>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
177
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
178 <para>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
179 If an HLS stream is protected with the
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
180 <link doc="ngx_http_secure_link_module.xml">ngx_http_secure_link_module</link>
1147
ff7defe134d8 HLS: fixed fallouts in the previous edition.
Ruslan Ermilov <ru@nginx.com>
parents: 1142
diff changeset
181 module, <var>$uri</var> should not be used in the
1142
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
182 <link doc="ngx_http_secure_link_module.xml" id="secure_link_md5"/>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
183 expression because this will cause errors when requesting the fragments.
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
184 <link doc="ngx_http_map_module.xml" id="map">Base URI</link> should be used
1147
ff7defe134d8 HLS: fixed fallouts in the previous edition.
Ruslan Ermilov <ru@nginx.com>
parents: 1142
diff changeset
185 instead of <var>$uri</var>
ff7defe134d8 HLS: fixed fallouts in the previous edition.
Ruslan Ermilov <ru@nginx.com>
parents: 1142
diff changeset
186 (<var>$hls_uri</var> in the example):
1142
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
187 <example>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
188 http {
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
189 ...
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
190
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
191 map $uri $hls_uri {
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
192 ~^(?&lt;base_uri&gt;.*).m3u8$ $base_uri;
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
193 ~^(?&lt;base_uri&gt;.*).ts$ $base_uri;
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
194 default $uri;
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
195 }
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
196
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
197 server {
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
198 ...
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
199
2206
5cacd6fffade Eliminated some examples of unsafe prefix locations.
Ruslan Ermilov <ru@nginx.com>
parents: 1497
diff changeset
200 location /hls/ {
1142
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
201 hls;
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
202 hls_forward_args on;
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
203
2206
5cacd6fffade Eliminated some examples of unsafe prefix locations.
Ruslan Ermilov <ru@nginx.com>
parents: 1497
diff changeset
204 alias /var/videos/;
1142
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
205
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
206 secure_link $arg_md5,$arg_expires;
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
207 secure_link_md5 "$secure_link_expires$hls_uri$remote_addr secret";
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
208
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
209 if ($secure_link = "") {
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
210 return 403;
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
211 }
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
212
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
213 if ($secure_link = "0") {
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
214 return 410;
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
215 }
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
216 }
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
217 }
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
218 }
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
219 </example>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
220 </para>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
221
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
222 </directive>
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
223
8cb0c634ff97 HLS: documented the "hls_forward_args" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1128
diff changeset
224
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
225 <directive name="hls_fragment">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
226 <syntax><value>time</value></syntax>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
227 <default>5s</default>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
228 <context>http</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
229 <context>server</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
230 <context>location</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
231
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
232 <para>
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
233 Defines the default fragment length for playlist URIs requested without the
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
234 “<literal>len</literal>” argument.
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
235 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
236
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
237 </directive>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
238
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
239
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
240 <directive name="hls_mp4_buffer_size">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
241 <syntax><value>size</value></syntax>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
242 <default>512k</default>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
243 <context>http</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
244 <context>server</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
245 <context>location</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
246
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
247 <para>
1153
4e20e4f8f49b Finished truncation of "memory buffers" to just "buffers".
Ruslan Ermilov <ru@nginx.com>
parents: 1147
diff changeset
248 Sets the initial <value>size</value> of the buffer used for
1476
c20c2b945f8c Added new URI arguments, corrected file formats in hls.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1228
diff changeset
249 processing MP4 and MOV files.
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
250 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
251
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
252 </directive>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
253
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
254
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
255 <directive name="hls_mp4_max_buffer_size">
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
256 <syntax><value>size</value></syntax>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
257 <default>10m</default>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
258 <context>http</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
259 <context>server</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
260 <context>location</context>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
261
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
262 <para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
263 During metadata processing, a larger buffer may become necessary.
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
264 Its size cannot exceed the specified <value>size</value>,
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
265 or else nginx will return the server error
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
266 <http-status code="500" text="Internal Server Error"/>,
956
488a3f738db0 Text revision of commercial modules.
Egor Nikitin <yegor.nikitin@gmail.com>
parents: 953
diff changeset
267 and log the following message:
953
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
268 <example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
269 "/some/movie/file.mp4" mp4 moov atom is too large:
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
270 12583268, you may want to increase hls_mp4_max_buffer_size
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
271 </example>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
272 </para>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
273
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
274 </directive>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
275
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
276 </section>
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
277
aded7086e84f Commercial version documentation.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
278 </module>