mirror of
https://github.com/nginx/nginx.git
synced 2024-12-18 21:23:36 -06:00
Added ngx_http_mp4_module documentation.
This commit is contained in:
Ruslan Ermilov
parent
1ebdcd1d90
commit
fc084d0b62
@ -58,7 +58,8 @@ docs/xslt/changes.xslt: docs/xsls/changes.xsls
|
||||
|
||||
html: \
|
||||
docs/html/ngx_core_module.html \
|
||||
docs/html/http/ngx_http_core_module.html
|
||||
docs/html/http/ngx_http_core_module.html \
|
||||
docs/html/http/ngx_http_mp4_module.html
|
||||
|
||||
docs/html/%.html: \
|
||||
docs/xml/%.xml \
|
||||
|
||||
156
docs/xml/http/ngx_http_mp4_module.xml
Normal file
156
docs/xml/http/ngx_http_mp4_module.xml
Normal file
@ -0,0 +1,156 @@
|
||||
<?xml version="1.0"?>
|
||||
|
||||
<!DOCTYPE module SYSTEM "../../dtd/module.dtd">
|
||||
|
||||
<module name="HTTP MP4 Module" id="http_mp4_module">
|
||||
|
||||
<section name="Summary">
|
||||
|
||||
<para>
|
||||
The module <code>ngx_http_mp4_module</code> provides pseudo-streaming
|
||||
server-side support for H.264/AAC files typically having filename extensions
|
||||
<pathname>.mp4</pathname>, <pathname>.m4v</pathname>,
|
||||
and <pathname>.m4a</pathname>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Pseudo-streaming works in alliance with conformant Flash players.
|
||||
A player sends an HTTP request to the server with a start time
|
||||
argument in the request URI’s query string (named simply
|
||||
<parameter>start</parameter>
|
||||
and specified in seconds), and the server responds with a stream
|
||||
so that its start position corresponds to the requested time,
|
||||
for example:
|
||||
<example>
|
||||
http://example.com/elephants_dream.mp4?start=238.88
|
||||
</example>
|
||||
This allows for a random seeking at any time, or starting playback
|
||||
in the middle of a timeline.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To support seeking, H.264-based formats store the metadata
|
||||
in the so-called “moov atom.”
|
||||
It is a part of the file that holds the index information for the
|
||||
whole file.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To start playback, a player first needs to read metadata.
|
||||
This is done by sending a special request with the
|
||||
<parameter>start=0</parameter>
|
||||
argument. Many encoding software will insert the metadata at
|
||||
the end of the file. This is bad for pseudo-streaming:
|
||||
the metadata needs to be located at the beginning of the file,
|
||||
or else the entire file will have to be downloaded before it
|
||||
starts playing. If a file is well-formed (with metadata at the
|
||||
beginning of a file), nginx just sends back the contents of a file.
|
||||
Otherwise, it has to read the file and prepare a new stream so that
|
||||
metadata comes before media data.
|
||||
This involves some CPU, memory, and disk I/O overhead,
|
||||
so it is a good idea to
|
||||
<link url="http://flowplayer.org/plugins/streaming/pseudostreaming.html#prepare">
|
||||
prepare an original file for pseudo-streaming</link>,
|
||||
rather than having nginx do this on every such request.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For a matching request with a non-zero
|
||||
<parameter>start</parameter>
|
||||
argument, nginx will read metadata from the file, prepare the
|
||||
stream starting from the requested offset, and send it to a client.
|
||||
This has the same overhead as described above.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If a matching request does not include the
|
||||
<parameter>start</parameter>
|
||||
argument, there is no overhead, and the file is just sent as a static resource.
|
||||
Some players also support byte-range requests, and thus do not require
|
||||
this module at all.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This module is not built by default, it should be enabled with the
|
||||
<command>--with-http_mp4_module</command>
|
||||
configuration parameter.
|
||||
<note>
|
||||
If you were using the third-party mp4 module, be sure to disable it.
|
||||
</note>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A similar pseudo-streaming support for FLV files is provided by the module
|
||||
<link doc="ngx_http_flv_module.xml">ngx_http_flv_module</link>.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<section id="example" name="Example Configuration">
|
||||
|
||||
<para>
|
||||
<example>
|
||||
location /video/ {
|
||||
mp4;
|
||||
mp4_buffer_size 1m;
|
||||
mp4_max_buffer_size 5m;
|
||||
}
|
||||
</example>
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<section id="directives" name="Directives">
|
||||
|
||||
<directive name="mp4">
|
||||
<syntax>mp4</syntax>
|
||||
<default/>
|
||||
<context>location</context>
|
||||
|
||||
<para>
|
||||
Turns on module processing in a surrounding location.
|
||||
</para>
|
||||
|
||||
</directive>
|
||||
|
||||
|
||||
<directive name="mp4_buffer_size">
|
||||
<syntax>mp4_buffer_size <argument>size</argument></syntax>
|
||||
<default>mp4_buffer_size 512K</default>
|
||||
<context>http</context>
|
||||
<context>server</context>
|
||||
<context>location</context>
|
||||
|
||||
<para>
|
||||
Sets the initial size of a memory buffer used to process MP4 files.
|
||||
</para>
|
||||
|
||||
</directive>
|
||||
|
||||
|
||||
<directive name="mp4_max_buffer_size">
|
||||
<syntax>mp4_max_buffer_size <argument>size</argument></syntax>
|
||||
<default>mp4_max_buffer_size 10M</default>
|
||||
<context>http</context>
|
||||
<context>server</context>
|
||||
<context>location</context>
|
||||
|
||||
<para>
|
||||
During metadata processing, a larger buffer may become necessary.
|
||||
Its size cannot exceed the specified <argument>size</argument>,
|
||||
or else nginx will return the server error
|
||||
<http-status code="500" text="Internal Server Error"/>,
|
||||
and log the following:
|
||||
<example>
|
||||
"/some/movie/file.mp4" mp4 moov atom is too large:
|
||||
12583268, you may want to increase mp4_max_buffer_size
|
||||
</example>
|
||||
</para>
|
||||
|
||||
</directive>
|
||||
|
||||
</section>
|
||||
|
||||
</module>
|
||||
Loading…
Reference in New Issue
Block a user