doc/muxers/dash: review documentation

Sort options by name, review formatting, apply consistency fixes and
fill the gaps (e.g. missing value for constants or flags), and review
and extend content.

1 files changed, 293 insertions, 125 deletions

diff --git a/doc/muxers.texi b/doc/muxers.texi
index b1716d7a6b..a49853daf2 100644
--- a/doc/muxers.texi
+++ b/doc/muxers.texi
@@ -971,12 +971,13 @@ ffmpeg -i INPUT -c:a pcm_u8 -c:v mpeg2video -f crc -
 
 @anchor{dash}
 @section dash
+Dynamic Adaptive Streaming over HTTP (DASH) muxer.
 
-Dynamic Adaptive Streaming over HTTP (DASH) muxer that creates segments
-and manifest files according to the MPEG-DASH standard ISO/IEC 23009-1:2014.
+This muxer creates segments and manifest files according to the
+MPEG-DASH standard ISO/IEC 23009-1:2014 and following standard
+updates.
 
 For more information see:
-
 @itemize @bullet
 @item
 ISO DASH Specification: @url{http://standards.iso.org/ittf/PubliclyAvailableStandards/c065274_ISO_IEC_23009-1_2014.zip}
@@ -984,166 +985,333 @@ ISO DASH Specification: @url{http://standards.iso.org/ittf/PubliclyAvailableStan
 WebM DASH Specification: @url{https://sites.google.com/a/webmproject.org/wiki/adaptive-streaming/webm-dash-specification}
 @end itemize
 
-It creates a MPD manifest file and segment files for each stream.
+This muxer creates an MPD (Media Presentation Description) manifest
+file and segment files for each stream. Segment files are placed in
+the same directory of the MPD manifest file.
+
+The segment filename might contain pre-defined identifiers used in the
+manifest @code{SegmentTemplate} section as defined in section
+5.3.9.4.4 of the standard.
+
+Available identifiers are @code{$RepresentationID$}, @code{$Number$},
+@code{$Bandwidth$}, and @code{$Time$}. In addition to the standard
+identifiers, an ffmpeg-specific @code{$ext$} identifier is also
+supported. When specified, @command{ffmpeg} will replace @code{$ext$}
+in the file name with muxing format's extensions such as @code{mp4},
+@code{webm} etc.
+
+@subsection Options
+@table @option
+@item adaptation_sets @var{adaptation_sets}
+Assign streams to adaptation sets, specified in the MPD manifest
+@code{AdaptationSets} section.
 
-The segment filename might contain pre-defined identifiers used with SegmentTemplate
-as defined in section 5.3.9.4.4 of the standard. Available identifiers are "$RepresentationID$",
-"$Number$", "$Bandwidth$" and "$Time$".
-In addition to the standard identifiers, an ffmpeg-specific "$ext$" identifier is also supported.
-When specified ffmpeg will replace $ext$ in the file name with muxing format's extensions such as mp4, webm etc.,
+An adaptation set contains a set of one or more streams accessed as a
+single subset, e.g. corresponding streams encoded at different size
+selectable by the user depending on the available bandwidth, or to
+different audio streams with a different language.
 
+Each adaptation set is specified with the syntax:
 @example
-ffmpeg -re -i <input> -map 0 -map 0 -c:a libfdk_aac -c:v libx264 \
--b:v:0 800k -b:v:1 300k -s:v:1 320x170 -profile:v:1 baseline \
--profile:v:0 main -bf 1 -keyint_min 120 -g 120 -sc_threshold 0 \
--b_strategy 0 -ar:a:1 22050 -use_timeline 1 -use_template 1 \
--window_size 5 -adaptation_sets "id=0,streams=v id=1,streams=a" \
--f dash /path/to/out.mpd
+id=@var{index},streams=@var{streams}
 @end example
 
+where @var{index} must be a numerical index, and @var{streams} is a
+sequence of @code{,}-separated stream indices. Multiple adaptation
+sets can be specified, separated by spaces.
+
+To map all video (or audio) streams to an adaptation set, @code{v} (or
+@code{a}) can be used as stream identifier instead of IDs.
+
+When no assignment is defined, this defaults to an adaptation set for
+each stream.
+
+The following optional fields can also be specified:
+
 @table @option
-@item seg_duration @var{duration}
-Set the segment length in seconds (fractional value can be set). The value is
-treated as average segment duration when @var{use_template} is enabled and
-@var{use_timeline} is disabled and as minimum segment duration for all the other
-use cases.
-@item frag_duration @var{duration}
-Set the length in seconds of fragments within segments (fractional value can be set).
-@item frag_type @var{type}
-Set the type of interval for fragmentation.
-@item window_size @var{size}
-Set the maximum number of segments kept in the manifest.
-@item extra_window_size @var{size}
-Set the maximum number of segments kept outside of the manifest before removing from disk.
-@item remove_at_exit @var{remove}
-Enable (1) or disable (0) removal of all segments when finished.
-@item use_template @var{template}
-Enable (1) or disable (0) use of SegmentTemplate instead of SegmentList.
-@item use_timeline @var{timeline}
-Enable (1) or disable (0) use of SegmentTimeline in SegmentTemplate.
-@item single_file @var{single_file}
-Enable (1) or disable (0) storing all segments in one file, accessed using byte ranges.
-@item single_file_name @var{file_name}
-DASH-templated name to be used for baseURL. Implies @var{single_file} set to "1". In the template, "$ext$" is replaced with the file name extension specific for the segment format.
-@item init_seg_name @var{init_name}
-DASH-templated name to used for the initialization segment. Default is "init-stream$RepresentationID$.$ext$". "$ext$" is replaced with the file name extension specific for the segment format.
-@item media_seg_name @var{segment_name}
-DASH-templated name to used for the media segments. Default is "chunk-stream$RepresentationID$-$Number%05d$.$ext$". "$ext$" is replaced with the file name extension specific for the segment format.
-@item utc_timing_url @var{utc_url}
-URL of the page that will return the UTC timestamp in ISO format. Example: "https://time.akamai.com/?iso"
-@item method @var{method}
-Use the given HTTP method to create output files. Generally set to PUT or POST.
-@item http_user_agent @var{user_agent}
-Override User-Agent field in HTTP header. Applicable only for HTTP output.
-@item http_persistent @var{http_persistent}
-Use persistent HTTP connections. Applicable only for HTTP output.
-@item hls_playlist @var{hls_playlist}
-Generate HLS playlist files as well. The master playlist is generated with the filename @var{hls_master_name}.
-One media playlist file is generated for each stream with filenames media_0.m3u8, media_1.m3u8, etc.
-@item hls_master_name @var{file_name}
-HLS master playlist name. Default is "master.m3u8".
-@item streaming @var{streaming}
-Enable (1) or disable (0) chunk streaming mode of output. In chunk streaming
-mode, each frame will be a moof fragment which forms a chunk.
-@item adaptation_sets @var{adaptation_sets}
-Assign streams to AdaptationSets. Syntax is "id=x,streams=a,b,c id=y,streams=d,e" with x and y being the IDs
-of the adaptation sets and a,b,c,d and e are the indices of the mapped streams.
+@item descriptor
+Define the descriptor as defined by ISO/IEC 23009-1:2014/Amd.2:2015.
 
-To map all video (or audio) streams to an AdaptationSet, "v" (or "a") can be used as stream identifier instead of IDs.
+For example:
+@example
+<SupplementalProperty schemeIdUri=\"urn:mpeg:dash:srd:2014\" value=\"0,0,0,1,1,2,2\"/>
+@end example
 
-When no assignment is defined, this defaults to an AdaptationSet for each stream.
+The descriptor string should be a self-closing XML tag.
 
-Optional syntax is "id=x,seg_duration=x,frag_duration=x,frag_type=type,descriptor=descriptor_string,streams=a,b,c id=y,seg_duration=y,frag_type=type,streams=d,e" and so on,
-descriptor is useful to the scheme defined by ISO/IEC 23009-1:2014/Amd.2:2015.
-For example, -adaptation_sets "id=0,descriptor=<SupplementalProperty schemeIdUri=\"urn:mpeg:dash:srd:2014\" value=\"0,0,0,1,1,2,2\"/>,streams=v".
-Please note that descriptor string should be a self-closing xml tag.
-seg_duration, frag_duration and frag_type override the global option values for each adaptation set.
-For example, -adaptation_sets "id=0,seg_duration=2,frag_duration=1,frag_type=duration,streams=v id=1,seg_duration=2,frag_type=none,streams=a"
-type_id marks an adaptation set as containing streams meant to be used for Trick Mode for the referenced adaptation set.
-For example, -adaptation_sets "id=0,seg_duration=2,frag_type=none,streams=0 id=1,seg_duration=10,frag_type=none,trick_id=0,streams=1"
-@item timeout @var{timeout}
-Set timeout for socket I/O operations. Applicable only for HTTP output.
-@item index_correction @var{index_correction}
-Enable (1) or Disable (0) segment index correction logic. Applicable only when
-@var{use_template} is enabled and @var{use_timeline} is disabled.
+@item frag_duration
+Override the global fragment duration specified with the
+@option{frag_duration} option.
+
+@item frag_type
+Override the global fragment type specified with the
+@option{frag_type} option.
+
+@item seg_duration
+Override the global segment duration specified with the
+@option{seg_duration} option.
+
+@item trick_id
+Mark an adaptation set as containing streams meant to be used for
+Trick Mode for the referenced adaptation set.
+@end table
+
+A few examples of possible values for the @option{adaptation_sets}
+option follow:
+@example
+id=0,seg_duration=2,frag_duration=1,frag_type=duration,streams=v id=1,seg_duration=2,frag_type=none,streams=a
+@end example
+
+@example
+id=0,seg_duration=2,frag_type=none,streams=0 id=1,seg_duration=10,frag_type=none,trick_id=0,streams=1
+@end example
 
-When enabled, the logic monitors the flow of segment indexes. If a streams's
-segment index value is not at the expected real time position, then the logic
-corrects that index value.
+@item dash_segment_type @var{type}
+Set DASH segment files type.
+
+Possible values:
+@table @samp
+@item auto
+The dash segment files format will be selected based on the stream
+codec. This is the default mode.
+@item mp4
+the dash segment files will be in ISOBMFF/MP4 format
+@item webm
+the dash segment files will be in WebM format
+@end table
+
+@item extra_window_size @var{size}
+Set the maximum number of segments kept outside of the manifest before
+removing from disk.
 
-Typically this logic is needed in live streaming use cases. The network bandwidth
-fluctuations are common during long run streaming. Each fluctuation can cause
-the segment indexes fall behind the expected real time position.
 @item format_options @var{options_list}
-Set container format (mp4/webm) options using a @code{:} separated list of
+Set container format (mp4/webm) options using a @code{:}-separated list of
 key=value parameters. Values containing @code{:} special characters must be
 escaped.
 
-@item global_sidx @var{global_sidx}
-Write global SIDX atom. Applicable only for single file, mp4 output, non-streaming mode.
+@item frag_duration @var{duration}
+Set the length in seconds of fragments within segments, fractional
+value can also be set.
+
+@item frag_type @var{type}
+Set the type of interval for fragmentation.
 
-@item dash_segment_type @var{dash_segment_type}
 Possible values:
-@table @option
+@table @samp
 @item auto
-If this flag is set, the dash segment files format will be selected based on the stream codec. This is the default mode.
+set one fragment per segment
 
-@item mp4
-If this flag is set, the dash segment files will be in in ISOBMFF format.
+@item every_frame
+fragment at every frame
 
-@item webm
-If this flag is set, the dash segment files will be in in WebM format.
+@item duration
+fragment at specific time intervals
+
+@item pframes
+fragment at keyframes and following P-Frame reordering (Video only,
+experimental)
 @end table
 
-@item ignore_io_errors @var{ignore_io_errors}
-Ignore IO errors during open and write. Useful for long-duration runs with network output.
+@item global_sidx @var{bool}
+Write global @code{SIDX} atom. Applicable only for single file, mp4
+output, non-streaming mode.
+
+@item hls_master_name @var{file_name}
+HLS master playlist name. Default is @file{master.m3u8}.
+
+@item hls_playlist @var{bool}
+Generate HLS playlist files. The master playlist is generated with
+filename specified by the @option{hls_master_name} option. One media
+playlist file is generated for each stream with filenames
+@file{media_0.m3u8}, @file{media_1.m3u8}, etc.
+
+@item http_opts @var{http_opts}
+Specify a list of @code{:}-separated key=value options to pass to the
+underlying HTTP protocol. Applicable only for HTTP output.
+
+@item http_persistent @var{bool}
+Use persistent HTTP connections. Applicable only for HTTP output.
+
+@item http_user_agent @var{user_agent}
+Override User-Agent field in HTTP header. Applicable only for HTTP
+output.
+
+@item ignore_io_errors @var{bool}
+Ignore IO errors during open and write. Useful for long-duration runs
+with network output. This is disabled by default.
+
+@item index_correction @var{bool}
+Enable or disable segment index correction logic. Applicable only when
+@option{use_template} is enabled and @option{use_timeline} is
+disabled. This is disabled by default.
+
+When enabled, the logic monitors the flow of segment indexes. If a
+streams's segment index value is not at the expected real time
+position, then the logic corrects that index value.
+
+Typically this logic is needed in live streaming use cases. The
+network bandwidth fluctuations are common during long run
+streaming. Each fluctuation can cause the segment indexes fall behind
+the expected real time position.
 
-@item lhls @var{lhls}
-Enable Low-latency HLS(LHLS). Adds #EXT-X-PREFETCH tag with current segment's URI.
-hls.js player folks are trying to standardize an open LHLS spec. The draft spec is available in https://github.com/video-dev/hlsjs-rfcs/blob/lhls-spec/proposals/0001-lhls.md
-This option tries to comply with the above open spec.
-It enables @var{streaming} and @var{hls_playlist} options automatically.
+@item init_seg_name @var{init_name}
+DASH-templated name to use for the initialization segment. Default is
+@code{init-stream$RepresentationID$.$ext$}. @code{$ext$} is replaced
+with the file name extension specific for the segment format.
+
+@item ldash @var{bool}
+Enable Low-latency Dash by constraining the presence and values of
+some elements. This is disabled by default.
+
+@item lhls @var{bool}
+Enable Low-latency HLS (LHLS). Add @code{#EXT-X-PREFETCH} tag with
+current segment's URI. hls.js player folks are trying to standardize
+an open LHLS spec. The draft spec is available at
+@url{https://github.com/video-dev/hlsjs-rfcs/blob/lhls-spec/proposals/0001-lhls.md}.
+
+This option tries to comply with the above open spec. It enables
+@option{streaming} and @option{hls_playlist} options automatically.
 This is an experimental feature.
 
-Note: This is not Apple's version LHLS. See @url{https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis}
+Note: This is not Apple's version LHLS. See
+@url{https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis}
 
-@item ldash @var{ldash}
-Enable Low-latency Dash by constraining the presence and values of some elements.
+@item master_m3u8_publish_rate @var{segment_intervals_count}
+Publish master playlist repeatedly every after specified number of
+segment intervals.
 
-@item master_m3u8_publish_rate @var{master_m3u8_publish_rate}
-Publish master playlist repeatedly every after specified number of segment intervals.
+@item max_playback_rate @var{rate}
+Set the maximum playback rate indicated as appropriate for the
+purposes of automatically adjusting playback latency and buffer
+occupancy during normal playback by clients.
 
-@item write_prft @var{write_prft}
-Write Producer Reference Time elements on supported streams. This also enables writing
-prft boxes in the underlying muxer. Applicable only when the @var{utc_url} option is enabled.
-It's set to auto by default, in which case the muxer will attempt to enable it only in modes
-that require it.
+@item media_seg_name @var{segment_name}
+DASH-templated name to use for the media segments. Default is
+@code{chunk-stream$RepresentationID$-$Number%05d$.$ext$}. @code{$ext$}
+is replaced with the file name extension specific for the segment
+format.
 
-@item mpd_profile @var{mpd_profile}
-Set one or more manifest profiles.
+@item method @var{method}
+Use the given HTTP method to create output files. Generally set to @code{PUT}
+or @code{POST}.
 
-@item http_opts @var{http_opts}
-A :-separated list of key=value options to pass to the underlying HTTP
-protocol. Applicable only for HTTP output.
+@item min_playback_rate @var{rate}
+Set the minimum playback rate indicated as appropriate for the
+purposes of automatically adjusting playback latency and buffer
+occupancy during normal playback by clients.
+
+@item mpd_profile @var{flags}
+Set one or more MPD manifest profiles.
+
+Possible values:
+@table @samp
+@item dash
+MPEG-DASH ISO Base media file format live profile
+@item dvb_dash
+DVB-DASH profile
+@end table
+
+Default value is @code{dash}.
+
+@item remove_at_exit @var{bool}
+Enable or disable removal of all segments when finished. This is
+disabled by default.
+
+@item seg_duration @var{duration}
+Set the segment length in seconds (fractional value can be set). The
+value is treated as average segment duration when the
+@option{use_template} option is enabled and the @option{use_timeline}
+option is disabled and as minimum segment duration for all the other
+use cases.
+
+Default value is @code{5}.
+
+@item single_file @var{bool}
+Enable or disable storing all segments in one file, accessed using
+byte ranges. This is disabled by default.
+
+The name of the single file can be specified with the
+@option{single_file_name} option, if not specified assume the basename
+of the manifest file with the output format extension.
+
+@item single_file_name @var{file_name}
+DASH-templated name to use for the manifest @code{baseURL}
+element. Imply that the @option{single_file} option is set to
+@var{true}. In the template, @code{$ext$} is replaced with the file
+name extension specific for the segment format.
+
+@item streaming @var{bool}
+Enable or disable chunk streaming mode of output. In chunk streaming
+mode, each frame will be a @code{moof} fragment which forms a
+chunk. This is disabled by default.
 
 @item target_latency @var{target_latency}
-Set an intended target latency in seconds (fractional value can be set) for serving. Applicable only when @var{streaming} and @var{write_prft} options are enabled.
-This is an informative fields clients can use to measure the latency of the service.
+Set an intended target latency in seconds for serving (fractional
+value can be set). Applicable only when the @option{streaming} and
+@option{write_prft} options are enabled. This is an informative fields
+clients can use to measure the latency of the service.
 
-@item min_playback_rate @var{min_playback_rate}
-Set the minimum playback rate indicated as appropriate for the purposes of automatically
-adjusting playback latency and buffer occupancy during normal playback by clients.
+@item timeout @var{timeout}
+Set timeout for socket I/O operations expressed in seconds (fractional
+value can be set). Applicable only for HTTP output.
+
+@item update_period @var{period}
+Set the MPD update period, for dynamic content. The unit is
+second. If set to @code{0}, the period is automatically computed.
+
+Default value is @code{0}.
 
-@item max_playback_rate @var{max_playback_rate}
-Set the maximum playback rate indicated as appropriate for the purposes of automatically
-adjusting playback latency and buffer occupancy during normal playback by clients.
+@item use_template @var{bool}
+Enable or disable use of @code{SegmentTemplate} instead of
+@code{SegmentList} in the manifest. This is enabled by default.
 
-@item update_period @var{update_period}
- Set the mpd update period ,for dynamic content.
- The unit is second.
+@item use_timeline @var{bool}
+Enable or disable use of @code{SegmentTimeline} within the
+@code{SegmentTemplate} manifest section. This is enabled by default.
 
+@item utc_timing_url @var{url}
+URL of the page that will return the UTC timestamp in ISO
+format, for example @code{https://time.akamai.com/?iso}
+
+@item window_size @var{size}
+Set the maximum number of segments kept in the manifest, discard the
+oldest one. This is useful for live streaming.
+
+If the value is @code{0}, all segments are kept in the
+manifest. Default value is @code{0}.
+
+@item write_prft @var{write_prft}
+Write Producer Reference Time elements on supported streams. This also
+enables writing prft boxes in the underlying muxer. Applicable only
+when the @var{utc_url} option is enabled. It is set to @var{auto} by
+default, in which case the muxer will attempt to enable it only in
+modes that require it.
 @end table
 
+@subsection Example
+Generate a DASH output reading from an input source in realtime using
+@command{ffmpeg}.
+
+Two multimedia streams are generated from the input file, both
+containing a video stream encoded through @samp{libx264}, and an audio
+stream encoded with @samp{libfdk_aac}. The first multimedia stream
+contains video with a bitrate of 800k and audio at the default rate,
+the second with video scaled to 320x170 pixels at 300k and audio
+resampled at 22005 Hz.
+
+The @option{window_size} option keeps only the latest 5 segments with
+the default duration of 5 seconds.
+
+@example
+ffmpeg -re -i <input> -map 0 -map 0 -c:a libfdk_aac -c:v libx264 \
+-b:v:0 800k -profile:v:0 main \
+-b:v:1 300k -s:v:1 320x170 -profile:v:1 baseline -ar:a:1 22050 \
+-bf 1 -keyint_min 120 -g 120 -sc_threshold 0 -b_strategy 0 \
+-use_timeline 1 -use_template 1 -window_size 5 \
+-adaptation_sets "id=0,streams=v id=1,streams=a" \
+-f dash /path/to/out.mpd
+@end example
+
 @anchor{fifo}
 @section fifo