Mercurial > mplayer.hg
changeset 14787:346ace66cdb4
Move audio filter descriptions to the man page.
| author | diego |
|---|---|
| date | Thu, 24 Feb 2005 11:00:45 +0000 |
| parents | e1bf5e07962f |
| children | f125873f1409 |
| files | DOCS/man/en/mplayer.1 DOCS/xml/en/audio.xml |
| diffstat | 2 files changed, 307 insertions(+), 743 deletions(-) [+] |
line wrap: on
line diff
--- a/DOCS/man/en/mplayer.1 Thu Feb 24 02:31:41 2005 +0000 +++ b/DOCS/man/en/mplayer.1 Thu Feb 24 11:00:45 2005 +0000 @@ -3507,15 +3507,57 @@ Available filters are: . .TP -.B resample[=srate[:sloppy][:type]] -Changes the sample rate of the audio stream to an integer srate in Hz. +.B resample[=srate[:sloppy[:type]]] +Changes the sample rate of the audio stream. +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 necessary. It only supports the 16-bit little-endian format. +.br +.I NOTE: With MEncoder, you need to also use \-srate <srate>. +.PD 0 +.RSs +.IPs <srate> +output sample frequency in Hz. +The valid range for this parameter is 8000 to 192000. +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. +.IPs <sloppy> +Allow (1) or disallow (0) the output frequency to differ slightly +from the frequency given by <srate> (default: 1). +Can be used if the startup of the playback is extremely slow. +.IPs <type> +Selects which resampling method to use. +.RSss +0: linear interpolation (fast, poor quality especially when upsampling) +.br +1: polyphase filterbank and integer processing +.br +2: polyphase filterbank and floating point processing (slow, best quality) +.REss +.PD 1 +.RE +.sp 1 +.RS +.I EXAMPLE: +.RE +.PD 0 +.RSs +.IPs "mplayer -af resample=44100:0:0" +would set the output frequency of the resample filter to 44100Hz using +exact output frequency scaling and linear interpolation. +.RE +.PD 1 . .TP .B lavcresample[=srate[:length[:linear[:count[:cutoff]]]]] -Changes the sample rate of the audio stream to an integer srate in Hz. +Changes the sample rate of the audio stream to an integer <srate> in Hz. It only supports the 16-bit little-endian format. +.br +.I NOTE: With MEncoder, you need to also use \-srate <srate>. .PD 0 .RSs @@ -3544,17 +3586,93 @@ 2 channel output for headphones, preserving the spatiality of the sound. . .TP -.B channels[=nch] -Change the number of channels to <nch> output channels. -If the number of output channels is bigger than the number of input channels -empty channels are inserted (except when 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. +.B equalizer=[g1:g2:g3:...:g10] +10 octave band graphic equalizer, implemented using 10 IIR band pass filters. +This means that it works regardless of what type of audio is being played back. +The center frequencies for the 10 bands are: +.sp 1 +.PD 0 +.RS +.IPs "No. frequency" +.IPs "0 31.25 Hz" +.IPs "1 62.50 Hz" +.IPs "2 125.00 Hz" +.IPs "3 250.00 Hz" +.IPs "4 500.00 Hz" +.IPs "5 1.00 kHz" +.IPs "6 2.00 kHz" +.IPs "7 4.00 kHz" +.IPs "8 8.00 kHz" +.IPs "9 16.00 kHz" +.RE +.PD 1 +.sp 1 +.RS +If the sample rate of the sound being played 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 +uppermost band are not completely symmetric if the sample +rate is close to the center frequency of that band. +This problem can be worked around by upsampling the sound +using the resample filter before it reaches this filter. +.RE +.PD 0 +.RSs +.IPs <g1>:<g2>:<g3>:...:<g10> +floating point numbers representing the gain in dB +for each frequency band (-12\-12) +.RE +.sp 1 +.RS +.I EXAMPLE: +.RE +.RSs +.IPs "mplayer \-af equalizer=11:11:10:5:0:-12:0:5:12:12 media.avi" +Would amplify the sound in the upper and lower frequency region +while canceling it almost completely around 1kHz. +.RE +.PD 1 +. +.TP +.B channels=nch[:nr:from1:to1:from2:to2:from3:to3:...] +Can be used for adding, removing, routing and copying audio channels. +If only <nch> 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. +.PD 0 +.RSs +.IPs <nch> +number of output channels (1\-6) +.IPs <nr>\ +number of routes (1\-6) +.IPs <from1:to1:from2:to2:from3:to3:...> +Pairs of numbers between 0 and 5 that define where to route each channel. +.RE +.sp 1 +.RS +.I EXAMPLE: +.RE +.RSs +.IPs "mplayer -af channels=4:4:0:1:1:0:2:2:3:3 media.avi" +Would change the number of channels to 4 and set up 4 routes that +swap channel 0 and channel 1 and leave 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. +.IPs "mplayer -af channels=6:4:0:0:0:1:0:2:0:3 media.avi" +Would change the number of channels to 6 and set up 4 routes +that copy channel 0 to channels 0 to 3. +Channel 4 and 5 will contain silence. +.RE +.PD 1 . .TP .B format[=format] -Change the current sample format. +Convert between different sample formats. +Automatically enabled when needed by the sound card or another filter. .PD 0 .RSs .IPs <format> @@ -3564,72 +3682,207 @@ and 'e' denotes the endianness ('le' means little-endian, 'be' big-endian and 'ne' the endianness of the computer MPlayer is running on). Valid values (amongst others) are: 's16le', 'u32be' and 'u24ne'. -Exceptions to this rule are: u8, s8, floatle, floatbe, floatne, mulaw, alaw, -mpeg2, ac3 and imaadpcm. -.RE -.PD 1 -. -.TP -.B volume[=v:sc] -Select the output volume level. -This filter is not reentrant and can therefore only be enabled once for every -audio stream. +Exceptions to this rule that are also valid format specifiers: u8, s8, +floatle, floatbe, floatne, mulaw, alaw, mpeg2, ac3 and imaadpcm. +.RE +.PD 1 +. +.TP +.B volume[=v[:sc]] +Implements 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. +In case your sound card has a digital PCM mixer instead of an analog +one, and you hear distortion, use the MASTER mixer instead. +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. +.br +This filter has a second feature: It measures the overall 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. +.br +.I NOTE: +This filter is not reentrant and can therefore only be enabled +once for every audio stream. .PD 0 .RSs .IPs <v>\ \ Sets the desired gain in dB for all channels in the stream -from -200dB to +60dB (where -200dB mutes the sound -completely and +60dB equals a gain of 1000). +from -200dB to +60dB, where -200dB mutes the sound +completely and +60dB equals a gain of 1000 (default: 0). .IPs <sc>\ -Enable soft clipping. -.RE -.PD 1 -. -.TP -.B pan[=n:l01:l02:...l10:l11:l12:...ln0:ln1:ln2:...] -Mixes channels arbitrarily, see DOCS/\:HTML/\:en/\:audio.html for details. -An example how to downmix a six-channel file to two channels with this -filter can be found in the examples section near the end of the man page. +Turns soft clipping on (1) or off (0). +Soft-clipping can make the sound more smooth if very +high volume levels are used. +Enable this option if the dynamic range of the +loudspeakers is very low. +.br +.I WARNING: +This feature creates distortion and should be considered a last resort. +.RE +.sp 1 +.RS +.I EXAMPLE: +.RE +.RSs +.IPs "mplayer -af volume=10.1:0 media.avi" +would amplify the sound by 10.1dB and hard-clip if the +sound level is too high. +.RE +.PD 1 +. +.TP +.B pan=n[:l01:l02:...l10:l11:l12:...ln0:ln1:ln2:...] +Mixes channels arbitrarily. +Basically a combination of the volume and the channels filter +that can be used to down-mix many channels to only a few, +e.g.\& stereo to mono or vary the "width" of the center +speaker in a surround sound system. +This filter is hard to use, and will require some tinkering +before the desired result is obtained. +The number of options for this filter depends on +the number of output channels. +An example how to downmix a six-channel file to two channels with +this filter can be found in the examples section near the end. .PD 0 .RSs .IPs <n>\ \ number of input channels (1\-6) .IPs <lij> -How much of input channel j is mixed into output channel i. +How much of input channel j is mixed into output channel i (0\-1). +.RE +.sp 1 +.RS +.I EXAMPLE: +.RE +.RSs +.IPs "mplayer -af pan=1:0.5:0.5 -channels 1 media.avi" +Would down-mix from stereo to mono. +.IPs "mplayer -af pan=3:1:0:1:0.5:0.5 -channels 3 media.avi" +Would give 3 channel output leaving channels 0 and 1 intact, +and mix channels 0 and 1 into output channel 2 (which could +be sent to a subwoofer for example). .RE .PD 1 . .TP .B sub[=fc:ch] -Add subwoofer channel. +Adds a subwoofer channel to the audio stream. +The audio data used for creating the subwoofer channel is +an average of the sound in channel 0 and channel 1. +The resulting sound is then low-pass filtered by a 4th order +Butterworth filter with a default cutoff frequency of 60Hz +and added to a separate channel in the audio stream. +.br +.I Warning: +Disable this filter when you are playing DVDs with Dolby +Digital 5.1 sound, otherwise this filter will disrupt +the sound to the subwoofer. .PD 0 .RSs .IPs <fc>\ -cutoff frequency for low-pass filter (20Hz to 300Hz) (default: 60Hz) +cutoff frequency in Hz for the low-pass filter (20Hz to 300Hz) (default: 60Hz) +For the best result try setting the cutoff frequency as low as possible. +This will improve the stereo or surround sound experience. .IPs <ch>\ -channel number for the sub-channel +Determines the channel number in which to insert the sub-channel audio. +Channel number can be between 0 and 5 (default: 5). +Observe that the number of channels will automatically +be increased to <ch> if necessary. +.RE +.sp 1 +.RS +.I EXAMPLE: +.RE +.RSs +.IPs "mplayer -af sub=100:4 -channels 5 media.avi" +would add a sub-woofer channel with a cutoff frequency of +100Hz to output channel 4. .RE .PD 1 . .TP .B surround[=delay] -Decoder for matrix encoded surround sound, works on many 2 channel files. +Decoder for matrix encoded surround sound like Dolby Surround. +Many files with 2 channel audio actually contain matrixed surround sound. +Requires a sound card supporting at least 4 channels. .PD 0 .RSs .IPs <delay> delay time in ms for the rear speakers (0 to 1000) (default: 20) +This delay should be set as follows: If d1 is the distance +from the listening position to the front speakers and d2 is the distance +from the listening position to the rear speakers, then the delay d should +be set to 15ms if d1 <= d2 and to 15 + 5*(d1-d2) if d1 > d2. +.RE +.sp 1 +.RS +.I EXAMPLE: +.RE +.RSs +.IPs "mplayer \-af surround=15 \-channels 4 media.avi" +Would add surround sound decoding with 15ms delay for the sound to the +rear speakers. .RE .PD 1 . .TP .B delay[=ch1:ch2:...] -Delays the sound output. -Specify the delay separately for each channel in milliseconds (floating point -number between 0 and 1000). +Delays the sound to the loudspeakers such that the sound from the +different channels arrives at the listening position simultaneously. +It is only useful if you have more than 2 loudspeakers. +.PD 0 +.RSs +.IPs ch1,ch2,... +The delay in ms that should be imposed on each channel +(floating point number between 0 and 1000). +.RE +.PD 1 +.sp 1 +.RS +To calculate the required delay for the different channels do as follows: +.IP 1. 3 +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 in compensating for the +subwoofer (you will not hear the difference anyway). +.IP 2. 3 +Subtract the distances s1 to s5 from the maximum distance, +i.e.\& s[i] = max(s) - s[i]; i = 1...5. +.IP 3. +Calculate the required delays in ms as d[i] = 1000*s[i]/342; i = 1...5. +.RE +.PD 0 +.sp 1 +.RS +.I EXAMPLE: +.RE +.RSs +.IPs "mplayer \-af delay=10.5:10.5:0:0:7:0 media.avi" +Would delay front left and right by 10.5ms, the two rear channels +and the sub by 0ms and the center channel by 7ms. +.RE +.PD 1 . .TP .B export[=mmapped_file[:nsamples]] Exports the incoming signal to other processes using memory mapping (mmap()). +Memory mapped areas contain a header: +.sp 1 +.nf +int nch /*number of channels*/ +int size /*buffer size*/ +unsigned long long counter /*Used to keep sync, updated every + time new data is exported.*/ +.fi +.sp 1 +The rest is payload (non-interleaved) 16 bit data. .PD 0 .RSs .IPs <mmapped_file> @@ -3637,16 +3890,26 @@ .IPs <nsamples> number of samples per channel (default: 512) .RE +.sp 1 +.RS +.I EXAMPLE: +.RE +.RSs +.IPs "mplayer \-af export=/tmp/mplayer-af_export:1024 media.avi" +Would export 1024 samples per channel to '/tmp/mplayer-af_export'. +.RE .PD 1 . .TP .B extrastereo[=mul] -Increases the difference between left and right channels to add some -sort of "live" effect to playback. +(Linearly) increases the difference between left and right channels +which adds some sort of "live" effect to playback. .PD 0 .RSs .IPs <mul> -difference coefficient (default: 2.5) +Sets the difference coefficient (default: 2.5). +0.0 means mono sound (average of both channels), with 1.0 sound will be +unchanged, with -1.0 left and right channels will be swapped. .RE .PD 1 . @@ -3703,7 +3966,7 @@ .I NOTE: To get a full list of available video filters, see \-vf help. .sp 1 -Filters are managed in lists. +Video filters are managed in lists. There are a few commands to manage the filter list. . .TP
--- a/DOCS/xml/en/audio.xml Thu Feb 24 02:31:41 2005 +0000 +++ b/DOCS/xml/en/audio.xml Thu Feb 24 11:00:45 2005 +0000 @@ -55,703 +55,4 @@ </para> </sect2> - </sect1> - -<sect1 id="af"> -<title>Audio filters</title> -<para> - Audio filters allow 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 properties of the audio data differ from those required by the sound card - and deactivated if unnecessary. The <option>-af filter1,filter2,...</option> - option is used to override the automatic activation of filters or to insert - filters that are not automatically inserted. The filters will be executed as - they appear in the comma separated list. -</para> - -<para> -Example: -<screen>mplayer -af resample,pan <replaceable>movie.avi</replaceable></screen> -would run the sound through the resampling filter followed by the pan filter. -Observe that the list must not contain any spaces, else it will fail. -</para> - -<para> -The filters often have options that change their behavior. These options -are explained in detail in the sections below. A filter will execute using -default settings if its options are omitted. Here is an example of how to use -filters in combination with filter specific options: -<screen>mplayer -af resample=11025,pan=1:0.5:0.5 -channels 1 -srate 11025 <replaceable>media.avi</replaceable></screen> -would set the output frequency of the resample filter to 11025Hz and downmix -the audio to 1 channel using the pan filter. -</para> - - -<para> -The overall execution of the filter layer is controlled using the -<option>-af-adv</option> option. This option has two suboptions: -</para> - -<para> -<option>force</option> is a bit field that controls how the filters -are inserted and what speed/accuracy optimizations they use: -</para> - -<variablelist> -<varlistentry> -<term><option>0</option></term> -<listitem><para> -Use automatic insertion of filters and optimize according to CPU speed. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>1</option></term> -<listitem><para> -Use automatic insertion of filters and optimize for the highest speed. -<emphasis>Warning:</emphasis> Some features in the audio filters may -silently fail, and the sound quality may drop. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>2</option></term> -<listitem><para> -Use automatic insertion of filters and optimize for quality. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>3</option></term> -<listitem><para> -Use no automatic insertion of filters and no optimization. -<emphasis>Warning:</emphasis> It may be possible to crash <application>MPlayer</application> -using this setting. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>4</option></term> -<listitem><para> -Use automatic insertion of filters according to 0 above, -but use floating point processing when possible. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>5</option></term> -<listitem><para> -Use automatic insertion of filters according to 1 above, -but use floating point processing when possible. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>6</option></term> -<listitem><para> -Use automatic insertion of filters according to 2 above, -but use floating point processing when possible. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>7</option></term> -<listitem><para> -Use no automatic insertion of filters according to 3 above, -and use floating point processing when possible. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -<option>list</option> is an alias for the -af option. -</para> - -<para> -The filter layer is also affected by the following generic options: -</para> - -<variablelist> -<varlistentry> -<term><option>-v</option></term> -<listitem><para> -Increases the verbosity level and makes most filters print out extra -status messages. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>-channels</option></term> -<listitem><para> -This option sets the number of output channels you would like your -sound card to use. It also affects the number of channels that are -being decoded from the media. If the media contains less channels -than requested the channels filter (see below) will automatically -be inserted. The routing will be the default routing for the channels -filter. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>-srate</option></term> -<listitem><para> -This option selects the sample rate you would like your sound card -to use (of course the cards have limits on this). If the sample frequency -of your sound card is different from that of the current media, the resample -filter (see below) will be inserted into the audio filter layer to compensate -for the difference. -</para></listitem> -</varlistentry> -<varlistentry> -<term><option>-format</option></term> -<listitem><para> -This option sets the sample format between the audio filter layer and the -sound card. If the requested sample format of your sound card is different -from that of the current media, a format filter (see below) will be inserted -to rectify the difference. -</para></listitem> -</varlistentry> -</variablelist> - -<sect2 id="af_resample"> -<title>Up/Downsampling</title> - -<para> -<application>MPlayer</application> fully supports sound up/down-sampling through the -<option>resample</option> filter. It 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 can also be explicitly enabled on the command line. It -has three options: -</para> - -<variablelist> -<varlistentry> -<term><option>srate <8000-192000></option></term> -<listitem><para> - 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. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>sloppy</option></term> -<listitem><para> - is an optional binary parameter that allows the output frequency to differ - slightly from the frequency given by <option>srate</option>. This option - can be used if the startup of the playback is extremely slow. It is enabled - by default. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>type <0-2></option></term> -<listitem><para> - is an optional integer between <literal>0</literal> and <literal>2</literal> that - selects which resampling method to use. Here <literal>0</literal> represents - linear interpolation as resampling method, <literal>1</literal> represents - resampling using a poly-phase filter-bank and integer processing and - <literal>2</literal> represents resampling using a poly-phase filter-bank and - floating point processing. Linear interpolation is extremely fast, but - suffers from poor sound quality especially when used for up-sampling. The - best quality is given by <literal>2</literal> but this method also suffers from - the highest CPU load. -</para></listitem> -</varlistentry> -</variablelist> - -<para>Example: -<screen>mplayer -af resample=44100:0:0</screen> -would set the output frequency of the resample filter to 44100Hz using exact output -frequency scaling and linear interpolation. -</para> -</sect2> - -<sect2 id="af_channels"> -<title>Changing the number of channels</title> -<para> -The <option>channels</option> 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 not needed. The number of options is dynamic: -</para> - -<variablelist> -<varlistentry> -<term><option>nch <1-6></option></term> -<listitem><para> - is an integer between <literal>1</literal> and <literal>6</literal> that is used - for setting the number of output channels. This option is required, leaving it - empty results in a runtime error. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>nr <1-6></option></term> -<listitem><para> - is an integer between <literal>1</literal> and <literal>6</literal> that is used - for specifying the number of routes. This parameter is optional. If it is - omitted the default routing is used. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>from1:to1:from2:to2:from3:to3...</option></term> -<listitem><para> - are pairs of numbers between <literal>0</literal> and <literal>5</literal> - that define where each channel should be routed. -</para></listitem> -</varlistentry> -</variablelist> - -<para> - If only <option>nch</option> 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. -</para> - -<para> -Example 1: -<screen>mplayer -af channels=4:4:0:1:1:0:2:2:3:3 <replaceable>media.avi</replaceable></screen> -would change the number of channels to 4 and set up 4 routes that swap -channel 0 and channel 1 and leave 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. -</para> - -<para> -Example 2: -<screen>mplayer -af channels=6:4:0:0:0:1:0:2:0:3 <replaceable>media.avi</replaceable></screen> -would change the number of channels to 6 and set up 4 routes that copy -channel 0 to channels 0 to 3. Channel 4 and 5 will contain silence. -</para> -</sect2> - -<sect2 id="af_format"> -<title>Sample format converter</title> -<para> -The <option>format</option> filter converts between different sample formats. It - is automatically enabled when needed by the sound card or another filter. -</para> - -<variablelist> -<varlistentry> -<term><option>bps <number></option></term> -<listitem><para> - can be <literal>1</literal>, <literal>2</literal> or <literal>4</literal> and - denotes the number of bytes per sample. This option is required, leaving it empty - results in a runtime error. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>f <format></option></term> -<listitem><para> - is a text string describing the sample format. The string is a - concatenated mix of: <option>alaw</option>, <option>mulaw</option> or - <option>imaadpcm</option>, <option>float</option> or <option>int</option>, - <option>unsigned</option> or <option>signed</option>, <option>le</option> or - <option>be</option> (little- or big-endian). This option is required, - leaving it empty results in a runtime error. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -Example: -<screen>mplayer -af format=4:float <replaceable>media.avi</replaceable></screen> -would set the output format to 4 bytes per sample floating point data. -</para> -</sect2> - -<sect2 id="af_delay"> -<title>Delay</title> -<para> -The <option>delay</option> filter delays the sound to the loudspeakers such that -the sound from the different channels arrives at the listening position -simultaneously. -It is only useful if you have more than 2 loudspeakers. This filter has a -variable number of parameters: -</para> - -<variablelist> -<varlistentry> -<term><option>d1:d2:d3...</option></term> -<listitem><para> - 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. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -To calculate the required delay for the different channels do as follows: -</para> - -<orderedlist> -<listitem><para> - 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 in compensating for the sub-woofer (you will not hear the - difference anyway). -</para></listitem> -<listitem><para> -Subtract the distances s1 to s5 from the maximum distance i.e. - s[i] = max(s) - s[i]; i = 1...5 -</para></listitem> -<listitem><para> -Calculate the required delays in ms as - d[i] = 1000*s[i]/342; i = 1...5 -</para></listitem> -</orderedlist> - -<para> -Example: -<screen>mplayer -af delay=10.5:10.5:0:0:7:0 <replaceable>media.avi</replaceable></screen> -would delay front left and right by 10.5ms, the two rear channels and the sub -by 0ms and the center channel by 7ms. -</para> - -</sect2> - -<sect2 id="af_volume"> -<title>Software volume control</title> -<para>Software volume control is implemented by the <option>volume</option> -audio filter. 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. In case your sound card -has a digital PCM mixer instead of an analog one, and you hear distortion, -use the MASTER mixer instead. 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 options: -</para> - -<variablelist> -<varlistentry> -<term><option>v <-200 - +60></option></term> -<listitem><para> - is a floating point number between <literal>-200</literal> and <literal>+60</literal> - which represents the volume level in dB. The default level is 0dB. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>c</option></term> -<listitem><para> - is a binary control that turns soft clipping on and off. Soft-clipping can - make the sound more smooth if very high volume levels are used. Enable this - option if the dynamic range of the loudspeakers is very low. Be aware that - this feature creates distortion and should be considered a last resort. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -Example: -<screen>mplayer -af volume=10.1:0 <replaceable>media.avi</replaceable></screen> -would amplify the sound by 10.1dB and hard-clip if the sound level is too high. -</para> - -<para> -This filter has a second feature: It measures the overall maximum sound level -and prints out that level when <application>MPlayer</application> exits. -This volume estimate can be used for setting the sound level in -<application>MEncoder</application> such that the maximum dynamic range is utilized. -</para> -</sect2> - -<sect2 id="af_equalizer"> -<title>Equalizer</title> -<para> -The <option>equalizer</option> filter represents a 10 octave band graphic -equalizer, implemented using 10 IIR band pass filters. This means that -it works regardless of what type of audio is being played back. The center -frequencies for the 10 bands are: -</para> - -<informaltable> -<tgroup cols="2"> -<thead> - <row> - <entry>Band No.</entry><entry>Center frequency</entry> - </row> -</thead> -<tbody> - <row><entry>0</entry><entry>31.25 Hz</entry></row> - <row><entry>1</entry><entry>62.50 Hz</entry></row> - <row><entry>2</entry><entry>125.0 Hz</entry></row> - <row><entry>3</entry><entry>250.0 Hz</entry></row> - <row><entry>4</entry><entry>500.0 Hz</entry></row> - <row><entry>5</entry><entry>1.000 kHz</entry></row> - <row><entry>6</entry><entry>2.000 kHz</entry></row> - <row><entry>7</entry><entry>4.000 kHz</entry></row> - <row><entry>8</entry><entry>8.000 kHz</entry></row> - <row><entry>9</entry><entry>16.00 kHz</entry></row> -</tbody> -</tgroup> -</informaltable> - -<para> -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 uppermost band -are not completely symmetric if the sample rate is close to 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. -</para> - -<para> -This filter has 10 parameters: -</para> - -<variablelist> -<varlistentry> -<term><option>g1:g2:g3...g10</option></term> -<listitem><para> -are floating point numbers between <literal>-12</literal> and <literal>+12</literal> -representing the gain in dB for each frequency band. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -Example: -<screen>mplayer -af equalizer=11:11:10:5:0:-12:0:5:12:12 <replaceable>media.avi</replaceable></screen> -would amplify the sound in the upper and lower frequency region while -canceling it almost completely around 1kHz. -</para> -</sect2> - -<sect2 id="af_panning"> -<title>Panning filter</title> -<para> -Use the <option>pan</option> filter to mix channels arbitrarily. It is -basically a combination of the volume control and the channels filter. -There are two major uses for this filter: -</para> - -<orderedlist> -<listitem><para> -Down-mixing many channels to only a few, stereo to mono for example. -</para></listitem> -<listitem><para> -Varying the "width" of the center speaker in a surround sound system. -</para></listitem> -</orderedlist> - -<para> -This filter is hard to use, and will require some tinkering before the -desired result is obtained. The number of options for this filter -depends on the number of output channels: -</para> - -<variablelist> -<varlistentry> -<term><option>nch <1-6></option></term> -<listitem><para> -is an integer between <literal>1</literal> and <literal>6</literal> and is used -for setting the number of input channels. This option is required, leaving it -empty results in a runtime error. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>l00:l01:l02:..l10:l11:l12:...ln0:ln1:ln2:...</option></term> -<listitem><para> -are floating point values between <literal>0</literal> and <literal>1</literal>. -<option>l[i][j]</option> determines how much of input channel j is mixed into -output channel i. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -Example 1: -<screen>mplayer -af pan=1:0.5:0.5 -channels 1 <replaceable>media.avi</replaceable></screen> -would down-mix from stereo to mono. -</para> - -<para> -Example 2: -<screen>mplayer -af pan=3:1:0:1:0.5:0.5 -channels 3 <replaceable>media.avi</replaceable></screen> -would give 3 channel output leaving channels 0 and 1 intact, and mix -channels 0 and 1 into output channel 2 (which could be sent to a -sub-woofer for example). -</para> -</sect2> - -<sect2 id="af_sub"> -<title>Sub-woofer</title> -<para> -The <option>sub</option> filter adds a sub woofer channel to the audio -stream. The audio data used for creating the sub-woofer channel is an -average of the sound in channel 0 and channel 1. The resulting sound is -then low-pass filtered by a 4th order Butterworth filter with a default -cutoff frequency of 60Hz and added to a separate channel in the audio -stream. Warning: Disable this filter when you are playing DVDs with Dolby -Digital 5.1 sound, otherwise this filter will disrupt the sound to the -sub-woofer. This filter has two parameters: -</para> - -<variablelist> -<varlistentry> -<term><option>fc <20-300></option></term> -<listitem><para> - is an optional floating point number used for setting the cutoff frequency - for the filter in Hz. The valid range is 20Hz to 300Hz. For the best result - try setting the cutoff frequency as low as possible. This will improve the - stereo or surround sound experience. The default cutoff frequency is 60Hz. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>ch <0-5></option></term> -<listitem><para> - is an optional integer between <literal>0</literal> and <literal>5</literal> - which determines the channel number in which to insert the sub-channel audio. - The default is channel number <literal>5</literal>. Observe that the number of - channels will automatically be increased to <replaceable>ch</replaceable> if - necessary. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -Example: -<screen>mplayer -af sub=100:4 -channels 5 <replaceable>media.avi</replaceable></screen> -would add a sub-woofer channel with a cutoff frequency of -100Hz to output channel 4. -</para> -</sect2> - -<sect2 id="af_surround"> -<title>Surround-sound decoder</title> -<para> -Matrix encoded surround sound can be decoded by the <option>surround</option> -filter. Dolby Surround is an example of a matrix encoded format. Many files -with 2 channel audio actually contain matrixed surround sound. To use this -feature you need a sound card supporting at least 4 channels. This filter has -one parameter: -</para> - -<variablelist> -<varlistentry> -<term><option>d <0-1000></option></term> -<listitem><para> -is an optional floating point number between <literal>0</literal> and -<literal>1000</literal> used for setting the delay time in ms for the -rear speakers. This delay should be set as follows: if d1 is the distance -from the listening position to the front speakers and d2 is the distance -from the listening position to the rear speakers, then the delay d should -be set to 15ms if d1 <= d2 and to 15 + 5*(d1-d2) if d1 > d2. The default -value for d is 20ms. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -Example: -<screen>mplayer -af surround=15 -channels 4 <replaceable>media.avi</replaceable></screen> -would add surround sound decoding with 15ms delay for the sound to the -rear speakers. -</para> -</sect2> - -<sect2 id="af_export"> -<title>Audio Exporter</title> -<para> -This audio filter exports the incoming signal to other processes using memory -mapping (<literal>mmap()</literal>). Memory mapped areas contain a header: - -<programlisting> -int nch /*number of channels*/ -int size /*buffer size*/ -unsigned long long counter /*Used to keep sync, it's updated - every time new data is exported.*/ -</programlisting> - -The rest is payload (non-interleaved) 16bit data. -</para> - -<variablelist> -<varlistentry> -<term><option>mmapped_file</option></term> -<listitem><para> -The file you want this filter to export to. The default is to map to -<filename>~/.mplayer/mplayer-af_export</filename>. -</para></listitem> -</varlistentry> - -<varlistentry> -<term><option>nsamples</option></term> -<listitem><para> -Number of samples per channel. The default is <literal>512</literal> samples. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -Example: -<screen>mplayer -af export=/tmp/mplayer-af_export:1024 <replaceable>media.avi</replaceable></screen> -would export 1024 samples per channel to <filename>/tmp/mplayer-af_export</filename>. -</para> -</sect2> - -<sect2 id="af_extrastereo"> -<title>Extrastereo</title> - -<para> -This audio filter (linearly) increases the difference between left and -right channels (like the <application>XMMS</application> extrastereo -plugin) which adds some sort of "live" effect to playback. -This filter has one parameter:</para> - -<variablelist> -<varlistentry> -<term><option>mul</option></term> -<listitem><para> -is the difference coefficient, an optional floating point number that defaults -to <literal>2.5</literal>. If you set it to <literal>0.0</literal>, you will -have mono sound (average of both channels). If you set it to -<literal>1.0</literal>, sound will be unchanged, if you set it to -<literal>-1.0</literal>, left and right channels will be swapped. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -Usage: -<screen> -mplayer -af extrastereo <replaceable>media.avi</replaceable> -mplayer -af extrastereo=3.45 <replaceable>media.avi</replaceable><!-- ---></screen> -</para> -</sect2> - -<sect2 id="af_volnorm"> -<title>Volume normalizer</title> - -<para> -This audio filter maximizes the volume without distorting the sound. -</para> - -<para> -Usage: -<screen>mplayer -af volnorm <replaceable>media.avi</replaceable></screen> -</para> -</sect2> - -</sect1>