[FFmpeg-devel] [PATCH 1/2] doc/muxers: extend documentation for MOV muxers

[Stefano Sabatini]

---
 doc/muxers.texi | 468 +++++++++++++++++++++++++++++++++---------------
 1 file changed, 321 insertions(+), 147 deletions(-)

diff --git a/doc/muxers.texi b/doc/muxers.texi
index 7b705b6a9e..345a55e8f4 100644
--- a/doc/muxers.texi
+++ b/doc/muxers.texi
@@ -19,6 +19,327 @@ enabled demuxers and muxers.
 
 A description of some of the currently available muxers follows.
 
+ at section 3gp, 3g2, f4v, ipod, ismv, mov, mp4, psp
+
+MOV/MPEG-4/ISOMBFF format family muxers.
+
+This section covers formats belonging to the QuickTime / MOV family,
+also named after the MPEG-4 Part 14 format, also named after the ISO
+base media file format (ISOBMFF).
+
+The MOV format was originally developed for the Apple QuickTime
+container format. Then it was later used as basis for the MPEG MPEG-4
+Part 1 (later Part 14) format, also named after ISO/IEC 14496-1.
+
+The format was later generalized into the ISO base media file format,
+also named MPEG-4 Part 12 format or ISO/IEC 14496-12 or ISO/IEC
+15444-12.
+
+It comprises the following muxers:
+
+ at table @samp
+ at item 3gp
+Third Generation Partnership Project (3GPP) format for 3G UMTS
+multimedia services.
+
+ at item 3g2
+Third Generation Partnership Project 2 (3GP2 or 3GPP2) format for 3G
+CDMA2000 multimedia services, similar to @code{3gp} with extensions
+and limitations
+
+ at item f4v
+Adobe Flash Video format.
+
+ at item ipod
+MPEG4 file formation audio file, as MOV/MP4 but limited to contain
+only audio streams, typically played with the Apple ipod device
+
+ at item ismv
+Microsoft IIS (Internet Information Services) Smooth Streaming
+Audio/Video (ISMV or ISMA) format. This is based on MPEG-4 Part 14
+format with a few incompatible variants, used to stream media files
+for the Microsoft IIS server.
+
+ at item mov
+A QuickTime format identified by the @code{.mov} extension, used
+natively by Apple QuickTime player.
+
+ at item mp4
+MP4 or MPEG-4 Part 14 format.
+
+ at item psp
+PlayStation Portable MP4/MPEG-4 Part 14 format variant. This is based
+on MPEG-4 Part 14 format with a few incompatible variants, used to
+play files on PlayStation devices.
+ at end table
+
+ at subsection Fragmentation
+
+The @samp{mov}, @samp{mp4}, and @samp{ismv} muxers support
+fragmentation. Normally, a MOV/MP4 file has all the metadata about all
+packets stored in one location.
+
+This data is usually written at the end of the file, but it can be
+moved to the start for better playback by adding @code{+faststart} to
+the @code{-movflags}, or 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 is not
+properly finished), and it requires less memory when 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 is less compatible with other applications.
+
+Fragmentation is enabled by setting one of the options that define
+how to cut the file into fragments:
+ at table @option
+ at item frag_duration
+ at item frag_size
+ at item min_frag_duration
+ at item movflags +frag_keyframe
+ at item movflags +frag_custom
+ at end table
+
+If more than one condition is specified, fragments are cut when one of
+the specified conditions is fulfilled. The exception to this is the
+option @option{min_frag_duration}, which has to be fulfilled for any
+of the other conditions to apply.
+
+ at subsection Options
+
+ at table @option
+
+ at item brand @var{brand_string}
+Override major brand.
+
+ at item empty_hdlr_name @var{bool}
+Enable to skip writing the name inside a @code{hdlr} box.
+Default is @code{false}.
+
+ at item encryption_key @var{key}
+set the media encryption key in hexadecimal format
+
+ at item encryption_kid @var{kid}
+set the media encryption key identifier in hexadecimal format
+
+ at item encryption_scheme @var{scheme}
+configure the encryption scheme, allowed values are @samp{none}, and
+ at samp{cenc-aes-ctr}
+
+ at item frag_duration @var{duration}
+Create fragments that are @var{duration} microseconds long.
+
+ at item frag_interleave  @var{number}
+Interleave samples within fragments (max number of consecutive
+samples, lower is tighter interleaving, but with more overhead. It is
+set to @code{0} by default.
+
+ at item frag_size @var{size}
+create fragments that contain up to @var{size} bytes of payload data
+
+ at item iods_audio_profile @var{profile}
+specify iods number for the audio profile atom (from -1 to 255),
+default is @code{-1}
+
+ at item iods_video_profile @var{profile}
+specify iods number for the video profile atom (from -1 to 255),
+default is @code{-1}
+
+ at item ism_lookahead @var{num_entries}
+specify number of lookahead entries for ISM files (from 0 to 255),
+default is @code{0}
+
+ at item min_frag_duration @var{duration}
+do not create fragments that are shorter than @var{duration} microseconds long
+
+ at item moov_size @var{bytes}
+Reserves space for the moov atom at the beginning of the file instead of placing the
+moov atom at the end. If the space reserved is insufficient, muxing will fail.
+
+ at item mov_gamma @var{gamma}
+specify gamma value for gama atom (as a decimal number from 0 to 10),
+default is @code{0.0}, must be set together with @code{+ movflags}
+
+ at item movflags @var{flags}
+Set various muxing switches. The following flags can be used:
+ at table @samp
+ at item cmaf
+write CMAF (Common Media Application Format) compatible fragmented
+MP4 output
+
+ at item dash
+write DASH (Dynamic Adaptive Streaming over HTTP) compatible fragmented
+MP4 output
+
+ at item default_base_moof
+Similarly to the @samp{omit_tfhd_offset} flag, this flag avoids
+writing the absolute base_data_offset field in tfhd atoms, but does so
+by using the new default-base-is-moof flag instead. This flag is new
+from 14496-12:2012. This may make the fragments easier to parse in
+certain circumstances (avoiding basing track fragment location
+calculations on the implicit end of the previous track fragment).
+
+ at item delay_moov
+delay writing the initial moov until the first fragment is cut, or
+until the first fragment flush
+
+ at item disable_chpl
+Disable Nero chapter markers (chpl atom). Normally, both Nero chapters
+and a QuickTime chapter track are written to the file. With this
+option set, only the QuickTime chapter track will be written. Nero
+chapters can cause failures when the file is reprocessed with certain
+tagging programs, like mp3Tag 2.61a and iTunes 11.3, most likely other
+versions are affected as well.
+
+ at item faststart
+Run a second pass moving the index (moov atom) to the beginning of the
+file. This operation can take a while, and will not work in various
+situations such as fragmented output, thus it is not enabled by
+default.
+
+ at item frag_custom
+Allow the caller to manually choose when to cut fragments, by calling
+ at 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{ffmpeg}.)
+
+ at item frag_discont
+signal that the next fragment is discontinuous from earlier ones
+
+ at item frag_every_frame
+fragment at every frame
+
+ at item frag_keyframe
+start a new fragment at each video keyframe
+
+ at item global_sidx
+write a global sidx index at the start of the file
+
+ at item isml
+create a live smooth streaming feed (for pushing to a publishing point)
+
+ at item negative_cts_offsets
+Enables utilization of version 1 of the CTTS box, in which the CTS offsets can
+be negative. This enables the initial sample to have DTS/CTS of zero, and
+reduces the need for edit lists for some cases such as video tracks with
+B-frames. Additionally, eases conformance with the DASH-IF interoperability
+guidelines.
+
+This option is implicitly set when writing @samp{ismv} (Smooth
+Streaming) files.
+
+ at item omit_tfhd_offset
+Do not write any absolute base_data_offset in tfhd atoms. This avoids
+tying fragments to absolute byte positions in the file/streams.
+
+ at item prefer_icc
+If writing colr atom prioritise usage of ICC profile if it exists in
+stream packet side data.
+
+ at item rtphint
+add RTP hinting tracks to the output file
+
+ at item 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 option set, the muxer writes one
+moof/mdat pair for each track, making it easier to separate tracks.
+
+ at item skip_sidx
+Skip writing of sidx atom. When bitrate overhead due to sidx atom is
+high, this option could be used for cases where sidx atom is not
+mandatory. When the @samp{global_sidx} flag is enabled, this option
+is ignored.
+
+ at item skip_trailer
+skip writing the mfra/tfra/mfro trailer for fragmented files
+
+ at item use_metadata_tags
+use mdta atom for metadata
+
+ at item write_colr
+write colr atom even if the color info is unspecified. This flag is
+experimental, may be renamed or changed, do not use from scripts.
+
+ at item write_gama
+write deprecated gama atom
+ at end table
+
+ at item movie_timescale @var{scale}
+Set the timescale written in the movie header box (@code{mvhd}).
+Range is 1 to INT_MAX. Default is @code{1000}.
+
+ at item rtpflags @var{flags}
+Add RTP hinting tracks to the output file.
+
+The following flags can be used:
+ at table @samp
+ at item h264_mode0
+use mode 0 for H.264 in RTP
+
+ at item latm
+use MP4A-LATM packetization instead of MPEG4-GENERIC for AAC
+
+ at item rfc2190
+use RFC 2190 packetization instead of RFC 4629 for H.263
+
+ at item send_bye
+send RTCP BYE packets when finishing
+
+ at item skip_rtcp
+do not send RTCP sender reports
+ at end table
+
+ at item skip_iods @var{bool}
+skip writing iods atom (default value is @code{true})
+
+ at item use_editlist @var{bool}
+use edit list (default value is @code{auto})
+
+ at item use_stream_ids_as_track_ids
+use stream ids as track ids (default value is @code{false})
+
+ at item video_track_timescale @var{scale}
+Set the timescale used for video tracks. Range is @code{0} to INT_MAX. If
+set to @code{0}, the timescale is automatically set based on the
+native stream time base. Default is @code{0}.
+
+ at item write_btrt @var{bool}
+Force or disable writing bitrate box inside stsd box of a track. The
+box contains decoding buffer size (in bytes), maximum bitrate and
+average bitrate for the track. The box will be skipped if none of
+these values can be computed.  Default is @code{-1} or @code{auto},
+which will write the box only in MP4 mode.
+
+ at item write_prft @var{option}
+Write producer time reference box (PRFT) with a specified time source for the
+NTP field in the PRFT box. Set value as @samp{wallclock} to specify timesource
+as wallclock time and @samp{pts} to specify timesource as input packets' PTS
+values.
+
+ at item write_tmcd @var{bool}
+Specify @code{on} to force writing a timecode track, @code{off} to disable it
+and @code{auto} to write a timecode track only for mov and mp4 output (default).
+
+Setting value to @samp{pts} is applicable only for a live encoding use case,
+where PTS values are set as as wallclock time at the source. For example, an
+encoding use case with decklink capture source where @option{video_pts} and
+ at option{audio_pts} are set to @samp{abs_wallclock}.
+ at end table
+
+ at subsection Examples
+
+ at itemize
+ at item
+Push Smooth Streaming content in real time to a publishing point on
+IIS with the @samp{ismv} muxer using @command{ffmpeg}:
+ at example
+ffmpeg -re @var{<normal input/transcoding options>} -movflags isml+frag_keyframe -f ismv http://server/publishingpoint.isml/Streams(Encoder1)
+ at end example
+ at end itemize
+
 @anchor{a64}
 @section a64
 
@@ -1623,153 +1944,6 @@ ffmpeg -i INPUT -f md5 -
 
 See also the @ref{hash} and @ref{framemd5} muxers.
 
- at section mov, mp4, ismv
-
-MOV/MP4/ISMV (Smooth Streaming) muxer.
-
-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 by adding @code{+faststart} to the @code{-movflags}, or
-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 is not properly finished), and it requires less memory when 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 is less compatible with other applications.
-
-Fragmentation is enabled by setting one of the options that define
-how to cut the file into fragments: @code{-frag_duration}, @code{-frag_size},
- at code{-min_frag_duration}, @code{-movflags +frag_keyframe} and
- at code{-movflags +frag_custom}. If more than one condition is specified,
-fragments are cut when one of the specified conditions is fulfilled. The
-exception to this is @code{-min_frag_duration}, which has to be fulfilled for
-any of the other conditions to apply.
-
- at subsection Options
-
- at table @option
- at item frag_duration @var{duration}
-Create fragments that are @var{duration} microseconds long.
- at item frag_size @var{size}
-Create fragments that contain up to @var{size} bytes of payload data.
- at item min_frag_duration @var{duration}
-Don't create fragments that are shorter than @var{duration} microseconds long.
- at item movflags @var{flags}
-Set various muxing switches. The following flags can be used:
- at table @samp
- at item frag_keyframe
-Start a new fragment at each video keyframe.
- at item 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{ffmpeg}.)
- at item empty_moov
-Write an initial moov atom directly at the start of the file, without
-describing any samples in it. Generally, an 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.
-
-This option is implicitly set when writing ismv (Smooth Streaming) files.
- at item 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 option 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.
- at item skip_sidx
-Skip writing of sidx atom. When bitrate overhead due to sidx atom is high,
-this option could be used for cases where sidx atom is not mandatory.
-When global_sidx flag is enabled, this option will be ignored.
- at item faststart
-Run a second pass moving the index (moov atom) to the beginning of the file.
-This operation can take a while, and will not work in various situations such
-as fragmented output, thus it is not enabled by default.
- at item rtphint
-Add RTP hinting tracks to the output file.
- at item disable_chpl
-Disable Nero chapter markers (chpl atom).  Normally, both Nero chapters
-and a QuickTime chapter track are written to the file. With this option
-set, only the QuickTime chapter track will be written. Nero chapters can
-cause failures when the file is reprocessed with certain tagging programs, like
-mp3Tag 2.61a and iTunes 11.3, most likely other versions are affected as well.
- at item omit_tfhd_offset
-Do not write any absolute base_data_offset in tfhd atoms. This avoids
-tying fragments to absolute byte positions in the file/streams.
- at item default_base_moof
-Similarly to the omit_tfhd_offset, this flag avoids writing the
-absolute base_data_offset field in tfhd atoms, but does so by using
-the new default-base-is-moof flag instead. This flag is new from
-14496-12:2012. This may make the fragments easier to parse in certain
-circumstances (avoiding basing track fragment location calculations
-on the implicit end of the previous track fragment).
- at item negative_cts_offsets
-Enables utilization of version 1 of the CTTS box, in which the CTS offsets can
-be negative. This enables the initial sample to have DTS/CTS of zero, and
-reduces the need for edit lists for some cases such as video tracks with
-B-frames. Additionally, eases conformance with the DASH-IF interoperability
-guidelines.
-
-This option is implicitly set when writing ismv (Smooth Streaming) files.
- at end table
-
- at item moov_size @var{bytes}
-Reserves space for the moov atom at the beginning of the file instead of placing the
-moov atom at the end. If the space reserved is insufficient, muxing will fail.
-
- at item write_tmcd
-Specify @code{on} to force writing a timecode track, @code{off} to disable it
-and @code{auto} to write a timecode track only for mov and mp4 output (default).
-
- at item write_btrt @var{bool}
-Force or disable writing bitrate box inside stsd box of a track.
-The box contains decoding buffer size (in bytes), maximum bitrate and
-average bitrate for the track. The box will be skipped if none of these values
-can be computed.
-Default is @code{-1} or @code{auto}, which will write the box only in MP4 mode.
-
- at item write_prft
-Write producer time reference box (PRFT) with a specified time source for the
-NTP field in the PRFT box. Set value as @samp{wallclock} to specify timesource
-as wallclock time and @samp{pts} to specify timesource as input packets' PTS
-values.
-
-Setting value to @samp{pts} is applicable only for a live encoding use case,
-where PTS values are set as as wallclock time at the source. For example, an
-encoding use case with decklink capture source where @option{video_pts} and
- at option{audio_pts} are set to @samp{abs_wallclock}.
-
- at item empty_hdlr_name @var{bool}
-Enable to skip writing the name inside a @code{hdlr} box.
-Default is @code{false}.
-
- at item movie_timescale @var{scale}
-Set the timescale written in the movie header box (@code{mvhd}).
-Range is 1 to INT_MAX. Default is 1000.
-
- at item video_track_timescale @var{scale}
-Set the timescale used for video tracks. Range is 0 to INT_MAX.
-If set to @code{0}, the timescale is automatically set based on
-the native stream time base. Default is 0.
- at end table
-
- at subsection Example
-
-Smooth Streaming content can be pushed in real time to a publishing
-point on IIS with this muxer. Example:
- at example
-ffmpeg -re @var{<normal input/transcoding options>} -movflags isml+frag_keyframe -f ismv http://server/publishingpoint.isml/Streams(Encoder1)
- at end example
-
 @section mp3
 
 The MP3 muxer writes a raw MP3 stream with the following optional features:
-- 
2.34.1