Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_mp4_module.xml @ 22:9d3403f5204d

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