[FFmpeg-devel] [PATCH] doc/utils: document channel layout specification

[Stefano Sabatini]

---
 doc/utils.texi | 144 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 144 insertions(+)

diff --git a/doc/utils.texi b/doc/utils.texi
index 16101f0..6dca9b7 100644
--- a/doc/utils.texi
+++ b/doc/utils.texi
@@ -579,6 +579,150 @@ The following names of colors are recognized:
 0x9ACD32
 @end table
 
+ at anchor{channel layout syntax}
+ at section Channel Layout
+
+Individual channels are identified by an id, as given by the table
+below:
+ at table @samp
+ at item FL
+front left
+ at item FR
+front right
+ at item FC
+front center
+ at item LFE
+low frequency
+ at item BL
+back left
+ at item BR
+back right
+ at item FLC
+front left-of-center
+ at item FRC
+front right-of-center
+ at item BC
+back center
+ at item SL
+side left
+ at item SR
+side right
+ at item TC
+top center
+ at item TFL
+top front left
+ at item TFC
+top front center
+ at item TFR
+top front right
+ at item TBL
+top back left
+ at item TBC
+top back center
+ at item TBR
+top back right
+ at item DL
+downmix left
+ at item DR
+downmix right
+ at item WL
+wide left
+ at item WR
+wide right
+ at item SDL
+surround direct left
+ at item SDR
+surround direct right
+ at item LFE2
+low frequency 2
+ at end table
+
+Standard channel layout compositions can be specified by using the
+following identifiers:
+ at table @samp
+ at item mono
+FC
+ at item stereo
+FL+FR
+ at item 2.1
+FL+FR+LFE
+ at item 3.0
+FL+FR+FC
+ at item 3.0(back)
+FL+FR+BC
+ at item 4.0
+FL+FR+FC+BC
+ at item quad
+FL+FR+BL+BR
+ at item quad(side)
+FL+FR+SL+SR
+ at item 3.1
+FL+FR+FC+LFE
+ at item 5.0
+FL+FR+FC+BL+BR
+ at item 5.0(side)
+FL+FR+FC+SL+SR
+ at item 4.1
+FL+FR+FC+LFE+BC
+ at item 5.1
+FL+FR+FC+LFE+BL+BR
+ at item 5.1(side)
+FL+FR+FC+LFE+SL+SR
+ at item 6.0
+FL+FR+FC+BC+SL+SR
+ at item 6.0(front)
+FL+FR+FLC+FRC+SL+SR
+ at item hexagonal
+FL+FR+FC+BL+BR+BC
+ at item 6.1
+FL+FR+FC+LFE+BC+SL+SR
+ at item 6.1
+FL+FR+FC+LFE+BL+BR+BC
+ at item 6.1(front)
+FL+FR+LFE+FLC+FRC+SL+SR
+ at item 7.0
+FL+FR+FC+BL+BR+SL+SR
+ at item 7.0(front)
+FL+FR+FC+FLC+FRC+SL+SR
+ at item 7.1
+FL+FR+FC+LFE+BL+BR+SL+SR
+ at item 7.1(wide)
+FL+FR+FC+LFE+BL+BR+FLC+FRC
+ at item 7.1(wide-side)
+FL+FR+FC+LFE+FLC+FRC+SL+SR
+ at item octagonal
+FL+FR+FC+BL+BR+BC+SL+SR
+ at item downmix
+DL+DR
+ at end table
+
+A custom channel layout can be specified as a sequence of terms, separated by
+'+' or '|'. Each term can be:
+ at itemize
+ at item
+the name of a standard channel layout (e.g. @samp{mono},
+ at samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.)
+
+ at item
+the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.)
+
+ at item
+a number of channels, in decimal, optionally followed by 'c', yielding
+the default channel layout for that number of channels (see the
+function @code{av_get_default_channel_layout})
+
+ at item
+a channel layout mask, in hexadecimal starting with "0x" (see the
+ at code{AV_CH_*} macros in @file{libavutil/channel_layout.h}.
+ at end itemize
+
+Starting from the next major bump the trailing character 'c' to
+specify a number of channels will be required, while a channel layout
+mask could also be specified as a decimal number (if and only if not
+followed by "c").
+
+See also the function @code{av_get_channel_layout} defined in
+ at file{libavutil/channel_layout.h}.
 @c man end SYNTAX
 
 @chapter Expression Evaluation
-- 
1.8.1.2