Mercurial > hg > nginx
changeset 4110:d889195c8db4
Added ngx_http_mp4_module documentation.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 15 Sep 2011 08:59:13 +0000 |
parents | dc1fa52222b4 |
children | 088ee72d2e57 |
files | docs/GNUmakefile docs/xml/http/ngx_http_mp4_module.xml |
diffstat | 2 files changed, 158 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/GNUmakefile +++ b/docs/GNUmakefile @@ -58,7 +58,8 @@ docs/xslt/changes.xslt: docs/xsls/chang 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 \
new file mode 100644 --- /dev/null +++ b/docs/xml/http/ngx_http_mp4_module.xml @@ -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>