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