Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_mp4_module.xml @ 22:9d3403f5204d
nginx-1.1.3, ngx_http_mp4_module
author | Igor Sysoev <igor@sysoev.ru> |
---|---|
date | Wed, 14 Sep 2011 15:05:04 +0000 |
parents | |
children | ae5aca1efe2c |
comparison
equal
deleted
inserted
replaced
21:a6e1763d5590 | 22:9d3403f5204d |
---|---|
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> |