[MPlayer-dev-eng] Usage of -af options

[Anders Johansson]

Hi,

I have changed committed changes to libaf that adds support for filter
chains using the -af option and some advanced options that can be
enabled using -af-adv. Below follows some documentation of how to use
current and future options. I am not sure who is in change of the
documentation nowadays and which format it should be committed in but
the below documentation will at least give a starting point for
debugging the new interface:

Some of this documentation was posted earlier.


Audio filters

The audio filters in MPlayer can be used for changing the properties
of the audio stream(s) before the sound reaches the encoding in
mencoder or the sound card in mplayer. The some filters are enabled
automatically so that any audio data can be played or recorded to any
type of output device or audio encoder. The properties that can be
changed are number of channels and sample frequency and format. The
settings are probed and automatically configured but can be overridden
by using the -channels -srate and -format switches respectively.

The filters used in the automatic probing are "channels" for changing
the number of channels, "resample" for changing the sample rate and
"format" for changing the sample format. Theses and other filters can
be enabled explicitly on the command line using the -af option as
well. The -af option is a comma separated list of audio filters used
as follows:

mplayer -af <filter1,filter2,filter3[=options],...>

where the filterX is the name of the filter you want to use and the
options is an optional argument controlling the initial settings for
the specific instance of that filter. 

The available filters are:
resample[=srate:sloppy:fast] 
    Changes the sample rate of the audio stream to srate [Hz]. The
    option srate must be an integer. This filter only supports the 
    16 bit little endian format. The option sloppy is binary (0 or 1)
    and can make the output sample rate deviate slightly from the
    optimum value but can be used if you experience very large delays
    for the playback to start (default: 0). This option will effect
    the frame rate for the video and should therefore never be used when
    recording. The fast option is also binary and can be used if you
    have a very slow computer to increase the conversion rate
    (default: automatic). This option does however increase the
    distortion level, and should therefore not be used for recording
    purposes.

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. The exception is mixing from
    mono to stereo, then the mono channel is repeated in both the
    output channels. If the number of output channels is smaller than
    the number of input channels the exceeding channels are truncated.

format[=f,bps]
    Select the format f used for output from the filter layer. The
    format is selected according to the defines in libao2/afmt.h.
    The option bps is an integer and denotes bytes per sample and has
    to conform to the chosen format.

volume[=v0:v1:v2:v3:v4:v5:sc:pr:en]
    Select the output volume level. This filter is not reentrant and
    can therefore only be enabled once for every audio stream. The
    option v0 to v5 is the desired gain in [dB] for each channel in
    the stream. The gain can be set from -60dB to +20dB (where -60dB
    equals a gain of 1/1000 and +20dB equals a gain of 10). The option
    sc is binary and enables soft clipping. This option introduces
    non linear distortion but can be used if your speakers have very
    low dynamic range to improve audiablility. The option pr is binary
    and enables probing of the audio stream instantaneous and max
    volume is probed on a per channel basis and can be accessed through
    the runtime interface of the filter (there is no command line
    interface for this option). Be aware that this option is rather
    CPU intensive, and may have a negative impact on the playback of
    the movie. The last option en is also binary and enables and
    disables the volume control. This option can be used if only
    probing is desired but not volume control.
    
delay[=d]
    Delay sound output by d seconds, where d is a single precision 
    floating point number. This filter is not useful for anything 
    but debugging. This filter eats a lot of RAM.



-channels
Change the number of playback channels. If the number of output
channels is bigger than the number of input channels empty channels
are inserted. The exception is mixing from mono to stereo, then the
mono channel is repeated in both the output channels. If the number of
output channels is smaller than the number of input channels the
exceeding channels are truncated. A mixer filter will correct the
shortcomings of this filter in the future.

-srate
Select output sample rate from the filter layer in <Hz>.

-format
Select the format used for output from the filter layer. The
format is selected according to the defines in libao2/afmt.h.



The -af-adv option has sub options that controls the over all behavior
of the audio filter layer:

force=<0-3> Forces the insertion of audio filters to one of the
            following:
	    0. Completely automatic insertion of filters (default)
	    1. Optimize for speed
	    2. Optimize for accuracy
	    3. Turn off auto (use this if you want to write your own
	       filter list).
list=...    Same as -af, see above.


Notes: The resample:fast option is not yet implemented.
       Now the delay compensation that A'rpi promised to enable can be
       easily debugged using delay :)


/. me

Cheers,
//Anders