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

Arpi arpi at thot.banki.hu
Fri Jan 3 13:43:50 CET 2003


Hi,

will this be ever commited? docs maintainers?

> Hi,
> 
> Attached is a patch documenting the audio filters.
> 
> 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/.
> 
> //Anders
> 
> -- 
> ______________________________________________________________________
> Anders Johansson   Room G09B      WATRI University of          .-_|\
> Visiting  Research Associate      Western Australia           /     \
> telephone:   +61 8 9380 8125      39 Stirling Highway         P_.-._/
> e-mail: ajh at watri.uwa.edu.au      Crawley WA 6009                  o
> ______________________________________________________________________
> 
> 
> 
> 
> 
> --- ../main.dev/DOCS/sound.html	Sat Dec 28 22:04:48 2002
> +++ DOCS/sound.html	Thu Jan  2 11:39:40 2003
> @@ -149,6 +149,314 @@
>  <P>Feedback to this document is welcome. Please tell us how MPlayer
>    and your sound card(s) worked together.</P>
>  
> +<H4><A NAME="af">2.3.2.3 Audio filters</A></H4>
> +<P>The old audio plugins have been superseded by a new audio filter
> +  layer. Audio filters are used for changing the properties of the
> +  audio data before the sound reaches the sound card. The activation
> +  and deactivation of the filters is normally automated but can be
> +  overridden. The filters are activated when the the properties of the
> +  audio data differs from those required by the sound card, and
> +  deactivated if unnecessary. The <CODE>-af filter1,filter2,...</CODE>
> +  switch is used to override the automatic activation of filters or to
> +  insert filters that aren't automatically inserted. The filters will
> +  be executed as they appear in the comma separated list.</P>
> +
> +<P> Example:<BR> &nbsp;&nbsp;<CODE>mplayer-af resample,pan media.avi
> </CODE></P>
> +
> +<P>would run the sound through the resampling filter followed by the
> +  pan filter. Observe that the list mustn't contain any spaces, or it
> +  will fail.</P>
> +
> +<P>The filters often have switches that change their behavior. These
> +  switches are explained in detail in the sections below. A filter
> +  will execute using default settings if its switches are omitted.
> +  Here is an example of how to use filters in combination with filter
> +  specific switches:</P>
> +
> +<P>&nbsp;&nbsp;<CODE>mplayer -af resample=11025,pan=1:0.5:0.5
> +  -channels 1 -srate 11025 media.avi</CODE></P>
> +
> +<P>would set the output frequency of the resample filter to 11025z
> +  and down mix the audio to 1 channel using the pan filter.</P>
> +
> +<P>Most filters respond to the <CODE>-v </CODE> switch and it makes
> +  the filters print out status messages when given.</P>
> +
> +<P>The overall execution of the filter layer is controlled using the
> +  <CODE>-af-adv</CODE> switch. This swithc has two sub options:</P>
> +
> +<UL>
> +  <LI><CODE>force</CODE> is an integer between 0 and 3 that controls
> +    how the filters are inserted and what speed/accuracy optimizations
> +    they use:
> +    <TABLE BORDER=0 WIDTH="100%">
> +    <TR><TD>Optimization</TD><TD>Description</TD></TR>
> +    <TR><TD>0</TD><TD>Use automatic insertion of filters and optimize
> +    according to CPU speed. </TD></TR> 
> +    <TR><TD>1</TD><TD>Use automatic insertion of filters and optimize
> +    for the highest speed. If this option is set the processing of the
> +    audio data will be done using fix point aritmetics. Warning some
> +    features in the audio filters will silently fail, and the sound
> +    quality may drop. </TD></TR>
> +    <TR><TD>2</TD><TD>Use automatic insertion of filters and optimize
> +    for quality. If this option is set the processing of the
> +    audio data will be done using floating point instructions and is
> +    therfore quite CPU intensive, but gives a lot higher sound quality
> +    than fix point processing. </TD></TR>
> +    <TR><TD>0</TD><TD>Use no automatic insertion of filters and no
> +    optimization. Warning it may be possibe to crash mplayer using
> +    this setting. </TD></TR>
> +    </TABLE>
> +    </LI>
> +  <LI><CODE>list</CODE> is an alias for the -af switch.</LI>
> +</UL>
> +
> +
> +
> +<H5><A NAME="af_resample">2.3.2.3.1 Up/Down-sampling</A></H5>
> +
> +<P>MPlayer fully supports up/down-sampling of the sound. This filter
> +  can be used if you have a fixed frequency sound card or if you are
> +  stuck with an old sound card that is only capable of max 44.1kHz.
> +  This filter is automatically enabled if it is necessary, but it also
> +  be explicitly enabled on the command line. This filter has three
> +  switches:</P>
> +
> +<UL>
> +  <LI><CODE>srate</CODE> is an integer used for setting the output
> +    sample frequency in Hz. The valid range for this parameter is 8kHz
> +    to 192kHz. If the input and output sample frequency are the same
> +    or if this parameter is omitted the filter is automatically
> +    unloaded. A high sample frequency normally improves the audio
> +    quality, especially when used in combination with other
> +    filters. </LI>
> +  <LI><CODE>sloppy</CODE> is binary and optional and allows the output
> +    frequency differ slightly from the frequency given by
> +    <CODE>srate</CODE>. This switch can be used if the startup of the
> +    playback is extremely slow.</LI>
> +  <LI><CODE>fast</CODE> is binary and optional and enables linear
> +    interpolation as resampling method. Linear interpolation is
> +    extremely fast, but suffers from poor sound quality especially
> +    when used for up-sampling.</LI>
> +</UL>
> +
> +<P>Example:<BR>
> +  &nbsp;&nbsp;<CODE>mplayer -af resample=44100:0:1</CODE></P>
> +
> +<P>would set the output frequency of the resample filter to 44100Hz
> +  using exact output frequency scaling and linear interpolation.</P>
> +
> +<H5><A NAME="af_channels">2.3.2.3.2 Changing the number of channels</A></H5>
> +
> +<P>The <CODE>channels</CODE> filter can be used for adding and
> +  removing channels, it can also be used for routing or copying
> +  channels. It is automatically enabled when the output from
> +  the audio filter layer differs from the input layer or when it is
> +  requested by another filter. This filter unloads itself if it isn't
> +  needed. The number of switches is dynamic: </P>
> +
> +<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>
> +
> +<P> If only <CODE>nch</CODE> is given the default routing is used, it
> +  works as follows: If the number of output channels is bigger than
> +  the number of input channels empty channels are inserted (except
> +  mixing from mono to stereo, then the mono channel is repeated in
> +  both of the output channels). If the number of output channels is
> +  smaller than the number of input channels the exceeding channels are
> +  truncated.</P>
> +
> +<P>Example 1:<BR>
> +  &nbsp;&nbsp;<CODE>mplayer -af channels=4:4:0:1:1:0:2:2:3:3 media.avi
> </CODE></P>
> +
> +<P>would change the number of channels to 4 and set up 4 routes that
> +  swaps channel 0 and channel 1 and leaves channel 2 and 3
> +  intact. Observe that if media containing two channels was played
> +  back channels 2 and 3 would contain silence but 0 and 1 would still
> +  be swapped.</P>
> +
> +<P>Example 2:<BR>
> +  &nbsp;&nbsp;<CODE>mplayer -af channels=6:4:0:0:0:1:0:2:0:3 media.avi
> </CODE></P>
> +
> +<P>would change the number of channels to 6 and set up 4 routes that
> +  copies channel 0 to channels 0 to 3. Channel 4 and 5 will contain
> +  silence.</P>
> +
> +<H5><A NAME="af_format">2.3.2.3.3 Sample format converter</A></H5>
> +                                                                         
> +<P>This filter is a sample format converter. It is automatically
> +  enabled when needed by the sound card or the by another filter. 
> +</P>
> +  
> +<UL>
> +  <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>
> +  <LI><CODE>f</CODE> is a text string describing the sample
> +    format. The string is a concatenated mix of: alaw, mulaw or
> +    imaadpcm float or int unsigned or signed le or be (little or big
> +    endian). This switch is required, leaving it empty results in a
> +    runtime error.</LI> 
> +</UL>
> +
> +<P>Example:<BR>
> +  &nbsp;&nbsp;<CODE>mplayer media.avi -af format=4:float</CODE></P>
> +
> +<P>would set the output output format to 4 bytes per sample floating
> +  point data.</P>
> +
> +<H5><A NAME="af_delay">2.3.2.3.4 Delay</A></H5>
> +
> +<P>This filter delays the sound to the loudspeakers differently in
> +  order to make the sound in the different channels arrive at the same
> +  time to the listening position. This filter is only useful if you
> +  have more than 2 loudspeakers. This filter has a variable number of
> +  parameters:</P>
> +
> +<UL>
> +  <LI><CODE>d1:d2:d3...</CODE> are floating point numbers representing
> +  the delays in ms that should be imposed on the different
> +  channels. The minimum delay is 0ms and the maximum is 1000ms. </LI>
> +</UL>
> +
> +  <P>To calculate the required delay for the different channels do as
> +  follows:</P>
> +<OL>
> +  <LI> Measure the distance to the loudspeakers in meters in relation to
> +     your listening position, giving you the distances s1 to s5 (for a
> +     5.1 system). There is no point compensating for the sub-woofer (you
> +     won't hear the difference anyway). </LI>
> +  <LI>Subtract the distances s1 to s5 from the maximum distance
> +     i.e. <BR>
> +     s[i] = max(s) - s[i]; i = 1...5</LI>
> +  <LI>Calculated the required delays in ms as <BR>
> +     d[i] = 1000*s[i]/342; i = 1...5 </LI>
> +</OL>
> +
> +<P>Example:<BR>
> +  &nbsp;&nbsp;<CODE>mplayer -af delay=10.5:10.5:0:0:7:0 media.avi</CODE></P>
> +
> +<P>would delay front left and right by 10.5ms, the two rear channels
> +  and the sub by 0ms and the center channel by 7ms.</P>
> +
> +<H5><A NAME="af_volume">2.3.2.3.5 Software volume control</A></H5>
> +
> +<P>This filter is a software volume control. Use this filter with
> +  caution since it can reduce the signal to noise ratio of the
> +  sound. In most cases it is best to set the level for the PCM sound
> +  to max, leave this filter out and control the output level to your
> +  speakers with the master volume control of the mixer. If there is an
> +  external amplifier connected to the computer (this is almost always
> +  the case), the noise level can be minimized by adjusting the master
> +  level and the volume knob on the amplifier until the hissing noise
> +  in the background is gone. This filter has two switches:</P>
> +
> +<UL>
> +  <LI><CODE>v</CODE> is a floating point number between -200 and +60
> +    who represents the volume level in dB. The default level is -10
> +    dB. </LI> 
> +  <LI><CODE>c</CODE> is a binary control that turns on and off soft
> +    clipping. Soft-clipping can make the sound more smooth if very high
> +    volume levels are used. Enable this switch if the dynamic range of
> +    the loudspeakers is very low. Be aware that this feature creates
> +    distortion and should be considered a last resort.</LI> 
> +</UL>
> +  
> +<P>Example:<BR>
> +  &nbsp;&nbsp;<CODE>mplayer -af volume=10.1:0 media.avi</CODE></P>
> +
> +<P>would amplify the sound by 10.1dB and hard-clip if the sound level is
> +  too high.</P>
> +
> +<P>This filter has a second feature: it measures the over all maximum
> +  sound level and prints out that level when mplayer exits. This
> +  volume estimate can be used for setting the sound level in mencoder
> +  such that the maximum dynamic range is utilized.</P>
> +
> +<H5><A NAME="af_equalizer">2.3.2.3.6 Equalizer</A></H5>
> +
> +<P> This filter is a 10 octave band graphic equalizer, implemented
> +  using 10 IIR band pass filters. This means that it works regardless
> +  of what type of audio being played back. The center frequencies for
> +  the 10 bands are:</P>
> +
> +<TABLE BORDER=0 WIDTH="100%">
> +  <TR><TD>Band nr.</TD><TD>Center frequency</TD></TR>
> +  <TR><TD>0</TD><TD>31.25 Hz</TD></TR>
> +  <TR><TD>1</TD><TD>62.50 Hz</TD></TR>
> +  <TR><TD>2</TD><TD>125.0 Hz</TD></TR>
> +  <TR><TD>3</TD><TD>250.0 Hz</TD></TR>
> +  <TR><TD>4</TD><TD>500.0 Hz</TD></TR>
> +  <TR><TD>5</TD><TD>1.000 kHz</TD></TR>
> +  <TR><TD>6</TD><TD>2.000 kHz</TD></TR>
> +  <TR><TD>7</TD><TD>4.000 kHz</TD></TR>
> +  <TR><TD>8</TD><TD>8.000 kHz</TD></TR>
> +  <TR><TD>9</TD><TD>16.00 kHz</TD></TR>
> +</TABLE>
> +
> +<P> If the sample rate of the sound being played back is lower than
> +  the center frequency for a frequency band, then that band will be
> +  disabled. A known bug with this filter is that the characteristics
> +  for the upper most band isn't completely symmetric if the sample rate
> +  is close too the center frequency of that band. This problem can be
> +  worked around by up-sampling the sound using the resample filter
> +  before it reaches this filter. </P>
> +
> +<P> This filter has 10 parameters:</P>
> +<UL>
> +  <LI><CODE>g1:g2:g3...g10</CODE> are floating point numbers between
> +    -12 to +12 dB representing the gain in dB for each frequency
> +    band.
> +  </LI>
> +</UL>
> +
> +<P>Example:<BR>
> +  &nbsp;&nbsp;<CODE>mplayer -af equalizer=11:11:10:5:0:-12:0:5:12:12
> media.avi</CODE></P>
> +
> +<P>would amplify the sound in the upper and lower frequency region
> +  while canceling it almost completely around 1kHz.</P>
> +
> +<H5><A NAME="af_equalizer">2.3.2.3.7 Panning filter </A></H5>
> +
> +<P> This filter can be used for mixing the channels arbitrarily. It is
> +  basically a combination of the volume control and the channels
> +  filter. There are two major uses for this filter: </P> 
> +
> +<OL>
> +  <LI> Down-mixing many channels to only a few, stereo to mono for
> +    example. </LI> 
> +  <LI> Varying the "width" of the center speaker in a surround sound
> +    system. </LI>
> +</OL>
> +
> +<P> This filter is hard to use, and will require some tinkering before
> +  the desired result is obtained. The number of switches for this
> +  filter depends on the number of output channels:</P>
> +
> +<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>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>
> +</UL>
> +
> +<P>Example:<BR>
> +  &nbsp;&nbsp;<CODE>mplayer -af pan=1:0.5:0.5 -channels 1 media.avi</CODE></P>
> + 
> +<P>would down-mix from stereo to mono.</P>
> +
>  
>  <H4><A NAME="plugins">2.3.2.3 Audio plugins</A></H4>
>  
> 
> 
> _______________________________________________
> MPlayer-dev-eng mailing list
> MPlayer-dev-eng at mplayerhq.hu
> http://mplayerhq.hu/mailman/listinfo/mplayer-dev-eng
> 
> 


A'rpi / Astral & ESP-team

--
Developer of MPlayer, the Movie Player for Linux - http://www.MPlayerHQ.hu


More information about the MPlayer-dev-eng mailing list