[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> <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> <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>
> + <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>
> + <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>
> + <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>
> + <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>
> + <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>
> + <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>
> + <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>
> + <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