Mercurial > hg > nginx

comparison docs/xml/http/ngx_http_mp4_module.xml @ 4110:d889195c8db4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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>