Index: ChangeLog
===================================================================
RCS file: /cvsroot/mplayer/main/ChangeLog,v
retrieving revision 1.246
diff -u -r1.246 ChangeLog
--- ChangeLog	13 Sep 2005 21:04:44 -0000	1.246
+++ ChangeLog	15 Sep 2005 02:54:42 -0000
@@ -69,6 +69,7 @@
     * remove_logo filter
     * lavcresample now used by default (-af-adv force=0 gives old behavior)
     * vf_expand and vf_dsize now support aspect and round parameters
+    * af_pan can mix channels in proportions between -512 and 512
     * screenshot filter
 
     MEncoder:
Index: DOCS/man/en/mplayer.1
===================================================================
RCS file: /cvsroot/mplayer/main/DOCS/man/en/mplayer.1,v
retrieving revision 1.1101
diff -u -r1.1101 mplayer.1
--- DOCS/man/en/mplayer.1	14 Sep 2005 22:08:03 -0000	1.1101
+++ DOCS/man/en/mplayer.1	15 Sep 2005 02:54:44 -0000
@@ -3988,7 +3988,19 @@
 .IPs <n>\ \ 
 number of input channels (1\-6)
 .IPs <lij>
-How much of input channel j is mixed into output channel i (0\-1).
+The multiple of input channel j that is to be mixed into output channel
+i (-512 \- 512, including decimals).
+Negative multiples will invert the phase of a channel before mixing and
+can be used to "subtract" one channel from another.
+Be aware that when mixing channels you can can end up with an output
+signal that contains values outside of the range your sound card
+accepts.
+This is particularly likely to happen when mixing with multiples greater
+than 1 or smaller than -1, which can be quite loud.
+If you hear any painful-sounding pops or clicks, either use multiples
+closer to 0 or follow pan with ",volume" so the volume filter will clip
+out-of-range values.
+Clipping damages sound quality so use it sparingly.
 .RE
 .sp 1
 .RS
Index: DOCS/xml/en/usage.xml
===================================================================
RCS file: /cvsroot/mplayer/main/DOCS/xml/en/usage.xml,v
retrieving revision 1.32
diff -u -r1.32 usage.xml
--- DOCS/xml/en/usage.xml	14 Sep 2005 21:15:38 -0000	1.32
+++ DOCS/xml/en/usage.xml	15 Sep 2005 02:54:44 -0000
@@ -988,11 +988,75 @@
 
 </para>
 
+<bridgehead>Example: Playing the difference between two channels</bridgehead>
+
+<para>
+If you want to hear how different two channels are, you can subtract the
+first from the second. The result will be mono sound that has only the
+differences. Audio that is exactly the same in each source channel will
+be silent; audio that is only in one channel will be just as loud; audio
+that is partly in one channel will be reduced in volume.
+
+<orderedlist>
+<listitem><para>
+For this example, we only need to work with two channels, so it is not
+necessary to specifiy <option>-channels</option>.
+<option>pan</option> will only be outputting a single channel, however,
+so <option>,channels=1</option> should be appended afterward.
+</para></listitem>
+<listitem><para>
+<option>pan</option> will use both channels, so the first suboption will
+be "2".
+</para></listitem>
+<listitem><para>
+For the single output channel, the right channel should be subtracted
+from the left, giving suboptions "1:-1". Actually, it does not matter
+which input channel is subtracted from the other. Reversing the order
+will invert the phase, but since <option>pan</option> is only outputting
+one channel it will not be able to interfere with another channel.
+</para></listitem>
+</orderedlist>
+
+Combining the suboptions yields:
+<screen>mplayer stereo.file -af pan=2:1:-1,channels=1</screen>
+You may hear more audio than you expected, particularly music. Often
+stereo music that sounds the same in both channels actually has some
+components out of phase. This gives more depth to the sound and results
+in each channel seeming almost the same but actually being quite
+different. In fact, if one channel is exactly out of phase with the
+other, then subtracting them will actually double the volume.
+</para>
+
 </sect3>
 
 </sect2>
 
 
+<sect2 id="advaudio-phase">
+<title>Phase inversion</title>
+<para>
+For a clear explanation of audio phase, read
+<ulink url="http://www.gcaudio.com/resources/howtos/absolutephase.html">this document</ulink>.
+<application>MPlayer</application>'s <option>pan</option> filter will
+invert the phase of one or more channels when directed to use a negative
+amount of a source channel. See the
+<link linkend="advaudio-channels-mixing">channel mixing</link> section
+for a more thorough explanation of <option>pan</option>.
+</para>
+
+<bridgehead>Example: invert phase of a stereo signal</bridgehead>
+<para>
+<screen>mplayer <replaceable>stereo.file</replaceable> -af pan=2:-1:0:0:-1</screen>
+</para>
+
+<bridgehead>Example: invert phase of only the left channel</bridgehead>
+<para>
+<screen>mplayer <replaceable>stereo.file</replaceable> -af pan=2:-1:0:0:1</screen>
+</para>
+
+</sect2>
+
+
 <sect2 id="advaudio-volume">
 <title>Software Volume adjustment</title>
 
Index: libaf/af_pan.c
===================================================================
RCS file: /cvsroot/mplayer/main/libaf/af_pan.c,v
retrieving revision 1.6
diff -u -r1.6 af_pan.c
--- libaf/af_pan.c	8 Jan 2005 21:34:06 -0000	1.6
+++ libaf/af_pan.c	15 Sep 2005 02:54:44 -0000
@@ -20,6 +20,8 @@
 
 #include "af.h"
 
+#define MAX_LVL 512
+
 // Data for specific instances of this filter
 typedef struct af_pan_s
 {
@@ -65,7 +67,7 @@
     j = 0; k = 0;
     while((*cp == ':') && (k < AF_NCH)){
       sscanf(cp, ":%f%n" , &s->level[k][j], &n);
-      s->level[k][j] = clamp(s->level[k][j],0.0,1.0);
+      s->level[k][j] = clamp(s->level[k][j],-MAX_LVL,MAX_LVL);
       af_msg(AF_MSG_VERBOSE,"[pan] Pan level from channel %i to" 
 	     " channel %i = %f\n",j,k,s->level[k][j]);
       cp =&cp[n];
@@ -82,7 +84,7 @@
     int    ch = ((af_control_ext_t*)arg)->ch;
     float* level = ((af_control_ext_t*)arg)->arg;
     for(i=0;i<AF_NCH;i++)
-      s->level[ch][i] = clamp(level[i],0.0,1.0);
+      s->level[ch][i] = clamp(level[i],-MAX_LVL,MAX_LVL);
     return AF_OK;
   }
   case AF_CONTROL_PAN_LEVEL | AF_CONTROL_GET:{