Mercurial > hg > nginx-site
annotate xml/en/docs/http/ngx_http_mp4_module.xml @ 75:2bf4cd2787c5
Added DTDs to make xmllint happy.
Note that these DTDs don't try to be actually correct: possible element
contents require cleanup. This is enough to pass all documents through
xmllint though.
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Mon, 10 Oct 2011 14:47:09 +0000 |
parents | 59969aeeeebc |
children | 6876e2558d09 |
rev | line source |
---|---|
22 | 1 <?xml version="1.0"?> |
2 | |
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | |
4 | |
33
ae5aca1efe2c
Using new <module> and <section> format in ngx_http_mp4_module.xml.
Igor Sysoev <igor@sysoev.ru>
parents:
22
diff
changeset
|
5 <module name="HTTP MP4 module" |
22 | 6 link="/en/docs/http/ngx_http_mp4_module.html" |
7 lang="en"> | |
8 | |
33
ae5aca1efe2c
Using new <module> and <section> format in ngx_http_mp4_module.xml.
Igor Sysoev <igor@sysoev.ru>
parents:
22
diff
changeset
|
9 <section name="Summary"> |
22 | 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 | |
52
666e85596e3c
Added support for <link url="..."> which should eventually replace
Ruslan Ermilov <ru@nginx.com>
parents:
33
diff
changeset
|
54 <link |
666e85596e3c
Added support for <link url="..."> which should eventually replace
Ruslan Ermilov <ru@nginx.com>
parents:
33
diff
changeset
|
55 url="http://flowplayer.org/plugins/streaming/pseudostreaming.html#prepare"> |
666e85596e3c
Added support for <link url="..."> which should eventually replace
Ruslan Ermilov <ru@nginx.com>
parents:
33
diff
changeset
|
56 prepare an original file for pseudo-streaming</link>, |
22 | 57 rather than having nginx do this on every such request. |
58 </para> | |
59 | |
60 <para> | |
61 For a matching request with a non-zero | |
62 <parameter>start</parameter> | |
63 argument, nginx will read metadata from the file, prepare the | |
64 stream starting from the requested offset, and send it to a client. | |
65 This has the same overhead as described above. | |
66 </para> | |
67 | |
68 <para> | |
69 If a matching request does not include the | |
70 <parameter>start</parameter> | |
71 argument, there is no overhead, and the file is just sent as a static resource. | |
72 Some players also support byte-range requests, and thus do not require | |
73 this module at all. | |
74 </para> | |
75 | |
76 <para> | |
77 This module is not built by default, it should be enabled with the | |
54 | 78 <code>--with-http_mp4_module</code> |
22 | 79 configuration parameter. |
80 <note> | |
81 If you were using the third-party mp4 module, be sure to disable it. | |
82 </note> | |
83 </para> | |
84 | |
85 <!-- | |
86 <para> | |
87 A similar pseudo-streaming support for FLV files is provided by the module | |
52
666e85596e3c
Added support for <link url="..."> which should eventually replace
Ruslan Ermilov <ru@nginx.com>
parents:
33
diff
changeset
|
88 <link doc="ngx_http_flv_module.xml">ngx_http_flv_module</link>. |
22 | 89 </para> |
90 --> | |
91 | |
92 </section> | |
93 | |
94 | |
53
60796d056dde
Renamed section name "Usage example" to "Example Configuration"
Ruslan Ermilov <ru@nginx.com>
parents:
52
diff
changeset
|
95 <section id="example" name="Example Configuration"> |
22 | 96 |
97 <para> | |
98 <example> | |
99 location /video/ { | |
100 mp4; | |
101 mp4_buffer_size 1m; | |
102 mp4_max_buffer_size 5m; | |
103 } | |
104 </example> | |
105 </para> | |
106 | |
107 </section> | |
108 | |
109 | |
33
ae5aca1efe2c
Using new <module> and <section> format in ngx_http_mp4_module.xml.
Igor Sysoev <igor@sysoev.ru>
parents:
22
diff
changeset
|
110 <section id="directives" name="Directives"> |
22 | 111 |
112 <directive name="mp4"> | |
113 <syntax>mp4</syntax> | |
114 <default/> | |
115 <context>location</context> | |
116 | |
117 <para> | |
118 Turns on module processing in a surrounding location. | |
119 </para> | |
120 | |
121 </directive> | |
122 | |
123 | |
124 <directive name="mp4_buffer_size"> | |
125 <syntax>mp4_buffer_size <argument>size</argument></syntax> | |
126 <default>mp4_buffer_size 512K</default> | |
127 <context>http</context> | |
128 <context>server</context> | |
129 <context>location</context> | |
130 | |
131 <para> | |
132 Sets the initial size of a memory buffer used to process MP4 files. | |
133 </para> | |
134 | |
135 </directive> | |
136 | |
137 | |
138 <directive name="mp4_max_buffer_size"> | |
139 <syntax>mp4_max_buffer_size <argument>size</argument></syntax> | |
140 <default>mp4_max_buffer_size 10M</default> | |
141 <context>http</context> | |
142 <context>server</context> | |
143 <context>location</context> | |
144 | |
145 <para> | |
146 During metadata processing, a larger buffer may become necessary. | |
147 Its size cannot exceed the specified <argument>size</argument>, | |
52
666e85596e3c
Added support for <link url="..."> which should eventually replace
Ruslan Ermilov <ru@nginx.com>
parents:
33
diff
changeset
|
148 or else nginx will return the server error |
666e85596e3c
Added support for <link url="..."> which should eventually replace
Ruslan Ermilov <ru@nginx.com>
parents:
33
diff
changeset
|
149 <http-status code="500" text="Internal Server Error"/>, |
22 | 150 and log the following: |
151 <example> | |
152 "/some/movie/file.mp4" mp4 moov atom is too large: | |
153 12583268, you may want to increase mp4_max_buffer_size | |
154 </example> | |
155 </para> | |
156 | |
157 </directive> | |
158 | |
159 </section> | |
160 | |
161 </module> |