[MPlayer-dev-eng] [DOCS] Documentation update for ac3 analogue surround stuff

[Stephen Davies]

Hi Gabucino,

Here's some documentation updates to describe the new multi-channel sound
output stuff.

Steve

-------------- next part --------------
? fibmap_mplayer
? libao2/pl_surround.c
Index: DOCS/codecs.html
===================================================================
RCS file: /cvsroot/mplayer/main/DOCS/codecs.html,v
retrieving revision 1.36
diff -u -r1.36 codecs.html
--- DOCS/codecs.html	28 Nov 2001 06:35:21 -0000	1.36
+++ DOCS/codecs.html	1 Dec 2001 10:30:03 -0000
@@ -207,7 +207,40 @@
 </UL></P>
 
 
-<P><B><A NAME=2.2.2.1>2.2.2.1.  Hardware AC3 decoding</A></B></P>
+<P><B><A NAME=2.2.2.1>2.2.2.1.  Software AC3 decoding</A></B></P>
+
+<P>This is the default decoder used for files with AC3 audio.</P>
+
+<P>The AC3 decoder can create output audio mixes for 2, 4, or 6
+speakers.  When configured for 6 speakers, this decoder provides
+separate output of all the AC3 channels to the soundcard driver,
+allowing the full "surround sound" experience without the external AC3
+decoder required to use the hwac3 codec. </P>
+
+<P>Use the "-channels" option to select the number of output channels.
+Use "-channels 2" for a stereo downmix.  For a 4 channel downmix (Left
+Front, Right Front, Left Surround and Right Surround outputs), use
+"-channels 4".  In this case, any Centre channel will be mixed equally
+to the front channels.  Lastly, "-channels 6" will output all the AC3
+channels as they are encoded - in the order Left, Right, Left
+Surround, Right Surround, Centre and LFE.</p>
+
+<P>This decoder will be selected by default for AC3 audio.  But,
+should you need to force its use, use the '-ac ac3' option.</P>
+
+<P>The default number of output channels is 2.</P>
+
+<P>To use more than 2 output channels, you'll need to be using OSS,
+and to have a soundcard driver that supports the appropriate number of
+output channels via the SNDCTL_DSP_CHANNELS ioctl.  For example, a
+version of the emu10k1 driver (used with the SB Live cards) newer than
+August 2001 should be suitable.</P>
+
+<P>Output mixes of more than 2 channels should be considered
+experimental. </P>
+
+
+<P><B><A NAME=2.2.2.2>2.2.2.2.  Hardware AC3 decoding</A></B></P>
 
 <P>You'll need an AC3 capable soundcard, with digital out (SP/DIF). The
 card's driver must support the AFMT_AC3 format (like SB Live! does).
@@ -215,7 +248,7 @@
 option. It may or may not work (experimental). (probably won't...)</P>
 
 
-<P><B><A NAME=2.2.2.2>2.2.2.2.  libmad support</A></B></P>
+<P><B><A NAME=2.2.2.3>2.2.2.3.  libmad support</A></B></P>
 
 <P><A HREF="http://mad.sourceforge.net">libmad</A> is a multiplatform MPEG audio
 decoding library. If you don't know why is it good, you probably don't need it.</P>
@@ -224,7 +257,7 @@
 option.</P>
 
 
-<P><B><A NAME=2.2.2.3>2.2.2.3.  VIVO audio</A></B></P>
+<P><B><A NAME=2.2.2.4>2.2.2.4.  VIVO audio</A></B></P>
 
 <P>The audio codec used in VIVO files depends on whether it's a VIVO/1.0 or
 VIVO/2.0 file. VIVO/1.0 files have <B>g.723</B> audio, and VIVO/2.0 files
Index: DOCS/documentation.html
===================================================================
RCS file: /cvsroot/mplayer/main/DOCS/documentation.html,v
retrieving revision 1.123
diff -u -r1.123 documentation.html
--- DOCS/documentation.html	1 Dec 2001 09:58:58 -0000	1.123
+++ DOCS/documentation.html	1 Dec 2001 10:30:08 -0000
@@ -55,9 +55,10 @@
       </UL>
       <LI><A HREF="codecs.html#2.2.2">2.2.2 Audio</A></LI>
       <UL>
-	<LI><A HREF="codecs.html#2.2.2.1">2.2.2.1 Hardware AC3 decoding</A></LI>
-	<LI><A HREF="codecs.html#2.2.2.2">2.2.2.2 libmad support</A></LI>
-	<LI><A HREF="codecs.html#2.2.2.3">2.2.2.3 VIVO audio</A></LI>
+	<LI><A HREF="codecs.html#2.2.2.1">2.2.2.1 Software AC3 decoding</A></LI>
+	<LI><A HREF="codecs.html#2.2.2.2">2.2.2.2 Hardware AC3 decoding</A></LI>
+	<LI><A HREF="codecs.html#2.2.2.3">2.2.2.3 libmad support</A></LI>
+	<LI><A HREF="codecs.html#2.2.2.4">2.2.2.4 VIVO audio</A></LI>
       </UL>
       <LI><A HREF="codecs.html#2.2.3">2.2.3 Win32 codec importing howto</A></LI>
       <UL>
Index: DOCS/mplayer.1
===================================================================
RCS file: /cvsroot/mplayer/main/DOCS/mplayer.1,v
retrieving revision 1.108
diff -u -r1.108 mplayer.1
--- DOCS/mplayer.1	30 Nov 2001 17:19:11 -0000	1.108
+++ DOCS/mplayer.1	1 Dec 2001 10:30:10 -0000
@@ -48,6 +48,7 @@
 .RB [ \-nodouble ]
 .RB [ \-double ]
 .RB [ \-stereo\ mode ]
+.RB [ \-channels\ n ]
 .RB [ \-srate\ Hz ]
 .RB [ \-osdlevel\ level ]
 .RB [ \-config\ file ]
@@ -403,7 +404,14 @@
         Stereo         0
         Left channel   1
         Right channel  2
+.TP
+.B \-channels n
+select number of audio output channels to be used
 
+        Stereo         2
+        Surround       4
+        Full 5.1       6
+Currently this option is only honoured for AC3 audio.
 .TP
 .B \-srate Hz
 specifies Hz to playback audio on. Has effect on playback speed!
? libavcodec/.depend
? libavcodec/README