22
|
1 <?xml version="1.0"?>
|
|
2
|
|
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
|
|
4
|
|
5 <module title="HTTP MP4 module"
|
|
6 link="/en/docs/http/ngx_http_mp4_module.html"
|
|
7 lang="en">
|
|
8
|
|
9 <section title="Summary">
|
|
10
|
|
11 <para>
|
|
12 The module <code>ngx_http_mp4_module</code> provides pseudo-streaming
|
|
13 server-side support for H.264/AAC files typically having filename extensions
|
|
14 <pathname>.mp4</pathname>, <pathname>.m4v</pathname>,
|
|
15 and <pathname>.m4a</pathname>.
|
|
16 </para>
|
|
17
|
|
18 <para>
|
|
19 Pseudo-streaming works in alliance with conformant Flash players.
|
|
20 A player sends an HTTP request to the server with a start time
|
|
21 argument in the request URI’s query string (named simply
|
|
22 <parameter>start</parameter>
|
|
23 and specified in seconds), and the server responds with a stream
|
|
24 so that its start position corresponds to the requested time,
|
|
25 for example:
|
|
26 <example>
|
|
27 http://example.com/elephants_dream.mp4?start=238.88
|
|
28 </example>
|
|
29 This allows for a random seeking at any time, or starting playback
|
|
30 in the middle of a timeline.
|
|
31 </para>
|
|
32
|
|
33 <para>
|
|
34 To support seeking, H.264-based formats store the metadata
|
|
35 in the so-called “moov atom.”
|
|
36 It is a part of the file that holds the index information for the
|
|
37 whole file.
|
|
38 </para>
|
|
39
|
|
40 <para>
|
|
41 To start playback, a player first needs to read metadata.
|
|
42 This is done by sending a special request with the
|
|
43 <parameter>start=0</parameter>
|
|
44 argument. Many encoding software will insert the metadata at
|
|
45 the end of the file. This is bad for pseudo-streaming:
|
|
46 the metadata needs to be located at the beginning of the file,
|
|
47 or else the entire file will have to be downloaded before it
|
|
48 starts playing. If a file is well-formed (with metadata at the
|
|
49 beginning of a file), nginx just sends back the contents of a file.
|
|
50 Otherwise, it has to read the file and prepare a new stream so that
|
|
51 metadata comes before media data.
|
|
52 This involves some CPU, memory, and disk I/O overhead,
|
|
53 so it is a good idea to
|
|
54 <a href="http://flowplayer.org/plugins/streaming/pseudostreaming.html#prepare">
|
|
55 prepare an original file for pseudo-streaming</a>,
|
|
56 rather than having nginx do this on every such request.
|
|
57 </para>
|
|
58
|
|
59 <para>
|
|
60 For a matching request with a non-zero
|
|
61 <parameter>start</parameter>
|
|
62 argument, nginx will read metadata from the file, prepare the
|
|
63 stream starting from the requested offset, and send it to a client.
|
|
64 This has the same overhead as described above.
|
|
65 </para>
|
|
66
|
|
67 <para>
|
|
68 If a matching request does not include the
|
|
69 <parameter>start</parameter>
|
|
70 argument, there is no overhead, and the file is just sent as a static resource.
|
|
71 Some players also support byte-range requests, and thus do not require
|
|
72 this module at all.
|
|
73 </para>
|
|
74
|
|
75 <para>
|
|
76 This module is not built by default, it should be enabled with the
|
|
77 <command>--with-http_mp4_module</command>
|
|
78 configuration parameter.
|
|
79 <note>
|
|
80 If you were using the third-party mp4 module, be sure to disable it.
|
|
81 </note>
|
|
82 </para>
|
|
83
|
|
84 <!--
|
|
85 <para>
|
|
86 A similar pseudo-streaming support for FLV files is provided by the module
|
|
87 <a href="/en/docs/http/ngx_http_flv_module.xml">ngx_http_flv_module</a>.
|
|
88 </para>
|
|
89 -->
|
|
90
|
|
91 </section>
|
|
92
|
|
93
|
|
94 <section name="example" title="Usage example">
|
|
95
|
|
96 <para>
|
|
97 <example>
|
|
98 location /video/ {
|
|
99 mp4;
|
|
100 mp4_buffer_size 1m;
|
|
101 mp4_max_buffer_size 5m;
|
|
102 }
|
|
103 </example>
|
|
104 </para>
|
|
105
|
|
106 </section>
|
|
107
|
|
108
|
|
109 <section name="directives" title="Directives">
|
|
110
|
|
111 <directive name="mp4">
|
|
112 <syntax>mp4</syntax>
|
|
113 <default/>
|
|
114 <context>location</context>
|
|
115
|
|
116 <para>
|
|
117 Turns on module processing in a surrounding location.
|
|
118 </para>
|
|
119
|
|
120 </directive>
|
|
121
|
|
122
|
|
123 <directive name="mp4_buffer_size">
|
|
124 <syntax>mp4_buffer_size <argument>size</argument></syntax>
|
|
125 <default>mp4_buffer_size 512K</default>
|
|
126 <context>http</context>
|
|
127 <context>server</context>
|
|
128 <context>location</context>
|
|
129
|
|
130 <para>
|
|
131 Sets the initial size of a memory buffer used to process MP4 files.
|
|
132 </para>
|
|
133
|
|
134 </directive>
|
|
135
|
|
136
|
|
137 <directive name="mp4_max_buffer_size">
|
|
138 <syntax>mp4_max_buffer_size <argument>size</argument></syntax>
|
|
139 <default>mp4_max_buffer_size 10M</default>
|
|
140 <context>http</context>
|
|
141 <context>server</context>
|
|
142 <context>location</context>
|
|
143
|
|
144 <para>
|
|
145 During metadata processing, a larger buffer may become necessary.
|
|
146 Its size cannot exceed the specified <argument>size</argument>,
|
|
147 or else nginx will return
|
|
148 <http-error code="500" text="Internal Server Error"/>,
|
|
149 and log the following:
|
|
150 <example>
|
|
151 "/some/movie/file.mp4" mp4 moov atom is too large:
|
|
152 12583268, you may want to increase mp4_max_buffer_size
|
|
153 </example>
|
|
154 </para>
|
|
155
|
|
156 </directive>
|
|
157
|
|
158 </section>
|
|
159
|
|
160 </module>
|