[13/13] doc: Document mov/mp4 fragmentation options

Message ID 1327084549-68492-1-git-send-email-martin@martin.st
State Superseded
Headers show

Commit Message

Martin Storsjö Jan. 20, 2012, 6:35 p.m.
---
 doc/muxers.texi |   61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 61 insertions(+), 0 deletions(-)

Comments

Martin Storsjö Jan. 27, 2012, 7:50 p.m. | #1
On Fri, 20 Jan 2012, Martin Storsjö wrote:

> ---
> doc/muxers.texi |   61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 61 insertions(+), 0 deletions(-)

All the things documented in this patch have now been committed, so it 
should be ok to commit once someone has reviewed it.

// Martin
Diego Biurrun Jan. 30, 2012, 12:10 p.m. | #2
On Fri, Jan 20, 2012 at 08:35:49PM +0200, Martin Storsjö wrote:
> 
> --- a/doc/muxers.texi
> +++ b/doc/muxers.texi
> @@ -142,6 +142,67 @@ Note also that the pattern must not necessarily contain "%d" or
>  
> +@section mov/mp4/ismv
> +
> +The mov/mp4/ismv muxer supports fragmentation. Normally, a mov/mp4
> +file has all the metadata about all packets stored in one location

I'd capitalize the format names.  You possibly want to keep the names
of the muxers spelled in the way they are used on the command line.
Same below..

> +it isn't properly finished), and it requires less memory if writing
> +very long files (since writing normal mov/mp4 files stores info about

s/if writing/when writing/

> +@table @option
> +@item -movflags frag_keyframe
> +Start a new fragment at each video keyframe

.

> +@item -frag_duration @var{duration}
> +Make fragments that are @var{duration} microseconds long.
> +@item -frag_size @var{size}
> +Make fragments that contain up to @var{size} bytes of payload data.

"Make" is somewhat generic, I'd replace by "write" or "generate" or
"create".

> +Additionally, the way the output file is written can be adjusted with
> +a few other options:

s/with/through/

> +@table @option
> +@item -movflags empty_moov
> +Write an initial moov atom directly at the start of the file, without
> +describing any samples in it. Normally, a normal mdat/moov pair is

Normally, a normal?  Sounds like you can drop "normal".

> +written at the start of the file, as a normal mov/mp4 file, containing

"normal" again - replace "Normally" by "Generally".

> +@item -movflags separate_moof
> +Write a separate moof (movie fragment) atom for each track. Normally,
> +packets for all tracks are written in a moof atom (which is slightly
> +more efficient), but with this set, the muxer writes one moof/mdat

with this option set

> +Smooth Streaming content can be pushed in real time to a publishing
> +point on IIS with this muxer. An example of doing this:

muxer. Example:

Diego

Patch

diff --git a/doc/muxers.texi b/doc/muxers.texi
index 5a609c8..e476fde 100644
--- a/doc/muxers.texi
+++ b/doc/muxers.texi
@@ -142,6 +142,67 @@  Note also that the pattern must not necessarily contain "%d" or
 avconv -i in.avi -f image2 -frames:v 1 img.jpeg
 @end example
 
+@section mov/mp4/ismv
+
+The mov/mp4/ismv muxer supports fragmentation. Normally, a mov/mp4
+file has all the metadata about all packets stored in one location
+(written at the end of the file, it can be moved to the start for
+better playback using the @command{qt-faststart} tool). A fragmented
+file consists of a number of fragments, where packets and metadata
+about these packets are stored together. Writing a fragmented
+file has the advantage that the file is decodable even if the
+writing is interrupted (while a normal mov/mp4 is undecodable if
+it isn't properly finished), and it requires less memory if writing
+very long files (since writing normal mov/mp4 files stores info about
+every single packet in memory until the file is closed). The downside
+is that it normally is less compatible with other applications.
+
+Fragmentation is enabled by setting one of the AVOptions that define
+how to cut the file into fragments:
+
+@table @option
+@item -movflags frag_keyframe
+Start a new fragment at each video keyframe
+@item -frag_duration @var{duration}
+Make fragments that are @var{duration} microseconds long.
+@item -frag_size @var{size}
+Make fragments that contain up to @var{size} bytes of payload data.
+@item -movflags frag_custom
+Allow the caller to manually choose when to cut fragments, by
+calling @code{av_write_frame(ctx, NULL)} to write a fragment with
+the packets written so far. (This is only useful with other
+applications integrating libavformat, not from @command{avconv}.)
+@end table
+
+Additionally, the way the output file is written can be adjusted with
+a few other options:
+
+@table @option
+@item -movflags empty_moov
+Write an initial moov atom directly at the start of the file, without
+describing any samples in it. Normally, a normal mdat/moov pair is
+written at the start of the file, as a normal mov/mp4 file, containing
+only a short portion of the file. With this option set, there is no
+initial mdat atom, and the moov atom only describes the tracks but has
+a zero duration.
+
+Files written with this option set do not work in QuickTime.
+This option is implicitly set when writing ismv (Smooth Streaming) files.
+@item -movflags separate_moof
+Write a separate moof (movie fragment) atom for each track. Normally,
+packets for all tracks are written in a moof atom (which is slightly
+more efficient), but with this set, the muxer writes one moof/mdat
+pair for each track, making it easier to separate tracks.
+
+This option is implicitly set when writing ismv (Smooth Streaming) files.
+@end table
+
+Smooth Streaming content can be pushed in real time to a publishing
+point on IIS with this muxer. An example of doing this:
+@example
+avconv -re @var{<normal input/transcoding options>} -movflags isml+frag_keyframe -f ismv http://server/publishingpoint.isml/Streams(Encoder1)
+@end example
+
 @section mpegts
 
 MPEG transport stream muxer.