[MPlayer-dev-eng] [PATCH] Audio filter docs for sound.html

[Diego Biurrun]

Anders Johansson writes:
 > Attached is a patch documenting the audio filters.

Very nice, thanks a million.

 > BTW: The docs are a bit harder to read nowadays. I don't think it was
 > a good idea to put all docs in the man page, they are not detailed
 > enough (due to the space limitation), also it is hard to find a
 > specific switch unless one knows exactly what to look for. Wouldn't it
 > be better to use some other more advanced documentation tool, that can
 > produce may different types of documents like for example
 > http://docbook.sourceforge.net/.

Docbook would be really cool, but none of us is a docbook wizard
(yet).  Expect something like this for 1.0.  You are right that
something of higher level than the man page would be desirable, but at
the moment it is more a choice between having the man page or no
documentation at all.

Some comments on your patch follow.  BTW, you had some trailing
whitespace in your patch, please try to avoid this.

 > +<UL>
 > +  <LI><CODE>nch</CODE> is and integer between 1 and 6 and is used for
 > +   setting the number of output channels. This switch is required,
 > +   leaving it empty results in a runtime error. </LI>
 > +  <LI><CODE>nr</CODE> is an integer between 1 and 6 and is used for
 > +    specifying the number of routes. This parameter is optional. If it
 > +    is omitted the default routing is used.</LI>
 > +  <LI><CODE>from1:to1:from2:to2:from3:to3...</CODE> are pairs of
 > +   numbers between 0 and 5 that defies which channels should be routed
 > +   where. </LI>
 > +</UL>

I used definition lists instead of unordered lists, I think it's more
readable and closer to semantic markup.

 > +  <LI><CODE>bps</CODE> is and integer 1, 2 or 4 and denotes the number
 > +    of bytes per sample. This switch is required, leaving it empty
 > +    results in a runtime error. </LI>

I take this that bps can be 1,2 or 4, right?

 > +  <LI><CODE>l00:l01:l02:..l10:l11:l12:...ln0:ln1:ln2:...</CODE> are
 > +    floating point values between 0 and 1 that determines the level
 > +    <CODE>l[i][j]</CODE> that the input channel j is mixed into output 
 > +    channel i.</LI>

I tried hard to understand this, but I could not..  Could you try to
explain this again?  Here it is again in a more readable form:

l00:l01:l02:..l10:l11:l12:...ln0:ln1:ln2:...
    are floating point values between 0 and 1 that determine the level
    l[i][j] that the input channel j is mixed into output channel i.

Example:
  mplayer -af pan=1:0.5:0.5 -channels 1 media.avi

Now that I have pondered it a bit, I think I know what you meant.  I
hope my version is a little bit clearer:

l00:l01:l02:..l10:l11:l12:...ln0:ln1:ln2:...
    are floating point values between 0 and 1. l[i][j] determines how
    much of input channel j is mixed into output channel i.

Diego